# Validator Operations within subnet

### Prerequisites

* Please make sure you set `$SUBNET_ID` with the subnet id of the **first** subnet we have created. The instructions in this page operate on Subnet A.

{% hint style="info" %}
Run all following commands from inside the `bitcoin-ipc` container, except if you used the Alternative deployment method.
{% endhint %}

***

### **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 [Optional: Helper scripts](/ipc-btc-scaling-docs/user-guide-for-using-subnets/optional-helper-scripts.md), also see for list of all ports):

```bash
# from your host machine
./scripts/list_validators.sh 26657
```

**Submit the join command for validator 5:**

<pre class="language-bash" data-overflow="wrap"><code class="lang-bash"># from inside the container
<strong>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)"
</strong></code></pre>

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:**

<pre class="language-bash" data-overflow="wrap"><code class="lang-bash"># from inside the container
<strong>ipc-cli --config-path ~/.ipc/validator5/config.toml cross-msg fund --subnet=$SUBNET_ID btc --to $IPC_ADDRESS_OF_VALIDATOR_5 25000000
</strong></code></pre>

**Run the docker container for validator 5:**

After the subnet creates the next checkpoint and you see `"total": "5"` printed, run the following:

{% hint style="warning" %}
**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 before running the following command.
{% endhint %}

**Assuming the validator joined Subnet A**, then run:

```bash
# from inside the container
/usr/local/bin/spin_up_subnet_a_from_container.sh $SUBNET_ID validator5
```

**If the validator joined Subnet B**, then run:

```bash
# from inside the container
/usr/local/bin/spin_up_subnet_b_from_container.sh $SUBNET_ID validator5
```

**View the status of the new validator:**\
We can query the CometBFT port of the new validator to view its status (explained in [Optional: Helper scripts](/ipc-btc-scaling-docs/user-guide-for-using-subnets/optional-helper-scripts.md), also see for list of all ports):

```bash
# from your host machine
./scripts/validator_status.sh 27057
```

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:**

{% code overflow="wrap" %}

```bash
# from inside the container
ipc-cli --config-path ~/.ipc/validator1/config.toml subnet stake --subnet $SUBNET_ID btc --collateral 100000000 --validator-address $IPC_ADDRESS_OF_VALIDATOR_1
```

{% endcode %}

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

{% code overflow="wrap" %}

```bash
# from your host machine
./scripts/validator_status.sh 26657
```

{% endcode %}

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 [Optional: Helper scripts](/ipc-btc-scaling-docs/user-guide-for-using-subnets/optional-helper-scripts.md).

{% code overflow="wrap" %}

```bash
# from your host machine, returns all validators, fetched from validator1 cometbft
./scripts/list_validators.sh 26657
```

{% endcode %}

### **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:**

{% code overflow="wrap" %}

```bash
# from inside the container
ipc-cli --config-path ~/.ipc/validator1/config.toml subnet unstake --subnet $SUBNET_ID btc --collateral 50000000
```

{% endcode %}

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

{% hint style="success" %}
**The process for staking:**

1. The ipc-cli uses the bitcoin provider to create a bitcoin transaction that sends the additional BTC to the subnet's multisig address.
2. Once the transaction is finalized, the bitcoin monitor will catch it and send it to the subnet through the top-down communication mechanism
3. 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.
{% endhint %}

### 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 [Optional: Helper scripts](/ipc-btc-scaling-docs/user-guide-for-using-subnets/optional-helper-scripts.md).

{% code overflow="wrap" %}

```bash
# from inside the container
ipc-cli --config-path ~/.ipc/validator5/config.toml subnet unstake --subnet $SUBNET_ID btc --collateral 230000000
```

{% endcode %}

## Optional

Instead of using the `spin_up_subnet_a_from_container` script, you can start the 5th validator manually using the following command:

```bash
# from inside the container
cargo-make 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bitcoin-scaling-labs-docs.gitbook.io/ipc-btc-scaling-docs/user-guide-for-using-subnets/publish-your-docs-2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.