For background and setup information, make sure to start with the of IPC on GitHub.
If you have IPC installed on your machine, you should be able to run ipc-cli --help to check all the available commands.
ipc-cli --help
The IPC agent command line tool
Usage: ipc-cli [OPTIONS] [COMMAND]
Commands:
config config related commands
subnet subnet related commands such as create, join and etc
wallet wallet related commands
cross-msg cross network messages related commands
checkpoint checkpoint related commands
util util commands
help Print this message or the help of the given subcommand(s)
Configuration
IPC initialization
ipc-cli config init
This command will initialize a new empty config file under ~/.ipc with all parameters required to connect to the IPC rootnet network.
Subnet Management
List active subnets
ipc-cli subnet list --subnet=<PARENT_SUBBNET_ID>
You can check all the active child subnets on a specific parent subnet.
This command only shows subnets that have been registered to the gateway, i.e. that have provided enough collateral to participate in the IPC protocol and haven't been killed. It is not an exhaustive list of all of the subnet actors deployed over the network.
This command will create a subnet and create a corresponding contract based on the parameters specified with it. Make a note of the subnet-id for the subnet just created.
# Example execution
$ ipc-cli subnet create --parent /r314159 --min-validators 3 --min-validator-stake 10 --bottomup-check-period 30
[ipc_cli::commands::subnet::create] created subnet actor with id: /r314159/t410fylyzufn7lfg3q6zxpt6cdvq4yyiwm4tkaged2oy
This command specifies the subnet to join, the amount of collateral to provide, and the public key of the --from address that is joining as a validator.
To join a subnet and also include some initial balance for the validator in the subnet, you can add the --initial-balance flag with the balance to be included in the genesis.
Leaving a subnet will release the collateral for the validator and remove all the validation rights from its account. This means that if you have a validator running in that subnet, its validation process will immediately terminate.
# Example execution
$ ipc-cli subnet leave --subnet /r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq
Validators need to claim their collateral after they reduce collateral in the subnet through unstake
# Example execution
$ ipc-cli subnet claim --subnet=/r314159/t410fh4ywg4wvxcjzz4vsja3uh4f53johc2lf5bpjo6i
Changes in collateral and the power table are not reflected immediately in the parent. They need to be confirmed in the execution of the next bottom-up checkpoint, so until this happens, even if there has been a change in collateral, you may not be the change immediately when running ipc-cli subnet list. This impacts any change to the collateral of validators, i.e. stake, unstake and leave commands.
To inspect the changes to the power table that have been performed between two epochs you can use the following command:
You can use this command to send tokens between addresses of the same subnet. If --from is not specified, ipc-cli will send tokens from the default wallet address.
The ipc-cli has an EVM-compatible wallet that it uses to sign transactions and interact with IPC on behalf of specific addresses. This wallet type can also be used with FEVM.
Create new address
ipc-cli wallet new -w <wallet-type>
This command will create a wallet, and store the key information in ~/.ipc/evm_keystore.json. You can create an EVM-compatible wallet which can also used with FVM (Filecoin Virtual Machine).
# Sample execution
$ ipc-cli wallet new --wallet-type evm
"0x406a7a1d002b71ece175cc7e067620ae5b58e9ec"
At the moment, the ipc-cli only expose commands to perform the basic IPC interoperability primitives for cross-net communication, which is the exchange of FIL (the native token for IPC) between the same address of a subnet. Mainly:
fund, which sends native tokens from one public key address to the address in the child subnet.
release that moves native tokens from one account in a child subnet to its counterpart in the parent.
Fund tokens in a child subnet
ipc-cli cross-msg fund
--subnet <subnet-id>
[--from <from-addr>]
[--to <to-addr>]
<amount>
This command includes the cross-net message into the next top-down proof-of-finality. Once the top-down finality is committed in the child, the message will be executed and you should see the funds in your account of the child subnet. If the --to is not set explicitly, the funds are sent to the address of the --from in the subnet.
# Example execution
$ ipc-cli cross-msg fund --subnet /r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq 100
fund performed in epoch 1030279
Alternatively, we can pass an additional parameter to send the funds to a specific address in the child subnet.
# Example execution
$ ipc-cli cross-msg fund --subnet /r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq --to=0x406a7a1d002b71ece175cc7e067620ae5b58e9ec 100
fund performed in epoch 1030279
To fund your address in a child subnet genesis before it is bootstrapped, and include some funds on your address in the subnet in genesis, you can use the pre-fund command. This command can only be used before the subnet is bootstrapped and started.
# Example execution
$ ./bin/ipc-cli cross-msg pre-fund --subnet /r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq 1
This command will release funds to the parent subnet from its subnet. To release funds from a subnet, your account must hold enough funds inside this subnet.
This command includes the cross-net message into a bottom-up checkpoint after the current epoch. Once the bottom-up checkpoint is committed in the parent, you should see the funds in your account in the parent.
# Example execution
$ ipc-cli cross-msg release --subnet /r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq 100
release performed in epoch 1023
Alternatively, we can pass an additional parameter to release the funds to a specific address in the parent subnet by setting --to address.
# Example execution
$ ipc-cli cross-msg release --subnet /r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq --to 0x406a7a1d002b71ece175cc7e067620ae5b58e9ec 100
release performed in epoch 1030
The epoch in which the message is performed can give you a sense of the time the message will take to be propagated. You can check the current finality in a subnet and wait for the finality height that includes your message to be committed.
Subnets are periodically committing checkpoints to their parent every bottomup-check-period (parameter defined when creating the subnet). You can use this command to inspect the information of a range of bottom-up checkpoints committed in the parent for a subnet.
As with bottom-up messages, you can get a sense of the time that your message will take to get to the parent by looking at the epoch in which your bottom-up message was triggered (the output of the command) and listing the latest bottom-up checkpoints to see how far it is from being propagated.
This command will list the bottom-up checkpoints populated, signed, and agreed on their validity by a majority of validators in the child subnet.
This command can be used to check the state of the checkpoints submitted from a subnet relayer. Once subnet validators have agreed on the bottom-up checkpoint to be submitted in the parent for a specific epoch, relayers need to pick up the checkpoint and submit it in the parent.
This command can be used to check the list of the bundle of bottom-up checkpoints and signatures populated and already signed by a child subnet for their submission to the parent on a window of heights.
IPC relies on the role of a specific type of peer on the network called the relayers that are responsible for submitting bottom-up checkpoints that have been finalized in a child subnet to its parent. Without relayers, cross-net messages will only flow from the top levels of the hierarchy to the bottom, but not the other way around.
# Example execution
$ ipc-cli checkpoint relayer --subnet /r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq
To run the relayer from a different address you can use the --submitted flag.
Relayers are rewarded through cross-net message fees for the timely submission of bottom-up checkpoints to the parent. Relayers can claim the checkpointing rewards collected for a subnet.
# Example execution
$ ipc-cli subnet claim --subnet=/r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq --reward