docs for cross-net messages (#167)

* docs for cross-net messages

* Update usage.md

* Edits and improvements

* Update usage.md

* Update wallet export step

* Fix subnet join syntax and use friendly names

* Update default port to match the one in docs

* Fix broken command

* Clean up topdown description

* address review and wallet list

* Update docs/usage.md

Co-authored-by: Jorge Soares <547492+jsoares@users.noreply.github.com>

* Minor edit

* Apply suggestions from code review

Co-authored-by: Jorge Soares <547492+jsoares@users.noreply.github.com>

---------

Co-authored-by: Jorge Soares <547492+jsoares@users.noreply.github.com>

docs/quickstart.md

@@ -108,7 +108,7 @@ $ nohup ./ipc-agent/bin/ipc-agent daemon &
 
 * The next step is to create a subnet under `/root`
 ```bash
-$ ./ipc-agent/bin/ipc-agent subnet create -p /root -n andromeda --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10
+$ ./ipc-agent/bin/ipc-agent subnet create --parent /root --name andromeda --min-validator-stake 1 --min-validators 2 --bottomup-check-period 30 --topdown-check-period 30
 ```
 * Make a note of the address of the subnet you created (`/root/<SUBNET_ID>`)
 

docs/subnet.md

@@ -25,7 +25,7 @@ If your daemon is running on a docker container, you can get the container id or
 $ docker exec -it <container-id> eudico wallet export --lotus-json <adress-to-export> > ~/.ipc-agent/wallet.key
 
 # Example execution
-$ docker exec -it 84711d67cf162e30747c4525d69728c4dea8c6b4b35cd89f6d0947fee14bf908 eudico wallet export --lotus-json t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq > ~/.ipc-agent/wallet.key
+$ docker exec -it ipc_root_1234 eudico wallet export --lotus-json t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq > ~/.ipc-agent/wallet.key
 ```
 
 ### Importing wallet keys
@@ -37,15 +37,15 @@ Depending on whether the subnet is running inside a docker container or not, you
 $ ./eudico wallet import --lotus-json <wallet-key-file-path>
 
 # Example execution
-$ ./eudico wallet import --lotus-json ~/.ipc-agent/t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy.key
+$ ./eudico wallet import --lotus-json ~/.ipc-agent/wallet.key
 ```
 
 ```bash
 # Docker: Copy the wallet key into the container and import into eudico
 $ docker cp <wallet-key-path> <container-id>:<target-file-in-container> && docker exec -it <container-id> eudico wallet import --format=json-lotus <target-file-in-container>
 
 # Example execution
-$ docker cp ~/.ipc-agent/t1ivy6mo2ofxw4fdmft22nel66w63fb7cuyslm4cy.key 91d2af805346:/input.key && docker exec -it 91d2af805346 eudico wallet import --format=json-lotus input.key
+$ docker cp ~/.ipc-agent/wallet.key ipc_root_t01002_1250:/input.key && docker exec -it ipc_root_t01002_1250 eudico wallet import --format=json-lotus input.key
 ```
 
 ## Running a simple subnet with a single validator
@@ -57,22 +57,17 @@ This section provides instructions for spawning a simple subnet with a single va
 To run a subnet the first thing is to configure and create the subnet actor that will govern the subnet's operation.
 
 ```bash
-$ ./bin/ipc-agent subnet create -p <parent-id> -n <subnet-name> --min-validator-stake 1 --min-validators <num-validators> --finality-threshold <number-epochs> --check-period <epochs-between-checks>
+$ ./bin/ipc-agent subnet create --parent <parent> --name <name> --min-validator-stake <min_validator_stake> --min-validators <min-validators> --bottomup-check-period <bottomup-check-period> --topdown-check-period <topdown-check-period>
 
 # Example execution
-$ ./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 0 --finality-threshold 10 --check-period 10
+$ ./bin/ipc-agent subnet create --parent /root --name test --min-validator-stake 1 --min-validators 0 --bottomup-check-period 30 --topdown-check-period 30
 [2023-03-21T09:32:58Z INFO  ipc_agent::cli::commands::manager::create] created subnet actor with id: /root/t01002
 ```
-This command deploys a subnet actor for a new subnet from the `root`, with a human-readable name `test`, that requires at least `1` validator to join the subnet to be able to mine new blocks, and with a checkpointing period to the parent of `10` blocks. We can see that the output of this command is the ID of the new subnet.
+This command deploys a subnet actor for a new subnet from the `root`, with a human-readable name `test`, that requires at least `1` validator to join the subnet to be able to mine new blocks, and with a checkpointing period (both bottom-up and top-down) of `30` blocks. We can see that the output of this command is the ID of the new subnet.
 
 ### Exporting your wallet
 
-Let's export the default wallet (or other wallet you'd like to use) for use in the subnet validator.
-```bash
-$ ./eudico wallet export --lotus-json `./eudico wallet default` > ~/.ipc-agent/wallet.key
-```
-
-Make sure that your wallet has enough funds to put up the collateral to join the subnet.
+We will need to export the wallet key from our root node so that we can import them to our validators. Depending on how you are running your rootnet node you'll have to make a call to the docker container, or your nodes API. More information about exporting keys from your node can be found under [this section](#Exporting-wallet-keys). Make sure that the wallet holds enough funds to meet the subnet collateral requirements.
 
 ### Deploying a subnet node
 
