Topdown finality proposal and execution

docs/running.md

@@ -26,14 +26,19 @@ In the following sections we will create a Genesis file for a network named `tes
 mkdir test-network
 ```
 
+If you are running in test network, define the network using env variable.
+```shell
+export FM_NETWORK=test
+```
+
 ### Create a new Genesis file
 
 First, create a new `genesis.json` file devoid of accounts and validators. The `--base-fee` here is completely arbitrary.
 The `--power-scale` value of `0` means we'll grant 1 voting power per 1 FIL; to use more precision, we can set it to `3`
 to use milliFIL for example.
 
 ```shell
-cargo run -p fendermint_app -- \
+cargo run -p fendermint_app --release -- \
   genesis --genesis-file test-network/genesis.json \
   new \
   --chain-name test \
@@ -64,7 +69,7 @@ Next, let's create some cryptographic key pairs we want want to use either for a
 ```shell
 mkdir test-network/keys
 for NAME in alice bob charlie dave; do
-  cargo run -p fendermint_app -- key gen --out-dir test-network/keys --name $NAME;
+  cargo run -p fendermint_app --release -- key gen --out-dir test-network/keys --name $NAME;
 done
 ```
 
@@ -83,7 +88,7 @@ Ak5Juk793ZAg/7Ojj4bzOmIFGpwLhET1vg2ROihUJFkq
 Add one of the keys we created to the Genesis file as a stand-alone account:
 
 ```shell
- cargo run -p fendermint_app -- \
+ cargo run -p fendermint_app --release -- \
         genesis --genesis-file test-network/genesis.json \
         add-account --public-key test-network/keys/alice.pk --balance 10
 ```
@@ -110,7 +115,7 @@ but it has to be one based on a public key, otherwise we would not be able to va
 Let's add an example of the other possible account type, a multi-sig account:
 
 ```shell
-cargo run -p fendermint_app -- \
+cargo run -p fendermint_app --release -- \
         genesis --genesis-file test-network/genesis.json \
         add-multisig --public-key test-network/keys/bob.pk --public-key test-network/keys/charlie.pk --public-key test-network/keys/dave.pk \
           --threshold 2 --vesting-start 0 --vesting-duration 1000000 --balance 30
@@ -142,7 +147,7 @@ $ cat test-network/genesis.json | jq .accounts[1]
 Finally, let's add one validator to the Genesis, with a monopoly on voting power, so we can run a standalone node:
 
 ```shell
-cargo run -p fendermint_app -- \
+cargo run -p fendermint_app --release -- \
       genesis --genesis-file test-network/genesis.json \
       add-validator --public-key test-network/keys/bob.pk --power 1;
 ```
@@ -166,6 +171,32 @@ The public key was spliced in as it was, in base64 format, which is how it would
 own genesis file format. Note that here we don't have the option to use `Address`, because we have to return
 these as actual `PublicKey` types to Tendermint through ABCI, not as a hash of a key.
 
+### (Optional) Add ipc to the Genesis file
+
+If you need ipc related function, let's add the subnet info to the Genesis with deployed subnet id: /r31415926
+
+```shell
+cargo run -p fendermint_app --release -- \
+      genesis --genesis-file test-network/genesis.json \
+      ipc \
+      gateway --subnet-id /r31415926 \
+      --bottom-up-check-period 10 --top-down-check-period 10 \
+      --msg-fee 1 --majority-percentage 65 --min-collateral 1
+```
+Check the result:
+```console
+$ cat test-network/genesis.json | jq .ipc
+{
+  "gateway": {
+    "subnet_id": "/r31415926",
+    "bottom_up_check_period": 10,
+    "top_down_check_period": 10,
+    "msg_fee": "1",
+    "majority_percentage": 65
+  }
+}
+```
+
 ### Configure CometBFT
 
 First, follow the instructions in [getting started with CometBFT](./tendermint.md) to install the binary,
