diff --git a/public/learn/zones/diagram-deposit.svg b/public/learn/zones/diagram-deposit.svg index ccd1202b..4e9cc7ee 100644 --- a/public/learn/zones/diagram-deposit.svg +++ b/public/learn/zones/diagram-deposit.svg @@ -79,7 +79,9 @@ - + + +Locks funds @@ -103,7 +105,9 @@ - + + +Locks funds diff --git a/public/learn/zones/diagram-withdraw.svg b/public/learn/zones/diagram-withdraw.svg index 7f3baa2f..a1a3c7c6 100644 --- a/public/learn/zones/diagram-withdraw.svg +++ b/public/learn/zones/diagram-withdraw.svg @@ -81,7 +81,9 @@ - + + +Locks funds diff --git a/src/pages/guide/private-zones/deposit-to-a-zone.mdx b/src/pages/guide/private-zones/deposit-to-a-zone.mdx index 15b8eb7f..a66e318a 100644 --- a/src/pages/guide/private-zones/deposit-to-a-zone.mdx +++ b/src/pages/guide/private-zones/deposit-to-a-zone.mdx @@ -85,7 +85,7 @@ console.log(receipt.blockNumber) A zone deposit settles in two phases. -First, you submit a public Tempo transaction depositing to the `ZonePortal`. The portal escrows the token, deducts the deposit fee in the same token, and records the net deposit in the portal's deposit queue. Later, the zone sequencer processes that queue and credits the recipient inside the zone. +First, you submit a public Tempo transaction depositing to the `ZonePortal`. The Zone Portal contract locks the token, deducts the deposit fee in the same token, and records the net deposit in its deposit queue. Later, the zone sequencer processes that queue and credits the recipient inside the zone. That means your public transaction receipt and your zone balance do not update at the same time. The Tempo transaction confirms that the deposit request was accepted. The zone balance changes only after the zone has processed that deposit, and it reflects the post-fee amount rather than the full amount you passed into `deposit(...)`. diff --git a/src/pages/protocol/zones/accounts.mdx b/src/pages/protocol/zones/accounts.mdx index fc68e729..e320f75d 100644 --- a/src/pages/protocol/zones/accounts.mdx +++ b/src/pages/protocol/zones/accounts.mdx @@ -24,7 +24,7 @@ On Tempo Mainnet, anyone can read any account's balance. On a Tempo Zone, `balan - If `msg.sender` is the sequencer, the call succeeds (required for block production and fee accounting). - Otherwise, the call reverts with `Unauthorized()`. -Enforcing this at the contract level (not just the RPC layer) ensures that even on-chain composition cannot leak balances. A contract on the Tempo Zone cannot read and emit another account's balance. +Enforcing this at the contract level (not just the RPC layer) ensures that even onchain composition cannot leak balances. A contract on the Tempo Zone cannot read and emit another account's balance. ## Private Allowances diff --git a/src/pages/protocol/zones/architecture.mdx b/src/pages/protocol/zones/architecture.mdx index ea47e651..33efeea0 100644 --- a/src/pages/protocol/zones/architecture.mdx +++ b/src/pages/protocol/zones/architecture.mdx @@ -36,7 +36,7 @@ The sequencer runs a Tempo node with one or more zone nodes attached. Each zone - Synchronizes the zone's view of Tempo Mainnet each time a Tempo Mainnet block finalizes - Executes zone transactions using privately submitted transactions and the zone's own state - Produces batches proving state transitions on the zone and posts them to Tempo Mainnet -- Watches for deposits by monitoring portal events on Tempo Mainnet, and creates corresponding transactions on the zone once the block finalizes +- Watches for deposits by monitoring Zone Portal events on Tempo Mainnet, and creates corresponding transactions on the zone once the block finalizes - Watches for withdrawals on the zone and submits transactions to Tempo Mainnet processing them once the batch has been proven @@ -62,8 +62,8 @@ The system consists of contracts on both Tempo Mainnet and within each Tempo Zon ### Tempo Contracts -- **`ZoneFactory`** deploys new Tempo Zones. Each zone gets its own portal and messenger contracts with deterministic addresses. -- **`ZonePortal`** is the central bridge contract. It locks all deposited tokens, verifies validity proofs, and processes withdrawals. The portal maintains the authoritative state: which deposits have been made, which batches have been proven, and which withdrawals are pending. +- **`ZoneFactory`** deploys new Tempo Zones. Each zone gets its own Zone Portal and Zone Messenger contracts with deterministic addresses. +- **`ZonePortal`** is the central bridge contract. It locks all deposited tokens, verifies validity proofs, and processes withdrawals. The Zone Portal contract maintains the authoritative state: which deposits have been made, which batches have been proven, and which withdrawals are pending. - **`ZoneMessenger`** handles withdrawals that include callbacks. When a user wants to withdraw tokens and trigger a contract call atomically, the messenger executes both operations together. If the callback fails, the entire withdrawal reverts and funds bounce back to the zone. ### Zone Predeploys @@ -73,7 +73,7 @@ Tempo Zones have four system contract predeploys at fixed addresses: | Contract | Address | Purpose | |----------|---------|---------| | `TempoState` | `0x1c00...0000` | Stores the zone's view of Tempo Mainnet. The sequencer updates this with Tempo Mainnet block headers, allowing zone contracts to read Tempo Mainnet state within proofs. | -| `ZoneInbox` | `0x1c00...0001` | Processes incoming deposits. Mints tokens to recipients and validates that processed deposits match what the portal expects. | +| `ZoneInbox` | `0x1c00...0001` | Processes incoming deposits. Mints tokens to recipients and validates that processed deposits match what the Zone Portal contract expects. | | `ZoneOutbox` | `0x1c00...0002` | Handles withdrawal requests. Users burn their zone tokens here and specify a Tempo Mainnet recipient. | | `ZoneConfig` | `0x1c00...0003` | Central configuration. Reads sequencer and token registry from Tempo Mainnet. | @@ -90,7 +90,7 @@ The factory deploys a new `ZonePortal` and `ZoneMessenger` for the Tempo Zone. T ### Chain ID -Each Tempo Zone has a unique EIP-155 chain ID derived deterministically from its on-chain zone ID: +Each Tempo Zone has a unique EIP-155 chain ID derived deterministically from its onchain zone ID: ``` chain_id = 421700000 + zone_id @@ -105,7 +105,7 @@ The sequencer can transfer control to a new address via a two-step process on Te 1. Current sequencer calls `ZonePortal.transferSequencer(newSequencer)` to nominate a new sequencer. 2. New sequencer calls `ZonePortal.acceptSequencer()` to accept the transfer. -Sequencer management happens on Tempo Mainnet. Zone-side system contracts read the sequencer from Tempo Mainnet via `ZoneConfig`, which queries `TempoState` to get the sequencer address from the finalized `ZonePortal` storage. +Sequencer management occurs on Tempo Mainnet. Zone-side system contracts read the sequencer from Tempo Mainnet via `ZoneConfig`, which queries `TempoState` to get the sequencer address from the finalized `ZonePortal` storage. ## Trust Model diff --git a/src/pages/protocol/zones/bridging.mdx b/src/pages/protocol/zones/bridging.mdx index e6980aea..34438824 100644 --- a/src/pages/protocol/zones/bridging.mdx +++ b/src/pages/protocol/zones/bridging.mdx @@ -18,7 +18,7 @@ Above is an example of the type of complex transaction that can remain privacy-p ## Deposits (Tempo → Zone) 1. User calls `ZonePortal.deposit(token, to, amount, memo)` on Tempo, specifying which enabled TIP-20 to deposit. -2. The portal validates the token is enabled and deposits are active, deducts the [deposit fee](/protocol/zones/execution#deposit-fees), holds the locked funds, and appends a deposit to the queue. +2. The Zone Portal contract validates the token is enabled and deposits are active, deducts the [deposit fee](/protocol/zones/execution#deposit-fees), locks the funds, and appends a deposit to the queue. 3. The sequencer observes `DepositMade` events and processes deposits in order via `ZoneInbox.advanceTempo()`, minting the corresponding zone-side TIP-20 to the recipient. 4. A batch proof must prove the zone correctly processed deposits by validating the Tempo state read inside the proof. @@ -33,7 +33,7 @@ For privacy-sensitive use cases, users can make encrypted deposits where the rec |-------|------------|--------| | `token` | Public | Needed for locked token accounting | | `sender` | Public | Needed for potential refunds if decryption fails | -| `amount` | Public | Needed for on-chain accounting | +| `amount` | Public | Needed for onchain locked token accounting | | `to` | Encrypted | Only sequencer knows recipient | | `memo` | Encrypted | Only sequencer knows payment context | @@ -42,9 +42,9 @@ The encryption uses ECIES with secp256k1: 1. Sequencer publishes a secp256k1 encryption public key via `setSequencerEncryptionKey()` with a proof of possession. 2. User generates an ephemeral keypair and derives a shared secret via ECDH. 3. User encrypts `(to || memo)` with AES-256-GCM using the derived key. -4. User calls `depositEncrypted(token, amount, keyIndex, encryptedPayload)` on the portal. +4. User calls `depositEncrypted(token, amount, keyIndex, encryptedPayload)` on the Zone Portal contract. -If decryption fails (invalid ciphertext, wrong key), the zone mints tokens to the `sender`'s address on the zone. The Tempo Mainnet funds remain locked in the portal. This ensures chain progress is never blocked by invalid encrypted deposits. +If decryption fails (invalid ciphertext, wrong key), the zone mints tokens to the `sender`'s address on the zone. The Tempo Mainnet funds remain locked in the Zone Portal contract. This ensures chain progress is never blocked by invalid encrypted deposits. ## Withdrawals (Zone → Tempo) @@ -58,7 +58,7 @@ Users withdraw by creating a withdrawal request on the zone. Withdrawals are pro Withdrawals support callbacks to Tempo contracts via the `ZoneMessenger`. When `gasLimit > 0`, the messenger: -1. Transfers tokens from the portal to the target via `transferFrom`. +1. Transfers tokens from the Zone Portal contract to the target via `transferFrom`. 2. Calls the target with the provided `callbackData`. Both operations are atomic. If the callback reverts, the transfer reverts too. Receiving contracts implement `IWithdrawalReceiver` and verify `msg.sender == zoneMessenger` to authenticate calls. This enables direct composition with DEX swaps, staking, or cross-zone deposits. @@ -76,7 +76,7 @@ interface IWithdrawalReceiver { ### Withdrawal Failure and Bounce-Back -Withdrawals can fail if the token transfer or callback reverts (out of gas, TIP-403 policy, token pause, etc.). When a withdrawal fails, the portal bounces back the funds by re-depositing into the same zone to the withdrawal's `fallbackRecipient`: +Withdrawals can fail if the token transfer or callback reverts (out of gas, TIP-403 policy, token pause, etc.). When a withdrawal fails, the Zone Portal contract bounces back the funds by re-depositing into the same zone to the withdrawal's `fallbackRecipient`: - The withdrawal is **popped unconditionally** from the queue, even on failure. - A new deposit is enqueued for the `fallbackRecipient` on the zone. diff --git a/src/pages/protocol/zones/execution.mdx b/src/pages/protocol/zones/execution.mdx index d48a1c63..0dc64559 100644 --- a/src/pages/protocol/zones/execution.mdx +++ b/src/pages/protocol/zones/execution.mdx @@ -65,4 +65,4 @@ The sequencer manages which TIP-20 tokens are available on a Tempo Zone: | `pauseDeposits(token)` | Stops new deposits for the token. Withdrawals continue. | | `resumeDeposits(token)` | Restarts deposits for a previously paused token. | -Once enabled, a token cannot be disabled. This preserves the withdrawal guarantee. Enabled tokens use the same address on the Tempo Zone as on Tempo Mainnet. `ZoneInbox` mints on deposit, `ZoneOutbox` burns on withdrawal. No mechanism exists to create new tokens on the Tempo Zone. +Once enabled, a token cannot be disabled. This preserves withdrawals for that token, subject to the token's own compliance policy. Tokens on the Tempo Zone use the same address as their Tempo Mainnet counterpart. `ZoneInbox` mints on deposit, `ZoneOutbox` burns on withdrawal. No mechanism exists to create new tokens on the Tempo Zone. diff --git a/src/pages/protocol/zones/index.mdx b/src/pages/protocol/zones/index.mdx index f40fcf48..386474c0 100644 --- a/src/pages/protocol/zones/index.mdx +++ b/src/pages/protocol/zones/index.mdx @@ -15,7 +15,7 @@ A Tempo Zone is a private execution environment attached to Tempo Mainnet. Insid ![Tempo Zones overview](/learn/zones/diagram-overview.svg) -Funds deposited into a Tempo Zone are locked in the zone contract on Tempo Mainnet. [Validity proofs](/protocol/zones/proving) guarantee that the sequencer executed every transaction correctly. The sequencer orders and includes transactions, but cannot steal funds or forge state transitions. +Funds deposited into a Tempo Zone are locked in the Zone Portal contract on Tempo Mainnet. [Validity proofs](/protocol/zones/proving) guarantee that the sequencer executed every transaction correctly. The sequencer orders and includes transactions, but cannot steal funds or forge state transitions. Each Tempo Zone operates as a separate chain, so adding more zones increases throughput without congesting Tempo Mainnet. Tempo Zones share liquidity through Tempo Mainnet. A zone can withdraw tokens, swap them on the Stablecoin DEX, and deposit the result into another zone without exposing who placed the trade. See [composable withdrawals](/protocol/zones/bridging#composable-withdrawals) for details. diff --git a/src/pages/protocol/zones/proving.mdx b/src/pages/protocol/zones/proving.mdx index 95961f39..38a97edb 100644 --- a/src/pages/protocol/zones/proving.mdx +++ b/src/pages/protocol/zones/proving.mdx @@ -63,7 +63,7 @@ The proof verifies that: ## State Transition Function -The prover takes a complete witness of zone blocks and their dependencies, executes the EVM state transitions, and outputs commitments for on-chain verification: +The prover takes a complete witness of zone blocks and their dependencies, executes the EVM state transitions, and outputs commitments for onchain verification: ```rust pub fn prove_zone_batch(witness: BatchWitness) -> Result @@ -122,7 +122,7 @@ The solution verifies ancestry inside the ZK circuit: | Direct | `recentTempoBlockNumber = 0` | Portal reads `tempoBlockNumber` hash from EIP-2935 | | Ancestry | `recentTempoBlockNumber > tempoBlockNumber` | Portal reads `recentTempoBlockNumber` hash; proof verifies parent chain | -Proving time increases linearly with the block gap (each gap block adds ~1 keccak operation), but on-chain verification cost remains constant. This prevents the zone from becoming stuck after an extended downtime. +Proving time increases linearly with the block gap (each gap block adds ~1 keccak operation), but onchain verification cost remains constant. This prevents the zone from becoming stuck after an extended downtime. ## Tempo State Access