docs: specify symmetric deposit bounceback mechanism

crates/primitives/src/abi.rs

@@ -52,6 +52,7 @@ macro_rules! define_abi {
                 address to;
                 uint128 amount;
                 bytes32 memo;
+                address bouncebackRecipient;
             }
 
             /// Encrypted deposit payload (ECIES encrypted recipient and memo)
@@ -72,6 +73,7 @@ macro_rules! define_abi {
                 uint128 amount;
                 uint256 keyIndex;
                 EncryptedDepositPayload encrypted;
+                address bouncebackRecipient;
             }
 
             #[derive(Debug)]
@@ -123,6 +125,7 @@ macro_rules! define_abi {
                     uint128 netAmount,
                     uint128 fee,
                     bytes32 memo,
+                    address bouncebackRecipient,
                     uint64 depositNumber
                 );
 
@@ -160,14 +163,21 @@ macro_rules! define_abi {
                 event WithdrawalProcessed(address indexed to, address token, uint128 amount, bool callbackSuccess);
 
                 #[derive(Debug)]
-                event BounceBack(
+                event WithdrawalBounceBack(
                     bytes32 indexed newCurrentDepositQueueHash,
                     address indexed fallbackRecipient,
                     address token,
                     uint128 amount,
                     uint64 depositNumber
                 );
 
+                #[derive(Debug)]
+                event DepositBounceBack(
+                    address indexed bouncebackRecipient,
+                    address token,
+                    uint128 amount
+                );
+
                 #[derive(Debug)]
                 event SequencerTransferStarted(
                     address indexed currentSequencer,
@@ -212,7 +222,7 @@ macro_rules! define_abi {
 
                 // -- State-changing functions --
 
-                function deposit(address token, address to, uint128 amount, bytes32 memo)
+                function deposit(address token, address to, uint128 amount, bytes32 memo, address bouncebackRecipient)
                     external
                     returns (bytes32 newCurrentDepositQueueHash);
 
@@ -234,7 +244,8 @@ macro_rules! define_abi {
                     address token,
                     uint128 amount,
                     uint256 keyIndex,
-                    EncryptedDepositPayload calldata encrypted
+                    EncryptedDepositPayload calldata encrypted,
+                    address bouncebackRecipient
                 ) external returns (bytes32 newCurrentDepositQueueHash);
 
                 function setSequencerEncryptionKey(
@@ -744,6 +755,7 @@ mod tests {
             to: address!("0x0000000000000000000000000000000000000002"),
             amount: 1000u128,
             memo: B256::ZERO,
+            bouncebackRecipient: Address::ZERO,
         };
 
         let encoded = d.abi_encode();
@@ -767,6 +779,7 @@ mod tests {
             to: address!("0x0000000000000000000000000000000000000002"),
             amount: 1000u128,
             memo: B256::ZERO,
+            bouncebackRecipient: Address::ZERO,
         };
 
         let deposit_data = Bytes::from(deposit.abi_encode());
@@ -826,6 +839,7 @@ mod tests {
             to: address!("0x0000000000000000000000000000000000000002"),
             amount: 1000u128,
             memo: B256::ZERO,
+            bouncebackRecipient: Address::ZERO,
         };
         let prev_hash = B256::ZERO;
 

crates/tempo-zone/src/builder.rs

@@ -600,7 +600,7 @@ pub fn build_advance_tempo_tx(prepared: &PreparedL1Block) -> Recovered<TempoTxEn
 #[cfg(test)]
 mod tests {
     use alloy_consensus::Header;
-    use alloy_primitives::{B256, Bytes, Log, U256, address};
+    use alloy_primitives::{Address, B256, Bytes, Log, U256, address};
     use alloy_sol_types::{SolCall, SolEvent};
     use reth_primitives_traits::SealedHeader;
     use tempo_primitives::{TempoHeader, TempoReceipt, TempoTxType};
@@ -671,6 +671,7 @@ mod tests {
                             to: recipient,
                             amount: 500_000,
                             memo: B256::ZERO,
+                            bouncebackRecipient: Address::ZERO,
                         }),
                     ),
                 },
@@ -689,6 +690,7 @@ mod tests {
                                 nonce: [0x05; 12].into(),
                                 tag: [0x06; 16].into(),
                             },
+                            bouncebackRecipient: Address::ZERO,
                         }),
                     ),
                 },

crates/tempo-zone/src/l1.rs

@@ -28,8 +28,8 @@ use crate::{
         EncryptedDepositPayload as AbiEncryptedDepositPayload, PORTAL_PENDING_SEQUENCER_SLOT,
         PORTAL_SEQUENCER_SLOT,
         ZonePortal::{
-            self, BounceBack, DepositMade, EncryptedDepositMade, SequencerTransferStarted,
-            SequencerTransferred, TokenEnabled, ZonePortalEvents,
+            self, DepositMade, EncryptedDepositMade, SequencerTransferStarted,
+            SequencerTransferred, TokenEnabled, WithdrawalBounceBack, ZonePortalEvents,
         },
     },
     ext::TempoStateExt,