@@ -191,7 +222,7 @@ file we created earlier to the format CometBFT accepts. Start with the genesis f
 
 ```shell
 mv ~/.cometbft/config/genesis.json ~/.cometbft/config/genesis.json.orig
-cargo run -p fendermint_app -- \
+cargo run -p fendermint_app --release -- \
   genesis --genesis-file test-network/genesis.json \
   into-tendermint --out ~/.cometbft/config/genesis.json
 ```
@@ -281,7 +312,7 @@ one of the validators we created.
 
 ```shell
 mv ~/.cometbft/config/priv_validator_key.json ~/.cometbft/config/priv_validator_key.json.orig
-cargo run -p fendermint_app -- \
+cargo run -p fendermint_app --release -- \
   key into-tendermint --secret-key test-network/keys/bob.sk --out ~/.cometbft/config/priv_validator_key.json
 ```
 

fendermint/app/Cargo.toml

@@ -48,15 +48,16 @@ fendermint_vm_genesis = { path = "../vm/genesis" }
 fendermint_vm_interpreter = { path = "../vm/interpreter", features = ["bundle"] }
 fendermint_vm_message = { path = "../vm/message" }
 fendermint_vm_resolver = { path = "../vm/resolver" }
+fendermint_vm_topdown = { path = "../vm/topdown" }
 
 fvm = { workspace = true }
 fvm_ipld_blockstore = { workspace = true }
 fvm_ipld_car = { workspace = true }
 fvm_ipld_encoding = { workspace = true }
 fvm_shared = { workspace = true }
 ipc-sdk = { workspace = true }
-ipc_ipld_resolver = { workspace = true }
 ipc-provider = { workspace = true }
+ipc_ipld_resolver = { workspace = true }
 
 [dev-dependencies]
 tempfile = { workspace = true }

fendermint/app/config/default.toml

@@ -168,3 +168,7 @@ event_buffer_capacity = 100
 rate_limit_bytes = 0
 # Length of the time period at which the consumption limit fills. 0 means no limit.
 rate_limit_period = 0
+
+# IPC related configuration parameters
+[ipc]
+subnet_id = "/r0"

fendermint/app/settings/Cargo.toml

@@ -21,5 +21,7 @@ tendermint-rpc = { workspace = true }
 fvm_shared = { workspace = true }
 fvm_ipld_encoding = { workspace = true }
 ipc-sdk = { workspace = true }
+ipc-provider = { workspace = true }
 
 fendermint_vm_encoding = { path = "../../vm/encoding" }
+fendermint_vm_topdown = { path = "../../vm/topdown" }

fendermint/app/settings/src/lib.rs

@@ -1,19 +1,24 @@
 // Copyright 2022-2023 Protocol Labs
 // SPDX-License-Identifier: Apache-2.0, MIT
 
-use anyhow::Context;
+use anyhow::{anyhow, Context};
 use config::{Config, ConfigError, Environment, File};
+use fvm_shared::address::Address;
 use fvm_shared::econ::TokenAmount;
 use ipc_sdk::subnet_id::SubnetID;
 use serde::Deserialize;
+use serde_with::{serde_as, DurationSeconds};
 use std::path::{Path, PathBuf};
+use std::time::Duration;
 use tendermint_rpc::Url;
 
 use fendermint_vm_encoding::{human_readable_delegate, human_readable_str};
+use fendermint_vm_topdown::BlockHeight;
 
 use self::eth::EthSettings;
 use self::fvm::FvmSettings;
 use self::resolver::ResolverSettings;
+use ipc_provider::config::deserialize::deserialize_eth_address_from_str;
 
 pub mod eth;
 pub mod fvm;
@@ -93,6 +98,54 @@ pub struct BroadcastSettings {
     pub max_retries: u8,
 }
 
