feat: teach the node to settle through safety-gated tasks

- epoch-manager: detect a safety gate behind the EpochSealed task via
  ERC-165 (pinned ISafetyGateTask id), cast a sentry vote when the
  signer is a sentry, start the fallback timer when sentries are missing
  or disagree, and point the PRT player at INNER_TASK.
- state-manager: store the epoch's final machine state alongside the
  computation hash, since canSettle now reports the final state.
- blockchain-reader: follow the EpochSealed field rename.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: GCdePaula

Cargo.lock

@@ -257,7 +257,7 @@ impl<SM: StateManager> BlockchainReader<SM> {
                         .inputIndexUpperBound
                         .to_u64()
                         .expect("fail to convert epoch boundary"),
-                    root_tournament: e.tournament,
+                    root_tournament: e.task,
                     block_created_number: meta.block_number.expect("block number should exist"),
                 };
                 info!(

cartesi-rollups/node/blockchain-reader/src/lib.rs

@@ -95,6 +95,7 @@ pub fn create_epoch_manager_task(watch: Watch, parameters: &PRTConfig) -> thread
                     let epoch_manager = EpochManager::new(
                         Arc::new(Mutex::new(arena_sender)),
                         params.address_book.consensus,
+                        params.signer_address,
                         state_manager,
                         params.sleep_duration,
                         params.long_block_range_error_codes.clone(),

cartesi-rollups/node/cartesi-rollups-prt-node/src/lib.rs

@@ -11,6 +11,7 @@ repository.workspace = true
 
 [dependencies]
 cartesi-dave-contracts = { workspace = true }
+cartesi-prt-contracts = { workspace = true }
 cartesi-prt-core = { workspace = true }
 rollups-state-manager = { workspace = true }
 

cartesi-rollups/node/epoch-manager/Cargo.toml

@@ -4,7 +4,7 @@
 mod error;
 
 use alloy::{
-    primitives::{Address, B256},
+    primitives::{Address, B256, FixedBytes},
     providers::{DynProvider, Provider},
 };
 use error::Result;
@@ -14,37 +14,49 @@ use std::{ops::ControlFlow, sync::Arc, time::Duration};
 use tokio::sync::Mutex;
 
 use cartesi_dave_contracts::dave_consensus::DaveConsensus;
+use cartesi_prt_contracts::safety_gate_task;
 use cartesi_prt_core::{
     db::dispute_state_access::{Input, Leaf},
     strategy::player::Player,
     tournament::{ArenaSender, allow_revert_rethrow_others},
 };
-use rollups_state_manager::{Epoch, Proof, StateManager, sync::Watch};
+use rollups_state_manager::{Epoch, Proof, Settlement, StateManager, sync::Watch};
+
+/// `type(ISafetyGateTask).interfaceId`, pinned by
+/// `testInterfaceIdMatchesNodeConstant` in `prt/contracts`.
+///
+/// Note: Solidity interface ids exclude inherited functions (`result`,
+/// `cleanup`, `supportsInterface`), so this cannot be derived by XORing the
+/// selectors of the full contract ABI.
+const SAFETY_GATE_TASK_INTERFACE_ID: FixedBytes<4> = FixedBytes::new([0xe1, 0x97, 0xd7, 0xb5]);
 
 pub struct EpochManager<AS: ArenaSender, SM: StateManager> {
     arena_sender: Arc<Mutex<AS>>,
     consensus: Address,
+    signer_address: Address,
     sleep_duration: Duration,
     long_block_range_error_codes: Vec<String>,
     state_manager: SM,
-    last_react_epoch: (Option<Player<AS>>, u64),
+    last_react_epoch: (Option<Player<AS>>, u64, Address),
 }
 
 impl<AS: ArenaSender, SM: StateManager> EpochManager<AS, SM> {
     pub fn new(
         arena_sender: Arc<Mutex<AS>>,
         consensus_address: Address,
+        signer_address: Address,
         state_manager: SM,
         sleep_duration: Duration,
         long_block_range_error_codes: Vec<String>,
     ) -> Self {
         Self {
             arena_sender,
             consensus: consensus_address,
+            signer_address,
             sleep_duration,
             long_block_range_error_codes,
             state_manager,
-            last_react_epoch: (None, 0),
+            last_react_epoch: (None, 0, Address::ZERO),
         }
     }
 
@@ -83,9 +95,8 @@ impl<AS: ArenaSender, SM: StateManager> EpochManager<AS, SM> {
             )? {
                 Some(settlement) => {
                     assert_eq!(
-                        settlement.computation_hash.data(),
-                        can_settle.winnerCommitment,
-                        "Winner commitment mismatch, notify all users!"
+                        settlement.final_state, can_settle.finalState,
+                        "Winner state mismatch, notify all users!"
                     );
                     info!(
                         "settle epoch {} with claim {}",
@@ -119,12 +130,20 @@ impl<AS: ArenaSender, SM: StateManager> EpochManager<AS, SM> {
                 .state_manager
                 .settlement_info(last_sealed_epoch.epoch_number)?
             {
-                Some(_) => {
+                Some(settlement) => {
                     trace!(
                         "dispute tournaments for epoch {}",
                         last_sealed_epoch.epoch_number
                     );
-                    self.react_dispute(provider, &last_sealed_epoch).await?
+                    let tournament_address = self
+                        .resolve_tournament_address(
+                            provider.clone(),
+                            last_sealed_epoch.root_tournament,
+                            &settlement,
+                        )
+                        .await?;
+                    self.react_dispute(provider, &last_sealed_epoch, tournament_address)
+                        .await?
                 }
                 None => {
                     debug!(
@@ -141,8 +160,9 @@ impl<AS: ArenaSender, SM: StateManager> EpochManager<AS, SM> {
         &mut self,
         provider: DynProvider,
         last_sealed_epoch: &Epoch,
+        tournament_address: Address,
     ) -> Result<()> {
-        self.get_latest_player(last_sealed_epoch, provider)?;
+        self.get_latest_player(last_sealed_epoch, provider, tournament_address)?;
         self.last_react_epoch
             .0
             .as_mut()
@@ -157,6 +177,7 @@ impl<AS: ArenaSender, SM: StateManager> EpochManager<AS, SM> {
         &mut self,
         last_sealed_epoch: &Epoch,
         provider: DynProvider,
+        tournament_address: Address,
     ) -> Result<()> {
         let snapshot = self
             .state_manager
@@ -167,6 +188,7 @@ impl<AS: ArenaSender, SM: StateManager> EpochManager<AS, SM> {
         // we need to instantiate new epoch player with appropriate data
         if self.last_react_epoch.0.is_none()
             || self.last_react_epoch.1 != last_sealed_epoch.epoch_number
+            || self.last_react_epoch.2 != tournament_address
         {
             let inputs = self
                 .state_manager
@@ -191,21 +213,134 @@ impl<AS: ArenaSender, SM: StateManager> EpochManager<AS, SM> {
                 leafs,
                 provider.erased(),
                 snapshot.to_string_lossy().to_string(),
-                last_sealed_epoch.root_tournament,
+                tournament_address,
                 last_sealed_epoch.block_created_number,
                 self.long_block_range_error_codes.clone(),
                 self.state_manager
                     .epoch_directory(last_sealed_epoch.epoch_number)?,
             )
             .expect("fail to initialize prt player");
 
-            self.last_react_epoch = (Some(player), last_sealed_epoch.epoch_number);
+            self.last_react_epoch = (
+                Some(player),
+                last_sealed_epoch.epoch_number,
+                tournament_address,
+            );
+        }
+
+        Ok(())
+    }
+
+    /// If the epoch task is a safety gate, participate in the gate (sentry
+    /// vote and fallback timer) and return the inner task address so the
+    /// player can interact with the actual tournament.
+    async fn resolve_tournament_address(
+        &self,
+        provider: DynProvider,
+        task_address: Address,
+        settlement: &Settlement,
+    ) -> Result<Address> {
+        if let Some(inner_task) = self
+            .try_safety_gate(provider, task_address, settlement)
+            .await?
+        {
+            Ok(inner_task)
+        } else {
+            Ok(task_address)
+        }
+    }
+
+    async fn try_safety_gate(
+        &self,
+        provider: DynProvider,
+        task_address: Address,
+        settlement: &Settlement,
+    ) -> Result<Option<Address>> {
+        if !supports_interface(
+            provider.clone(),
+            task_address,
+            SAFETY_GATE_TASK_INTERFACE_ID,
+        )
+        .await
+        {
+            return Ok(None);
+        }
+
+        let safety_gate = safety_gate_task::SafetyGateTask::new(task_address, provider.clone());
+
+        self.try_sentry_vote(&safety_gate, settlement).await?;
+        try_start_fallback_timer(&safety_gate).await?;
+
+        let inner_task = safety_gate.INNER_TASK().call().await?;
+        Ok(Some(inner_task))
+    }
+
+    async fn try_sentry_vote(
+        &self,
+        safety_gate: &safety_gate_task::SafetyGateTask::SafetyGateTaskInstance<DynProvider>,
+        settlement: &Settlement,
+    ) -> Result<()> {
+        let is_sentry = safety_gate.isSentry(self.signer_address).call().await?;
+        if !is_sentry {
+            return Ok(());
+        }
+
+        let has_voted = safety_gate.hasVoted(self.signer_address).call().await?;
+        if has_voted {
+            return Ok(());
         }
 
+        let vote = B256::from(settlement.final_state);
+        info!(
+            "sentry vote {} on safety gate {}",
+            vote,
+            safety_gate.address()
+        );
+        let tx_result = safety_gate.sentryVote(vote).send().await;
+        allow_revert_rethrow_others("sentryVote", tx_result).await?;
         Ok(())
     }
 }
 
+/// The gate never starts its own fallback timer; an offchain actor must do
+/// it for liveness whenever sentries are missing or disagree.
+async fn try_start_fallback_timer(
+    safety_gate: &safety_gate_task::SafetyGateTask::SafetyGateTaskInstance<DynProvider>,
+) -> Result<()> {
+    let can_start = safety_gate.canStartFallbackTimer().call().await?;
+    if !can_start {
+        return Ok(());
+    }
+
+    info!(
+        "start fallback timer on safety gate {}",
+        safety_gate.address()
+    );
+    let tx_result = safety_gate.startFallbackTimer().send().await;
+    allow_revert_rethrow_others("startFallbackTimer", tx_result).await?;
+    Ok(())
+}
+
+async fn supports_interface(
+    provider: DynProvider,
+    contract: Address,
+    interface_id: FixedBytes<4>,
+) -> bool {
+    let erc165 = safety_gate_task::SafetyGateTask::new(contract, provider);
+    match erc165.supportsInterface(interface_id).call().await {
+        Ok(value) => value,
+        Err(err) => {
+            let message = err.to_string();
+            if message.contains("execution reverted") {
+                trace!("supportsInterface reverted: {}", message);
+            } else {
+                debug!("supportsInterface call failed: {}", message);
+            }
+            false
+        }
+    }
+}
+
 fn to_bytes_32_vec(proof: Proof) -> Vec<B256> {
     proof.inner().iter().map(B256::from).collect()
 }

cartesi-rollups/node/epoch-manager/src/lib.rs

@@ -65,6 +65,7 @@ impl Proof {
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Settlement {
     pub computation_hash: Digest,
+    pub final_state: Hash,
     pub output_merkle: Hash,
     pub output_proof: Proof,
 }

cartesi-rollups/node/state-manager/src/lib.rs

@@ -12,6 +12,7 @@ use crate::{
 
 use alloy::primitives::U256;
 use cartesi_dave_merkle::{Digest, MerkleBuilder};
+use cartesi_machine::types::Hash;
 use rusqlite::Connection;
 
 #[derive(Debug)]
@@ -212,7 +213,7 @@ impl StateManager for PersistentStateAccess {
         let settlement = {
             let leafs = rollup_data::get_all_commitments(&self.connection, previous_epoch_number)?;
 
-            let computation_hash = if !leafs.is_empty() {
+            let (computation_hash, final_state) = if !leafs.is_empty() {
                 build_commitment_from_hashes(&leafs)
             } else {
                 assert_eq!(machine.next_input_index_in_epoch(), 0);
@@ -226,6 +227,7 @@ impl StateManager for PersistentStateAccess {
 
             Settlement {
                 computation_hash,
+                final_state,
                 output_merkle,
                 output_proof,
             }
@@ -286,7 +288,7 @@ impl StateManager for PersistentStateAccess {
     }
 }
 
-fn build_commitment_from_hashes(state_hashes: &[CommitmentLeaf]) -> Digest {
+fn build_commitment_from_hashes(state_hashes: &[CommitmentLeaf]) -> (Digest, Hash) {
     let mut builder = MerkleBuilder::default();
 
     assert!(!state_hashes.is_empty());
@@ -306,7 +308,7 @@ fn build_commitment_from_hashes(state_hashes: &[CommitmentLeaf]) -> Digest {
     );
 
     let tree = builder.build();
-    tree.root_hash()
+    (tree.root_hash(), last.hash)
 }
 
 #[cfg(test)]
@@ -526,13 +528,14 @@ mod tests {
         access.roll_epoch()?;
         assert_eq!(access.latest_snapshot()?.epoch(), 1);
 
+        let (computation_hash, final_state) =
+            build_commitment_from_hashes(&[commitment_leaf_1.clone(), commitment_leaf_2.clone()]);
+
         assert_eq!(
             access.settlement_info(0)?.unwrap(),
             Settlement {
-                computation_hash: build_commitment_from_hashes(&[
-                    commitment_leaf_1.clone(),
-                    commitment_leaf_2.clone()
-                ]),
+                computation_hash,
+                final_state,
                 output_merkle,
                 output_proof
             },

cartesi-rollups/node/state-manager/src/persistent_state_access.rs

@@ -4,6 +4,7 @@
 CREATE TABLE IF NOT EXISTS settlement_info (
     epoch_number INTEGER NOT NULL PRIMARY KEY CHECK (epoch_number >= 0),
     computation_hash BLOB NOT NULL,
+    final_state BLOB NOT NULL,
     output_merkle BLOB NOT NULL,
     output_proof BLOB NOT NULL
 );