Kill subnet
An L2 subnet can be discontinued, or, simply, killed.
The process is the following:
Any validator of a subnet can propose a kill for that subnet, using the
ipc-cli subnet killcommand. The proposal expires after a certain amount of time, defined as number of blocks on the bitcoin network (currently set to 36 blocks, equivalent to 6 hours when deployed on bitcoin mainnet).The subnet remains active and fully operational and it accepts stake-change requests and new validators until the kill proposal is accepted.
The kill is accepted when enough validators (⅔ of the current collateral of the subnet) vote for it before the proposal expires. When this happens, the subnet is marked as "to_be_killed".
For period of time, which we refer to as kill delay period, a subnet that is marked as "to_be_killed" remains available to users but it does not accept stake-change requests or new validators any more. This allows users to withdraw their funds.
Currently, the length of the kill delay period is set to five subnet checkpoints, that is, the subnet will remain available until it creates and submits five checkpoints. Future versions of the software will support longer and configurable values for the kill delay period, specified per each subnet at subnet creation time.
After the kill delay period, the subnet will be marked as "killed". The collateral is returned to the validators (implemented using the checkpoint functionality of IPC) and the subnet stops being operational. Any user funds that has not be withdrawn is split among the validators proportionally to their weight.
Step 1: Propose a kill
Let's have validator 1 propose a kill for a subnet — make sure you have set $SUBNET_ID to the subnet you want to be killed.
# from inside the container
ipc-cli --config-path ~/.ipc/validator1/config.toml subnet kill --subnet $SUBNET_ID btcObserve the result:
Mine a new block, wait until the bitcoin-provider binary processes the block, and you should see bitcoin monitor showing a message like the following:
Kill request added for subnet /b4/t410fafkd6bwax3vxeqan6dwqnhja3iw666wlngjey4a but majority not reached: 15000/64000 power (threshold: 42667)You can use the getkillrequests helper script, as presented in Optional: Helper scripts. This will show one active kill request for the subnet. You can also use the getsubnet helper script, also presented in Optional: Helper scripts. In the output observe the field "killed", which still shows the subnet as "not_killed".
Check the balances on bitcoin:
Let's check the balance of the validators on the bitcoin network at this point:
Step 2: Vote for the kill
Let's have validators 2 and 3 vote for that kill request.
Observe the result:
Now the bitcoin monitor should show a message like the following:
The script getkillrequests, as presented in Optional: Helper scripts will now show three entries, as three validators have proposed and accepted the termination of the subnet. The script getsubnet now shows in the field "killed" the subnet as "to_be_killed".
Currently the vote collection for a kill request is performed on bitcoin, that is, all ipc-cli subnet kill commands above are recorded on bitcoin. An optimization is to use the subnet for collecting the votes, same as how checkpointing has been implemented.
You can now try submitting a new join or a stake or unstake command, as presented in Validator Operations within subnet, and you will see the bitcoin monitor and provider rejecting it.
Step 3: Release user funds
Due to an outstanding bug, Fendermint significantly overestimates transaction fees. As a result the current code does not allow the user to release all its funds. For purposes of the demo, we will withdraw 0.3 wBTC, and then observe that the balance of user 1 is 0.19997576 wBTC (the actual fee was much lower than what Fendermint estimated). The remaining balance cannot be withdrawn at once, but you can recursively withdraw some more funds. Future versions of the codebase will fix this problem.
At this point, user 1 still has 0.5 wBTC in the subnet. Let's release it, using the following command.
To check the balance of the user on the subnet, you can observe the output of the balancer helper script, or use:
Step 4: Wait for the subnet to be killed
Reminder: A relayer must be running for the checkpoint functionality to work.
The subnet will be be killed after five bottom-up checkpoints are created by the subnet. Then you can verify that the bitcoin balance of the validators has been updated using the same commands as before:
The balance of each validator has increased by its collateral, and the funds that were not withdrawn were divided among the validators.
The script getsubnet, as presented in Optional: Helper scripts, now shows the subnet as "killed". The subnet is not anchored on bitcoin anymore, it cannot create checkpoint messages, and it cannot perform cross-subnet transfers. The docker containers can now be stopped.
Last updated