# Interacting with a subnet: deposit from Bitcoin and release back to Bitcoin This guide will walk you through the supported interactions between bitcoin and L2 subnets, specifically depositing BTC and releasing BTC back to the bitcoin network. Transferring tokens between L2 subnets is addressed in the [Cross-chain token transfers](/ipc-btc-scaling-docs/user-guide-for-using-subnets/publish-your-docs-1.md). We call "wrapped BTC" and "wrapped satoshi" the tokens used in a L2 subnet. *** ### **Prerequisites** Before starting, ensure that you have 1. deployed subnet with id `$SUBNET_ID` 2. exported the IPC address of each validator as `$IPC_ADDRESS_OF_VALIDATOR_1` ... `$IPC_ADDRESS_OF_VALIDATOR_4` and of user 1 as `$IPC_ADDRESS_OF_USER_1` 3. created wallets and configuration files for user 1 4. funded the validators via `cross-msg fund` The previous steps should have covered all these prerequisites. The default Docker-based deployment has set all required environment variables. Moreover, the helper scripts described earlier will be useful for monitoring the balances in the subnet and mining bitcoin blocks on regtest. You can optionally run them in separate terminals/panels that you can easily watch. {% hint style="info" %} Run all following commands from inside the `bitcoin-ipc` container, except if you used the Alternative deployment method. {% endhint %} *** ### Step 1: Fund a user Let's fund the account of user 1 in the subnet `$SUBNET-ID` with 1 wBTC: {% code overflow="wrap" %} ```bash ipc-cli --config-path ~/.ipc/user1/config.toml cross-msg fund --subnet=$SUBNET_ID btc --to $IPC_ADDRESS_OF_USER_1 100000000 ``` {% endcode %} #### **Parameters:** * `--subnet`: The ID of the subnet where we are depositing BTC. * `--to`: The recipient IPC address within the subnet. * The sender is the wallet used by the bitcoin provider of the user (defined in `~/.ipc/user1/.env` , which was given as argument when we run the bitcoin provider, in this case the wallet is `user1`). **Returns:** The bitcoin block height when the fund transaction was submitted to bitcoin (not the block in which it was included). Make sure you mine a block (not needed if you are running the `miner.sh` script). {% code overflow="wrap" %} ``` bitcoin-cli generatetoaddress 1 "$(bitcoin-cli --rpcwallet=default getnewaddress)" ``` {% endcode %} {% hint style="warning" %} Caveat: If the fund amount is too low, the transaction may not get accepted in the mempool. You can verify that it was indeed included in a block by checking the output of the `monitor` after mining the blocks. {% endhint %} #### Verify the balance in the subnet You can use the *balancer* helper script to check that the balance was updated in the subnet (described in [Optional: Helper scripts](/ipc-btc-scaling-docs/user-guide-for-using-subnets/optional-helper-scripts.md)): ```bash ./scripts/balancer.sh $SUBNET_ID ``` or use following command. {% code overflow="wrap" %} ```bash ipc-cli wallet balances --subnet $SUBNET_ID --wallet-type btc | grep $IPC_ADDRESS_OF_USER_1 ``` {% endcode %} #### Verify the balance on bitcoin The following commands can be used to verify that the balance of user 1 on bitcoin was decreased: ```bash bitcoin-cli --rpcwallet=user1 getbalance ``` ```sh cast balance $IPC_ADDRESS_OF_USER_1 --rpc-url http://localhost:8545/ ``` {% hint style="success" %} **More commands and implementation details** 1. The `ipc-cli fund` command is implemented by a bitcoin transaction sending the funds to a multisig address. * The multisig address is managed by the subnet's validators. * The deposit transaction includes metadata linking it to the user’s wallet within the subnet. 2. Validators monitor the Bitcoin network and confirm the transaction (through what is called "top-down messaging" in IPC). 3. Once confirmed, validators mint an equivalent amount of wrapped tokens in the subnet and transfer them to the user’s address. You can see the top-down messages on bitcoin between blocks `` and `` destined to subnet `` using: {% code overflow="wrap" %} ```bash ipc-cli cross-msg list-topdown-msgs --subnet=$SUBNET_ID --from --to ``` {% endcode %} You can also see the latest block considered final for the subnet using: {% code overflow="wrap" %} ```bash ipc-cli cross-msg parent-finality --subnet=$SUBNET_ID ``` {% endcode %} {% endhint %} *** ### Step 2: Release BTC back to L1 We will perform a release for `IPC_ADDRESS_OF_USER_1` , whose wallet on bitcoin is `user1`. Check the balances before performing the release for some address `IPC_ADDRESS_OF_USER_1` in the L2 subnet: ```bash # Balance on the L1 bitcoin-cli -rpcwallet=user1 getbalance ``` {% code overflow="wrap" %} ```bash # Balance on the L2 ipc-cli wallet balances --subnet $SUBNET_ID --wallet-type btc | grep $IPC_ADDRESS_OF_USER_1 ``` {% endcode %} Perform the release: {% code overflow="wrap" %} ```bash ipc-cli cross-msg release --subnet $SUBNET_ID --from $IPC_ADDRESS_OF_USER_1 btc --to "$(bitcoin-cli --rpcwallet=user1 getnewaddress)" 50000000 ``` {% endcode %} #### **Parameters:** * `--subnet`: The ID of the subnet where we are releasing from. * `--from` : The IPC address of an account in subnet `` . * `--to`: The bitcoin address of the recipient. You can use the same commands as above to check the balances after the release. Notice that the balance in the subnet is updated almost immediately, while **the balance on bitcoin will be updated after the next checkpoint transaction is submitted**. This may take a while, depending on the parameter `--bottomup-check-period` chosen at subnet creation. {% hint style="success" %} **More information and implementation details** After submitting the release command, you can look at the output of any bitcoin monitor. You should see that it picked up the corresponding checkpoint transaction (`IpcCheckpointSubnetMsg`), and that it contains the withdrawal we submitted. After this, the balance on bitcoin should reflect all performed withdrawals. {% endhint %} ## Alternative: Install on the host machine If you have installed `ipc-cli` on your host machine, you need to manually start a relayer. You can start a relayer using the following command: {% code overflow="wrap" %} ```bash ipc-cli --config-path ~/.ipc/validator1/config.toml checkpoint relayer --subnet $SUBNET_ID ``` {% endcode %} You can use the same command, but pointing to a different validator's config, to start a second relayer. {% hint style="warning" %} Common problems and caveats: * Make sure the subnet is added to the config.toml file, otherwise the command returns the error that the subnet is not configured. * Make sure that you have funded all validators (as described in [Subnet creation and deployment](/ipc-btc-scaling-docs/user-guide-for-using-subnets/subnet-creation-and-deployment.md)), otherwise they will not be able to vote for and finalize checkpoint messages. * When the relayer starts, it tries to submit all previous checkpoints found in the subnet. When bitcoin is the parent subnet, this has the implication that the input UTXOs to an old checkpoint transaction might not be available anymore. Hence, because different checkpoints which are causally dependent may spend the same UTXO, instead of chained UTXOs, **at least one relayer must be running for the subnet at all times.** * Since in this guide we are starting the relayer much later than when the subnet was deployed, the relayer may initially print some warnings, as it may not be able to submit old checkpoints. * If the checkpoint period is lower than the block-generation parameter on bitcoin (which does not make sense in a real deployment, but may happen when testing on Regtest if you do not generate blocks soon enough and you do not run the `miner.sh` script), then the relayer will return warnings saying that "transaction is already in mempool". These messages can anyway be ignored, as the bitcoin has been submitted to bitcoin. The same will happen if you are running more than one relayers, as they will all by trying to submit the same transactions to bitcoin. {% endhint %} {% hint style="success" %} **More commands and implementation details** You can use the following ipc-cli command to query the bottom-up messages finalized in `$SUBNET_ID` between epochs `` and `` (you can see current block height in child subnets using the script provided in the previous page). {% code overflow="wrap" %} ```bash ipc-cli checkpoint list-bottomup-bundle --subnet $SUBNET_ID --from-epoch --to-epoch ``` {% endcode %} {% endhint %} After the Relayer is started, you can follow the steps of this page. --- # 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.md?ask= ``` 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.