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 kill command. 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.

ipc-cli --config-path ~/.ipc/validator1/config.toml subnet kill --subnet $SUBNET_ID btc

Observe 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 Helper scripts. This will show one active kill request for the subnet. You can also use the getsubnet helper script, also presented in 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:

 bitcoin-cli --rpcwallet=validator1 getbalance
 bitcoin-cli --rpcwallet=validator2 getbalance
 bitcoin-cli --rpcwallet=validator3 getbalance
 bitcoin-cli --rpcwallet=validator4 getbalance

Step 2: Vote for the kill

Let's have validators 2 and 3 vote for that kill request.

ipc-cli --config-path ~/.ipc/validator2/config.toml subnet kill --subnet $SUBNET_ID btc

ipc-cli --config-path ~/.ipc/validator3/config.toml subnet kill --subnet $SUBNET_ID btc

Observe the result:

Now the bitcoin monitor should show a message like the following:

Kill request majority reached for subnet /b4/t410fafkd6bwax3vxeqan6dwqnhja3iw666wlngjey4a: 46000/64000 power, marking subnet pending killed.

The script getkillrequests, as presented in 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.

ipc-cli cross-msg release --subnet $SUBNET_ID --from $IPC_ADDRESS_OF_USER_1 btc --to "$(bitcoin-cli --rpcwallet=user1 getnewaddress)" 30000000

To check the balance of the user on the subnet, you can observe the output of the balancer helper script, or use:

# Balance on the L2
ipc-cli wallet balances --subnet $SUBNET_ID --wallet-type btc | grep $IPC_ADDRESS_OF_USER_1

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:

 bitcoin-cli --rpcwallet=validator1 getbalance
 bitcoin-cli --rpcwallet=validator2 getbalance
 bitcoin-cli --rpcwallet=validator3 getbalance
 bitcoin-cli --rpcwallet=validator4 getbalance

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 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.