@@ -144,7 +139,7 @@ $ ./bin/ipc-agent subnet send-value --subnet /root --to <target-wallet> <amount_
 
 With this, we can already create the subnet with `/root` as its parent. We are going to set the `--min-validators 2` so no new blocks can be created without this number of validators in the subnet.
 ```bash
-./bin/ipc-agent subnet create -p /root -n test --min-validator-stake 1 --min-validators 2 --finality-threshold 10 --check-period 10
+./bin/ipc-agent subnet create --parent /root --name test --min-validator-stake 1 --min-validators 2 --bottomup-check-period 30 --topdown-check-period 30
 ```
 ### Deploying the infrastructure
 

docs/troubleshooting.md

@@ -28,7 +28,7 @@ Not online yet... (could not get API info for FullNode: could not get api endpoi
 ```
 Or because when the script finishes no validator address has been reported as expected by the logs, the best way to debug this situation is to attach to the docker container and check the logs with the following command:
 ```bash
-$ docker exec -it <container_name/id> bash
+$ docker exec -it <container_name> bash
 
 # Inside the container
 tmux a

docs/usage.md

@@ -9,7 +9,7 @@ As a sanity-check that we have joined the subnet successfully and that we provid
 ```bash
 $ ./bin/ipc-agent list-subnets --gateway-address=<gateway-addr> --subnet=<parent-subnet-id>
 
-# Sample execution
+# Example execution
 $ ./bin/ipc-agent list-subnets --gateway-address=t064 --subnet=/root
 [2023-03-30T17:00:25Z INFO  ipc_agent::cli::commands::manager::list_subnets] /root/t01003 - status: 0, collateral: 2 FIL, circ.supply: 0.0 FIL
 ```
@@ -27,6 +27,16 @@ $ ./bin/ipc-agent subnet join --subnet /root/t01002 --collateral 2 --validator-n
 ```
 This command specifies the subnet to join, the amount of collateral to provide and the validator net address used by other validators to dial them.
 
+## Listing your balance in a subnet
+In order to send messages in a subnet, you'll need to have funds in your subnt account. You can use the following command to list the balance of your wallets in a subnet:
+```bash
+$ ./bin/ipc-agent wallet list --subnet=<subnet-id>
+
+# Example execution
+$ ./bin/ipc-agent wallet list --subnet=/root/t01002
+ipc_agent::cli::commands::wallet::list] wallets in subnet /root are {"t1cp4q4lqsdhob23ysywffg2tvbmar5cshia4rweq": "500.0"}
+```
+
 ## Sending funds in a subnet
 
 The agent provides a command to conveniently exchange funds between addresses of the same subnet. This can be achieved through the following command:
@@ -37,28 +47,75 @@ $ ./bin/ipc-agent subnet send-value --subnet <subnet-id> --to <to-addr> <value>
 $ ./bin/ipc-agent subnet send-value --subnet /root/t01002 --to t1xbevqterae2tanmh2kaqksnoacflrv6w2dflq4i 10
 ```
 