@@ -789,6 +789,8 @@ pub struct Deposit {
     pub fee: u128,
     /// User-provided memo.
     pub memo: B256,
+    /// Bounceback recipient on L1 (receives funds if the zone rejects the deposit).
+    pub bounceback_recipient: Address,
 }
 
 impl Deposit {
@@ -801,18 +803,20 @@ impl Deposit {
             amount: event.netAmount,
             fee: event.fee,
             memo: event.memo,
+            bounceback_recipient: event.bouncebackRecipient,
         }
     }
 
     /// Create a bounce-back deposit from an event.
-    pub fn from_bounce_back(event: BounceBack, portal_address: Address) -> Self {
+    pub fn from_bounce_back(event: WithdrawalBounceBack, portal_address: Address) -> Self {
         Self {
             token: event.token,
             sender: portal_address,
             to: event.fallbackRecipient,
             amount: event.amount,
             fee: 0,
             memo: B256::ZERO,
+            bounceback_recipient: Address::ZERO,
         }
     }
 }
@@ -840,6 +844,8 @@ pub struct EncryptedDeposit {
     pub nonce: [u8; 12],
     /// GCM authentication tag (16 bytes).
     pub tag: [u8; 16],
+    /// Bounceback recipient on L1 (receives funds if the zone rejects the deposit).
+    pub bounceback_recipient: Address,
 }
 
 impl EncryptedDeposit {
@@ -856,6 +862,7 @@ impl EncryptedDeposit {
             ciphertext: event.ciphertext.to_vec(),
             nonce: event.nonce.0,
             tag: event.tag.0,
+            bounceback_recipient: Address::ZERO,
         }
     }
 }
@@ -882,6 +889,7 @@ impl L1Deposit {
                         to: d.to,
                         amount: d.amount,
                         memo: d.memo,
+                        bouncebackRecipient: d.bounceback_recipient,
                     },
                     prev_hash,
                 )
@@ -902,6 +910,7 @@ impl L1Deposit {
                             nonce: d.nonce.into(),
                             tag: d.tag.into(),
                         },
+                        bouncebackRecipient: d.bounceback_recipient,
                     },
                     prev_hash,
                 )
