From 2ab796755191a6a6901b148f28c04712fe6fe36c Mon Sep 17 00:00:00 2001 From: adityapk00 <31996805+adityapk00@users.noreply.github.com> Date: Mon, 16 Nov 2026 19:15:25 +0000 Subject: [PATCH 1/2] docs(tip-1160): retitle and remove sequencer allowlist section --- tips/tip-1160.md | 64 ++++-------------------------------------------- 1 file changed, 5 insertions(+), 59 deletions(-) diff --git a/tips/tip-1160.md b/tips/tip-1160.md index 59ab0e2938..d90c0b6682 100644 --- a/tips/tip-1160.md +++ b/tips/tip-1160.md @@ -1,14 +1,14 @@ --- id: TIP-1160 -title: Zone TIP-20 Transfers and L1 Pause Mirroring +title: Zone TIP-20 Transfers, L1 Pause Mirroring and Predeploy Removal description: Lets a Zone's portal admin opt in to zone-internal TIP-20 transfers from T15, removes the Permit2 and Multicall3 predeploys from Zones, and mirrors each token's Tempo pause flag into Zone execution. authors: Aditya Kulkarni, Daniel Couser status: Draft -related: TIP-1091, TIP-1096, TIP-1098, TIP-1028, TIP-1022, [Tempo Zones spec](../zones/specs/spec.md), [tempoxyz/tempo#8549](https://github.com/tempoxyz/tempo/pull/8549), [tempoxyz/tempo#8634](https://github.com/tempoxyz/tempo/pull/8634), [tempoxyz/tempo#8987](https://github.com/tempoxyz/tempo/pull/8987) +related: TIP-1091, TIP-1096, TIP-1098, TIP-1028, TIP-1022, [Tempo Zones spec](../zones/specs/spec.md), [tempoxyz/tempo#8549](https://github.com/tempoxyz/tempo/pull/8549), [tempoxyz/tempo#8987](https://github.com/tempoxyz/tempo/pull/8987) protocolVersion: T15 --- -# TIP-1160: Zone TIP-20 Transfers and L1 Pause Mirroring +# TIP-1160: Zone TIP-20 Transfers, L1 Pause Mirroring and Predeploy Removal ## Abstract @@ -187,53 +187,6 @@ No Zone TIP-20 interface changes. The errors already exist: `Unauthorized`, `Pol | Permit2 and Multicall3 users on Zones | Both contracts have no code from T15. Existing Permit2 approvals stay in storage but can no longer be used, and batched reads through Multicall3 must become separate calls. | | Zone node operators | Must run a T15-capable release before T15 activates. The L1 state cache invalidates a token's cached pause flag on its `PauseStateUpdate` event, as it already does for TIP-403 registry entries on `TransferPolicyUpdate`. | | Zone checker | Ignores `TransfersEnabledUpdated`; it does not change L1 liabilities. | -| Sequencer allowlist | Optional and builder-local; see [Sequencer transfer allowlist](#sequencer-transfer-allowlist). | - -## Sequencer transfer allowlist - -Sequencers can restrict transfers further with the deposit allowlist -([tempoxyz/tempo#8634](https://github.com/tempoxyz/tempo/pull/8634)). This is block-builder -policy: Zone followers and the prover accept any block that passes the rules above, so it adds -no consensus rule and needs no hardfork. One flag, `--deposits.allowlist`, gates deposits and -transfers together on purpose: users keep the same address on Tempo and the Zone, and gating -deposits while leaving transfers open would let a listed account pay an unlisted one privately. - -Allowlist enforcement is sequencer censorship, not an on-chain failure. A blocked transfer never -reverts. It is either rejected over RPC or left out of a block, so it leaves no receipt, event or -fee. A block that includes an unlisted transfer is still valid, and nothing on Tempo or in the -proof shows that a transfer was excluded. Users and issuers rely on the sequencer to apply the -list, the same way they rely on it for inclusion. - -With the flag and a written list: - -- While leading, the sequencer bounces a deposit whose L1 sender or decrypted Zone recipient is - unlisted, so a listed depositor cannot fund an unlisted Zone account. -- Submission screens the calldata of each call, including each call of an AA batch. It rejects - the transaction when a `transfer` or `transferWithMemo` names an unlisted sender or `to`, when a - `transferFrom` or `transferFromWithMemo` has an unlisted caller, `from` or `to`, or when a - `requestWithdrawal` names a `zoneFallbackRecipient` other than the withdrawer unless both are - listed. Every party is checked against one version of the list. The error is - `transfer sender or recipient is not allowlisted`. A screened call whose arguments do not decode - is rejected with `malformed transfer calldata`, since the precompile would revert it. -- A transfer whose `from` or `to` is `ZoneOutbox` skips the `from` and `to` check (a - `transferFrom` caller is still checked), and fees are not transfers, so an account removed from - the list can still pay fees and withdraw. -- While leading, the sequencer runs the same calldata screen against its current list before - executing each pool transaction. It leaves out, without executing, any the list now rejects and - drops them from its pool, which catches list changes after admission. -- Every RPC follower mirrors the leader's list in memory, with no flag and no file: at startup, - after each write it relays (when started with `--deposits.allowlist.admin`), and every second, - or every 30 seconds while the leader reports no written list. It rejects the same transactions - on submission and evicts pooled ones the new list rejects. While it holds no written list it - admits every transfer whose calldata decodes, and the leader still enforces its own. -- Without a written list, the sequencer admits every transfer whose calldata decodes and credits - every deposit. Simulations (`eth_call`, `eth_estimateGas`) do not check the list. - -Screening calldata is enough because, from T15, no contract can move funds on a user's behalf -(see Assumptions). Checking the literal `to` is enough because a virtual `to` never resolves on a -Zone (section 2), so the screened recipient is always the credited one. `ReceivePolicyGuard` -claims need no screen: on a Zone a blocked inbound -reverts instead of moving funds into the guard, so it never holds funds there. # Observability @@ -243,9 +196,6 @@ reverts instead of moving funds into the guard, so it never holds funds there. Whether it has reached a Zone follows from the Zone's anchor in `TempoState`. - Rejected transfers revert with `Unauthorized` (pre-T15 or opted out), `PolicyForbids` (TIP-403 or receive policy), `ContractPaused`, or `VirtualAddressUnregistered` (virtual `to`). -- Allowlist rejections are visible only off chain: the submitting RPC returns - `transfer sender or recipient is not allowlisted`, and a transaction evicted from the pool - after admission is never included. Neither leaves anything on chain. - The Zone executor fails a block with `L1Write`, naming the address (and the slot, for a storage write), if a transaction tried to persist a change to a mirrored slot. @@ -258,7 +208,7 @@ issuer's current Tempo controls, delayed only by the anchor's lag. | Actor | Controls | Enforcing check | If compromised or wrong | |---|---|---|---| | Portal admin | The opt-in flag | `onlyAdmin`; `AccessPolicy` abdication freezes it | Can enable or disable transfers on its own Zone, not on others. | -| Sequencer | Ordering, inclusion and the optional allowlist | Validation and the prover re-run the admission checks; nothing checks the allowlist | Can censor transfers, cannot admit ones the consensus rules forbid. The allowlist uses this same censorship power, so a sequencer that ignores or misconfigures it produces valid blocks. | +| Sequencer | Ordering and inclusion | Validation and the prover re-run the admission checks | Can censor transfers, cannot admit ones the consensus rules forbid. | | Issuer | Pause, TIP-403 policies on Tempo | Mirrored reads at the anchor | Controls take effect after the anchor lag, not instantly. | | Approved spender | `transferFrom` simulations | None (accepted) | Learns `min(balance, allowance)` of the owner. The owner bounds this by approving exact amounts. | @@ -269,9 +219,6 @@ Residual risks: ([tempoxyz/tempo#8722](https://github.com/tempoxyz/tempo/pull/8722)). - After a pause, pooled transactions that pay fees in the paused token stay in the pool until a block rejects them. -- The allowlist submission error tells a listed sender that a counterparty is not listed, so a - listed account can probe addresses one at a time. An unlisted `transferFrom` caller is rejected - whatever parties it names, so an unlisted account cannot. # Invariants @@ -296,8 +243,7 @@ writes a mirrored slot. - **Keep Permit2 and Multicall3 and reject them as transfer parties.** Rejected: every path that moves funds (transfers, `approve`, the outbox's internal `transferFrom`, and any future one) - would need to recognize both addresses, and a sequencer allowlist would still have to screen - calls through Multicall3. Clearing their code removes them for good (see Assumptions). + would need to recognize both addresses. Clearing their code removes them for good (see Assumptions). - **Copy the pause flag into Zone storage during `advanceTempo`**, the system call that opens each Zone block by importing finalized Tempo headers. Rejected: it needs a system write for every token on every import. The Zone's database adapter already answers TIP-403 registry reads From b30359cc69f85f6a95075adcd03465de1c08334a Mon Sep 17 00:00:00 2001 From: malleshpai <5857042+malleshpai@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:25:39 -0500 Subject: [PATCH 2/2] docs(tip-1160): add overview example, assumptions table, existing-behavior section Adds a summary table and worked example to the Overview, turns Assumptions into a table with what happens when each fails, and moves rules that already apply at every fork into their own section. Each rule now lives in one place, and open questions are marked "Flag for authors". Co-Authored-By: Claude Opus 5.5 --- tips/tip-1160.md | 133 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 94 insertions(+), 39 deletions(-) diff --git a/tips/tip-1160.md b/tips/tip-1160.md index d90c0b6682..a1f68eb4b6 100644 --- a/tips/tip-1160.md +++ b/tips/tip-1160.md @@ -39,25 +39,29 @@ TIP-403 state. Finally, two predeploys that were harmless while no balance could move become dangerous once transfers are enabled. Permit2's allowance and nonce getters are public, which would expose who approved whom, and anyone can make Multicall3 call a token as itself, so any balance or allowance -Multicall3 held would be anyone's. Removing both is simpler and safer than teaching every -fund-moving path to recognize them. +Multicall3 held would be anyone's. T15 removes both; [Alternatives Considered](#alternatives-considered) +explains why removal beats teaching every fund-moving path to recognize them. ## Assumptions -- Zones read Tempo state at the finalized anchor recorded in `TempoState`. A - `setTransfersEnabled` call or an issuer's pause takes effect on a Zone only once the Zone has - imported the Tempo block that recorded it. Until then the Zone follows the previous value. -- The portal admin is trusted to decide whether its Zone allows transfers. Abdicating - `Capability.AccessPolicy` (giving up the right to change the Zone's access policy, effective - after a fixed delay) freezes the flag at its current value. -- Contract creation and authorization lists are disabled on Zones, so once T15 clears the code - at the Permit2 and Multicall3 addresses, no code can return there, and no other contract can - move funds on a user's behalf. Funds move only through TIP-20 calls, the outbox, and fees. -- Transfers need T15 active on both the Zone (`t15Time` in its genesis) and Tempo, where the - flag lives. A Zone whose genesis does not schedule T15 rejects transfers even after its portal - opts in. Operators schedule the Zone's T15 no earlier than Tempo's. Tempo verifies Zone proofs - against the enclave measurements approved for the fork active on Tempo, so a prover running the - T15 Zone rules needs its measurements approved for T15. +| Assumption | If it does not hold | +|---|---| +| Zones read Tempo state at the *anchor*: the finalized Tempo block number recorded in `TempoState.tempoBlockNumber`. A `setTransfersEnabled` call or an issuer's pause takes effect on a Zone only once the Zone has imported the Tempo block that recorded it. Until then the Zone follows the previous value. | Not stated. See flag 1. | +| The portal admin is trusted to decide whether its Zone allows transfers. | The admin can turn transfers on or off for its own Zone only. It cannot affect other Zones. Abdicating `Capability.AccessPolicy` gives up the right to change the Zone's access policy, effective after a fixed delay. From then on the flag is frozen at its current value ([§1](#1-transfer-opt-in)). | +| Contract creation and authorization lists are disabled on Zones. So once T15 clears the code at the Permit2 and Multicall3 addresses, no code can return there, and no other contract can move funds on a user's behalf. Funds move only through TIP-20 calls, the outbox, and fees. | A contract could hold approvals and move funds for users. Code could return at the removed predeploy addresses, breaking the [§3](#3-predeploy-removal) invariant. | +| T15 is active on the Zone (`t15Time` in its genesis) as well as on Tempo, where the flag lives. | A Zone whose genesis does not schedule T15 rejects transfers even after its portal opts in. | +| Operators schedule the Zone's T15 no earlier than Tempo's. | Not stated. See flag 2. | +| Tempo has approved the enclave measurements of a prover running the T15 Zone rules. Tempo verifies Zone proofs against the measurements approved for the fork active on Tempo. | Not stated. See flag 3. | + +> **Flag for authors.** Three rows do not say what happens when the assumption fails. +> +> 1. **Anchor.** Is anything lost if the anchor is not finalized, for example after a Tempo +> reorg that removes a `setTransfersEnabled` or `pause` call the Zone has already acted on? +> 2. **Zone T15 before Tempo T15.** Our reading: the Zone reads the portal flag before the +> portal has it, so transfers stay rejected, and Tempo rejects the Zone's T15 proofs, so +> withdrawals stop until Tempo reaches T15. Please confirm, or say what actually happens. +> 3. **Measurements not approved.** Our reading: Tempo rejects the proofs and withdrawals stop. +> Please confirm. --- @@ -73,17 +77,47 @@ fund-moving path to recognize them. | Removed predeploys | Permit2 (`PERMIT2_ADDRESS`) and Multicall3 (`MULTICALL3_ADDRESS`). | | Transfer-family call | `transfer`, `transferWithMemo`, `transferFrom` and `transferFromWithMemo` on a Zone token. | +T15 makes three changes on Zones: + +| Change | Controlled by | Takes effect on the Zone | Applies to Zones that have not opted in | +|---|---|---|---| +| Transfer opt-in ([§1](#1-transfer-opt-in), [§2](#2-transfer-admission-on-the-zone)) | Portal admin, on Tempo | When the Zone imports the Tempo block with the `setTransfersEnabled` call | No. Their transfers keep reverting. | +| Predeploy removal ([§3](#3-predeploy-removal)) | The fork | At the first T15 Zone block | Yes | +| Pause mirroring ([§4](#4-l1-pause-mirroring)) | Token issuer, on Tempo | When the Zone imports the Tempo block with the `pause` or `unpause` call | Yes | + Only the portal admin authorizes a Zone's transfers, on Tempo. The Zone sequencer cannot enable them, and block validation re-executes the admission check, so a sequencer cannot include a transfer that the Zone's flag forbids. +Out of scope: + +- TIP-20 behavior on Tempo. The only Tempo-side change is the new `ZonePortal` flag. +- TIP-1022 virtual addresses on Zones. They never resolve ([§2](#2-transfer-admission-on-the-zone)). + +### Example + +A Zone has the token USDX enabled. Alice and Bob each hold USDX on the Zone. In this example the +Zone's anchor trails Tempo by 5 blocks. + +1. The Zone activates T15. Its first T15 block clears the code at Permit2 and Multicall3. +2. In Tempo block 1,000, the portal admin calls `setTransfersEnabled(true)`. +3. The Zone's anchor is 995. Alice calls `transfer(bob, 50)` on the Zone. It reverts with + `Unauthorized`, because the flag at the anchor is still `false`. +4. The Zone imports block 1,000. Alice sends the same transfer, and it succeeds. +5. In Tempo block 1,050, the USDX issuer calls `pause`. Zone transfers keep succeeding until the + Zone imports block 1,050. +6. After that import, Alice's next transfer reverts with `ContractPaused`. A USDX deposit + arriving from Tempo fails its mint and bounces back to Tempo. Bob's `requestWithdrawal` + reverts. +7. In Tempo block 1,200, the issuer calls `unpause`. Once the Zone imports block 1,200, + transfers, deposits and withdrawals work again. + ## Mechanics ### 1. Transfer opt-in -`ZonePortal` gains `bool transfersEnabled`, packed into slot 28 at byte offset 9, after -`tokenEnablementCursorInitialized`. It defaults to `false`, so every existing portal starts -opted out. +`ZonePortal` gains `bool transfersEnabled` (storage location in [Interfaces](#interfaces)). It +defaults to `false`, so every existing portal starts opted out. `setTransfersEnabled(bool enabled)`: @@ -105,22 +139,15 @@ transfer-family call, the checks run in this order: Upstream then applies its normal TIP-20 checks unchanged, including TIP-1022 virtual-address resolution (see below), the pause check (section 4), the TIP-403 policies (mirrored from Tempo), -the allowance, the TIP-1028 receive policy, and the balance check. - -Upstream behaves differently on a Zone in one place. On Tempo, funds a receive policy blocks are -diverted to `ReceivePolicyGuard`, where the policy's recovery authority can claim them. On a Zone -the recovery authority may be an address that cannot act there, such as an L1 contract, and could -never claim them, so the precompile reverts with `PolicyForbids` instead. This already applies -on every Zone at every fork: before T15 no Zone transfer reached it, and `ZoneInbox` rejects -blocked deposits before the mint. +the allowance, the TIP-1028 receive policy, and the balance check. A transfer the receive policy +blocks reverts with `PolicyForbids` on a Zone +([Existing Zone behavior](#existing-zone-behavior-this-tip-relies-on)). Virtual addresses never resolve on a Zone. The Zone has no `AddressRegistry` precompile and does not mirror Tempo's registry, so no virtual master is ever registered there. Every transfer-family call whose `to` is a TIP-1022 virtual address therefore reverts with `VirtualAddressUnregistered`, and funds never reach a virtual address through a Zone transfer. -The fixed 100,000 gas charge for transfer-family calls, `approve` and `permit` is unchanged. - ### 3. Predeploy removal Zone genesis omits Permit2 and Multicall3, and before every T15 block the Zone executor clears @@ -132,10 +159,14 @@ Assumptions). Calls to either address from T15 behave as calls to an account wit From T15, Zone execution reads the `paused` slot (`tip20::slots::PAUSED`) of any TIP-20-prefixed address from Tempo state at the anchor, not from Zone storage. Like a TIP-403 registry read, the -EVM's `SLOAD` charge covers it, with no extra host charge. The Zone never writes this slot: -`pause` and `unpause` stay blocked for every caller, and at any fork the Zone executor fails a -block in which a transaction would persist a change to a mirrored slot (any TIP-403 registry -slot, or a TIP-20 `paused` slot). +EVM's `SLOAD` charge covers it, with no extra host charge. The Zone never writes this slot +([Existing Zone behavior](#existing-zone-behavior-this-tip-relies-on)). + +> **Flag for authors.** Why is the ordinary `SLOAD` charge enough? A read from Tempo state is +> more work for the sequencer and prover than a read from Zone storage, and the rule covers any +> TIP-20-prefixed address, including tokens not enabled on the Zone. Either give the reason +> (for example, the cost per cold read and why it is bounded) or accept the extra cost here +> and in the Threat Model. A token paused on Tempo therefore blocks on the Zone exactly what it blocks on Tempo: @@ -145,10 +176,31 @@ A token paused on Tempo therefore blocks on the Zone exactly what it blocks on T | Deposit (`ZoneInbox` mint) | Reverts, so the deposit bounces back to Tempo | | Withdrawal bounce-back (`ZoneInbox` refund) | Held as a pending refund; `claimRefund` reverts with `ContractPaused` | | `requestWithdrawal` (burn) | Reverts | -| Transactions paying fees in the token | Invalid | +| Transactions paying fees in the token | Cannot be included in a block. Ones already in the pool stay there until block building rejects them ([Threat Model](#threat-model)). | | `approve`, `permit`, reads | Unaffected | -Before T15, the Zone reads the Zone-local slot, which is always unpaused. +> **Flag for authors.** Which error does `requestWithdrawal` revert with while paused? +> Presumably `ContractPaused`; naming it would match the other rows. + +## Existing Zone behavior this TIP relies on + +These rules already apply on every Zone at every fork. T15 does not change them, but the +mechanics above depend on them. + +1. **Blocked receives revert.** On Tempo, funds a receive policy blocks are diverted to + `ReceivePolicyGuard`, where the policy's recovery authority can claim them. On a Zone the + recovery authority may be an address that cannot act there, such as an L1 contract, and could + never claim them, so the precompile reverts with `PolicyForbids` instead. Before T15 no Zone + transfer reached this path, and `ZoneInbox` rejects blocked deposits before the mint. +2. **Mirrored slots are read-only.** `pause` and `unpause` are blocked for every caller. The Zone + executor fails a block in which a transaction would persist a change to a mirrored slot: any + TIP-403 registry slot, or a TIP-20 `paused` slot. +3. **The Zone-local pause slot is always unpaused.** Before T15 the Zone reads this slot, and + nothing writes it. +4. **Fixed gas charge.** Transfer-family calls, `approve` and `permit` cost a fixed 100,000 gas. + +> **Flag for authors.** Please confirm that none of these is new in T15. If rule 2 is new for +> TIP-20 `paused` slots, it belongs in [§4](#4-l1-pause-mirroring) with a fork gate. ## Interfaces @@ -172,7 +224,7 @@ interface IZonePortal { | `transfersEnabled()` | `0xbef97c87` | | `setTransfersEnabled(bool)` | `0x26b9ce13` | | `TransfersEnabledUpdated(bool)` topic | `0xdb41d2f25c62ff78fc21d2ee04045d19649e1a120537236682b9688ddd4eb27c` | -| Storage | slot 28, offset 9, `bool` | +| Storage | slot 28, offset 9, `bool`, packed after `tokenEnablementCursorInitialized` | No Zone TIP-20 interface changes. The errors already exist: `Unauthorized`, `PolicyForbids`, `ContractPaused`, and `VirtualAddressUnregistered` (from `IAddressRegistry`). @@ -183,7 +235,7 @@ No Zone TIP-20 interface changes. The errors already exist: `Unauthorized`, `Pol |---|---| | Existing Zones | Nothing until the portal admin calls `setTransfersEnabled(true)`. Transfers keep reverting with `Unauthorized`. The `set-transfers-enabled` xtask sends the call or builds a Safe proposal; `just set-transfers-enabled` sends it. | | Zone users and wallets | Can send TIP-20 within an opted-in Zone. A transfer may revert while the opt-in waits for the Zone to import the block that recorded it. Wallets should read `transfersEnabled()` on the portal before offering transfers. | -| Issuers | A Tempo pause now also pauses the token on every Zone, including deposits and withdrawals. | +| Issuers | A Tempo pause now also applies on every Zone, including to deposits and withdrawals. [§4](#4-l1-pause-mirroring) lists the effect on each operation. | | Permit2 and Multicall3 users on Zones | Both contracts have no code from T15. Existing Permit2 approvals stay in storage but can no longer be used, and batched reads through Multicall3 must become separate calls. | | Zone node operators | Must run a T15-capable release before T15 activates. The L1 state cache invalidates a token's cached pause flag on its `PauseStateUpdate` event, as it already does for TIP-403 registry entries on `TransferPolicyUpdate`. | | Zone checker | Ignores `TransfersEnabledUpdated`; it does not change L1 liabilities. | @@ -220,6 +272,9 @@ Residual risks: - After a pause, pooled transactions that pay fees in the paused token stay in the pool until a block rejects them. +> **Flag for authors.** "Time- and count-bounded" needs the bounds: the time limit and the +> maximum number of uncached reads per simulation. + # Invariants - Before T15, every transfer-family call on a Zone token reverts with `Unauthorized`. @@ -247,5 +302,5 @@ writes a mirrored slot. - **Copy the pause flag into Zone storage during `advanceTempo`**, the system call that opens each Zone block by importing finalized Tempo headers. Rejected: it needs a system write for every token on every import. The Zone's database adapter already answers TIP-403 registry reads - from Tempo state at the anchor; routing the pause slot through it costs nothing until a call - reads the slot. + from Tempo state at the anchor. Routing the pause slot through it adds no work to + `advanceTempo`; the cost falls only on calls that read the slot.