Ready to test the waters with your first subnet? This guide will deploy a subnet with three local validators orchestrated by ipc-cli. This subnet will be anchored to the public . This will be a minimal example and may not work on all systems. The full documentation provides more details on each step.
Several steps in this guide involve running long-lived processes. In each of these cases, the guide advises starting a new session. Depending on your set-up, you may do this using tools like screen or tmux, or, if using a graphical environment, by opening a new terminal tab, pane, or window.
NOTE: this step may take a while to compile, depending on OS version and hardware build
# make sure that rust has the wasm32 target & use stable version of rustc
rustup target add wasm32-unknown-unknown
rustup default stable
# add your user to the docker group
sudo usermod -aG docker $USER && newgrp docker
# clone this repo and build
git clone https://github.com/consensus-shipyard/ipc.git
cd ipc
make
# building will generate the following binaries
./target/release/ipc-cli --version
./target/release/fendermint --version
# make sure that rust has the wasm32 target & use stable version of rustc
rustup target add wasm32-unknown-unknown
rustup default stable
# clone this repo and build
git clone https://github.com/consensus-shipyard/ipc.git
cd ipc/contracts
make gen
cd ..
cargo build --release
# building will generate the following binaries
./target/release/ipc-cli --version
./target/release/fendermint --version
Step 2: Initialise your config
Initialise the config
alias ipc-cli="cargo run -q -p ipc-cli --release --"
ipc-cli config init
This should have populated a default config file with all the parameters required to connect to calibration at ~/.ipc/config.toml. Feel free to update this configuration to fit your needs.
The IPC stack is changing rapidly. To make sure you use the latest contracts deployed on Filecoin Calibration:
Run nano ~/.ipc/config.toml to see your configuration
NOTE: you may hit faucet rate limits. In that case, wait a few minutes or continue with the guide and come back to this before step 9. Alternatively, you can send funds from your primary wallet to your owner wallets.
Step 4: Create a child subnet
The next step is to create a subnet under /r314159 calibration. Remember to set a default wallet or explicitly specify the wallet from which you want to perform the action with the --from flag.
Make a note of the address of the subnet you created because you will use it below.
Step 5: Join the subnet
Before we deploy the infrastructure for the subnet, we will have to bootstrap the subnet and join from our validators, putting some initial collateral into the subnet and giving our validator address some initial balance in the subnet. For this, we need to send a join command from each of our validators from their validator owner addresses.
ipc-cli subnet join --from=<PLEASE PUT ADDRESS 1> --subnet=<PLEASE PUT SUBNET ID> --collateral=10 --initial-balance 1
ipc-cli subnet join --from=<PLEASE PUT ADDRESS 2> --subnet=<PLEASE PUT SUBNET ID> --collateral=10 --initial-balance 1
ipc-cli subnet join --from=<PLEASE PUT ADDRESS 3> --subnet=<PLEASE PUT SUBNET ID> --collateral=10 --initial-balance 1
ipc-cli subnet join --from=<PLEASE PUT ADDRESS 3> --subnet=<PLEASE PUT SUBNET ID> --collateral=10 --initial-balance 1
Step 6: Deploy the infrastructure
First, we need to export the validator private keys for all wallets into separate files which we will use to set up a validator node.
You'll need the final component of the IPLD Resolver Multiaddress (the peer ID) and the CometBFT node ID for the next nodes to start.
BOOTSTRAPS: <CometBFT node ID for validator1>@validator-1-cometbft:26656
// An example
ca644ac3194d39a2834f5d98e141d682772c149b@validator-1-cometbft:26656
RESOLVER_BOOTSTRAPS: /dns/validator-1-fendermint/tcp/26655/p2p/<Peer ID in IPLD Resolver Multiaddress>
// An example
/dns/validator-1-fendermint/tcp/26655/p2p/16Uiu2HAkwhrWn9hYFQMR2QmW5Ky7HJKSGVkT8xKnQr1oUGCkqWms
Now, run the 2nd validator in a separate terminal.
cargo make --makefile infra/fendermint/Makefile.toml \
-e NODE_NAME=validator-2 \
-e PRIVATE_KEY_PATH=<PLEASE PUT FULL PATH TO validator_2.sk> \
-e SUBNET_ID=<PLEASE PUT SUBNET ID> \
-e CMT_P2P_HOST_PORT=26756 \
-e CMT_RPC_HOST_PORT=26757 \
-e ETHAPI_HOST_PORT=8645 \
-e RESOLVER_HOST_PORT=26755 \
-e BOOTSTRAPS=<PLEASE PUT COMETBFT NODE ID of VALIDATOR-1>@validator-1-cometbft:26656 \
-e RESOLVER_BOOTSTRAPS=/dns/validator-1-fendermint/tcp/26655/p2p/<PLEASE PUT PEER_ID of VALIDATOR-1> \
-e PARENT_GATEWAY=`curl -s https://raw.githubusercontent.com/consensus-shipyard/ipc/cd/contracts/deployments/r314159.json | jq -r '.gateway_addr'` \
-e PARENT_REGISTRY=`curl -s https://raw.githubusercontent.com/consensus-shipyard/ipc/cd/contracts/deployments/r314159.json | jq -r '.registry_addr'` \
child-validator
Now, the 3rd:
cargo make --makefile infra/fendermint/Makefile.toml \
-e NODE_NAME=validator-3 \
-e PRIVATE_KEY_PATH=<PLEASE PUT FULL PATH TO validator_3.sk> \
-e SUBNET_ID=<PLEASE PUT SUBNET ID> \
-e CMT_P2P_HOST_PORT=26856 \
-e CMT_RPC_HOST_PORT=26857 \
-e ETHAPI_HOST_PORT=8745 \
-e RESOLVER_HOST_PORT=26855 \
-e BOOTSTRAPS=<PLEASE PUT COMETBFT NODE ID of VALIDATOR-1>@validator-1-cometbft:26656 \
-e RESOLVER_BOOTSTRAPS=/dns/validator-1-fendermint/tcp/26655/p2p/<PLEASE PUT PEER_ID of VALIDATOR-1> \
-e PARENT_GATEWAY=`curl -s https://raw.githubusercontent.com/consensus-shipyard/ipc/cd/contracts/deployments/r314159.json | jq -r '.gateway_addr'` \
-e PARENT_REGISTRY=`curl -s https://raw.githubusercontent.com/consensus-shipyard/ipc/cd/contracts/deployments/r314159.json | jq -r '.registry_addr'` \
child-validator
And finally, the 4th:
cargo make --makefile infra/fendermint/Makefile.toml \
-e NODE_NAME=validator-4 \
-e PRIVATE_KEY_PATH=<PLEASE PUT FULL PATH TO validator_4.sk> \
-e SUBNET_ID=<PLEASE PUT SUBNET ID> \
-e CMT_P2P_HOST_PORT=26956 \
-e CMT_RPC_HOST_PORT=26957 \
-e ETHAPI_HOST_PORT=8845 \
-e RESOLVER_HOST_PORT=26955 \
-e BOOTSTRAPS=<PLEASE PUT COMETBFT NODE ID of VALIDATOR-1>@validator-1-cometbft:26656 \
-e RESOLVER_BOOTSTRAPS=/dns/validator-1-fendermint/tcp/26655/p2p/<PLEASE PUT PEER_ID of VALIDATOR-1> \
-e PARENT_GATEWAY=`curl -s https://raw.githubusercontent.com/consensus-shipyard/ipc/cd/contracts/deployments/r314159.json | jq -r '.gateway_addr'` \
-e PARENT_REGISTRY=`curl -s https://raw.githubusercontent.com/consensus-shipyard/ipc/cd/contracts/deployments/r314159.json | jq -r '.registry_addr'` \
child-validator
NOTE:
Use full path to PRIVATE_KEY_PATH, don't path with "~"
Do not change values of any port from the ones provided unless you have to
If you are deploying all validators on a single server, ports will need to be different, as shown in above examples. If you are deploying them from different servers, the ports can be similar.
Step 7: Interact with your subnet using the IPC CLI
Make sure ~/.ipc/config.toml contains the configuration of your subnet in the "Subnet template" section. Uncomment the section and populate the corresponding fields
# Subnet template - uncomment and adjust before using
[[subnets]]
id = <PUT YOUR SUBNET ID>
[subnets.config]
network_type = "fevm"
provider_http = "http://localhost:8545/"
gateway_addr = "0x77aa40b105843728088c0132e43fc44348881da8"
registry_addr = "0x74539671a1d2f1c8f200826baba665179f53a1b7"
NOTE: The ETH addresses for gateway_addr and registry_addr used when they are deployed in genesis in a child subnet by Fendermint are 0x77aa40b105843728088c0132e43fc44348881da8 and 0x74539671a1d2f1c8f200826baba665179f53a1b7, respectively, so no need to change them.
Fetch the balances of your wallets using the following command. The result should show the initial balance that you have included for your validator address in genesis:
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.
This process is key for the commitment of child subnet checkpoints in the parent, and the execution of bottom-up cross-net messages. Without relayers, cross-net messages will only flow from top levels of the hierarchy to the bottom, but not the other way around.
Run the relayer process passing the 0x address of the submitter account:
Replace the gateway_addr and registry_addr with the following values. Click on the badges below to take you to the source to copy and paste them or go to .
Go to the and get some funds sent to each of your addresses
TIP: If you'd like to import an EVM account into Metamask, you can use export the private key using ipc-cli wallet export --wallet-type evm --address <ADDRESS>. More information is available in the .