-## Leaving a subnet
+## Sending funds between subnets
 
-To leave a subnet, the following agent command can be used:
+At the moment, the IPC agent 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 FIL from one public key address, to the same public key address in the child.
+- `release` that moves FIL from one account in a child subnet to its counter-part in the parent.
+
+Complex behavior can be implemented using these primitives: sending value to a user in another subnet can be implemented a set of `release/fund` and `sendValue` operations. Calling  smart contract from one subnet to another works by providing funds to one account in the destination subnet, and then calling the contract. The agent doesn't currently include abstractions for this complex operations, but it will in the future. That being said, users can still leverage the agent's API to easily compose the basic primitives into complex functionality.
+
+>💡 All cross-net operations need to pay an additional cross-msg fee (apart from the gas cost of the message). This is reason why even if you sent `X FIL` you may see `X - fee FIL` arriving to you account at destination. This fee is used to reward subnet validators for their work committing the checkpoint that carries the message.
+
+### Fund
+Funding a subnet can be performed by using the following command:
 ```bash
-$ ./bin/ipc-agent subnet leave --subnet <subnet-id>
+$ ./bin/ipc-agent cross-msg fund --subnet=<subnet-id> <amount>
 
 # Example execution
-$ ./bin/ipc-agent subnet leave --subnet /root/t01002
+$ ./bin/ipc-agent cross-msg fund --subnet=/root/t01002 100
+
 ```
-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.
+This command includes the cross-net message into the next top-down checkpoint after the current epoch. Once the top-down checkpoint is committed, you should see the funds in your account of the child subnet.
 
+>💡 Top-down checkpoints are not used to anchor the security of the parent into the child (as is the case for bottom-up checkpoints). They just include information of the top-down messages that need to be executed in the child subnet, and are a way for validators in the subnet to reach consensus on the finality on their parent.
+
+### 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 comand:
+```bash
+$ ./bin/ipc-agent cross-msg release --subnet=<subnet-id> <amount>
+
+# Example execution
+$ ./bin/ipc-agent cross-msg release --subnet=/root/t01002 100
+```
+This command includes the cross-net message into a bottom-up checkpoint after the current epoch. Once the bottom-up checkpoint is committed, you should see the funds in your account in the parent. 
 
-### Listing checkpoints from a subnet
 
-Subnets are periodically committing checkpoints to their parent every `check-period` (parameter defined when creating the subnet). If you want to inspect the information of a range of checkpoints committed in the parent for a subnet, you can use the `checkpoint list` command provided by the agent as follows: 
+## 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: 
 ```bash
 # List checkpoints between two epochs for a subnet
-$ ./bin/ipc-agent checkpoint list --from-epoch <range-start> --to-epoch <range-end> --subnet <subnet-id>
+$ ./bin/ipc-agent checkpoint list-bottomup --from-epoch <range-start> --to-epoch <range-end> --subnet <subnet-id>
 
 # Example execution
-$ ./bin/ipc-agent checkpoint list --from-epoch 0 --to-epoch 100 --subnet root/t01002
+$ ./bin/ipc-agent checkpoint list-bottomup --from-epoch 0 --to-epoch 100 --subnet /root/t01002
 [2023-03-29T12:43:42Z INFO  ipc_agent::cli::commands::manager::list_checkpoints] epoch 0 - prev_check={"/":"bafy2bzacedkoa623kvi5gfis2yks7xxjl73vg7xwbojz4tpq63dd5jpfz757i"}, cross_msgs=null, child_checks=null
 [2023-03-29T12:43:42Z INFO  ipc_agent::cli::commands::manager::list_checkpoints] epoch 10 - prev_check={"/":"bafy2bzacecsatvda6lodrorh7y7foxjt3a2dexxx5jiyvtl7gimrrvywb7l5m"}, cross_msgs=null, child_checks=null
 [2023-03-29T12:43:42Z INFO  ipc_agent::cli::commands::manager::list_checkpoints] epoch 30 - prev_check={"/":"bafy2bzaceauzdx22hna4e4cqf55jqmd64a4fx72sxprzj72qhrwuxhdl7zexu"}, cross_msgs=null, child_checks=null
 ```
