IPC CLI
This page lists all the ipc-cli commands to interact with IPC subnets.
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
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
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.
Create a child subnet
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.
Join a subnet as a validator
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.
Leave a subnet
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.
Stake more collateral as a validator
After initially joining a subnet with specified collateral, a validator can stake more collaterals to the subnet.
Unstake collateral from a subnet
Claim the unstaked collateral
Validators need to claim their collateral after they reduce collateral in the subnet through unstake
Transfer tokens within a subnet
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.
Wallet Key Management
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
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).
Check wallet balance
You can check the token balance in your wallet addresses for any active subnet configured in the ipc-cli.
Set default wallet address
You can set a default address for your wallet so it is always the one used when the --from flag is not explicitly set.
Get the default wallet address
Export a wallet key
This command will exporte a wallet private key which is stored in the ipc-cli keystore ~/.ipc/evm_keystore.json.
Export key encoded in based64 for Fendermint
Export key in HEX
Import a wallet
This command will import a wallet from an EVM key file with this format {“address”:,“private_key”:<PRIVATE_KEY>}.
Import a wallet from the private key.
Cross subnet messages
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.releasethat moves native tokens from one account in a child subnet to its counterpart in the parent.
Fund tokens in a child subnet
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.
Alternatively, we can pass an additional parameter to send the funds to a specific address in the child subnet.
Pre-fund subnet address in genesis
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.
Release funds from a subnet
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.
Alternatively, we can pass an additional parameter to release the funds to a specific address in the parent subnet by setting --to address.
Release initial subnet funds
This command will recover some (or all) of the funds that were sent to a subnet through pre-fund to be included as a genesis balance for your address.
Check parent subnet finality
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.
List top-down messages
This command will list the top-down messages sent for a subnet from a parent network for a specific epoch.
CheckPoint
List checkpoints for a subnet
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.
Check quorum-reached bottom-up checkpoints
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.
Check if bottom-up checkpoints are submitted
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.
List submitted bottom-up checkpoints
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.
Run a relayer
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.
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.
Last updated