spec: add deposit counter for transparent deposit confirmation (#355)

* spec: add deposit counter for transparent deposit confirmation

Add a monotonic deposit counter alongside the existing hash chain so that
checking whether a deposit was processed is a simple integer comparison
(lastProcessedDepositNumber >= myDepositNumber) instead of requiring
hash chain reconstruction.

- Add depositCount and lastProcessedDepositNumber storage to ZonePortal
- Add prevDepositNumber/nextDepositNumber to DepositQueueTransition
- Emit depositNumber in DepositMade, EncryptedDepositMade, BounceBack events
- Emit lastProcessedDepositNumber in BatchSubmitted and TempoAdvanced events
- Add processedDepositNumber storage to ZoneInbox
- Document deposit counter and status checking in overview.md

Made-with: Cursor

* style: fix forge fmt formatting in test files

Made-with: Cursor

* fix: update Rust ABI bindings and zone monitor for deposit counter

Align Rust code with the updated Solidity spec:
- Add prevDepositNumber/nextDepositNumber to DepositQueueTransition struct
- Add depositNumber to DepositMade, EncryptedDepositMade, BounceBack events
- Add lastProcessedDepositNumber to BatchSubmitted and TempoAdvanced events
- Add depositCount, lastProcessedDepositNumber views to ZonePortal ABI
- Add processedDepositNumber view to ZoneInbox ABI
- Track prev_processed_deposit_number in ZoneMonitor and BatchData
- Read processedDepositNumber in fetch_block_snapshot

Co-Authored-By: dankrad <[email protected]>

* fix: update ZoneInbox bytecode in zone-test-genesis

Recompile ZoneInbox with the deposit counter changes so the
embedded TempoAdvanced event signature matches the updated ABI.

Co-Authored-By: dankrad <[email protected]>

* fix: set config and tempoState immutables in ZoneInbox genesis bytecode

The raw forge deployedBytecode has all immutables zeroed. The genesis
patching code replaces 32-byte zero needles with the portal address,
so config and tempoState must be pre-set to avoid being overwritten.

Co-Authored-By: dankrad <[email protected]>

* fix: recompile ZoneInbox bytecode in zone-test-genesis

The genesis bytecode was compiled from an older version of ZoneInbox.sol
that didn't include the deposit counter changes, causing a function
selector mismatch. The Rust ABI generates selector 0xd01e8d31 for
advanceTempo, but the old genesis bytecode didn't have that selector,
so all advanceTempo calls hit the fallback and reverted with empty output.

Also fixes the advance_tempo test's local sol! declaration which was
missing the EnabledToken[] parameter.

Co-Authored-By: dankrad <[email protected]>
Amp-Thread-ID: https://ampcode.com/threads/T-019d5485-9b88-71df-8d85-a0bafe2f6815

---------

Co-authored-by: Dankrad Feist <[email protected]>
Co-authored-by: dankrad <[email protected]>

Author: decofe

crates/primitives/src/abi.rs

@@ -84,6 +84,8 @@ macro_rules! define_abi {
             struct DepositQueueTransition {
                 bytes32 prevProcessedHash;
                 bytes32 nextProcessedHash;
+                uint64 prevDepositNumber;
+                uint64 nextDepositNumber;
             }
 
             #[derive(Debug)]
@@ -120,7 +122,8 @@ macro_rules! define_abi {
                     address to,
                     uint128 netAmount,
                     uint128 fee,
-                    bytes32 memo
+                    bytes32 memo,
+                    uint64 depositNumber
                 );
 
                 #[derive(Debug)]
@@ -135,7 +138,8 @@ macro_rules! define_abi {
                     uint8 ephemeralPubkeyYParity,
                     bytes ciphertext,
                     bytes12 nonce,
-                    bytes16 tag
+                    bytes16 tag,
+                    uint64 depositNumber
                 );
 
                 /// Event emitted when a new TIP-20 token is enabled for bridging.
@@ -148,7 +152,8 @@ macro_rules! define_abi {
                     uint64 indexed withdrawalBatchIndex,
                     bytes32 nextProcessedDepositQueueHash,
                     bytes32 nextBlockHash,
-                    bytes32 withdrawalQueueHash
+                    bytes32 withdrawalQueueHash,
+                    uint64 lastProcessedDepositNumber
                 );
 
                 #[derive(Debug)]
@@ -159,7 +164,8 @@ macro_rules! define_abi {
                     bytes32 indexed newCurrentDepositQueueHash,
                     address indexed fallbackRecipient,
                     address token,
-                    uint128 amount
+                    uint128 amount,
+                    uint64 depositNumber
                 );
 
                 #[derive(Debug)]
@@ -201,6 +207,8 @@ macro_rules! define_abi {
                 function withdrawalQueueSlot(uint256 slot) external view returns (bytes32);
                 function genesisTempoBlockNumber() external view returns (uint64);
                 function calculateDepositFee() external view returns (uint128 fee);
+                function depositCount() external view returns (uint64);
+                function lastProcessedDepositNumber() external view returns (uint64);
 
                 // -- State-changing functions --
 
@@ -448,7 +456,8 @@ macro_rules! define_abi {
                     bytes32 indexed tempoBlockHash,
                     uint64 indexed tempoBlockNumber,
                     uint256 depositsProcessed,
-                    bytes32 newProcessedDepositQueueHash
+                    bytes32 newProcessedDepositQueueHash,
+                    uint64 lastProcessedDepositNumber
                 );
 
                 #[derive(Debug)]
@@ -489,6 +498,7 @@ macro_rules! define_abi {
                 error ExtraDecryptionData();
                 error InvalidSharedSecretProof();
                 function processedDepositQueueHash() external view returns (bytes32);
+                function processedDepositNumber() external view returns (uint64);
                 function tempoPortal() external view returns (address);
                 function tempoState() external view returns (address);
                 function config() external view returns (address);

crates/tempo-zone/src/batch.rs

@@ -78,6 +78,10 @@ pub struct BatchData {
     pub prev_processed_deposit_hash: B256,
     /// Deposit queue: where the zone processed up to.
     pub next_processed_deposit_hash: B256,
+    /// Deposit counter at the start of processing.
+    pub prev_deposit_number: u64,
+    /// Deposit counter after processing.
+    pub next_deposit_number: u64,
     /// Withdrawal queue hash for this batch (`B256::ZERO` if no withdrawals).
     pub withdrawal_queue_hash: B256,
 }
@@ -167,6 +171,8 @@ impl BatchSubmitter {
         let deposit_transition = DepositQueueTransition {
             prevProcessedHash: batch.prev_processed_deposit_hash,
             nextProcessedHash: batch.next_processed_deposit_hash,
+            prevDepositNumber: batch.prev_deposit_number,
+            nextDepositNumber: batch.next_deposit_number,
         };
 
         let anchor_mode = self.resolve_anchor_mode(batch.tempo_block_number).await?;
@@ -1003,6 +1009,8 @@ pub(crate) struct ZoneBlockSnapshot {
     pub tempo_block_number: u64,
     /// Cumulative hash of all deposits processed by the zone up to this block.
     pub processed_deposit_hash: B256,
+    /// Total number of deposits processed by the zone up to this block.
+    pub processed_deposit_number: u64,
     /// Zone L2 block hash.
     pub block_hash: B256,
 }
@@ -1103,6 +1111,7 @@ mod tests {
             nextProcessedDepositQueueHash: B256::ZERO,
             nextBlockHash: B256::ZERO,
             withdrawalQueueHash: withdrawal_queue_hash,
+            lastProcessedDepositNumber: 0,
         }
     }
 

crates/tempo-zone/src/l1.rs

@@ -1997,6 +1997,7 @@ mod tests {
             fallbackRecipient: fallback_recipient,
             token,
             amount: 123_456,
+            depositNumber: 1,
         };
         let log = Log {
             inner: alloy_primitives::Log {

crates/tempo-zone/src/zonemonitor.rs

@@ -112,6 +112,9 @@ pub struct ZoneMonitor {
     /// Deposit queue hash from the previous block, used to construct the
     /// [`DepositQueueTransition`](crate::abi::DepositQueueTransition) for each batch.
     prev_processed_deposit_hash: B256,
+    /// Deposit counter from the previous batch, used to construct the
+    /// [`DepositQueueTransition`](crate::abi::DepositQueueTransition) for each batch.
+    prev_processed_deposit_number: u64,
     /// Previous zone block hash, used as `prev_block_hash` in [`BatchData`].
     /// Initialized from the portal's on-chain `blockHash()` at startup.
     prev_zone_block_hash: B256,
@@ -208,11 +211,14 @@ impl ZoneMonitor {
             B256::ZERO,
         )
         .await;
+        let prev_processed_deposit_number =
+            Self::read_processed_deposit_number_at_block(&inbox, last_submitted_zone_block).await;
 
         info!(
             last_submitted_zone_block,
             %prev_zone_block_hash,
             %prev_processed_deposit_hash,
+            prev_processed_deposit_number,
             portal_withdrawal_queue_tail,
             "Initialized from portal state"
         );
@@ -238,6 +244,7 @@ impl ZoneMonitor {
             repair_notify,
             last_submitted_zone_block,
             prev_processed_deposit_hash,
+            prev_processed_deposit_number,
             prev_zone_block_hash,
             portal_withdrawal_queue_tail,
             latest_observed_zone_block: last_submitted_zone_block,
@@ -486,6 +493,8 @@ impl ZoneMonitor {
             next_block_hash: end_state.block_hash,
             prev_processed_deposit_hash: self.prev_processed_deposit_hash,
             next_processed_deposit_hash: end_state.processed_deposit_hash,
+            prev_deposit_number: self.prev_processed_deposit_number,
+            next_deposit_number: end_state.processed_deposit_number,
             withdrawal_queue_hash,
         };
 
@@ -560,6 +569,8 @@ impl ZoneMonitor {
                 next_block_hash: step_state.block_hash,
                 prev_processed_deposit_hash: self.prev_processed_deposit_hash,
                 next_processed_deposit_hash: step_state.processed_deposit_hash,
+                prev_deposit_number: self.prev_processed_deposit_number,
+                next_deposit_number: step_state.processed_deposit_number,
                 withdrawal_queue_hash,
             };
 
@@ -586,14 +597,19 @@ impl ZoneMonitor {
     async fn fetch_block_snapshot(&self, to: u64) -> Result<ZoneBlockSnapshot> {
         let tempo_call = self.tempo_state.tempoBlockNumber().block(to.into());
         let deposit_call = self.inbox.processedDepositQueueHash().block(to.into());
+        let deposit_number_call = self.inbox.processedDepositNumber().block(to.into());
         let block_fut = async {
             self.provider
                 .get_block_by_number(to.into())
                 .await
                 .map_err(Into::into)
         };
-        let (tempo_block_number, processed_deposit_hash, block) =
-            tokio::try_join!(tempo_call.call(), deposit_call.call(), block_fut,)?;
+        let (tempo_block_number, processed_deposit_hash, processed_deposit_number, block) = tokio::try_join!(
+            tempo_call.call(),
+            deposit_call.call(),
+            deposit_number_call.call(),
+            block_fut,
+        )?;
 
         let block_hash = block
             .ok_or_else(|| eyre::eyre!("zone block {to} not found"))?
@@ -603,6 +619,7 @@ impl ZoneMonitor {
         Ok(ZoneBlockSnapshot {
             tempo_block_number,
             processed_deposit_hash,
+            processed_deposit_number,
             block_hash,
         })
     }
@@ -673,6 +690,7 @@ impl ZoneMonitor {
                     // Only advance local state on success.
                     self.prev_zone_block_hash = batch_data.next_block_hash;
                     self.prev_processed_deposit_hash = batch_data.next_processed_deposit_hash;
+                    self.prev_processed_deposit_number = batch_data.next_deposit_number;
                     self.last_submitted_zone_block = last_zone_block;
                     self.metrics
                         .latest_zone_block_submitted_to_l1
@@ -772,6 +790,11 @@ impl ZoneMonitor {
                     self.prev_processed_deposit_hash,
                 )
                 .await;
+                let deposit_number = Self::read_processed_deposit_number_at_block(
+                    &self.inbox,
+                    last_submitted_zone_block,
+                )
+                .await;
 
                 warn!(
                     old_prev_block_hash = %old_hash,
@@ -784,12 +807,14 @@ impl ZoneMonitor {
                     store_first_slot_before_resync,
                     store_last_slot_before_resync,
                     %deposit_hash,
+                    deposit_number,
                     "Resynced from portal and zone state"
                 );
                 self.prev_zone_block_hash = portal_hash;
                 self.portal_withdrawal_queue_tail = portal_tail;
                 self.last_submitted_zone_block = last_submitted_zone_block;
                 self.prev_processed_deposit_hash = deposit_hash;
+                self.prev_processed_deposit_number = deposit_number;
                 self.metrics
                     .latest_zone_block_submitted_to_l1
                     .set(last_submitted_zone_block as f64);
@@ -875,6 +900,32 @@ impl ZoneMonitor {
         }
     }
 
+    async fn read_processed_deposit_number_at_block(
+        inbox: &ZoneInbox::ZoneInboxInstance<DynProvider<TempoNetwork>, TempoNetwork>,
+        zone_block_number: u64,
+    ) -> u64 {
+        if zone_block_number == 0 {
+            return 0;
+        }
+
+        match inbox
+            .processedDepositNumber()
+            .block(zone_block_number.into())
+            .call()
+            .await
+        {
+            Ok(n) => n,
+            Err(e) => {
+                warn!(
+                    zone_block_number,
+                    error = %e,
+                    "Failed to read processedDepositNumber at portal-confirmed zone block"
+                );
+                0
+            }
+        }
+    }
+
     fn record_observed_zone_block(&mut self, latest_zone_block: u64) {
         self.latest_observed_zone_block = latest_zone_block;
         self.metrics
@@ -1016,6 +1067,7 @@ mod tests {
             repair_notify: Arc::new(Notify::new()),
             last_submitted_zone_block: 10,
             prev_processed_deposit_hash: B256::repeat_byte(0xaa),
+            prev_processed_deposit_number: 0,
             prev_zone_block_hash: B256::repeat_byte(0xbb),
             portal_withdrawal_queue_tail: 3,
             latest_observed_zone_block: 50,
@@ -1205,6 +1257,8 @@ mod tests {
             next_block_hash: B256::repeat_byte(0x55),
             prev_processed_deposit_hash: B256::repeat_byte(0x77),
             next_processed_deposit_hash: B256::repeat_byte(0x66),
+            prev_deposit_number: 0,
+            next_deposit_number: 0,
             withdrawal_queue_hash: B256::ZERO,
         };
 

crates/tempo-zone/tests/advance_tempo.rs

@@ -23,7 +23,7 @@ const ZONE_CONFIG_ADDRESS: Address = address!("0x1c00000000000000000000000000000
 const DEPLOYER: Address = address!("0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef");
 
 sol! {
-    function advanceTempo(bytes calldata header, QueuedDeposit[] calldata deposits, DecryptionData[] calldata decryptions);
+    function advanceTempo(bytes calldata header, QueuedDeposit[] calldata deposits, DecryptionData[] calldata decryptions, EnabledToken[] calldata enabledTokens);
     function config() external view returns (address);
     function tempoBlockHash() external view returns (bytes32);
 
@@ -42,6 +42,12 @@ sol! {
         bytes32 memo;
         ChaumPedersenProof cpProof;
     }
+    struct EnabledToken {
+        address token;
+        string name;
+        string symbol;
+        string currency;
+    }
 }
 
 /// Load a Foundry artifact's creation bytecode from the specs output directory.
@@ -370,6 +376,7 @@ fn advance_tempo_repro() {
         header: Bytes::from(next_header_rlp),
         deposits: vec![],
         decryptions: vec![],
+        enabledTokens: vec![],
     }
     .abi_encode();
 

crates/tempo-zone/tests/assets/zone-test-genesis.json

@@ -45,9 +45,13 @@ struct BlockTransition {
 /// @dev The proof reads currentDepositQueueHash from Tempo state to validate
 ///      that nextProcessedHash is an ancestor of (or equal to) currentDepositQueueHash.
 ///      This allows partial deposit processing.
+///      The deposit numbers mirror the hash chain for easy status checking:
+///      a deposit with number N is confirmed once lastProcessedDepositNumber >= N.
 struct DepositQueueTransition {
     bytes32 prevProcessedHash; // where proof starts (verified against zone state)
     bytes32 nextProcessedHash; // where zone processed up to (proof output)
+    uint64 prevDepositNumber; // deposit counter at prevProcessedHash
+    uint64 nextDepositNumber; // deposit counter at nextProcessedHash
 }
 
 /// @notice Deposit type discriminator for the unified deposit queue
@@ -495,14 +499,16 @@ interface IZonePortal {
         address to,
         uint128 netAmount,
         uint128 fee,
-        bytes32 memo
+        bytes32 memo,
+        uint64 depositNumber
     );
 
     event BatchSubmitted(
         uint64 indexed withdrawalBatchIndex,
         bytes32 nextProcessedDepositQueueHash,
         bytes32 nextBlockHash,
-        bytes32 withdrawalQueueHash
+        bytes32 withdrawalQueueHash,
+        uint64 lastProcessedDepositNumber
     );
 
     event WithdrawalProcessed(
@@ -513,7 +519,8 @@ interface IZonePortal {
         bytes32 indexed newCurrentDepositQueueHash,
         address indexed fallbackRecipient,
         address token,
-        uint128 amount
+        uint128 amount,
+        uint64 depositNumber
     );
 
     event SequencerTransferStarted(
@@ -533,7 +540,8 @@ interface IZonePortal {
         uint8 ephemeralPubkeyYParity,
         bytes ciphertext,
         bytes12 nonce,
-        bytes16 tag
+        bytes16 tag,
+        uint64 depositNumber
     );
 
     /// @notice Emitted when sequencer updates their encryption key
@@ -850,7 +858,8 @@ interface IZoneInbox {
         bytes32 indexed tempoBlockHash,
         uint64 indexed tempoBlockNumber,
         uint256 depositsProcessed,
-        bytes32 newProcessedDepositQueueHash
+        bytes32 newProcessedDepositQueueHash,
+        uint64 lastProcessedDepositNumber
     );
 
     event DepositProcessed(