Cross-chain token transfers

Now we have two subnets up and running. We can send tokens from subnet A to subnet B.

Prerequisites

All steps of the are a prerequisite. In particular, make sure

• you have created and deployed both subnets

• the relayer for subnet 1 is running

• you have exported the IPC address of user 1 and user 2 as $IPC_ADDRESS_OF_USER_1 and $IPC_ADDRESS_OF_USER_2 , respectively

Step 1: Set env variables for ease of use

• Create a env variable $SOURCE_SUBNET_ID with the SubnetID of the subnet of the first subnet.

• Create a env variable $TARGET_SUBNET_ID with the SubnetID of the second subnet.

Step 2: Transfer tokens between subnets

To transfer tokens from address IPC_ADDRESS_OF_USER_1 in subnet SOURCE_SUBNET_ID to address IPC_ADDRESS_OF_USER_2 in subnet TARGET_SUBNET_ID, we use the following command.

ipc-cli --config-path ~/.ipc/user1/config.toml cross-msg transfer --source-subnet $SOURCE_SUBNET_ID --destination-subnet $TARGET_SUBNET_ID --source-address $IPC_ADDRESS_OF_USER_1 --destination-address $IPC_ADDRESS_OF_USER_2 222200

The command returns the epoch in the source subnet in which the transfer was submitted.

Caveat:

Please make sure the sender has enough balance in the source subnet. If that's not the case, ipc-cli returns an error like "Actor balance less than needed".

Using the numbers in this demo, user 1 should have at 0.5 wBTC in subnet A — if you have performed additional release operations in the previous step you might have to perform an addition fund to user 1.

Check balance updates

The balance of user 1 one the source subnet is updated immediately. Observe the balancer script or run:

ipc-cli wallet balances --subnet $SOURCE_SUBNET_ID --wallet-type btc | grep  $IPC_ADDRESS_OF_USER_1

For the target subnet, wait until the next checkpoint is created and finalized in the source subnet (parameter --bottomup-check-period of ipc-cli subnet create ). Then you can check the balances in the output of the balancer script or use:

ipc-cli wallet balances --subnet $TARGET_SUBNET_ID --wallet-type btc | grep  $IPC_ADDRESS_OF_USER_2

Implementation details for the transfer

1. ipc-cli submits a transfer transaction to the source subnet.

2. When finalized in the source subnet, the transaction appears in a checkpoint message. You can see these messages using the list-bottomup-bundle command (described earlier) for subnet SOURCE_SUBNET_ID.

3. The relayer submits the checkpoint message to bitcoin.

4. The bitcoin monitor parses the checkpoint message, once it becomes finalized on the bitcoin network. You can look at the output of any bitcoin monitor. You should see that it picked up the checkpoint transaction (keyoword IpcCheckpointSubnetMsg) containing a transfer (IpcCrossSubnetTransfer) , followed by a second bitcoin transaction (keyword IpcBatchTransferMsg).

5. When validators of subnet TARGET_SUBNET_ID ask its parent subnet (bitcoin) for new top-down messages, the monitor will return the transfer transaction. You can see these transactions using the list-topdown-msgs command (described earlier) for subnet TARGET_SUBNET_ID.

You can also test the opposite direction, sending funds from subnet B to subnet A. The command is analogous to the one above. However, make sure you run a relayer for subnet B first.