From c30668568d47ba9059bddd74408a750b9f3f6ef1 Mon Sep 17 00:00:00 2001 From: Alfonso de la Rocha Date: Thu, 2 Nov 2023 19:35:09 +0100 Subject: [PATCH] IPC-363: adds docs for pre-fund/pre-release --- Cargo.toml | 3 --- dev.md | 6 ------ docs/quickstart-calibration.md | 10 +++++----- docs/usage.md | 33 ++++++++++++++++++++++++++++++++- 4 files changed, 37 insertions(+), 15 deletions(-) delete mode 100644 dev.md diff --git a/Cargo.toml b/Cargo.toml index e982439f..fd568425 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,10 +1,7 @@ [workspace] resolver = "2" members = [ - # "ipc/daemon", "ipc/cli", - # "ipc/testing/e2e", - # "ipc/testing/*", "ipc/provider", "ipc/identity", "ipc/sdk" diff --git a/dev.md b/dev.md deleted file mode 100644 index 2a334f81..00000000 --- a/dev.md +++ /dev/null @@ -1,6 +0,0 @@ -# Dev -This file includes some development related notes. - -### Debug Tips -1. Remember to set your network before sending requests to lotus: `set_current_network(Network::Testnet)`. Or else your address might not be parsed. -2. Return results from lotus are usually base64 encoded to string (based on test results). Might be helpful when converting string to struct. diff --git a/docs/quickstart-calibration.md b/docs/quickstart-calibration.md index 22c39be6..501bc0a7 100644 --- a/docs/quickstart-calibration.md +++ b/docs/quickstart-calibration.md @@ -125,7 +125,7 @@ You'll need to create a set of wallets to spawn and interact of the subnet. Plea ## 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. For this, we need to send a `join` command from each of our validators from their validator owner addresses providing their corresponding public key. +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 providing their corresponding public key. * Get the public key for all of your wallets and note it down. This is the public key that each of your validators will use to sign blocks in the subnet. ```bash @@ -136,9 +136,9 @@ Before we deploy the infrastructure for the subnet, we will have to bootstrap th * Join the subnet with each validator ```bash -./bin/ipc-cli subnet join --from= --subnet=/r314159/ --collateral=10 --public-key= -./bin/ipc-cli subnet join --from= --subnet=/r314159/ --collateral=10 --public-key= -./bin/ipc-cli subnet join --from= --subnet=/r314159/ --collateral=10 --public-key= +./bin/ipc-cli subnet join --from= --subnet=/r314159/ --collateral=10 --public-key= --initial-balance 1 +./bin/ipc-cli subnet join --from= --subnet=/r314159/ --collateral=10 --public-key= --initial-balance 1 +./bin/ipc-cli subnet join --from= --subnet=/r314159/ --collateral=10 --public-key= --initial-balance 1 ``` ## Step 6: Deploy the infrastructure @@ -230,7 +230,7 @@ gateway_addr = "0x77aa40b105843728088c0132e43fc44348881da8" registry_addr = "0x74539671a1d2f1c8f200826baba665179f53a1b7" ``` -With this you should be able to start interacting with your local subnet directly through your `ipc-cli`. You can try to fetch the balances of your wallets through: +With this you should be able to start interacting with your local subnet directly through your `ipc-cli`. You can try to fetch the balances of your wallets through the following command. The result should show the initial balance that you have included for your validators address in genesis: ```bash ./bin/ipc-cli wallet balances -w evm --subnet= ``` diff --git a/docs/usage.md b/docs/usage.md index a9746eff..b55efe1c 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -174,10 +174,22 @@ The epoch were the message is performed can give you a sense of the time the mes >💡 Top-down proofs-of-finality is the underlying process used for IPC to propagate information from the parent to the child. Validators in the child subnet include information in every block in the child subnet about the height of the parent they agree to consider final. When this information is committed on-chain, changes into the validator set of the subnet, and the execution of top-down messages are correspondingly triggered. -* In order to list the top-down messages sent for a subnet from a parent network for a specific epoch, run the following command: +* In order to list the top-down messages sent for a subnet from a parent network for a specific epoch, run the following command: ```bash ./bin/ipc-cli cross-msg list-topdown-msgs --subnet= --epoch= + +``` + +#### Funding subnet address in genesis +In order 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 bootsrapped and started. The inverse of this operation is `pre-release`, which allows you to recover some of these initial funds before the subnet starts: +```bash +./bin/ipc-cli cross-msg pre-fund --subnet [--from ] +``` +```console +# Example execution +$ ./bin/ipc-cli cross-msg pre-fund --subnet=/r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq 0.1 ``` + ### Release In order to release funds from a subnet, your account must hold enough funds inside it. Releasing funds to the parent subnet can be permformed with the following commnd: ```bash @@ -198,6 +210,16 @@ release performed in epoch 1030 ``` As with top-down 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. +#### Releasing initial subnet balance +To recover some (or all) of the funds that were sent to a subnet through `pre-fund` to be included as genesis balance for your address, you can use the `pre-release` command as follows: +```bash +./bin/ipc-cli cross-msg pre-release --subnet [--from ] +``` +```console +# Example execution +$ ./bin/ipc-cli cross-msg pre-release --subnet=/r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq 0.1 +``` + ## Listing checkpoints from a subnet Subnets are periodically committing checkpoints to their parent every `bottomup-check-period` (parameter defined when creating the subnet). If you want to inspect the information of a range of bottom-up checkpoints committed in the parent for a subnet, you can use the `checkpoint list-bottomup` command provided by the agent as follows: @@ -226,6 +248,15 @@ $ ./bin/ipc-cli subnet join --subnet=/r314159/t410fh4ywg4wvxcjzz4vsja3uh4f53johc ``` 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 genesis: +```bash +./bin/ipc-cli subnet join --subnet --collateral --public-key --initial-balance +``` +```console +# Example execution +$ ./bin/ipc-cli subnet join --subnet=/r314159/t410fh4ywg4wvxcjzz4vsja3uh4f53johc2lf5bpjo6i --collateral=1 \ + --public-key=043385c3b9ab8a697cd7bec6ca623cbdd0fea1293e8b464df825b104eb58a44cc8efacc6a3482b866b85ecdf734b5d4ef5495737deb348625ce6a35536142d2955 --initial-balance 0.5 +``` * To leave a subnet, the following agent command can be used: ```bash