+#[serde_as]
+#[derive(Debug, Deserialize, Clone)]
+pub struct TopDownConfig {
+    /// The number of blocks to delay before reporting a height as final on the parent chain.
+    /// To propose a certain number of epochs delayed from the latest height, we see to be
+    /// conservative and avoid other from rejecting the proposal because they don't see the
+    /// height as final yet.
+    pub chain_head_delay: BlockHeight,
+    /// Parent syncing cron period, in seconds
+    #[serde_as(as = "DurationSeconds<u64>")]
+    pub polling_interval_secs: Duration,
+    /// Top down exponential back off retry base
+    #[serde_as(as = "DurationSeconds<u64>")]
+    pub exponential_back_off_secs: Duration,
+    /// The max number of retries for exponential backoff before giving up
+    pub exponential_retry_limit: usize,
+    /// The parent rpc http endpoint
+    pub parent_http_endpoint: Url,
+    /// The parent registry address
+    #[serde(deserialize_with = "deserialize_eth_address_from_str")]
+    pub parent_registry: Address,
+    /// The parent gateway address
+    #[serde(deserialize_with = "deserialize_eth_address_from_str")]
+    pub parent_gateway: Address,
+}
+
+#[serde_as]
+#[derive(Debug, Deserialize, Clone)]
+pub struct IpcSettings {
+    #[serde_as(as = "IsHumanReadable")]
+    pub subnet_id: SubnetID,
+    /// The config for top down checkpoint. It's None if subnet id is root or not activating
+    /// any top down checkpoint related operations
+    pub topdown: Option<TopDownConfig>,
+}
+
+impl IpcSettings {
+    pub fn is_topdown_enabled(&self) -> bool {
+        !self.subnet_id.is_root() && self.topdown.is_some()
+    }
+
+    pub fn topdown_config(&self) -> anyhow::Result<&TopDownConfig> {
+        self.topdown
+            .as_ref()
+            .ok_or_else(|| anyhow!("top down config missing"))
+    }
+}
+
 #[derive(Debug, Deserialize, Clone)]
 pub struct Settings {
     /// Home directory configured on the CLI, to which all paths in settings can be set relative.
@@ -115,6 +168,7 @@ pub struct Settings {
     pub fvm: FvmSettings,
     pub resolver: ResolverSettings,
     pub broadcast: BroadcastSettings,
+    pub ipc: IpcSettings,
 }
 
 #[macro_export]

fendermint/app/src/app.rs

@@ -17,7 +17,9 @@ use fendermint_vm_genesis::{Power, Validator};
 use fendermint_vm_interpreter::bytes::{
     BytesMessageApplyRes, BytesMessageCheckRes, BytesMessageQuery, BytesMessageQueryRes,
 };
-use fendermint_vm_interpreter::chain::{ChainMessageApplyRet, CheckpointPool, IllegalMessage};
+use fendermint_vm_interpreter::chain::{
+    ChainMessageApplyRet, CheckpointPool, IllegalMessage, TopDownFinalityProvider,
+};
 use fendermint_vm_interpreter::fvm::state::{
     empty_state_tree, CheckStateRef, FvmExecState, FvmGenesisState, FvmQueryState, FvmStateParams,
 };
@@ -31,6 +33,7 @@ use fendermint_vm_message::query::FvmQueryHeight;
 use fvm::engine::MultiEngine;
 use fvm_ipld_blockstore::Blockstore;
 use fvm_shared::chainid::ChainID;
+use fvm_shared::clock::ChainEpoch;
 use fvm_shared::econ::TokenAmount;
 use fvm_shared::version::NetworkVersion;
 use num_traits::Zero;
@@ -157,6 +160,8 @@ where
     interpreter: Arc<I>,
     /// CID resolution pool.
     resolve_pool: CheckpointPool,
+    /// The parent finality provider for top down checkpoint
+    parent_finality_provider: TopDownFinalityProvider,
     /// State accumulating changes during block execution.
     exec_state: Arc<Mutex<Option<FvmExecState<SS>>>>,
     /// Projected (partial) state accumulating during transaction checks.
@@ -183,6 +188,7 @@ where
         state_store: SS,
         interpreter: I,
         resolve_pool: CheckpointPool,
+        parent_finality_provider: TopDownFinalityProvider,
     ) -> Result<Self> {
         let app = Self {
             db: Arc::new(db),
@@ -194,6 +200,7 @@ where
             state_hist_size: config.state_hist_size,
             interpreter: Arc::new(interpreter),
             resolve_pool,
+            parent_finality_provider,
             exec_state: Arc::new(Mutex::new(None)),
             check_state: Arc::new(tokio::sync::Mutex::new(None)),
         };
@@ -298,15 +305,55 @@ where
     /// Take the execution state, update it, put it back, return the output.
     async fn modify_exec_state<T, F, R>(&self, f: F) -> Result<T>
     where
-        F: FnOnce((CheckpointPool, FvmExecState<SS>)) -> R,
-        R: Future<Output = Result<((CheckpointPool, FvmExecState<SS>), T)>>,
+        F: FnOnce((CheckpointPool, TopDownFinalityProvider, FvmExecState<SS>)) -> R,
+        R: Future<
+            Output = Result<(
+                (CheckpointPool, TopDownFinalityProvider, FvmExecState<SS>),
+                T,
+            )>,
+        >,
     {
         let state = self.take_exec_state();
-        let ((_pool, state), ret) = f((self.resolve_pool.clone(), state)).await?;
+        let ((_pool, _provider, state), ret) = f((
+            self.resolve_pool.clone(),
+            self.parent_finality_provider.clone(),
+            state,
+        ))
+        .await?;
         self.put_exec_state(state);
         Ok(ret)
     }
 
+    /// Get a read only fvm execution state. This is useful to perform query commands targeting
+    /// the latest state.
+    pub fn new_read_only_exec_state(
+        &self,
+    ) -> Result<Option<FvmExecState<ReadOnlyBlockstore<Arc<SS>>>>> {
+        let maybe_app_state = self.get_committed_state()?;
+
+        Ok(if let Some(app_state) = maybe_app_state {
+            let block_height = app_state.block_height;
+            let state_params = app_state.state_params;
+
+            // wait for block production
+            if block_height == 0 {
+                return Ok(None);
+            }
+
+            let exec_state = FvmExecState::new(
+                ReadOnlyBlockstore::new(self.state_store.clone()),
+                self.multi_engine.as_ref(),
+                block_height as ChainEpoch,
+                state_params,
+            )
+            .context("error creating execution state")?;
+
+            Some(exec_state)
+        } else {
+            None
+        })
+    }
+
     /// Look up a past state at a particular height Tendermint Core is looking for.
     ///
     /// A height of zero means we are looking for the latest state.
@@ -356,9 +403,9 @@ where
         Genesis = Vec<u8>,
         Output = FvmGenesisOutput,
     >,
-    I: ProposalInterpreter<State = CheckpointPool, Message = Vec<u8>>,
+    I: ProposalInterpreter<State = (CheckpointPool, TopDownFinalityProvider), Message = Vec<u8>>,
     I: ExecInterpreter<
-        State = (CheckpointPool, FvmExecState<SS>),
+        State = (CheckpointPool, TopDownFinalityProvider, FvmExecState<SS>),
         Message = Vec<u8>,
         BeginOutput = FvmApplyRet,
         DeliverOutput = BytesMessageApplyRes,
@@ -554,7 +601,13 @@ where
 
         let txs = self
             .interpreter
-            .prepare(self.resolve_pool.clone(), txs)
+            .prepare(
+                (
+                    self.resolve_pool.clone(),
+                    self.parent_finality_provider.clone(),
+                ),
+                txs,
+            )
             .await
             .context("failed to prepare proposal")?;
 
@@ -573,7 +626,13 @@ where
 
         let accept = self
             .interpreter
-            .process(self.resolve_pool.clone(), txs)
+            .process(
+                (
+                    self.resolve_pool.clone(),
+                    self.parent_finality_provider.clone(),
+                ),
+                txs,
+            )
             .await
             .context("failed to process proposal")?;