Skip to main content

cast/cmd/tempo/zone/
l1.rs

1//! Parent-chain selection and correlated withdrawal settlement.
2
3use super::abi::{IZoneOutbox, IZonePortal, OUTBOX};
4use alloy_primitives::{Address, B256, keccak256};
5use alloy_provider::{Provider, RootProvider};
6use alloy_rpc_types::Filter;
7use alloy_sol_types::SolEvent;
8use clap::Parser;
9use eyre::{Result, ensure, eyre};
10use std::time::Duration;
11use tempo_alloy::TempoNetwork;
12
13/// L1 connection options, deliberately separate from the authenticated zone RPC.
14#[derive(Debug, Parser)]
15pub(super) struct L1Args {
16    /// Override the public mainnet or Moderato RPC inferred from the zone chain ID.
17    ///
18    /// Withdrawals also read a configurable account sender's configuration from it.
19    #[arg(long, env = "L1_RPC_URL")]
20    l1_rpc_url: Option<String>,
21    /// Zone portal on Tempo L1. Required for --wait-l1 and Earn callback builders.
22    #[arg(long, env = "L1_PORTAL_ADDRESS")]
23    portal: Option<Address>,
24}
25
26impl L1Args {
27    pub(super) fn portal(&self) -> Result<Address> {
28        self.portal.ok_or_else(|| eyre!("--portal is required for L1 operations"))
29    }
30
31    pub(super) async fn provider(
32        &self,
33        zone_chain_id: u64,
34        zone_id: u32,
35    ) -> Result<RootProvider<TempoNetwork>> {
36        let portal = self.portal()?;
37        let url = self.parent_rpc_url(zone_chain_id, zone_id).await?;
38        let provider = RootProvider::<TempoNetwork>::new_http(url.parse()?);
39        ensure!(
40            IZonePortal::new(portal, &provider).zoneId().call().await? == zone_id,
41            "--portal does not belong to --zone-id"
42        );
43        Ok(provider)
44    }
45
46    /// Returns the RPC URL of the zone's parent chain, after checking that it serves that chain.
47    pub(super) async fn parent_rpc_url(&self, zone_chain_id: u64, zone_id: u32) -> Result<String> {
48        let parent = parent_chain(zone_chain_id, zone_id)?;
49        let url = match &self.l1_rpc_url {
50            Some(url) => url.clone(),
51            None => public_rpc(parent)?.to_string(),
52        };
53        let provider = RootProvider::<TempoNetwork>::new_http(url.parse()?);
54        ensure!(
55            provider.get_chain_id().await? == parent,
56            "L1 RPC chain ID does not match the zone's parent chain"
57        );
58        Ok(url)
59    }
60}
61
62// Chain ID allocation mirrored from zones/crates/primitives/src/constants.rs at a1c15e9f.
63fn parent_chain(chain: u64, zone: u32) -> Result<u64> {
64    ensure!(zone != 0, "--zone-id must be nonzero");
65    let (parent, decoded_zone) = match chain {
66        421_700_000..1_424_310_000 => (4217, chain - 421_700_000),
67        1_424_310_000..2_147_483_648 => (42431, chain - 1_424_310_000),
68        _ if chain >= 1 << 32 => (chain >> 32, chain & 0xffff_ffff),
69        _ => return Err(eyre!("invalid zone chain ID: {chain}")),
70    };
71    ensure!(decoded_zone == u64::from(zone), "--zone-id does not match --zone-chain-id");
72    ensure!(parent <= (1 << 20) - 2, "invalid parent chain ID");
73    ensure!(chain < 1 << 32 || !matches!(parent, 4217 | 42431), "noncanonical zone chain ID");
74    Ok(parent)
75}
76
77fn public_rpc(parent: u64) -> Result<&'static str> {
78    match parent {
79        4217 => Ok("https://rpc.tempo.xyz"),
80        42431 => Ok("https://rpc.moderato.tempo.xyz"),
81        _ => Err(eyre!("no public RPC for parent chain {parent}; supply --l1-rpc-url")),
82    }
83}
84
85fn sender_tag(sender: Address, tx_hash: B256, nonce: u64) -> B256 {
86    let mut bytes = [0u8; 60];
87    bytes[..20].copy_from_slice(sender.as_slice());
88    bytes[20..52].copy_from_slice(tx_hash.as_slice());
89    bytes[52..].copy_from_slice(&nonce.to_be_bytes());
90    keccak256(bytes)
91}
92
93pub(super) async fn wait_for_withdrawal(
94    zone: &impl Provider<TempoNetwork>,
95    l1: &impl Provider<TempoNetwork>,
96    portal: Address,
97    mut from_block: u64,
98    zone_block: u64,
99    zone_hash: B256,
100) -> Result<B256> {
101    let logs = zone
102        .get_logs(
103            &Filter::new()
104                .address(OUTBOX)
105                .event_signature(IZoneOutbox::WithdrawalRequested::SIGNATURE_HASH)
106                .from_block(zone_block)
107                .to_block(zone_block),
108        )
109        .await?;
110    let requested = logs
111        .iter()
112        .filter(|log| log.transaction_hash == Some(zone_hash))
113        .find_map(|log| IZoneOutbox::WithdrawalRequested::decode_log(&log.inner).ok())
114        .ok_or_else(|| eyre!("withdrawal request event missing from {zone_hash}"))?;
115    let tag = sender_tag(requested.sender, zone_hash, requested.fallbackNonce);
116    loop {
117        let head = l1.get_block_number().await?;
118        if head >= from_block {
119            // Bound each query for public RPC providers and advance through historical ranges.
120            let end = head.min(from_block.saturating_add(999));
121            let logs = l1
122                .get_logs(
123                    &Filter::new()
124                        .address(portal)
125                        .event_signature(IZonePortal::WithdrawalProcessed::SIGNATURE_HASH)
126                        .topic1(requested.to)
127                        .topic2(tag)
128                        .from_block(from_block)
129                        .to_block(end),
130                )
131                .await?;
132            for log in logs {
133                let event = IZonePortal::WithdrawalProcessed::decode_log(&log.inner)?;
134                if !log.removed
135                    && event.senderTag == tag
136                    && event.to == requested.to
137                    && event.token == requested.token
138                    && event.amount == requested.amount
139                {
140                    let hash = log
141                        .transaction_hash
142                        .ok_or_else(|| eyre!("L1 event missing transaction hash"))?;
143                    ensure!(
144                        event.callbackSuccess,
145                        "L1 delivery failed in {hash}; a refund was queued for the zone fallback recipient"
146                    );
147                    return Ok(hash);
148                }
149            }
150            from_block = end + 1;
151            if end < head {
152                continue;
153            }
154        }
155        tokio::time::sleep(Duration::from_secs(2)).await;
156    }
157}
158
159#[cfg(test)]
160mod tests {
161    use super::*;
162    use alloy_primitives::Bytes;
163    use alloy_provider::{ProviderBuilder, mock::Asserter};
164    use alloy_rpc_types::Log;
165
166    #[test]
167    fn parent_chain_and_public_defaults() {
168        assert_eq!(
169            public_rpc(parent_chain(421_700_007, 7).unwrap()).unwrap(),
170            "https://rpc.tempo.xyz"
171        );
172        assert_eq!(
173            public_rpc(parent_chain(1_424_310_003, 3).unwrap()).unwrap(),
174            "https://rpc.moderato.tempo.xyz"
175        );
176        assert_eq!(parent_chain((31337 << 32) | 2, 2).unwrap(), 31337);
177        assert!(public_rpc(31337).is_err());
178        for (chain, zone) in
179            [(421_700_007, 8), (1_424_310_000, 0), (1 << 31, 1), ((4217 << 32) | 1, 1)]
180        {
181            assert!(parent_chain(chain, zone).is_err());
182        }
183    }
184
185    #[test]
186    fn sender_tag_binds_transaction_and_nonce() {
187        let sender = Address::repeat_byte(0x11);
188        let hash = B256::repeat_byte(0x22);
189        let expected =
190            keccak256([sender.as_slice(), hash.as_slice(), &3u64.to_be_bytes()].concat());
191        assert_eq!(sender_tag(sender, hash, 3), expected);
192        assert_ne!(sender_tag(sender, hash, 3), sender_tag(sender, hash, 4));
193        assert_ne!(sender_tag(sender, hash, 3), sender_tag(sender, B256::ZERO, 3));
194    }
195    #[tokio::test]
196    async fn wait_checks_delivery_result_and_ignores_other_transactions() {
197        for success in [Some(true), Some(false), None] {
198            let zone_hash = B256::repeat_byte(1);
199            let l1_hash = B256::repeat_byte(2);
200            let portal = Address::repeat_byte(3);
201            let request = IZoneOutbox::WithdrawalRequested {
202                withdrawalIndex: 0,
203                sender: Address::repeat_byte(4),
204                token: Address::repeat_byte(5),
205                to: Address::repeat_byte(6),
206                amount: 7,
207                fee: 0,
208                memo: B256::ZERO,
209                gasLimit: 100_000,
210                fallbackNonce: 8,
211                data: Bytes::new(),
212                revealTo: Bytes::new(),
213            };
214            let request_log = Log {
215                inner: alloy_primitives::Log { address: OUTBOX, data: request.encode_log_data() },
216                transaction_hash: Some(zone_hash),
217                ..Default::default()
218            };
219            let mut unrelated = request_log.clone();
220            unrelated.transaction_hash = Some(B256::ZERO);
221            let zone_responses = Asserter::new();
222            zone_responses.push_success(&vec![unrelated, request_log]);
223            let zone = ProviderBuilder::new()
224                .network::<TempoNetwork>()
225                .connect_mocked_client(zone_responses);
226            let delivered = IZonePortal::WithdrawalProcessed {
227                to: request.to,
228                senderTag: sender_tag(request.sender, zone_hash, 8),
229                token: request.token,
230                amount: request.amount,
231                callbackSuccess: success.unwrap_or(true),
232            };
233            let delivered_log = Log {
234                inner: alloy_primitives::Log { address: portal, data: delivered.encode_log_data() },
235                transaction_hash: Some(l1_hash),
236                ..Default::default()
237            };
238            let l1_responses = Asserter::new();
239            l1_responses.push_success(&"0xa");
240            let mut removed = delivered_log.clone();
241            removed.removed = true;
242            let unrelated = IZonePortal::WithdrawalProcessed { senderTag: B256::ZERO, ..delivered };
243            let mut unrelated_log = delivered_log.clone();
244            unrelated_log.inner.data = unrelated.encode_log_data();
245            let mut logs = vec![removed, unrelated_log];
246            if success.is_some() {
247                logs.push(delivered_log);
248            }
249            l1_responses.push_success(&logs);
250            let l1 = ProviderBuilder::new()
251                .network::<TempoNetwork>()
252                .connect_mocked_client(l1_responses);
253            let result = tokio::time::timeout(
254                Duration::from_millis(100),
255                wait_for_withdrawal(&zone, &l1, portal, 10, 20, zone_hash),
256            )
257            .await;
258            match success {
259                Some(true) => assert_eq!(result.unwrap().unwrap(), l1_hash),
260                Some(false) => assert_eq!(
261                    result.unwrap().unwrap_err().to_string(),
262                    format!(
263                        "L1 delivery failed in {l1_hash}; a refund was queued for the zone fallback recipient"
264                    )
265                ),
266                None => assert!(
267                    result.is_err(),
268                    "unrelated or removed events must not complete the wait"
269                ),
270            }
271        }
272    }
273}