IPC-364: relayer docs and parent finality command

docs/quickstart-calibration.md

@@ -86,7 +86,7 @@ registry_addr = "0x2fdf1b18907341b751B32aF7088D32f6f5a617E0"
 
 ## Step 3: Set up your wallets
 
-You'll need to create a set of wallets to spawn and interact of the subnet. Please make a note of the addresses as you go along. It may make your life easier.
+You'll need to create a set of wallets to spawn and interact of the subnet. Please make a note of the addresses as you go along, it may make your life easier.
 
 * Create the three different wallets
 ```bash
@@ -116,7 +116,7 @@ You'll need to create a set of wallets to spawn and interact of the subnet. Plea
 
 ## Step 4: Create a child subnet
 
-* The next step is to create a subnet under `/r314159` in calibration. Remember to set a default wallet or explicitly specify the wallet from which you want to perform the action with the `--from` flag.
+* The next step is to create a subnet under `/r314159` in calibration. Remember to set a default wallet or explicitly specifying the wallet from which you want to perform the action with the `--from` flag.
 ```bash
 ./bin/ipc-cli subnet create --parent /r314159 --min-validators 3 --min-validator-stake 1 --bottomup-check-period 30
 ```
@@ -145,7 +145,7 @@ Before we deploy the infrastructure for the subnet, we will have to bootstrap th
 With the collateral and number of minimum validators fulfilled, the subnet is bootstrapped in the parent, and we can deploy the infrastructure.
 
 ### Deploying a bootstrap node
-Before running our validators, at least one bootstrap needs to be deployed and advertised in the network. Bootstrap nodes allow validators to discover other peers and validators in the network. In the current implementation of IPC, only validators are allowed to advertise bootstrap nodes.
+Before running our validators, at least one bootstrap needs to be deployed and advertised in the network. Bootstrap nodes allow validators discover other peers and validators in the network. In the current implementation of IPC, only validators are allowed to advertise bootstrap nodes.
 
 * We can deploy a new bootstrap node in the subnet by running: 
 ```bash
@@ -172,7 +172,7 @@ cargo make --makefile bin/ipc-infra/Makefile.toml bootstrap-id
 cargo make --makefile bin/ipc-infra/Makefile.toml bootstrap-down
 ```
 
-* To advertise the endpoint to the rest of the nodes in the network we need to run:
+* To advertise the endpoint to the rest of nodes in the network we need to run:
 ```bash
 # Example of BOOTSTRAP_ENDPOINT = [email protected]:26650
 ./bin/ipc-cli subnet add-bootstrap --subnet=<SUBNET_ID> --endpoint="<BOOTSRAP_ENDPOINT>"
@@ -241,7 +241,24 @@ With this you should be able to start interacting with your local subnet directl
 
 For information about how to connect your Ethereum tooling with your subnet refer to the [following docs](./contracts.md).
 