+You can find the checkpoint where your cross-message was included by listing the checkpoints around the epoch where your message was sent.
+
+## Checking the health of top-down checkpoints
+In order to check the health of top-down checkpointing in a subnet, the following command can be run:
+```bash
+$./bin/ipc-agent checkpoint last-topdown --subnet=<subnet-id>
+
+# Example execution
+$./bin/ipc-agent checkpoint last-topdown --subnet /root/t01002
+[2023-04-18T17:11:34Z INFO  ipc_agent::cli::commands::checkpoint::topdown_executed] Last top-down checkpoint executed in epoch: 9866
+```
+
+This command returns the epoch of the last top-down checkpoint executed in the child. If you see that this epoch is way below the current epoch of the parent subnet, then top-down checkpointing may be lagging, validators need to catch-up, and the forwarding of top-down messages (from parent to child) may take longer to be committed.
+
+
+## Leaving a subnet
+
+To leave a subnet, the following agent command can be used:
+```bash
+$ ./bin/ipc-agent subnet leave --subnet <subnet-id>
+
+# Example execution
+$ ./bin/ipc-agent subnet leave --subnet /root/t01002
+```
+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.

src/cli/commands/checkpoint/mod.rs

@@ -22,14 +22,14 @@ pub(crate) struct CheckpointCommandsArgs {
 impl CheckpointCommandsArgs {
     pub async fn handle(&self, global: &GlobalArguments) -> anyhow::Result<()> {
         match &self.command {
-            Commands::List(args) => ListBottomUpCheckpoints::handle(global, args).await,
+            Commands::ListBottomup(args) => ListBottomUpCheckpoints::handle(global, args).await,
             Commands::LastTopdown(args) => LastTopDownExec::handle(global, args).await,
         }
     }
 }
 
 #[derive(Debug, Subcommand)]
 pub(crate) enum Commands {
-    List(ListBottomUpCheckpointsArgs),
+    ListBottomup(ListBottomUpCheckpointsArgs),
     LastTopdown(LastTopDownExecArgs),
 }

src/cli/commands/subnet/create.rs

@@ -78,8 +78,8 @@ pub struct CreateSubnetArgs {
     pub min_validator_stake: u64,
     #[arg(long, help = "The minimal number of validators")]
     pub min_validators: u64,
-    #[arg(long, help = "The bottom up checkpoint period")]
+    #[arg(long, help = "The bottom up checkpoint period in number of blocks")]
     pub bottomup_check_period: ChainEpoch,
-    #[arg(long, help = "The top down checkpoint period")]
+    #[arg(long, help = "The top down checkpoint period in number of blocks")]
     pub topdown_check_period: ChainEpoch,
 }

src/config/mod.rs

@@ -37,7 +37,7 @@ json_rpc_address = "127.0.0.1:3030"
 id = "/root"
 gateway_addr = "t064"
 network_name = "root"
-jsonrpc_api_http = "http://127.0.0.1:1235/rpc/v1"
+jsonrpc_api_http = "http://127.0.0.1:1234/rpc/v1"
 jsonrpc_api_ws = "wss://example.org/rpc/v0"
 auth_token = "YOUR TOKEN"
 accounts = ["t01"]
@@ -46,7 +46,7 @@ accounts = ["t01"]
 id = "/root/t01"
 gateway_addr = "t064"
 network_name = "child"
-jsonrpc_api_http = "http://127.0.0.1:1235/rpc/v1"
+jsonrpc_api_http = "http://127.0.0.1:1250/rpc/v1"
 auth_token = "YOUR TOKEN"
 accounts = ["t01"]
 "#;