@@ -983,7 +992,7 @@ impl L1PortalEvents {
     const SIGNATURE_HASHES: [B256; 6] = [
         DepositMade::SIGNATURE_HASH,
         EncryptedDepositMade::SIGNATURE_HASH,
-        BounceBack::SIGNATURE_HASH,
+        WithdrawalBounceBack::SIGNATURE_HASH,
         TokenEnabled::SIGNATURE_HASH,
         SequencerTransferStarted::SIGNATURE_HASH,
         SequencerTransferred::SIGNATURE_HASH,
@@ -1034,7 +1043,7 @@ impl L1PortalEvents {
                 self.deposits
                     .push(L1Deposit::Encrypted(EncryptedDeposit::from_event(event)));
             }
-            ZonePortalEvents::BounceBack(event) => {
+            ZonePortalEvents::WithdrawalBounceBack(event) => {
                 info!(
                     l1_block = block_number,
                     token = %event.token,
@@ -1145,6 +1154,7 @@ impl L1BlockDeposits {
                         to: d.to,
                         amount: d.amount,
                         memo: d.memo,
+                        bouncebackRecipient: d.bounceback_recipient,
                     };
                     queued_deposits.push(abi::QueuedDeposit {
                         depositType: abi::DepositType::Regular,
@@ -1167,6 +1177,7 @@ impl L1BlockDeposits {
                                     nonce: d.nonce.into(),
                                     tag: d.tag.into(),
                                 },
+                                bouncebackRecipient: d.bounceback_recipient,
                             }
                             .abi_encode(),
                         ),
@@ -1992,7 +2003,7 @@ mod tests {
         let portal_address = address!("0x0000000000000000000000000000000000000ABC");
         let fallback_recipient = address!("0x00000000000000000000000000000000000000F1");
         let token = address!("0x0000000000000000000000000000000000002000");
-        let event = BounceBack {
+        let event = WithdrawalBounceBack {
             newCurrentDepositQueueHash: B256::with_last_byte(0x42),
             fallbackRecipient: fallback_recipient,
             token,
@@ -2192,6 +2203,7 @@ mod tests {
             amount: 1000,
             fee: 0,
             memo: B256::ZERO,
+            bounceback_recipient: Address::ZERO,
         });
 
         queue.enqueue(
@@ -2218,6 +2230,7 @@ mod tests {
             amount: 2000,
             fee: 0,
             memo: B256::ZERO,
+            bounceback_recipient: Address::ZERO,
         });
 
         queue.enqueue(
@@ -2239,6 +2252,7 @@ mod tests {
                 amount: 1000,
                 fee: 0,
                 memo: B256::ZERO,
+                bounceback_recipient: Address::ZERO,
             }),
             L1Deposit::Regular(Deposit {
                 token: address!("0x0000000000000000000000000000000000001000"),
@@ -2247,6 +2261,7 @@ mod tests {
                 amount: 2000,
                 fee: 0,
                 memo: B256::ZERO,
+                bounceback_recipient: Address::ZERO,
             }),
         ];
 
@@ -2278,6 +2293,7 @@ mod tests {
             amount: 500,
             fee: 0,
             memo: FixedBytes::from([0xABu8; 32]),
+            bounceback_recipient: Address::ZERO,
         })];
 
         queue.enqueue(
@@ -2302,6 +2318,7 @@ mod tests {
             amount: 100,
             fee: 0,
             memo: B256::ZERO,
+            bounceback_recipient: Address::ZERO,
         });
 
         let d2 = L1Deposit::Regular(Deposit {
@@ -2311,6 +2328,7 @@ mod tests {
             amount: 200,
             fee: 0,
             memo: B256::ZERO,
+            bounceback_recipient: Address::ZERO,
         });
 
         let h10 = make_test_header(10);
@@ -2349,6 +2367,7 @@ mod tests {
             ciphertext: vec![0x42u8; 64],
             nonce: [0x01; 12],
             tag: [0x02; 16],
+            bounceback_recipient: Address::ZERO,
         };
 
         // Compute via PendingDeposits (Rust implementation)
@@ -2368,6 +2387,7 @@ mod tests {
                 nonce: encrypted.nonce.into(),
                 tag: encrypted.tag.into(),
             },
+            bouncebackRecipient: Address::ZERO,
         };
         let expected = keccak256((DepositType::Encrypted, abi_encrypted, B256::ZERO).abi_encode());
 
@@ -2395,6 +2415,7 @@ mod tests {
             amount: 500_000,
             fee: 0,
             memo: B256::ZERO,
+            bounceback_recipient: Address::ZERO,
         };
 
         let encrypted = EncryptedDeposit {
@@ -2408,6 +2429,7 @@ mod tests {
             ciphertext: vec![0x55u8; 64],
             nonce: [0x0A; 12],
             tag: [0x0B; 16],
+            bounceback_recipient: Address::ZERO,
         };
 
         let deposits = vec![
@@ -2427,6 +2449,7 @@ mod tests {
                     to: regular.to,
                     amount: regular.amount,
                     memo: regular.memo,
+                    bouncebackRecipient: Address::ZERO,
                 },
                 B256::ZERO,
             )
@@ -2448,6 +2471,7 @@ mod tests {
                         nonce: encrypted.nonce.into(),
                         tag: encrypted.tag.into(),
                     },
+                    bouncebackRecipient: Address::ZERO,
                 },
                 hash_1,
             )
@@ -2474,6 +2498,7 @@ mod tests {
             ciphertext: vec![0x99u8; 64],
             nonce: [0x03; 12],
             tag: [0x04; 16],
+            bounceback_recipient: Address::ZERO,
         };
 
         let deposits = vec![L1Deposit::Encrypted(encrypted)];
@@ -2694,6 +2719,7 @@ mod tests {
             amount: 100,
             fee: 0,
             memo: B256::ZERO,
+            bounceback_recipient: Address::ZERO,
         });
         assert!(matches!(
             queue.try_enqueue(seal(h1), L1PortalEvents::from_deposits(vec![d1]), vec![]),
@@ -2709,6 +2735,7 @@ mod tests {
             amount: 200,
             fee: 0,
             memo: B256::ZERO,
+            bounceback_recipient: Address::ZERO,
         });
         assert!(matches!(
             queue.try_enqueue(seal(h2), L1PortalEvents::from_deposits(vec![d2]), vec![]),
@@ -2742,6 +2769,7 @@ mod tests {
             amount,
             fee: 0,
             memo: B256::ZERO,
+            bounceback_recipient: Address::ZERO,
         })
     }
 

crates/tempo-zone/tests/advance_tempo.rs

@@ -195,12 +195,13 @@ fn setup_zone_evm_with_contracts() -> TempoEvm<CacheDB<EmptyDB>> {
     );
     nonce += 1;
 
-    // 3. ZoneInbox(address config, address tempoPortal, address tempoState)
+    // 3. ZoneInbox(address config, address tempoPortal, address tempoState, address outbox)
     let zone_inbox_bytecode = load_artifact("ZoneInbox");
     let zone_inbox_args = alloy_sol_types::SolValue::abi_encode_params(&(
         ZONE_CONFIG_ADDRESS,
         tempo_portal,
         TEMPO_STATE_ADDRESS,
+        ZONE_OUTBOX_ADDRESS,
     ));
     deploy_contract(
         &mut evm,