Validator Operations within subnet

Prerequisites

Please make sure you set $SUBNET_ID with the subnet id of the first subnet we have created. We will not be using Subnet B anymore.

Step 1: Join additional validator

After a subnet is bootstrapped, additional validators can join, even if they where not included in the $WHITELIST when the subnet was created.

To view the validators in a subnet, you can run (explained in Helper scripts):

./scripts/list_validators.sh

Submit the join command for validator 5:

Make sure the monitor and provider for validator 5 are running, as specified in Run bitcoin monitor and provider.

ipc-cli --config-path ~/.ipc/validator5/config.toml subnet join --from $IPC_ADDRESS_OF_VALIDATOR_5 --subnet $SUBNET_ID btc --collateral=230000000 --ip 66.222.44.55:8080 --backup-address "$(bitcoin-cli --rpcwallet=validator5 getnewaddress)"

The validator set in the subnet is updated when the subnet creates a checkpoint, so the above command may take a while to take effect (parameter --bottomup-check-period at subnet creation). After that, you will observe the output in the script above: you should see "total": "5" printed. At the same time you can observe in the output of the l2_block_checker helper script that sometimes it takes a bit longer to create a new block, which is because validator 5 was expected to create that block — this will change when we start the docker containers for the new validator.

Fund validator 5:

ipc-cli --config-path ~/.ipc/validator5/config.toml cross-msg fund --subnet=$SUBNET_ID btc --to $IPC_ADDRESS_OF_VALIDATOR_5 25000000

Run the docker container for validator 5:

Attention: The command uses the ${ResolverAddress} and ${CometBftID} returned by the spin_up_subnet_a script when we started the containers for Subnet A. You need to set these env variables for the following cargo-make command to work.

cargo make --makefile "../ipc/infra/fendermint/Makefile.toml" \
    -e NODE_NAME="validator-5" \
    -e SUBNET_ID="$SUBNET_ID" \
    -e PRIVATE_KEY_PATH="$HOME/.ipc/validator5/validator.sk" \
    -e CMT_P2P_HOST_PORT="27056" \
    -e CMT_RPC_HOST_PORT="27057" \
    -e ETHAPI_HOST_PORT="8945" \
    -e RESOLVER_HOST_PORT="27055" \
    -e BOOTSTRAPS="$CometBftID@validator-1-cometbft:26656" \
    -e RESOLVER_BOOTSTRAPS="/dns/validator-1-fendermint/tcp/26655/p2p/$ResolverAddress" \
    -e PARENT_ENDPOINT="http://host.docker.internal:3034/api" \
    -e PARENT_AUTH_TOKEN=validator5_auth_token \
    -e TOPDOWN_CHAIN_HEAD_DELAY=0 \
    -e TOPDOWN_PROPOSAL_DELAY=0 \
    -e FM_PULL_SKIP=1 \
    child-validator

View the status of the new validator: We can query the CometBFT port (27057, specified in the docker-make script above) of the new validator to view its status:

./scripts/validator_status.sh 5

The new validator does not start participating in consensus immediately — it must first sync with the rest of the network. You can see this in the output of the status RPC method: The field "catching_up" will be true, "voting_power" will be 0, and the field "latest_block_height" will be increasing but smaller than the current height in the subnet.

When syncing is completed, the validator will start participating in consensus. You should see the status call report the correct "voting_power" , and you will see the subnet producing blocks faster again.

Step 2: Stake Additional Collateral

Validators can increase their collateral in a subnet and, as a result, accordingly increase their stake and voting power in the subnet.

The following command will increase the collateral of validator 1 by 1 bitcoin.

Command:

ipc-cli --config-path ~/.ipc/validator1/config.toml subnet stake --subnet $SUBNET_ID btc --collateral 100000000 --validator-address $IPC_ADDRESS_OF_VALIDATOR_1

Parameters:

The --config-path parameter determines the bitcoin wallet that pays the additional collateral.
--validator-address determines the subnet validator whose collateral will increase

In order to observe the results, we can run the following commands in separate terminals.

./scripts/validator_status.sh 1

After the changes take effect, you should see the voting power (field "voting_power") of validator 1 being 3,000 (as validator 1 staked 2 BTC at join and 1 BTC now) — notice the scaling done by CometBFT, explained in the page Helper scripts.

# all validators, fetched from validator1 cometbft
./scripts/list_validators.sh

Step 3: Unstake Collateral

Validators can decrease their collateral in a subnet and, as a result, accordingly decrease their stake and voting power.

The following command will decrease the collateral of validator 1 by 0.5 bitcoin.

Command:

ipc-cli --config-path ~/.ipc/validator1/config.toml subnet unstake --subnet $SUBNET_ID btc --collateral 50000000

Parameters:

The --config-path determines both the bitcoin wallet that receives the unstaked collateral and validator that unstakes it.

After the changes take effect, you should see the voting power (field "voting_power" in the status CometBFT RPC call) of validator 1 being 2,500.

The process for staking:

The ipc-cli uses the bitcoin provider to create a bitcoin transaction that sends the additional BTC to the subnet's multisig address.
Once the transaction is finalized, the bitcoin monitor will catch it and send it to the subnet through the top-down communication mechanism
The subnet processes all top-down messages at checkpoint time. So, at the next checkpoint of the child subnet the stake will be updated.

Observe that the command allows the user to send the additional collateral to any validator in the subnet.

The process for unstaking:

Unstaking works in a similar way. Observe that the command does not accept a validator-address argument. This is inferred by the address that signs the corresponding bitcoin transaction. In other words, a user can unstake only from a validator whose signing key it controls.

Step 4: Leave the subnet

A validator can leave the subnet by unstaking all of its collateral. Let's do this for validator 5. If you have used the exact numbers in this demo, validator 5 should have 2.3 BTC staked by now. Otherwise, please see the correct number in the output of the status RPC method — again, notice the scaling done by CometBFT, explained in the page Helper scripts.

ipc-cli --config-path ~/.ipc/validator5/config.toml subnet unstake --subnet $SUBNET_ID btc --collateral 230000000

PreviousCross-chain token transfers NextKill subnet

Last updated 3 months ago