-## Step 9: What now?
+## Step 9 (optional): 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. 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.
+
+* *session* Run the relayer process for your subnet using your default address by calling:
+```bash
+./bin/ipc-cli checkpoint relayer --subnet <SUBNET_ID>
+```
+* In order to run the relayer from a different address you can use the `--submitted` flag: 
+```bash
+./bin/ipc-cli checkpoint relayer --subnet <SUBNET_ID> --submitter <RELAYER_ADDR>
+```
+
+Relayers are rewarded through cross-net messages fees for the timely submission of bottom-up checkpoints to the parent. In order to claim the checkpointing rewards collected for a subnet, the following command need to be run from the relayer address:
+```bash
+./bin/ipc-cli subnet claim --subnet=<SUBNET_ID> --reward
+```
+
+## Step 10: What now?
 * Proceed to the [usage](usage.md) guide to learn how you can test your new subnet.
 * If something went wrong, please have a look at the [README](https://github.com/consensus-shipyard/ipc). If it doesn't help, please join us in #ipc-help. In either case, let us know your experience!
 * Please note that to repeat this guide or spawn a new subnet, you may need to change the parameters or reset your system.

docs/usage.md

@@ -169,8 +169,15 @@ fund performed in epoch 1030279
 ```
 
 The epoch were 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.
+```bash
+./bin/ipc-cli cross-msg parent-finality --subnet <SUBNET_ID>
+```
 
-> TODO: Add a cli command to check the finality committed in a child.
+```console
+# Example execution
+$ ./bin/ipc-cli cross-msg parent-finality --subnet /r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq
+1030
+```
 
 >💡 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.
 
@@ -210,6 +217,19 @@ 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.
 
+The propagation of a bottom-up checkpoint from a child subnet to its parent follows these stages:
+* Validators in the child subnet populate the checkpoint, sign it, and agree on their validity. When validators have agreed on the validity of a checkpoint for a specific epoch, a new `QuorumReached` event is emitted in the child subnet. You can check if a checkpoint for certain epoch has already been signed by a majority of child validators through the following command: `./bin/ipc-cli checkpoint quorum-reached-events --from-epoch 600 --to-epoch 680 --subnet`.
+```shell
+# Sample execution
+./bin/ipc-cli checkpoint quorum-reached-events --from-epoch 600 --to-epoch 680 --subnet /r314159/t410ffumhfeppdjixhkxtgagowxkdu77j7xz5aaa52vy
+```
+
+* Once validators have agree on the checkpoint to be submitted in the parent for a specific epoch, relayers need to pick up the checkpoint and submit it in the parent. The following commands can be used to determine what is the state of this submission:
+  * Check if the address of a relayer has already submitted a checkpoint for execution in the parent for the latest checkpoint: `./bin/ipc-cli checkpoint has-submitted-bottomup-height --subnet <SUBNET_ID> --submitter <RELAYER_ADDR>`
+  * Check the height of the latest checkpoint committed in the parent: `./bin/ipc-cli checkpoint last-bottomup-checkpoint-height --subnet <SUBNET_ID>`
+
+Finally, the bundle of checkpoints and signatures populated and already signed by a child subnet for their submission to the parent on a window of heights can be checked through the command `./bin/ipc-cli checkpoint list-bottomup-bundle --subnet <SUBNET> --from-epoch <FROM_EPOCH> --to-epoch <TO_EPOCH>`
+
 #### 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
@@ -220,6 +240,23 @@ To recover some (or all) of the funds that were sent to a subnet through `pre-fu
 $ ./bin/ipc-cli cross-msg pre-release --subnet=/r31415926/t4xwzbdu7z5sam6hc57xxwkctciuaz7oe5omipwbq 0.1
 ```
 
+## Running 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. 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.
+
+* *session* Run the relayer process for your subnet using your default address by calling:
+```bash
+./bin/ipc-cli checkpoint relayer --subnet <SUBNET_ID>
+```
+* In order to run the relayer from a different address you can use the `--submitted` flag: 
+```bash
+./bin/ipc-cli checkpoint relayer --subnet <SUBNET_ID> --submitter <RELAYER_ADDR>
+```
+
+Relayers are rewarded through cross-net messages fees for the timely submission of bottom-up checkpoints to the parent. In order to claim the checkpointing rewards collected for a subnet, the following command need to be run from the relayer address:
+```bash
+./bin/ipc-cli subnet claim --subnet=<SUBNET_ID> --reward
+```
+
 ## 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: 

ipc/cli/src/commands/checkpoint/mod.rs

@@ -48,10 +48,10 @@ impl CheckpointCommandsArgs {
             Commands::QuorumReachedEvents(args) => {
                 GetQuorumReacehdEvents::handle(global, args).await
             }
-            Commands::LastBottomUpCheckpointHeight(args) => {
+            Commands::LastBottomupCheckpointHeight(args) => {
                 LastBottomUpCheckpointHeight::handle(global, args).await
             }
-            Commands::HasSubmittedBottomUpHeight(args) => {
+            Commands::HasSubmittedBottomupHeight(args) => {
                 SubmittedInBottomUpHeight::handle(global, args).await
             }
         }
@@ -65,6 +65,6 @@ pub(crate) enum Commands {
     ListValidatorChanges(ListValidatorChangesArgs),
     ListBottomupBundle(GetBottomUpBundlesArgs),
     QuorumReachedEvents(GetQuorumReachedEventsArgs),
-    LastBottomUpCheckpointHeight(LastBottomUpCheckpointHeightArgs),
-    HasSubmittedBottomUpHeight(SubmittedInBottomUpHeightArgs),
+    LastBottomupCheckpointHeight(LastBottomUpCheckpointHeightArgs),
+    HasSubmittedBottomupHeight(SubmittedInBottomUpHeightArgs),
 }

ipc/cli/src/commands/crossmsg/mod.rs

@@ -2,7 +2,9 @@
 // SPDX-License-Identifier: MIT
 use self::fund::{PreFund, PreFundArgs};
 use self::release::{PreRelease, PreReleaseArgs};
-use self::topdown_cross::{ListTopdownMsgs, ListTopdownMsgsArgs};
+use self::topdown_cross::{
+    LatestParentFinality, LatestParentFinalityArgs, ListTopdownMsgs, ListTopdownMsgsArgs,
+};
 use crate::commands::crossmsg::fund::Fund;
 use crate::commands::crossmsg::propagate::Propagate;
 use crate::commands::crossmsg::release::Release;
@@ -35,6 +37,7 @@ impl CrossMsgsCommandsArgs {
             Commands::PreRelease(args) => PreRelease::handle(global, args).await,
             Commands::Propagate(args) => Propagate::handle(global, args).await,
             Commands::ListTopdownMsgs(args) => ListTopdownMsgs::handle(global, args).await,
+            Commands::ParentFinality(args) => LatestParentFinality::handle(global, args).await,
         }
     }
 }
@@ -47,4 +50,5 @@ pub(crate) enum Commands {
     PreRelease(PreReleaseArgs),
     Propagate(PropagateArgs),
     ListTopdownMsgs(ListTopdownMsgsArgs),
+    ParentFinality(LatestParentFinalityArgs),
 }

ipc/cli/src/commands/crossmsg/topdown_cross.rs

@@ -65,3 +65,27 @@ pub(crate) struct ListTopdownMsgsArgs {
     #[arg(long, short, help = "The block hash to query until")]
     pub block_hash: Option<String>,
 }
+
+pub(crate) struct LatestParentFinality;
+
+#[async_trait]
+impl CommandLineHandler for LatestParentFinality {
+    type Arguments = LatestParentFinalityArgs;
+
+    async fn handle(global: &GlobalArguments, arguments: &Self::Arguments) -> anyhow::Result<()> {
+        log::debug!("latest parent finality: {:?}", arguments);
+
+        let provider = get_ipc_provider(global)?;
+        let subnet = SubnetID::from_str(&arguments.subnet)?;
+
+        println!("{}", provider.latest_parent_finality(&subnet).await?);
+        Ok(())
+    }
+}
+
+#[derive(Debug, Args)]
+#[command(about = "Latest height of parent finality committed in child subnet")]
+pub(crate) struct LatestParentFinalityArgs {
+    #[arg(long, short, help = "The subnet id to check parent finality")]
+    pub subnet: String,
+}

ipc/provider/src/lib.rs

@@ -766,6 +766,16 @@ impl IpcProvider {
 
         conn.manager().list_bootstrap_nodes(subnet).await
     }
+
+    /// Returns the latest finality from the parent committed in a child subnet.
+    pub async fn latest_parent_finality(&self, subnet: &SubnetID) -> anyhow::Result<ChainEpoch> {
+        let conn = match self.connection(subnet) {
+            None => return Err(anyhow!("target subnet not found")),
+            Some(conn) => conn,
+        };
+
+        conn.manager().latest_parent_finality().await
+    }
 }
 
 /// Lotus JSON keytype format

ipc/provider/src/manager/evm/manager.rs

@@ -20,7 +20,7 @@ use crate::config::subnet::SubnetConfig;
 use crate::config::Subnet;
 use crate::lotus::message::ipc::SubnetInfo;
 use crate::manager::subnet::{
-    BottomUpCheckpointRelayer, GetBlockHashResult, SubnetGenesisInfo, TopDownCheckpointQuery,
+    BottomUpCheckpointRelayer, GetBlockHashResult, SubnetGenesisInfo, TopDownFinalityQuery,
     TopDownQueryPayload,
 };
 use crate::manager::{EthManager, SubnetManager};
@@ -76,7 +76,7 @@ struct IPCContractInfo {
 }
 
 #[async_trait]
-impl TopDownCheckpointQuery for EthSubnetManager {
+impl TopDownFinalityQuery for EthSubnetManager {
     async fn genesis_epoch(&self, subnet_id: &SubnetID) -> Result<ChainEpoch> {
         let address = contract_address_from_subnet(subnet_id)?;
         log::info!("querying genesis epoch in evm subnet contract: {address:}");
@@ -200,6 +200,17 @@ impl TopDownCheckpointQuery for EthSubnetManager {
             block_hash,
         })
     }
+
+    async fn latest_parent_finality(&self) -> Result<ChainEpoch> {
+        log::info!("querying latest parent finality ");
+
+        let contract = gateway_getter_facet::GatewayGetterFacet::new(
+            self.ipc_contract_info.gateway_addr,
+            Arc::new(self.ipc_contract_info.provider.clone()),
+        );
+        let finality = contract.get_latest_parent_finality().call().await?;
+        Ok(finality.height.as_u64() as ChainEpoch)
+    }
 }
 
 #[async_trait]

ipc/provider/src/manager/mod.rs

@@ -4,7 +4,7 @@ pub use crate::lotus::message::ipc::SubnetInfo;
 pub use evm::{EthManager, EthSubnetManager};
 pub use subnet::{
     BottomUpCheckpointRelayer, GetBlockHashResult, SubnetGenesisInfo, SubnetManager,
-    TopDownCheckpointQuery, TopDownQueryPayload,
+    TopDownFinalityQuery, TopDownQueryPayload,
 };
 
 pub mod evm;

ipc/provider/src/manager/subnet.rs

@@ -18,7 +18,7 @@ use crate::lotus::message::ipc::SubnetInfo;
 
 /// Trait to interact with a subnet and handle its lifecycle.
 #[async_trait]
-pub trait SubnetManager: Send + Sync + TopDownCheckpointQuery + BottomUpCheckpointRelayer {
+pub trait SubnetManager: Send + Sync + TopDownFinalityQuery + BottomUpCheckpointRelayer {
     /// Deploys a new subnet actor on the `parent` subnet and with the
     /// configuration passed in `ConstructParams`.
     /// The result of the function is the ID address for the subnet actor from which the final
@@ -169,7 +169,7 @@ pub struct GetBlockHashResult {
 
 /// Trait to interact with a subnet to query the necessary information for top down checkpoint.
 #[async_trait]
-pub trait TopDownCheckpointQuery: Send + Sync {
+pub trait TopDownFinalityQuery: Send + Sync {
     /// Returns the genesis epoch that the subnet is created in parent network
     async fn genesis_epoch(&self, subnet_id: &SubnetID) -> Result<ChainEpoch>;
     /// Returns the chain head height
@@ -189,6 +189,8 @@ pub trait TopDownCheckpointQuery: Send + Sync {
         subnet_id: &SubnetID,
         epoch: ChainEpoch,
     ) -> Result<TopDownQueryPayload<Vec<StakingChangeRequest>>>;
+    /// Returns the latest parent finality committed in a child subnet
+    async fn latest_parent_finality(&self) -> Result<ChainEpoch>;
 }
 
 /// The bottom up checkpoint manager that handles the bottom up relaying from child subnet to the parent