From 75c3135f72092cf5d2d4adaec6deaa165136f1ad Mon Sep 17 00:00:00 2001 From: 0xrusowsky <90208954+0xrusowsky@users.noreply.github.com> Date: Sat, 21 Nov 2026 08:39:19 +0000 Subject: [PATCH 1/3] docs(tip-1094): rewrite for readability --- tips/tip-1094.md | 229 ++++++++++++++++++++++++----------------------- 1 file changed, 116 insertions(+), 113 deletions(-) diff --git a/tips/tip-1094.md b/tips/tip-1094.md index 5a02b14d3e..caf1be013b 100644 --- a/tips/tip-1094.md +++ b/tips/tip-1094.md @@ -12,27 +12,15 @@ protocolVersion: T15 ## Abstract -This TIP lets anyone deposit into a zone with an ordinary TIP-20 transfer on mainnet. The Zone deposit virtual address holds a public zone ID, a key version, and a 6-byte ciphertext. Only the zone can decrypt the ciphertext to determine which address to credit in the zone. - -Upon TIP-20 detecting a transfer to a Zone Virtual Deposit Address, the protocol reroutes the transfer to the zone and initiates a zone deposit. The zone then decrypts the ciphertext and processes the deposit if possible. The zone credits the registered recipient, or refunds the sender on Tempo if the deposit fails. - +This TIP lets anyone deposit into a zone with an ordinary TIP-20 transfer on Tempo. A zone deposit address holds a public zone ID, a key version and a 6-byte ciphertext that only the zone can decrypt. Tempo routes a transfer to such an address into the zone's portal as a virtual deposit. The zone decrypts the ciphertext, looks up the registered recipient and credits it, or refunds the sender on Tempo if the deposit fails. Refunds are public, so a token's policy controller can learn who owns an address by blocking candidates and watching for refunds. ## Motivation -Zones accept user deposits only through the portal's `deposit()` and `depositEncrypted()` calls ([Zones protocol](https://github.com/tempoxyz/zones/blob/a88c2ac6b6b407225e2861c660806faccc0217df/specs/spec.md#deposits)). Both require the sender to build an ECIES payload that encrypts the recipient and memo to the sequencer's key. Many systems (wallets, exchanges, and payment systems) can send ordinary TIP-20 transfers, but would need integration work to build that payload and call the portal. - -This TIP gives each zone recipient the option to have reusable addresses on mainnet that work with a plain transfer and do not reveal who the recipient is. The central idea is to encrypt the recipient's identifier into the address itself. The zone registers the recipient privately and assigns it a 4-byte master ID. The recipient adds a 2-byte user tag to tell senders apart. The zone encrypts those 6 bytes with FF1, a standard NIST cipher whose output is the same size as its input to generate a ciphertext. Only the zone holds the key, so only the zone can recover the master ID and credit the recipient. - -Because addresses are computed from the master ID and tag, there is no per-address state. Registration and lookup stay in confidential zone state, so Tempo mainnet never learns that a recipient registered. Each zone has its own registry; receiving in several zones takes one registration in each. - +Zones accept user deposits only through the portal's `deposit()` and `depositEncrypted()` calls ([Zones protocol](https://github.com/tempoxyz/zones/blob/a88c2ac6b6b407225e2861c660806faccc0217df/specs/spec.md#deposits)). Both require the sender to build an ECIES payload that encrypts the recipient and memo to the sequencer's key. Wallets, exchanges and payment systems can send ordinary TIP-20 transfers, but would need integration work to build that payload and call the portal. -### Alternatives considered - -- **Keep only ECIES deposits.** Stronger, randomized, authenticated encryption, but every sender has to integrate it. -- **Store a private address-to-recipient mapping.** Lookup is simpler, but every address becomes durable state that must be stored and recovered. Encrypting the identifier into the address needs no such state. -- **Reuse the L1 TIP-1022 registry.** One registration would serve every zone, but it needs L1 registry witnesses during zone processing, and the registration is public on Tempo, so anyone could link a deposit address's master ID to its recipient. -- **Expose the master ID.** No encryption is needed, but the recipient is no longer hidden. +This TIP gives each zone recipient reusable addresses on Tempo that work with a plain transfer and do not reveal the recipient. The zone registers the recipient privately and assigns it a 4-byte master ID. The recipient adds a 2-byte user tag to tell senders apart. The zone encrypts those 6 bytes with FF1, a NIST cipher whose output is the same size as its input, and puts the ciphertext in the address. Only the zone holds the key, so only the zone can recover the master ID and credit the recipient. +Addresses are computed from the master ID and tag, so there is no per-address state. Registration and lookup stay in confidential zone state, so Tempo never learns that a recipient registered. Each zone has its own registry; receiving in several zones takes one registration in each. ## Assumptions @@ -43,13 +31,14 @@ Because addresses are computed from the master ID and tag, there is no per-addre | Each zone keeps every FF1 key it has initialized, confidentially, for the life of the zone. A zone can have several keys over time; the address's key version byte says which one encrypted it (see [Key versions](#key-versions)). Substituting another key for a version is forbidden. | A lost key can stop zone execution. A substituted key changes the recipient behind every address under that version. | | The zone keeps executing, its data and witnesses stay available, batches settle, and Tempo processes withdrawals. | Queued deposits are stuck. This TIP adds no forced inclusion and no recovery from permanent zone failure. A parked refund also needs the refund recipient to act, with permission restored. | - --- # Specification ## Overview +A deposit address is a reserved 20-byte address: the zone ID, magic bytes, a key version and an FF1 ciphertext of a master ID and user tag. Tempo intercepts TIP-20 transfers to these addresses, moves the tokens to the zone's portal and queues a new `ZoneVirtual` deposit. The zone's native inbox decrypts the address under the committed key, looks up the master ID in a confidential zone registry, and mints to the recipient or refunds the debited account on Tempo. + ### Terms | Term | Meaning | @@ -77,17 +66,17 @@ Because addresses are computed from the master ID and tag, there is no per-addre ### Authority boundary -Each step has one party that can authorize it, and the checks that limit them are proof-covered or enforced on Tempo: +Each step has one party that can authorize it, and the checks that limit it are proof-covered or enforced on Tempo: | Step | Who authorizes it | What limits them | |---|---|---| -| Retire key versions | Portal admin | Retirement reverts only new transfers on Tempo; queued deposits still process ([Portal controls](#portal-controls)). | +| Retire key versions | Portal admin | Retirement reverts only new transfers on Tempo; queued deposits still process ([Retiring versions](#retiring-versions)). | | Register a recipient | Anyone | The registration is bound to the named recipient and grants the caller nothing ([Registering a recipient](#registering-a-recipient)). | -| Issue addresses | The recipient, through the authenticated RPC | No public derivation; the payer of a registration cannot issue an address ([Recipient RPC](#recipient-rpc)). | +| Issue addresses | The recipient, through the authenticated RPC | No public derivation; the payer of a registration cannot issue an address ([Issuing addresses](#issuing-addresses)). | | Choose the credited recipient | Nobody | The zone's proof-covered execution decrypts and looks up the recipient; the sequencer has no input ([Processing in the zone](#processing-in-the-zone)). | | Reject a deposit | The token's TIP-403 policy and the recipient's TIP-1028 receive policy, checked in the zone, and the sequencer via the `rejected` flag | A rejection is a public refund on Tempo. The sequencer can reject a deposit but can't redirect it. | -The last row is the boundary that matters most. A refund is public, so a token's policy controller can potentially learn who owns an address by blocking candidates and watching which deposits come back. Given that zones will presumably work with trusted issuers, we view this threat as minimal, but provide more details below ([Threat Model](#threat-model)). +The last row matters most. A refund is public, so a token's policy controller can learn who owns an address by blocking candidates and watching which deposits come back. Zones are expected to accept only trusted issuers, which keeps this risk small ([Threat Model](#threat-model)). ### Worked example @@ -124,9 +113,9 @@ Out of scope: An address is a deposit address if and only if bytes `[4:13]` equal `0xFCFCFCFCFCFCFCFCFC`. `zoneId` is big-endian at `[0:4]`, `version` is at `[13]`, and the ciphertext is at `[14:20]`. Zone ID zero is unregistered. -`version` is the key version. Values `0x01` through `0xFF` each select one zone key (see [Key versions](#key-versions)). Version `0x00` is unsupported and reverts on Tempo. +`version` is the key version. Values `0x01` through `0xFF` each select one zone key ([Key versions](#key-versions)). Version `0x00` is unsupported and reverts on Tempo. -Every address with the magic bytes is reserved, including version `0x00`. A reserved address MUST NOT receive a literal TIP-20 balance through any recipient-bearing operation, except a payout from a TIP-1034 channel opened before T15 (see [Changes to other components](#changes-to-other-components)). +Every address with the magic bytes is reserved, including version `0x00`. A reserved address MUST NOT receive a literal TIP-20 balance through any recipient-bearing operation, except a payout from a TIP-1034 channel opened before T15 ([Changes to other components](#changes-to-other-components)). TIP-1022 uses different magic bytes, `0xFDFDFDFDFDFDFDFDFDFD` at `[4:14]`. Routing never chains the two resolvers. @@ -134,9 +123,9 @@ TIP-1022 uses different magic bytes, `0xFDFDFDFDFDFDFDFDFDFD` at `[4:14]`. Routi The plaintext is 6 bytes: the 4-byte master ID followed by the 2-byte user tag. Every tag from `0x0000` through `0xFFFF` is valid. All 6 bytes are encrypted together, so neither field appears in the address. -Tags select aliases of one recipient registration. Derivation is deterministic for a fixed zone, version, key, master ID, and tag. The same master ID and tag give unrelated ciphertexts under different versions. +Tags select aliases of one registration. Derivation is deterministic for a fixed zone, version, key, master ID and tag. The same master ID and tag give unrelated ciphertexts under different versions. -The token is not part of the address. The deposited token MUST NOT affect the key, the tweak, or decryption, so every token resolves an address to the same registration. +The token is not part of the address. The deposited token MUST NOT affect the key, the tweak or decryption, so every token resolves an address to the same registration. ### FF1 encryption @@ -151,7 +140,7 @@ Addresses use FF1 with AES-256, as specified in [NIST SP 800-38G](https://csrc.n The tweak is the 12-byte ASCII string `TEMPO-ZVDA-v`, then the version number in decimal ASCII digits without leading zeros, then the 4 big-endian zone ID bytes. For version 1 the tweak is `0x54454D504F2D5A5644412D7631 || zoneId`, which is 17 bytes. For version 10 it is `0x54454D504F2D5A5644412D763130 || zoneId`, which is 18 bytes. -Each plaintext byte expands most-significant bit first, in byte order. The output packs in the same order, and decryption reverses this. Implementations MUST NOT truncate a conventional cipher, hash, or MAC in place of FF1. Every version uses the same FF1 parameters; only the key and the tweak's version digits differ. Conformance vectors are in [Interfaces](#ff1-conformance-vectors). +Each plaintext byte expands most-significant bit first, in byte order. The output packs in the same order, and decryption reverses this. Implementations MUST NOT truncate a conventional cipher, hash or MAC in place of FF1. Every version uses the same FF1 parameters; only the key and the tweak's version digits differ. Conformance vectors are in [Interfaces](#ff1-conformance-vectors). ## Key versions @@ -159,14 +148,14 @@ Each plaintext byte expands most-significant bit first, in byte order. The outpu FF1 decryption runs inside the native inbox, following the existing native ECIES model. There is no callable decrypt precompile, no cross-contract storage read, and no dependency on the removed `ZoneConfig` contract. -The native inbox at `0x1c00000000000000000000000000000000000001` stores keys by version (layout in [Interfaces](#storage-layouts)). Each version has a 0-or-1 initialized flag. The flag separates an unconfigured version from a configured all-zero key. FF1 has no proof of correct decryption, so every verifier holds the keys: zone full node operators and provers can read them from state. The redacted RPC never serves them. +The native inbox at `0x1c00000000000000000000000000000000000001` stores keys by version ([Storage layouts](#storage-layouts)). Each version has a 0-or-1 initialized flag, which separates an unconfigured version from a configured all-zero key. FF1 has no proof of correct decryption, so every verifier holds the keys: zone full node operators and provers can read them from state. The redacted RPC never serves them. -A key is set by the system-only call `initializeVirtualAddressKey(version, key)`. These rules apply: +A key is set by the system-only call `initializeVirtualAddressKey(version, key)`: 1. A zone block MUST NOT contain more than one key-initialization system transaction. If present, it comes immediately after `advanceTempo` and before user transactions. The block witness carries it as an optional `(version, key)` field. Blocks that do not advance Tempo MUST NOT contain it. 2. The block validator and prover MUST bind the witness field to the exact system transaction and enforce its position and system origin. An ordinary call with a claimed sender MUST NOT initialize a key. 3. The first initialization MUST use version `0x01`. Each later one MUST use the highest initialized version plus one. -4. Initialization MUST revert if its calldata is not the canonical ABI encoding of `(version, key)`, including any trailing bytes, or if `version` is `0x00`, out of order, or already initialized. This includes a repeat with the same key. +4. Initialization MUST revert if its calldata is not the canonical ABI encoding of `(version, key)`, including any trailing bytes, or if `version` is `0x00`, out of order, or already initialized, even with the same key. 5. Success stores the key, sets the flag in proof-covered state, and emits `VirtualAddressKeyInitialized(version)`. Configuring the address keys is part of running a T15 zone, as with the sequencer's other keys. Each key file the sequencer is given names its version. In each block that advances Tempo, the sequencer initializes the lowest configured version that is not yet in state, once the version before it is, right after `advanceTempo`, so at most one version per block. Initialized keys are read from state, so a sequencer only needs keys that are not yet rotated in. @@ -175,13 +164,13 @@ Existing zones start with no initialized version. Initialization cannot rewrite ### Key confidentiality -A key is confidential execution state. User-scoped storage and proof queries, transaction and block responses, traces, simulations, logs, and state dumps MUST NOT expose any key, initialization calldata, or decryption input. +A key is confidential execution state. User-scoped storage and proof queries, transaction and block responses, traces, simulations, logs and state dumps MUST NOT expose any key, initialization calldata or decryption input. -Every executing replica holds every initialized key, including RPC-only followers. So does every system that handles initialization, state, or batch witnesses. These systems need not hold the ECIES private key, but they are inside the FF1 confidentiality boundary. +Every executing replica holds every initialized key, including RPC-only followers, and so does every system that handles initialization, state or batch witnesses. These systems need not hold the ECIES private key, but they are inside the FF1 confidentiality boundary. ### Rotation -A version's key never changes. Rotation means initializing the next version. Replacing a key in place was rejected because it would change the recipient behind every outstanding address under that version. Each version's key MUST be generated uniformly at random, independently of every other version's key and every other zone's keys. A zone can initialize at most 255 versions in its lifetime. +A version's key never changes; rotation initializes the next version. Replacing a key in place would change the recipient behind every outstanding address under that version. Each version's key MUST be generated uniformly at random, independently of every other version's key and every other zone's keys. A zone can initialize at most 255 versions in its lifetime. Operators MUST keep every initialized key, with protected backups, for the life of the zone. A retired version's key is still needed for deposits already queued under it and to re-execute historical blocks. No call clears a key, and an operator cannot change the meaning of an initialized version. Addresses under an initialized version stay valid until the portal admin retires that version. @@ -191,21 +180,29 @@ To rotate, the operator: 2. Configures the key as the next version on the sequencers, which initialize it with the key-initialization system transaction. 3. Waits for the batch containing that block to settle. The new version becomes the issuance version. 4. Tells recipients to reissue addresses. A master ID and tag carry over: the same pair under the new version is a new, unrelated address for the same recipient. -5. Optionally, after recipients migrate, asks the portal admin to call `retireAddressVersionsBelow` on the portal (see [Portal controls](#portal-controls)). Tempo then reverts new transfers to older versions with `AddressVersionRetired(uint8)`. +5. Optionally, after recipients migrate, asks the portal admin to retire older versions ([Retiring versions](#retiring-versions)). -A leaked key plus one known address-to-recipient link, such as a past payment or a published address, reveals every address of that recipient under that version. The registry stays in confidential zone state, so the key alone does not name recipients. The key's holder can decrypt every address under that version. That reveals each address's master ID and tag, and so which addresses share a master. The holder can also derive every alias of a known master ID under that version. One known binding of a master ID to its recipient, for example from a sponsored registration or a past payment, then links every address under that master to that recipient. Addresses under other versions stay unlinkable without their keys. Rotation cannot undo disclosure of addresses already issued. +A key's holder can decrypt every address under that version, which reveals each address's master ID and tag, and so which addresses share a master. It can also derive every alias of a known master ID under that version. The registry stays in confidential zone state, so the key alone does not name recipients. One known binding of a master ID to its recipient, for example from a sponsored registration, a past payment or a published address, then links every address under that master to that recipient. Addresses under other versions stay unlinkable without their keys. Rotation cannot undo disclosure of addresses already issued. + +### Retiring versions + +The portal admin calls `retireAddressVersionsBelow(uint8 minimumVersion)` to raise the minimum accepted version, which starts at `0x01`. This is the portal's only new admin control. It is gated like the existing access-policy controls, so it is frozen once the admin abdicates `AccessPolicy`. + +The call MUST revert with `InvalidVersionRetirement(uint8)` unless `minimumVersion` is exactly the current minimum plus one, so each call retires one version and a mistyped value cannot retire every issued address. After it, `depositVirtual` reverts with `AddressVersionRetired(uint8)` for lower versions. Deposits already queued under a retired version are processed normally. Each call emits `AddressVersionsRetired(uint8)`. + +Retirement has no notice delay and fails on Tempo before funds move. The portal admin SHOULD announce a retirement in advance so recipients can reissue addresses. ## Registering a recipient ### The registry -A native zone registry precompile is deployed at `0x1C00000000000000000000000000000000000005` at the T15 boundary. It is separate from the TIP-1022 registry at `0xFDC0000000000000000000000000000000000000`. The zone registry stores only TIP-1094 master IDs, does not change the L1 registration API, and is never consulted when resolving a TIP-1022 virtual address. +A native zone registry precompile is deployed at `0x1C00000000000000000000000000000000000005` at the T15 boundary. It is separate from the TIP-1022 registry at `0xFDC0000000000000000000000000000000000000`. It stores only TIP-1094 master IDs, does not change the L1 registration API, and is never consulted when resolving a TIP-1022 virtual address. -The zone node and the prover MUST execute the same registry implementation. Calls follow the zone's existing direct-call-only precompile rules, transaction admission, and fee metering. +The zone node and the prover MUST execute the same registry implementation. Calls follow the zone's existing direct-call-only precompile rules, transaction admission and fee metering. -A recipient is registered with `registerMaster`, which takes the recipient and a salt and returns a master ID (see [Interfaces](#zone-registry)). Registration is permissionless. The caller need not be the recipient, and no recipient signature is needed. Registration gives the caller no authority over the recipient, its funds, or address issuance. A third party can pay for registration before the recipient has any funds. A recipient's own registration transaction may use sponsorship where the zone supports it. +`registerMaster` takes the recipient and a salt and returns a master ID ([Interfaces](#zone-registry)). Registration is permissionless: the caller need not be the recipient, and no recipient signature is needed. Registration gives the caller no authority over the recipient, its funds or address issuance. A third party can pay for registration before the recipient has any funds, and a recipient's own registration transaction may use sponsorship where the zone supports it. -A registration does not name a token. A registered master ID accepts any token enabled for deposits in the zone, including tokens enabled later. Registration does not enable a token. It does not bypass the deposit path's canonical-token, initialization, enablement, pause, fee, admission, or recipient-policy checks. Binding a registration to one token, with an optional any-token wildcard, was considered. It narrows the issuer-policy probing attack to one token's policy controller but does not close it, and it adds a token constraint to registration, processing, the RPC, and failure handling. +A registration does not name a token. A registered master ID accepts any token enabled for deposits in the zone, including tokens enabled later. Registration does not enable a token, and does not bypass the deposit path's canonical-token, initialization, enablement, pause, fee, admission or recipient-policy checks. Binding a registration to one token would only narrow the issuer-policy probing attack to one token's policy controller, while adding a token constraint to registration, processing, the RPC and failure handling. ### Request hash @@ -217,60 +214,80 @@ requestHash = keccak256(abi.encodePacked( )) ``` -The domain is the exact ASCII string `TEMPO-ZVDA-MASTER-v1`, with no terminator. Its `-v1` versions the request format and is unrelated to key versions. `zoneId` is the executing zone's configured 4-byte big-endian ID, not a caller-supplied value. `recipient` is exactly 20 bytes and `salt` exactly 32 bytes. Neither `msg.sender` nor transaction order affects `requestHash`. Because the hash includes the recipient, a copied request cannot redirect a registration. +The domain is the exact ASCII string `TEMPO-ZVDA-MASTER-v1`, with no terminator. Its `-v1` versions the request format and is unrelated to key versions. `zoneId` is the executing zone's configured 4-byte big-endian ID, not a caller-supplied value. `recipient` is exactly 20 bytes and `salt` exactly 32 bytes. Neither `msg.sender` nor transaction order affects `requestHash`. The hash includes the recipient, so a copied request cannot redirect a registration. ### ID allocation The registry assigns IDs in order from `0x00000000` through `0xFFFFFFFF`. A proof-covered `uint64 nextMasterId` starts at zero and can hold the exhausted value `0x100000000` without wrapping. `registerMaster` runs these steps: 1. Revert with `InvalidMasterAddress()` if `recipient` is zero, a TIP-20 token address, a TIP-1022 virtual address, or a deposit address. -2. If `requestHash` already has a record, return its ID. Do not advance the counter, write storage, or emit an event. +2. If `requestHash` already has a record, return its ID. Do not advance the counter, write storage or emit an event. 3. Revert with `MasterIdSpaceExhausted()` if `nextMasterId == 0x100000000`. 4. Assign the 4-byte big-endian value of `nextMasterId`. Store the recipient binding and the request record, then increment the counter. These writes MUST be atomic. Emit `MasterRegistered(recipient, masterId)`. -New IDs depend on execution order. Recipients MUST use the ID the registry assigned, from their `MasterRegistered` logs or a `registerMaster` simulation for themselves, and MUST NOT predict an ID. Deriving IDs from a recipient-bound hash with grinding would let clients predict them, but clients would pay for grinding and retry collisions in the 4-byte space. Copying a request is harmless: it maps to the same ID, bound to the same recipient. +New IDs depend on execution order. Recipients MUST use the ID the registry assigned, from their `MasterRegistered` logs or a `registerMaster` simulation for themselves, and MUST NOT predict an ID. Deriving IDs from a recipient-bound hash with grinding would make them predictable, but clients would pay for grinding and retry collisions in the 4-byte space. Copying a request is harmless: it maps to the same ID, bound to the same recipient. -Each master ID binds permanently to one recipient. No call can request, overwrite, delete, rotate, or reassign an ID or its binding. Sequential allocation prevents ID collisions. Several IDs MAY bind to one recipient through different salts; there is no one-ID-per-address or one-ID-per-recipient rule. ID `0x00000000` is valid. An unregistered ID is represented by a zero recipient. IDs are never reused, so a zone has a lifetime limit of 4,294,967,296 registrations. Master IDs are independent of key versions: one ID has aliases under every initialized version. +Each master ID binds permanently to one recipient. No call can request, overwrite, delete, rotate or reassign an ID or its binding. Sequential allocation prevents ID collisions. Several IDs MAY bind to one recipient through different salts; there is no one-ID-per-address or one-ID-per-recipient rule. ID `0x00000000` is valid. An unregistered ID is represented by a zero recipient. IDs are never reused, so a zone has a lifetime limit of 4,294,967,296 registrations. Master IDs are independent of key versions: one ID has aliases under every initialized version. IDs come from one shared counter, so any account can infer allocation order and the registration count, and a submitter can learn the ID of a registration it sponsors by reading the counter around it. Deposit addresses expose neither. ### Registry confidentiality -Registry lookup is internal to native execution and the authenticated issuance service. The precompile has no public getter and no enumeration API. Storage and proof RPCs, traces, receipts, logs, errors, and simulations MUST NOT expose another recipient's registration to an unauthorized user or to Tempo observers. Registration calldata and results are confidential zone data. Implementations MUST NOT publish a registration event or mapping on Tempo. The zone's `MasterRegistered` log is served only to its recipient ([Deriving addresses](#deriving-addresses)). +Registry lookup is internal to native execution and the authenticated issuance service. The precompile has no public getter and no enumeration API. Storage and proof RPCs, traces, receipts, logs, errors and simulations MUST NOT expose another recipient's registration to an unauthorized user or to Tempo observers. Registration calldata and results are confidential zone data. Implementations MUST NOT publish a registration event or mapping on Tempo. The zone's `MasterRegistered` log is served only to its recipient ([Issuing addresses](#issuing-addresses)). The native inbox and the prover read the proof-covered mapping internally, without a public getter call or an EVM2 cross-contract storage read. A missing or invalid registry witness invalidates execution. It is not evidence that an ID is unregistered. -A submitter knows the recipient and salt of its request and may learn the assigned ID. Even with the ID it cannot derive the recipient's addresses or see the recipient's private activity. A registration also does not show that the recipient agreed to it, or that the submitter owns the recipient. +A submitter knows the recipient and salt of its request and may learn the assigned ID. Even with the ID it cannot derive the recipient's addresses or see the recipient's private activity. A registration does not show that the recipient agreed to it, or that the submitter owns the recipient. ## Issuing addresses -The recipient gets addresses from the authenticated zone RPC (see [Recipient RPC](#recipient-rpc)). Issuance under a version MUST wait until both the registration and that version's key initialization are settled. Issuance uses the highest settled version unless the recipient asks for another. Issuance MUST NOT use a version below the portal's minimum accepted version. No other party can derive a recipient's addresses, including the account that paid for registration. +Only zone nodes hold the address keys, so a recipient gets its addresses from the zone's authenticated redacted RPC through one method, `zone_deriveDepositAddresses` ([RPC methods](#rpc-methods)). No index beyond zone state and logs is needed. + +### Authorization -Clients SHOULD NOT choose user tags at random. With 65,536 tags, random picks repeat long before the space is used up due to the Birthday Paradox. Clients SHOULD allocate tags in order without reuse. Wallets and apps that share a master ID SHOULD coordinate allocation, or use separate master IDs. Encryption hides the order. When a master ID runs out of tags, register another ID instead of wrapping the counter. Rotation does not reset tag allocation: reissuing tag `t` under a new version gives the same customer a new address. +The RPC uses the zone's existing authorization tokens. The caller is the token's account, including through authorized Keychain keys and configurable-account owners. A contract recipient needs one of those to act for it. Deploying a contract or paying for its registration grants no access. No other party can derive a recipient's addresses, including the account that paid for registration. + +### Finding master IDs + +A recipient finds its master IDs in its `MasterRegistered(recipient, masterId)` logs, which the registry emits the first time a master ID is assigned and the redacted RPC serves only to `recipient` (topic 1). Recipients MUST take their IDs from these logs, not from a simulation, since allocation depends on execution order. The redacted RPC refuses `eth_call`, `eth_estimateGas` and gas-estimating `eth_fillTransaction` of `registerMaster` unless the recipient is the caller, so simulations do not confirm another recipient's registrations; a submitter can still learn the ID of a registration it sponsors ([ID allocation](#id-allocation)). + +### Deriving addresses + +`zone_deriveDepositAddresses` returns one address per requested user tag, at most 1024 per call, for a master ID registered to the caller. The node reads the registry and key versions at the zone block the portal last settled (`ZonePortal.blockHash()` as of the latest finalized Tempo block), so a registration or key initialization is usable only once it has settled. The response names that block. Issuance under a version MUST wait until both the registration and that version's key initialization are settled. Issuance uses the highest settled version unless the recipient asks for another, and MUST NOT use a version below the portal's minimum accepted version. + +A `null` or absent `version` selects the highest initialized version. Any version that is uninitialized, zero, or below the portal's minimum accepted version is rejected with `-32602`. An unregistered master ID and another recipient's master ID are rejected with the same error, so the method does not reveal registrations. Nodes MUST NOT offer derivation for master IDs the caller does not own. Clients may cache addresses until their version is retired. + +### Choosing user tags + +Clients SHOULD NOT choose user tags at random: with 65,536 tags, random picks repeat long before the space is used up. Clients SHOULD allocate tags in order without reuse. Wallets and apps that share a master ID SHOULD coordinate allocation, or use separate master IDs. Encryption hides the order. When a master ID runs out of tags, register another ID instead of wrapping the counter. Rotation does not reset tag allocation: reissuing tag `t` under a new version gives the same customer a new address. Reusing an address is valid, but it links payments and can make attribution ambiguous. ## Sending to a deposit address +Virtual deposits are on for every zone from T15; no switch turns them on or off. + ### Routing on Tempo -Tempo intercepts exactly `transfer`, `transferFrom`, `transferWithMemo`, `transferFromWithMemo`, and `systemTransferFrom`. `mint` and `mintWithMemo` to a deposit address MUST revert with the existing TIP-20 `InvalidRecipient()` error. An issuer that wants to fund a deposit address mints to itself and then transfers. Mints are excluded because a failed mint has no sender to refund: handling it would need a new privileged TIP-20 burn of portal escrow that bypasses issuer roles, pauses, and policies. Fee-payment and reward-recipient paths MUST reject deposit addresses instead of queueing. +Tempo intercepts exactly `transfer`, `transferFrom`, `transferWithMemo`, `transferFromWithMemo` and `systemTransferFrom`. `mint` and `mintWithMemo` to a deposit address MUST revert with the existing TIP-20 `InvalidRecipient()` error; an issuer that wants to fund a deposit address mints to itself and then transfers. A failed mint has no sender to refund, and handling it would need a new privileged TIP-20 burn of portal escrow that bypasses issuer roles, pauses and policies. Fee-payment and reward-recipient paths MUST reject deposit addresses instead of queueing. For a transfer to a deposit address, Tempo MUST: 1. Revert with `UnsupportedAddressVersion(uint8)` if the version is `0x00`. Revert with `ZoneUnregistered(uint32)` if `zoneId` does not resolve to a registered portal. -2. Run the entrypoint's usual balance, pause, allowance, and spending-limit checks. TIP-403 checks the sender where it applies, and checks the portal as the Tempo recipient. TIP-1028 checks the portal using the operation's ordinary originator. A blocked TIP-1028 receive policy reverts the transfer; it does not divert escrow to `ReceivePolicyGuard`. +2. Run the entrypoint's usual balance, pause, allowance and spending-limit checks. TIP-403 checks the sender where it applies, and checks the portal as the Tempo recipient. TIP-1028 checks the portal using the operation's ordinary originator. A blocked TIP-1028 receive policy reverts the transfer; it does not divert escrow to `ReceivePolicyGuard`. 3. Revert if the amount does not fit the portal's `uint128` amount field. 4. Debit `from` and credit the portal. Never credit the deposit address itself. -5. Call the portal's `depositVirtual`. If it fails, revert the whole transfer, including balance changes, fees, allowances, and events. +5. Call the portal's `depositVirtual`. If it fails, revert the whole transfer, including balance changes, fees, allowances and events. The hidden recipient is checked only inside the zone. -The token calls `depositVirtual` exactly once, after crediting the portal, with its own address as `msg.sender`. Only a transfer made directly to the token routes: when another precompile moves the token to a deposit address (for example a fee AMM burn), the token reverts with `InvalidRecipient()`, since the portal would see that precompile as `msg.sender`. A zero-amount transfer to a deposit address reverts with `InvalidAmount()`: `transferFrom` of zero needs no allowance, so it could name any account as the originator. These portal rules are the same for the Solidity portal runtime and the native ZonePortal precompile. The portal derives the token from `msg.sender`. It MUST verify that the caller is an initialized canonical TIP-20 precompile and an enabled token. A user-supplied token parameter or an enabled ERC-20 is not enough. Only native transfer routing can make this call, and routing fixes every argument from the originating transfer. Ordinary contract calls cannot impersonate the token precompile. The call counts toward normal gas accounting and reentrancy protection. +The token calls `depositVirtual` exactly once, after crediting the portal, with its own address as `msg.sender`. Only a transfer made directly to the token routes: when another precompile moves the token to a deposit address (for example a fee AMM burn), the token reverts with `InvalidRecipient()`, since the portal would see that precompile as `msg.sender`. A zero-amount transfer to a deposit address reverts with `InvalidAmount()`: `transferFrom` of zero needs no allowance, so it could name any account as the originator. + +The portal derives the token from `msg.sender` and MUST verify that the caller is an initialized canonical TIP-20 precompile and an enabled token. A user-supplied token parameter or an enabled ERC-20 is not enough. Only native transfer routing can make this call, and routing fixes every argument from the originating transfer; ordinary contract calls cannot impersonate the token precompile. The call counts toward normal gas accounting and reentrancy protection. These portal rules are the same for the Solidity portal runtime and the native ZonePortal precompile. ### Portal checks -`depositVirtual` receives the tokens already credited and MUST NOT pull them again. Its `originator` is the debited account. For `transferFrom`, that is the owner, not the spender. `hasMemo` is true only for memo-bearing entrypoints, even when the memo is zero. When `hasMemo` is false, `memo` MUST be zero. One flag replaces separate memo and no-memo deposit types, which would duplicate the queue entry and API. There is no refund-address field: a failed deposit refunds `originator`. +`depositVirtual` receives the tokens already credited and MUST NOT pull them again. Its `originator` is the debited account; for `transferFrom`, that is the owner, not the spender. `hasMemo` is true only for memo-bearing entrypoints, even when the memo is zero. When `hasMemo` is false, `memo` MUST be zero. One flag replaces separate memo and no-memo deposit types, which would duplicate the queue entry and API. There is no refund-address field: a failed deposit refunds `originator`. The portal MUST run these checks in order, reverting at the first failure: @@ -278,7 +295,7 @@ The portal MUST run these checks in order, reverting at the first failure: 2. The magic bytes and its own zone ID. Otherwise revert with `InvalidVirtualDeposit()`. 3. `version` is nonzero and at least the minimum accepted version. Otherwise revert with `AddressVersionRetired(uint8)`. 4. `originator` is not a zone portal (`0x5AD0…` prefix). Otherwise revert with `InvalidBouncebackRecipient()`. A portal is the originator only when a withdrawal pays out to a deposit address; reverting makes the payout fail on Tempo so the withdrawal bounces back to its fallback recipient, instead of queuing a deposit whose refund no one could claim. -5. The existing deposit checks: portal and token pauses, token enablement, depositor membership, minimum amount, and fees. Depositor membership applies to `originator`, never to the routing call's caller. The existing refund-recipient validation applies to `originator`, which is also the refund recipient. A callback gateway therefore cannot originate a virtual deposit under access control: the gateway exception covers depositors, not refund recipients. All other access rules stay in force. +5. The existing deposit checks: portal and token pauses, token enablement, depositor membership, minimum amount and fees. Depositor membership applies to `originator`, never to the routing call's caller. The existing refund-recipient validation applies to `originator`, which is also the refund recipient. A callback gateway therefore cannot originate a virtual deposit under access control: the gateway exception covers depositors, not refund recipients. All other access rules stay in force. The fee is TIP-1171's deposit fee, operational plus congestion. A plain transfer cannot pass `maxFee`, so it accepts only the operational fee, like the legacy deposit signatures: while a congestion fee applies, the transfer reverts with `FeeTooHigh` and moves no funds. The one deposit a withdrawal callback may return pays no congestion fee. @@ -286,7 +303,7 @@ The fee is TIP-1171's deposit fee, operational plus congestion. A plain transfer This TIP appends `ZoneVirtual = 2` to the `DepositType` enum. `WithdrawalBounceBack = 0` and the ECIES `Deposit = 1` keep their values. Existing type values and payloads MUST NOT be reinterpreted. -The portal deducts and pays the existing deposit fee. It then builds a `VirtualDeposit` with the net amount and appends exactly one entry: +The portal deducts and pays the existing deposit fee, builds a `VirtualDeposit` with the net amount, and appends exactly one entry: ``` currentDepositQueueHash = keccak256(abi.encode( @@ -294,7 +311,7 @@ currentDepositQueueHash = keccak256(abi.encode( )) ``` -The portal increments the existing deposit counter and emits `VirtualDepositMade`. The new type changes the inbox's decoder and the execution proof. It does not change queue ordering, hash chaining, numbering, or settlement commitments. Only ECIES deposits consume `DecryptionData` entries; virtual deposits consume none. A virtual deposit's only sequencer input is the `rejected` flag ([Sequencer-side depositor allowlist](#portal-controls)). +The portal increments the existing deposit counter and emits `VirtualDepositMade`. The new type changes the inbox's decoder and the execution proof. It does not change queue ordering, hash chaining, numbering or settlement commitments. Only ECIES deposits consume `DecryptionData` entries; virtual deposits consume none. A virtual deposit's only sequencer input is the `rejected` flag ([Sequencer rejection](#sequencer-rejection)). ### Transfer events @@ -306,40 +323,38 @@ Routing follows TIP-1022's two-hop event convention, with the portal in place of These events come before the portal's fee-transfer events and `VirtualDepositMade`. The transfer never credits the deposit address. A revert removes all events. A successful transfer means the deposit is queued, not that the recipient is credited. -## Portal controls - -The portal adds one admin-only control, gated like the existing access-policy controls, so it is frozen once the admin abdicates `AccessPolicy`. Virtual deposits are on for every zone from T15; there is no switch that turns them on or off. A deposit to a version with no initialized key is refunded with `KeyUnconfigured` ([Processing in the zone](#processing-in-the-zone)). - -**Version retirement.** `retireAddressVersionsBelow(uint8 minimumVersion)` raises the minimum accepted version, which starts at `0x01`. The call MUST revert with `InvalidVersionRetirement(uint8)` unless `minimumVersion` is exactly the current minimum plus one, so each call retires one version and a single mistyped value cannot retire every issued address. After it, `depositVirtual` reverts with `AddressVersionRetired(uint8)` for lower versions. Deposits already queued under a retired version are processed normally. Each call emits `AddressVersionsRetired(uint8)`. - -Retirement has no notice delay. It fails on Tempo before funds move. The portal admin SHOULD announce a retirement in advance so recipients can reissue addresses. - -**Sequencer-side depositor allowlist.** The sequencer rejects a virtual deposit by setting `rejected` on the queued deposit. The zone refunds `originator`. `rejected` is a field of the per-deposit `QueuedDeposit` entry the sequencer passes to `advanceTempo`, next to the deposit's type and data. It is not part of the deposit hash chain: the inbox still checks each entry's type and data against the portal's queue hash. It is part of the zone block's input, so the execution proof covers it, as it covers `DecryptionData`. The inbox reads it only for virtual entries and ignores it on ECIES deposits and withdrawal bounce-backs. With the allowlist on, the sequencer sets the flag if `originator` isn't listed, or if the recipient it resolves from the parent zone state isn't listed. If the address doesn't resolve to a recipient, only `originator` is checked; the deposit fails in the zone anyway. Portal-enforced depositor membership still applies to `originator`. - ## Processing in the zone The native inbox consumes the authenticated queue in its existing order. The ECIES decoder does not change. A deposit address is not converted into an ECIES payload: each decoder produces a recipient, and both feed the same mint and failure handling. For a virtual deposit, the inbox: 1. Checks the `rejected` flag. If it is set, the inbox refunds `originator` and skips the remaining steps. -2. Checks the magic bytes, a nonzero version, and a matching zone ID. +2. Checks the magic bytes, a nonzero version and a matching zone ID. 3. Loads the committed key for that version and decrypts the 6-byte ciphertext. 4. Looks up the master ID in the zone registry, in the execution state at that point. 5. Mints to the recipient through the existing zone mint path: `mint` when `hasMemo` is false, `mintWithMemo` otherwise. -The lookup is covered by the zone state witness, not an L1 registry proof. The inbox MUST NOT cache absence across registrations. A registration executed after this deposit cannot change its result. The inbox MUST NOT reinterpret the ciphertext using the deposited token, or retry resolution against another registration. +After a successful mint or a recorded failure, the inbox advances the deposit queue once. The destination and decoded attribution are recorded only in recipient-authorized zone execution data. Ordinary withdrawals and internal withdrawal bounce-backs keep their existing behavior. + +### Sequencer rejection + +The sequencer rejects a virtual deposit by setting `rejected` on the queued deposit, and the zone refunds `originator`. `rejected` is a field of the per-deposit `QueuedDeposit` entry the sequencer passes to `advanceTempo`, next to the deposit's type and data. It is not part of the deposit hash chain: the inbox still checks each entry's type and data against the portal's queue hash. It is part of the zone block's input, so the execution proof covers it, as it covers `DecryptionData`. The inbox reads it only for virtual entries and ignores it on ECIES deposits and withdrawal bounce-backs. The sequencer can force the failure path with `rejected`, but can't pick a recipient. + +This is how the sequencer-side depositor allowlist applies to virtual deposits. With the allowlist on, the sequencer sets the flag if `originator` isn't listed, or if the recipient it resolves from the parent zone state isn't listed. If the address doesn't resolve to a recipient, only `originator` is checked; the deposit fails in the zone anyway. Portal-enforced depositor membership still applies to `originator`. + +### Lookup and mint + +The lookup is covered by the zone state witness, not an L1 registry proof. The inbox MUST NOT cache absence across registrations. A registration executed after this deposit cannot change its result. The inbox MUST NOT reinterpret the ciphertext using the deposited token, or retry resolution against another registration. An unregistered master ID takes the failure path; processing never registers it. The mint runs the ordinary zone recipient checks, including TIP-403 and the TIP-1028 precheck that prevents diverting a deposit into `ReceivePolicyGuard`. A successful virtual deposit credits exactly the registered recipient. The user tag is attribution metadata only. -Tempo-side checks cover the transfer's sender and the portal, not the hidden recipient. Inside the zone, the TIP-1028 precheck and the mint use `ZoneInbox` (`0x1c00000000000000000000000000000000000001`) as the sender, as for existing deposits. A recipient's sender allowlist therefore accepts or rejects the inbox as a whole. It cannot tell individual depositors apart on this path. The zone still checks the recipient's TIP-403 authorization and receive policy before crediting. +Tempo-side checks cover the transfer's sender and the portal, not the hidden recipient. Inside the zone, the TIP-1028 precheck and the mint use `ZoneInbox` (`0x1c00000000000000000000000000000000000001`) as the sender, as for existing deposits. A recipient's sender allowlist therefore accepts or rejects the inbox as a whole and cannot tell individual depositors apart on this path. The zone still checks the recipient's TIP-403 authorization and receive policy before crediting. -Any of these selects the committed failure action (see [Failures and refunds](#failures-and-refunds)): an invalid address encoding, a version with no initialized key at processing time, an unregistered master ID, or a caught recipient or mint rejection. Only the last one has a recipient, so only it emits `VirtualDepositFailed`; the others refund silently, like a rejected ECIES deposit. +### Deposit failures and execution failures -An unregistered master ID takes the failure path; processing never registers it. The sequencer can force the failure path with `rejected`, but can't pick a recipient. The flag is ignored on ECIES deposits and withdrawal bounce-backs. A failed mint's partial state MUST be rolled back before the failure is recorded. +Any of these selects the committed failure action ([Failures and refunds](#failures-and-refunds)): an invalid address encoding, a version with no initialized key at processing time (refunded with `KeyUnconfigured`), an unregistered master ID, or a caught recipient or mint rejection. Only the last one has a recipient, so only it emits `VirtualDepositFailed`; the others refund silently, like a rejected ECIES deposit. A failed mint's partial state MUST be rolled back before the failure is recorded. Execution-system failures are different. A missing or invalid witness, an inconsistent queue payload, out-of-gas, or a missing key for an initialized version invalidates the system transaction or the batch. Such a failure MUST NOT become a recipient failure or cancel a valid deposit. -After a successful mint or a recorded failure, the inbox advances the deposit queue once. The destination and decoded attribution are recorded only in recipient-authorized zone execution data. Ordinary withdrawals and internal withdrawal bounce-backs keep their existing behavior. - ## Failures and refunds | Deposit | Failure action | @@ -347,46 +362,32 @@ After a successful mint or a recorded failure, the inbox advances the deposit qu | Existing ECIES deposit | Existing refund to its `tempoRefundRecipient` | | Virtual deposit | Existing refund to `originator` | -A failed virtual deposit calls the existing inbox-only outbox bounce-back operation with the token, the net amount, and `originator`. After the batch settles, the portal attempts the refund and charges the existing processing fee when it can collect it. It parks undeliverable amounts in its existing refund registry. Membership, token pauses, and receive-policy changes can delay delivery or require a later claim. They never cause a second zone mint or a second bounce-back. +A failed virtual deposit calls the existing inbox-only outbox bounce-back operation with the token, the net amount and `originator`. After the batch settles, the portal attempts the refund and charges the existing processing fee when it can collect it. It parks undeliverable amounts in its existing refund registry. Membership, token pauses and receive-policy changes can delay delivery or require a later claim. They never cause a second zone mint or a second bounce-back. TIP-1028's `ReceivePolicyGuard` cannot hold a failed deposit inside the zone, because its recovery authority exists only on Tempo. -## Recipient RPC +## Deposit results -A recipient needs two things from the zone: its deposit addresses, which only the zone can compute because only zone nodes hold the address key, and the outcome of each deposit sent to them. The authenticated zone RPC provides the first with one method, `zone_deriveDepositAddresses`. The second uses the existing private `eth_getLogs` over the inbox's result events. Neither needs an index beyond zone state and logs. +A recipient reads the outcome of each deposit through the redacted RPC's existing private `eth_getLogs` over the inbox's result events, with the same [authorization](#authorization) as address derivation. -### Authorization - -Both use the zone's authenticated redacted RPC and its existing authorization tokens. The caller is the token's account, including through authorized Keychain keys and configurable-account owners. A contract recipient needs one of those to act for it. Deploying a contract or paying for its registration grants no access. - -### Deriving addresses - -`zone_deriveDepositAddresses` returns one address per requested user tag for a master ID registered to the caller. At most 1024 tags are accepted per call. The node reads the registry and key versions at the zone block the portal last settled (`ZonePortal.blockHash()` as of the latest finalized Tempo block), so a registration or key initialization is usable only once it has settled. The response names that block. - -A `null` or absent `version` selects the highest initialized version. Any version that is uninitialized, zero, or below the portal's minimum accepted version is rejected with `-32602`. An unregistered master ID and another recipient's master ID are rejected with the same error, so the method does not reveal registrations. Nodes MUST NOT offer derivation for master IDs the caller does not own. Clients may cache addresses until their version is retired. - -A recipient finds its master IDs in its `MasterRegistered(recipient, masterId)` logs, which the registry emits the first time a master ID is assigned and the redacted RPC serves only to `recipient` (topic 1). Recipients MUST take their IDs from these logs, not from a simulation, since allocation depends on execution order. The redacted RPC refuses `eth_call`, `eth_estimateGas`, and gas-estimating `eth_fillTransaction` of `registerMaster` unless the recipient is the caller, so simulations do not confirm another recipient's registrations; a submitter can still learn the ID of a registration it sponsors, as above. - -### Deposit results - -`VirtualDepositProcessed` and `VirtualDepositFailed` index the resolved recipient `to` first. The redacted RPC serves them through `eth_getLogs`, filters, and receipts only to that recipient, and only when the zone inbox emitted them. The caller filters by topic 0 and its own address in topic 1. Both carry the originator, token, net amount, master ID, and user tag. `VirtualDepositProcessed` also carries the version and memo. The originator is never served them unless it is also the recipient (a self-funded deposit), because they name the recipient behind the address it paid. +`VirtualDepositProcessed` and `VirtualDepositFailed` index the resolved recipient `to` first. The redacted RPC serves them through `eth_getLogs`, filters and receipts only to that recipient, and only when the zone inbox emitted them. The caller filters by topic 0 and its own address in topic 1. Both carry the originator, token, net amount, master ID and user tag. `VirtualDepositProcessed` also carries the version and memo. The originator is never served them unless it is also the recipient (a self-funded deposit), because they name the recipient behind the address it paid. A recipient sees a failed deposit only if lookup resolved to it before the failure. Failures that never identified a recipient (sequencer rejections, invalid encodings, unconfigured keys, unregistered master IDs) have a zero `to` and are served to no one. `VirtualDepositFailed` means a refund was enqueued, not that it was delivered on Tempo; the existing refund records track that. ## Changes to other components -- **TIP-1022.** L1 master registration MUST reject deposit addresses. If an older L1 master matches the format, TIP-1022 resolution reverts. The zone registry rejects deposit addresses, zero, TIP-1022 virtual addresses, and token addresses as recipients. Neither resolver forwards into the other. -- **TIP-20 inside a zone.** All seven recipient-bearing entrypoints reject deposit addresses as destinations with `InvalidRecipient()`: the five intercepted on Tempo, plus `mint` and `mintWithMemo`. Withdrawal requests reject a deposit address as `to` with `InvalidWithdrawalRecipient()`, and as fallback recipient with `InvalidFallbackRecipient()`. Refund-recipient fields, reward recipients, and literal policy-subject operations also reject them. Zero is not a valid refund address. +- **TIP-1022.** L1 master registration MUST reject deposit addresses. If an older L1 master matches the format, TIP-1022 resolution reverts. The zone registry rejects deposit addresses, zero, TIP-1022 virtual addresses and token addresses as recipients. Neither resolver forwards into the other. +- **TIP-20 inside a zone.** All seven recipient-bearing entrypoints reject deposit addresses as destinations with `InvalidRecipient()`: the five intercepted on Tempo, plus `mint` and `mintWithMemo`. Withdrawal requests reject a deposit address as `to` with `InvalidWithdrawalRecipient()`, and as fallback recipient with `InvalidFallbackRecipient()`. Refund-recipient fields, reward recipients and literal policy-subject operations also reject them. Zero is not a valid refund address. - **TIP-1034.** From T15, channel `open` rejects a deposit address as payee with `InvalidPayee()`. A channel payout is not one of the routed transfer entrypoints, and a deposit address can never submit vouchers, so such a channel could never pay out. Channels opened before T15 are unaffected: their payouts to a payee in the deposit-address format stay literal TIP-20 credits, since such an address had no owner before T15 either. -- **Literal addresses.** Approvals and transaction origination keep literal-address semantics. The reservation does not prove that no account or contract exists at a deposit address. This TIP does not sweep, route, or burn any balance an address held before T15. -- **TIP-1180.** When identity enforcement is on, a virtual deposit is checked like any deposit: from the L1 `originator` to the recipient found in the zone registry, after the lookup and before the mint. A denied deposit is refunded to `originator` with reason `MintFailed`. That refund is public on Tempo, so, like issuer-policy probing, a sender can learn whether its originator is allowed to pay the hidden recipient. The portal keeps the minimum accepted version in its own slot at the end of the portal layout. +- **Literal addresses.** Approvals and transaction origination keep literal-address semantics. The reservation does not prove that no account or contract exists at a deposit address. This TIP does not sweep, route or burn any balance an address held before T15. +- **TIP-1180.** When identity enforcement is on, a virtual deposit is checked like any deposit: from the L1 `originator` to the recipient found in the zone registry, after the lookup and before the mint. A denied deposit is refunded to `originator` with reason `MintFailed`. That refund is public on Tempo, so, like issuer-policy probing, a sender can learn whether its originator is allowed to pay the hidden recipient. - **ECIES deposits.** Unchanged, including the encrypted memo, except that `tempoRefundRecipient` cannot be a deposit address. The portal reverts such a deposit with `InvalidBouncebackRecipient()`, as it does for a TIP-1022 virtual address: a parked refund is claimed by the address it is parked under, which a deposit address can never be. ## Execution budget -Each FF1 decryption costs a fixed `ZVDA_DECRYPT_GAS = 10_000`, independent of the key, plaintext, and ciphertext. Registry storage, existing policy reads, and the mint cost extra. +Each FF1 decryption costs a fixed `ZVDA_DECRYPT_GAS = 10_000`, independent of the key, plaintext and ciphertext. Registry storage, existing policy reads and the mint cost extra. -Registration meters its fixed-size hash, input, and storage operations normally. Key initialization uses ordinary system-call input and storage metering. Tempo routing and queueing use normal native and EVM gas. +Registration meters its fixed-size hash, input and storage operations normally. Key initialization uses ordinary system-call input and storage metering. Tempo routing and queueing use normal native and EVM gas. A `ZoneVirtual` entry counts as one deposit in TIP-1171's per-block limit. A block of `DEPOSITS_PER_BUCKET` virtual entries, each taking the worst case (decode, decrypt, a successful registry lookup, a failed policy check and mint, then the refund), MUST fit the zone system-transaction budget. @@ -504,6 +505,8 @@ Zone registry precompile: A new request pays ordinary hash, counter, and new-storage costs. Ordinary fees and zone admission are what limit state growth and ID exhaustion. +Portal: the minimum accepted version takes its own slot at the end of the portal layout. + Native inbox: the address keys are `mapping(uint8 version => bytes32 key)`, declared after the existing inbox fields. A zero key means the version is not initialized, so `initializeVirtualAddressKey` rejects a zero key. ### RPC methods @@ -531,21 +534,21 @@ Each vector MUST round-trip. The version-2 and version-10 vectors reuse the vers # Compatibility -All rows describe specified behavior unless marked otherwise. No implementation exists yet, so no row describes observed behavior of this TIP. - | Integration | What changes | |---|---| -| Sending wallets and exchanges | A plain TIP-20 transfer to a deposit address works with no custom payload. The transfer can succeed on Tempo and still fail in the zone. The refund then arrives later, minus fees, at the debited account ([Failures and refunds](#failures-and-refunds)). Untested risk: exchange withdrawal systems may not expect late refunds, or transfers that revert with `FeeTooHigh` while a congestion fee applies ([Portal checks](#portal-checks)). | +| Sending wallets and exchanges | A plain TIP-20 transfer to a deposit address works with no custom payload. The transfer can succeed on Tempo and still fail in the zone; the refund then arrives later, minus fees, at the debited account ([Failures and refunds](#failures-and-refunds)). Untested risk: exchange withdrawal systems may not expect late refunds, or transfers that revert with `FeeTooHigh` while a congestion fee applies ([Portal checks](#portal-checks)). | | Routers and forwarding contracts | A refund goes to the debited account, not to the router's end user. Routers must handle late refunds and claims, and may be unable to attribute a refund to the user it belongs to. Use the ECIES API with an explicit `tempoRefundRecipient` when that control is needed. | | Token issuers | `mint` and `mintWithMemo` to a deposit address revert with `InvalidRecipient()` ([Routing on Tempo](#routing-on-tempo)). Mint to yourself, then transfer. | | Receiving businesses | Register once per zone and wait for settlement before requesting addresses ([Issuing addresses](#issuing-addresses)). Reissue addresses after a key rotation. | | Zone operators | Running a T15 zone includes giving the sequencers each new key, with its version, before it is rotated in, and keeping every key with protected backups ([Key versions](#key-versions)). | -| Zones using the sequencer-side depositor allowlist | The allowlist rejects virtual deposits from unlisted originators or to unlisted recipients by setting `rejected`. They're refunded to `originator` ([Portal controls](#portal-controls)). | -| Future portal deposit authorizations | Deduction: a plain transfer cannot carry a signed deposit authorization. Any later authorization mode for the portal needs its own rule for virtual deposits. | +| Zones using the sequencer-side depositor allowlist | The allowlist rejects virtual deposits from unlisted originators or to unlisted recipients by setting `rejected`. They're refunded to `originator` ([Sequencer rejection](#sequencer-rejection)). | +| Future portal deposit authorizations | A plain transfer cannot carry a signed deposit authorization, so any later authorization mode for the portal needs its own rule for virtual deposits. | | ECIES depositors | `tempoRefundRecipient` cannot be a deposit address; the portal reverts such a deposit with `InvalidBouncebackRecipient()`. | | Zone wallets | Zone TIP-20 transfers to a deposit address revert with `InvalidRecipient()`. Withdrawals reject one as `to` or fallback recipient ([Changes to other components](#changes-to-other-components)). | | TIP-1034 channel payers | From T15, `open` rejects a deposit-address payee with `InvalidPayee()`. Channels opened earlier are unaffected. | +# Tooling + SDKs expose: - permissionless registration, with random salt generation and no grinding; @@ -553,7 +556,7 @@ SDKs expose: - address derivation through `zone_deriveDepositAddresses` and results through `eth_getLogs`; - the conformance vectors. -Clients keep the recipient and salt so they can retry a registration safely. They use a new salt to request another master ID for the same recipient. Wallets should show the destination zone next to the address. They should distinguish a queued deposit from a credited one. +Clients keep the recipient and salt so they can retry a registration safely, and use a new salt to request another master ID for the same recipient. Wallets should show the destination zone next to the address, and distinguish a queued deposit from a credited one. Operator runbooks cover key initialization, witness and replica confidentiality, backups, and rotation and retirement. These procedures are not consensus rules. @@ -564,7 +567,7 @@ Operator runbooks cover key initialization, witness and replica confidentiality, | `VirtualDepositMade` | Portal | Was a transfer to a deposit address queued, for how much, with what fee and deposit number? | | `AddressVersionsRetired` | Portal | Which key versions does this portal still accept? | | `VirtualAddressKeyInitialized` | Native inbox (zone) | Which key versions has the zone initialized, and in which block? | -| `Transfer`, `TransferWithMemo` | TIP-20 | Which deposit address did the sender pay? (see [Transfer events](#transfer-events)) | +| `Transfer`, `TransferWithMemo` | TIP-20 | Which deposit address did the sender pay? ([Transfer events](#transfer-events)) | Evidence for each stage: @@ -576,35 +579,35 @@ Evidence for each stage: | Refund delivered or parked | Existing refund events distinguish a delivered refund from a parked claim. | | Key initialized or rotated | `VirtualAddressKeyInitialized(version)` from the inbox. Recipients see the change in the version `zone_deriveDepositAddresses` returns. | -Missing evidence: this TIP does not specify how a sender matches a refund on Tempo to the deposit it reverses. +This TIP does not specify how a sender matches a refund on Tempo to the deposit it reverses. -Public events and errors MUST NOT contain decrypted identifiers, failure reasons, or key material. The inbox emits `VirtualDepositProcessed` for a credit and `VirtualDepositFailed` for a failed mint, and nothing for earlier failures. Both are served only to the resolved recipient ([Deposit results](#deposit-results)). System and witness failures are reported separately and never produce a committed failure result. +Public events and errors MUST NOT contain decrypted identifiers, failure reasons or key material. The inbox emits `VirtualDepositProcessed` for a credit and `VirtualDepositFailed` for a failed mint, and nothing for earlier failures. Both are served only to the resolved recipient ([Deposit results](#deposit-results)). System and witness failures are reported separately and never produce a committed failure result. # Threat Model The most consequential attack is **issuer-policy probing**. A token's TIP-403 policy controller can learn who owns a deposit address. The zone checks the hidden recipient against the token's policy before crediting, and a rejection produces a public refund on Tempo. To test whether address `X` belongs to Carol, the controller blocks Carol, sends a small deposit to `X`, and watches for a refund. Blocking half of a candidate set per probe finds one recipient among `2^k` candidates in `k` probes, for `k` deposit and refund fees. -Any accepted token's controller can probe any deposit address, including through a token the zone accepts after the address was issued. ECIES deposits leak in a weaker way: the controller gets one observation per deposit someone else makes. Deposit addresses let the controller probe whenever it likes. Zones should accept only tokens with trusted issuers and policy controllers. That reduces the risk but does not remove it. Private failure reasons, delays, or fees do not help, because the refund itself is public. Closing the attack needs private failure handling inside the zone, which this TIP does not provide. +Any accepted token's controller can probe any deposit address, including through a token the zone accepts after the address was issued. ECIES deposits leak more weakly: the controller gets one observation per deposit someone else makes, while deposit addresses let it probe whenever it likes. Zones should accept only tokens with trusted issuers and policy controllers, which reduces the risk but does not remove it. Private failure reasons, delays or fees do not help, because the refund itself is public. Closing the attack needs private failure handling inside the zone, which this TIP does not provide. -The sequencer-side allowlist leaks in a similar way. Anyone can learn whether a known account is listed by sending it an ECIES deposit and watching for a refund; that already holds today. A deposit address adds a new leak: whether its hidden owner is listed right now. The prober cannot change the list, but every listing or delisting is a fresh probe. If an address switches between refunded and credited right after account `X` is listed or delisted, `X` is its owner. When few accounts change at once, this identifies the owner outright. The prober must wait for list changes and pay a deposit and refund fee per probe, so the leak is slower than issuer-policy probing, but it does not need a malicious issuer. Zones that list and delist often should treat deposit-address ownership as visible to anyone willing to pay those fees. +The sequencer-side allowlist leaks in a similar way. Anyone can already learn whether a known account is listed by sending it an ECIES deposit and watching for a refund. A deposit address adds a new leak: whether its hidden owner is listed right now. The prober cannot change the list, but every listing or delisting is a fresh probe: if an address switches between refunded and credited right after account `X` is listed or delisted, `X` is its owner. When few accounts change at once, this identifies the owner outright. The prober must wait for list changes and pay a deposit and refund fee per probe, so the leak is slower than issuer-policy probing, but it does not need a malicious issuer. Zones that list and delist often should treat deposit-address ownership as visible to anyone willing to pay those fees. | Actor | Capability and trust | Boundary check and failure consequence | |---|---|---| -| Tempo observer or depositor | Sees the zone, version, token, amount, sender, address, and memo of every deposit. Trusted with nothing. | FF1 encryption and the confidential registry ([Address format](#address-format), [Registry confidentiality](#registry-confidentiality)). It can link reuse of one address, but not learn its master ID or recipient. | +| Tempo observer or depositor | Sees the zone, version, token, amount, sender, address and memo of every deposit. Trusted with nothing. | FF1 encryption and the confidential registry ([Address format](#address-format), [Registry confidentiality](#registry-confidentiality)). It can link reuse of one address, but not learn its master ID or recipient. | | Token policy controller | Sets the token's TIP-403 policy, which the zone applies to the hidden recipient. Trusted not to probe recipients. | None. It can identify address owners by probing (above). Zones limit exposure by accepting only trusted tokens. | -| Registration submitter | Chooses the recipient and salt of its own request and pays for it. Trusted with nothing. | The request hash binds the recipient, and issuance needs the recipient's authorization ([ID allocation](#id-allocation), [Authorization](#authorization)). It can use up IDs and infer allocation order, but cannot choose an ID, take over a binding, redirect funds, or issue addresses. | -| Operator, sequencer, and other key holders | Hold every FF1 key and the registry, sequence blocks, and run the RPC. Trusted to keep keys and the registry confidential. | Recipient selection is proof-covered with no sequencer input ([Processing in the zone](#processing-in-the-zone)). A malicious operator can withhold service, disclose keys and mappings, or reject any deposit with `rejected` (refunded to `originator`), but can't change a recipient or a key. | +| Registration submitter | Chooses the recipient and salt of its own request and pays for it. Trusted with nothing. | The request hash binds the recipient, and issuance needs the recipient's authorization ([ID allocation](#id-allocation), [Authorization](#authorization)). It can use up IDs and infer allocation order, but cannot choose an ID, take over a binding, redirect funds or issue addresses. | +| Operator, sequencer and other key holders | Hold every FF1 key and the registry, sequence blocks and run the RPC. Trusted to keep keys and the registry confidential. | Recipient selection is proof-covered with no sequencer input ([Processing in the zone](#processing-in-the-zone)). A malicious operator can withhold service, disclose keys and mappings, or reject any deposit with `rejected` (refunded to `originator`), but can't change a recipient or a key. | | Issuance service | Returns addresses to recipients. Trusted to return the requested master's address. | Only authentication of the service. A malicious service can hand out an address for the wrong master; nothing in the address lets the recipient check it. | -| Portal admin | Retires key versions. Trusted to retire versions only after recipients migrate. | Retirement reverts new transfers on Tempo before funds move and leaves queued deposits alone ([Portal controls](#portal-controls)). A careless admin can break issued addresses, but cannot strand queued funds or lower the minimum version again. | +| Portal admin | Retires key versions. Trusted to retire versions only after recipients migrate. | Retirement reverts new transfers on Tempo before funds move and leaves queued deposits alone ([Retiring versions](#retiring-versions)). A careless admin can break issued addresses, but cannot strand queued funds or lower the minimum version again. | -A leaked key reveals the master ID and tag behind every address under that version, past and future. With one known master-ID-to-recipient binding, it links every address under that master to that recipient. A version has no forward secrecy. Rotation limits the exposure to the leaked version (see [Rotation](#rotation)). +A leaked key reveals the master ID and tag behind every address under that version, past and future, and with one known master-ID-to-recipient binding links every address under that master to that recipient. A version has no forward secrecy; rotation limits the exposure to the leaked version ([Rotation](#rotation)). The FF1 keys protect privacy. Committed execution protects recipient selection once an address is issued. Apart from the sequencer's `rejected` flag, deleting a local key or withholding a witness cannot legitimately turn a configured address's deposit into a refund. Proof verification and confidential-state handling must keep these cases apart. Residual risks: -- **Corrupted addresses.** Every 6-byte ciphertext decrypts to some plaintext. With `N` registered master IDs, a random ciphertext under an initialized version resolves to some registered master with probability `N / 2^32`, before recipient checks. A corrupted address can therefore credit the wrong recipient. Including the zone and version in the tweak changes the permutation, but does not authenticate the address. This TIP adds no checksum. FF1 provides confidentiality and invertibility, not authentication. Recipients must distribute addresses through authenticated channels, and senders must keep the complete address. -- **Linkability.** Each version has `2^48` addresses, and each master ID has 65,536 tags per version. Deterministic derivation reveals address reuse. Amounts, timing, public memos, and outside knowledge can also link deposits. Public enumeration of a candidate master's tags would reveal its address set, which is why issuance requires authentication. Keep private attribution out of public memos. +- **Corrupted addresses.** Every 6-byte ciphertext decrypts to some plaintext. With `N` registered master IDs, a random ciphertext under an initialized version resolves to some registered master with probability `N / 2^32`, before recipient checks, so a corrupted address can credit the wrong recipient. Including the zone and version in the tweak changes the permutation, but does not authenticate the address. This TIP adds no checksum: FF1 provides confidentiality and invertibility, not authentication. Recipients must distribute addresses through authenticated channels, and senders must keep the complete address. +- **Linkability.** Each version has `2^48` addresses, and each master ID has 65,536 tags per version. Deterministic derivation reveals address reuse. Amounts, timing, public memos and outside knowledge can also link deposits. Public enumeration of a candidate master's tags would reveal its address set, which is why issuance requires authentication. Keep private attribution out of public memos. - **ID exhaustion and state growth.** Registration needs no proof of work, so registration fees and zone admission must cover state growth and the permanent 4,294,967,296-registration cap. Wider IDs would not remove this risk. Exhaustion stops new registrations only; existing master IDs keep working. - **Disclosure by the operator.** A malicious operator or a public export can reveal registry mappings. Registrations and their execution data otherwise share the zone's confidentiality boundary. From 25c395b3d211428899aff6c5ba277b1e45219329 Mon Sep 17 00:00:00 2001 From: 0xrusowsky <90208954+0xrusowsky@users.noreply.github.com> Date: Sat, 21 Nov 2026 08:44:17 +0000 Subject: [PATCH 2/3] docs(tip-1094): link zones spec locally --- tips/tip-1094.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tips/tip-1094.md b/tips/tip-1094.md index caf1be013b..fcc854a9c3 100644 --- a/tips/tip-1094.md +++ b/tips/tip-1094.md @@ -16,7 +16,7 @@ This TIP lets anyone deposit into a zone with an ordinary TIP-20 transfer on Tem ## Motivation -Zones accept user deposits only through the portal's `deposit()` and `depositEncrypted()` calls ([Zones protocol](https://github.com/tempoxyz/zones/blob/a88c2ac6b6b407225e2861c660806faccc0217df/specs/spec.md#deposits)). Both require the sender to build an ECIES payload that encrypts the recipient and memo to the sequencer's key. Wallets, exchanges and payment systems can send ordinary TIP-20 transfers, but would need integration work to build that payload and call the portal. +Zones accept user deposits only through the portal's `deposit()` and `depositEncrypted()` calls ([Zones protocol](../zones/specs/spec.md#deposits)). Both require the sender to build an ECIES payload that encrypts the recipient and memo to the sequencer's key. Wallets, exchanges and payment systems can send ordinary TIP-20 transfers, but would need integration work to build that payload and call the portal. This TIP gives each zone recipient reusable addresses on Tempo that work with a plain transfer and do not reveal the recipient. The zone registers the recipient privately and assigns it a 4-byte master ID. The recipient adds a 2-byte user tag to tell senders apart. The zone encrypts those 6 bytes with FF1, a NIST cipher whose output is the same size as its input, and puts the ciphertext in the address. Only the zone holds the key, so only the zone can recover the master ID and credit the recipient. From 28673952b2e35ad18fa07d03588f6ff57cf6dec3 Mon Sep 17 00:00:00 2001 From: 0xrusowsky <90208954+0xrusowsky@users.noreply.github.com> Date: Sat, 21 Nov 2026 14:34:52 +0000 Subject: [PATCH 3/3] docs(tip-1094): minimize rewrite diff --- tips/tip-1094.md | 113 ++++++++++++++++++++++++----------------------- 1 file changed, 57 insertions(+), 56 deletions(-) diff --git a/tips/tip-1094.md b/tips/tip-1094.md index fcc854a9c3..9ac052bca7 100644 --- a/tips/tip-1094.md +++ b/tips/tip-1094.md @@ -12,7 +12,10 @@ protocolVersion: T15 ## Abstract -This TIP lets anyone deposit into a zone with an ordinary TIP-20 transfer on Tempo. A zone deposit address holds a public zone ID, a key version and a 6-byte ciphertext that only the zone can decrypt. Tempo routes a transfer to such an address into the zone's portal as a virtual deposit. The zone decrypts the ciphertext, looks up the registered recipient and credits it, or refunds the sender on Tempo if the deposit fails. Refunds are public, so a token's policy controller can learn who owns an address by blocking candidates and watching for refunds. +This TIP lets anyone deposit into a zone with an ordinary TIP-20 transfer on mainnet. The Zone deposit virtual address holds a public zone ID, a key version, and a 6-byte ciphertext. Only the zone can decrypt the ciphertext to determine which address to credit in the zone. + +Upon TIP-20 detecting a transfer to a Zone Virtual Deposit Address, the protocol reroutes the transfer to the zone and initiates a zone deposit. The zone then decrypts the ciphertext and processes the deposit if possible. The zone credits the registered recipient, or refunds the sender on Tempo if the deposit fails. + ## Motivation @@ -20,7 +23,7 @@ Zones accept user deposits only through the portal's `deposit()` and `depositEnc This TIP gives each zone recipient reusable addresses on Tempo that work with a plain transfer and do not reveal the recipient. The zone registers the recipient privately and assigns it a 4-byte master ID. The recipient adds a 2-byte user tag to tell senders apart. The zone encrypts those 6 bytes with FF1, a NIST cipher whose output is the same size as its input, and puts the ciphertext in the address. Only the zone holds the key, so only the zone can recover the master ID and credit the recipient. -Addresses are computed from the master ID and tag, so there is no per-address state. Registration and lookup stay in confidential zone state, so Tempo never learns that a recipient registered. Each zone has its own registry; receiving in several zones takes one registration in each. +Because addresses are computed from the master ID and tag, there is no per-address state. Registration and lookup stay in confidential zone state, so Tempo mainnet never learns that a recipient registered. Each zone has its own registry; receiving in several zones takes one registration in each. ## Assumptions @@ -66,7 +69,7 @@ A deposit address is a reserved 20-byte address: the zone ID, magic bytes, a key ### Authority boundary -Each step has one party that can authorize it, and the checks that limit it are proof-covered or enforced on Tempo: +Each step has one party that can authorize it, and the checks that limit them are proof-covered or enforced on Tempo: | Step | Who authorizes it | What limits them | |---|---|---| @@ -113,9 +116,9 @@ Out of scope: An address is a deposit address if and only if bytes `[4:13]` equal `0xFCFCFCFCFCFCFCFCFC`. `zoneId` is big-endian at `[0:4]`, `version` is at `[13]`, and the ciphertext is at `[14:20]`. Zone ID zero is unregistered. -`version` is the key version. Values `0x01` through `0xFF` each select one zone key ([Key versions](#key-versions)). Version `0x00` is unsupported and reverts on Tempo. +`version` is the key version. Values `0x01` through `0xFF` each select one zone key (see [Key versions](#key-versions)). Version `0x00` is unsupported and reverts on Tempo. -Every address with the magic bytes is reserved, including version `0x00`. A reserved address MUST NOT receive a literal TIP-20 balance through any recipient-bearing operation, except a payout from a TIP-1034 channel opened before T15 ([Changes to other components](#changes-to-other-components)). +Every address with the magic bytes is reserved, including version `0x00`. A reserved address MUST NOT receive a literal TIP-20 balance through any recipient-bearing operation, except a payout from a TIP-1034 channel opened before T15 (see [Changes to other components](#changes-to-other-components)). TIP-1022 uses different magic bytes, `0xFDFDFDFDFDFDFDFDFDFD` at `[4:14]`. Routing never chains the two resolvers. @@ -123,9 +126,9 @@ TIP-1022 uses different magic bytes, `0xFDFDFDFDFDFDFDFDFDFD` at `[4:14]`. Routi The plaintext is 6 bytes: the 4-byte master ID followed by the 2-byte user tag. Every tag from `0x0000` through `0xFFFF` is valid. All 6 bytes are encrypted together, so neither field appears in the address. -Tags select aliases of one registration. Derivation is deterministic for a fixed zone, version, key, master ID and tag. The same master ID and tag give unrelated ciphertexts under different versions. +Tags select aliases of one recipient registration. Derivation is deterministic for a fixed zone, version, key, master ID, and tag. The same master ID and tag give unrelated ciphertexts under different versions. -The token is not part of the address. The deposited token MUST NOT affect the key, the tweak or decryption, so every token resolves an address to the same registration. +The token is not part of the address. The deposited token MUST NOT affect the key, the tweak, or decryption, so every token resolves an address to the same registration. ### FF1 encryption @@ -140,7 +143,7 @@ Addresses use FF1 with AES-256, as specified in [NIST SP 800-38G](https://csrc.n The tweak is the 12-byte ASCII string `TEMPO-ZVDA-v`, then the version number in decimal ASCII digits without leading zeros, then the 4 big-endian zone ID bytes. For version 1 the tweak is `0x54454D504F2D5A5644412D7631 || zoneId`, which is 17 bytes. For version 10 it is `0x54454D504F2D5A5644412D763130 || zoneId`, which is 18 bytes. -Each plaintext byte expands most-significant bit first, in byte order. The output packs in the same order, and decryption reverses this. Implementations MUST NOT truncate a conventional cipher, hash or MAC in place of FF1. Every version uses the same FF1 parameters; only the key and the tweak's version digits differ. Conformance vectors are in [Interfaces](#ff1-conformance-vectors). +Each plaintext byte expands most-significant bit first, in byte order. The output packs in the same order, and decryption reverses this. Implementations MUST NOT truncate a conventional cipher, hash, or MAC in place of FF1. Every version uses the same FF1 parameters; only the key and the tweak's version digits differ. Conformance vectors are in [Interfaces](#ff1-conformance-vectors). ## Key versions @@ -148,14 +151,14 @@ Each plaintext byte expands most-significant bit first, in byte order. The outpu FF1 decryption runs inside the native inbox, following the existing native ECIES model. There is no callable decrypt precompile, no cross-contract storage read, and no dependency on the removed `ZoneConfig` contract. -The native inbox at `0x1c00000000000000000000000000000000000001` stores keys by version ([Storage layouts](#storage-layouts)). Each version has a 0-or-1 initialized flag, which separates an unconfigured version from a configured all-zero key. FF1 has no proof of correct decryption, so every verifier holds the keys: zone full node operators and provers can read them from state. The redacted RPC never serves them. +The native inbox at `0x1c00000000000000000000000000000000000001` stores keys by version (layout in [Interfaces](#storage-layouts)). Each version has a 0-or-1 initialized flag. The flag separates an unconfigured version from a configured all-zero key. FF1 has no proof of correct decryption, so every verifier holds the keys: zone full node operators and provers can read them from state. The redacted RPC never serves them. -A key is set by the system-only call `initializeVirtualAddressKey(version, key)`: +A key is set by the system-only call `initializeVirtualAddressKey(version, key)`. These rules apply: 1. A zone block MUST NOT contain more than one key-initialization system transaction. If present, it comes immediately after `advanceTempo` and before user transactions. The block witness carries it as an optional `(version, key)` field. Blocks that do not advance Tempo MUST NOT contain it. 2. The block validator and prover MUST bind the witness field to the exact system transaction and enforce its position and system origin. An ordinary call with a claimed sender MUST NOT initialize a key. 3. The first initialization MUST use version `0x01`. Each later one MUST use the highest initialized version plus one. -4. Initialization MUST revert if its calldata is not the canonical ABI encoding of `(version, key)`, including any trailing bytes, or if `version` is `0x00`, out of order, or already initialized, even with the same key. +4. Initialization MUST revert if its calldata is not the canonical ABI encoding of `(version, key)`, including any trailing bytes, or if `version` is `0x00`, out of order, or already initialized. This includes a repeat with the same key. 5. Success stores the key, sets the flag in proof-covered state, and emits `VirtualAddressKeyInitialized(version)`. Configuring the address keys is part of running a T15 zone, as with the sequencer's other keys. Each key file the sequencer is given names its version. In each block that advances Tempo, the sequencer initializes the lowest configured version that is not yet in state, once the version before it is, right after `advanceTempo`, so at most one version per block. Initialized keys are read from state, so a sequencer only needs keys that are not yet rotated in. @@ -164,13 +167,13 @@ Existing zones start with no initialized version. Initialization cannot rewrite ### Key confidentiality -A key is confidential execution state. User-scoped storage and proof queries, transaction and block responses, traces, simulations, logs and state dumps MUST NOT expose any key, initialization calldata or decryption input. +A key is confidential execution state. User-scoped storage and proof queries, transaction and block responses, traces, simulations, logs, and state dumps MUST NOT expose any key, initialization calldata, or decryption input. -Every executing replica holds every initialized key, including RPC-only followers, and so does every system that handles initialization, state or batch witnesses. These systems need not hold the ECIES private key, but they are inside the FF1 confidentiality boundary. +Every executing replica holds every initialized key, including RPC-only followers. So does every system that handles initialization, state, or batch witnesses. These systems need not hold the ECIES private key, but they are inside the FF1 confidentiality boundary. ### Rotation -A version's key never changes; rotation initializes the next version. Replacing a key in place would change the recipient behind every outstanding address under that version. Each version's key MUST be generated uniformly at random, independently of every other version's key and every other zone's keys. A zone can initialize at most 255 versions in its lifetime. +A version's key never changes. Rotation means initializing the next version. Replacing a key in place was rejected because it would change the recipient behind every outstanding address under that version. Each version's key MUST be generated uniformly at random, independently of every other version's key and every other zone's keys. A zone can initialize at most 255 versions in its lifetime. Operators MUST keep every initialized key, with protected backups, for the life of the zone. A retired version's key is still needed for deposits already queued under it and to re-execute historical blocks. No call clears a key, and an operator cannot change the meaning of an initialized version. Addresses under an initialized version stay valid until the portal admin retires that version. @@ -188,17 +191,17 @@ A key's holder can decrypt every address under that version, which reveals each The portal admin calls `retireAddressVersionsBelow(uint8 minimumVersion)` to raise the minimum accepted version, which starts at `0x01`. This is the portal's only new admin control. It is gated like the existing access-policy controls, so it is frozen once the admin abdicates `AccessPolicy`. -The call MUST revert with `InvalidVersionRetirement(uint8)` unless `minimumVersion` is exactly the current minimum plus one, so each call retires one version and a mistyped value cannot retire every issued address. After it, `depositVirtual` reverts with `AddressVersionRetired(uint8)` for lower versions. Deposits already queued under a retired version are processed normally. Each call emits `AddressVersionsRetired(uint8)`. +The call MUST revert with `InvalidVersionRetirement(uint8)` unless `minimumVersion` is exactly the current minimum plus one, so each call retires one version and a single mistyped value cannot retire every issued address. After it, `depositVirtual` reverts with `AddressVersionRetired(uint8)` for lower versions. Deposits already queued under a retired version are processed normally. Each call emits `AddressVersionsRetired(uint8)`. -Retirement has no notice delay and fails on Tempo before funds move. The portal admin SHOULD announce a retirement in advance so recipients can reissue addresses. +Retirement has no notice delay. It fails on Tempo before funds move. The portal admin SHOULD announce a retirement in advance so recipients can reissue addresses. ## Registering a recipient ### The registry -A native zone registry precompile is deployed at `0x1C00000000000000000000000000000000000005` at the T15 boundary. It is separate from the TIP-1022 registry at `0xFDC0000000000000000000000000000000000000`. It stores only TIP-1094 master IDs, does not change the L1 registration API, and is never consulted when resolving a TIP-1022 virtual address. +A native zone registry precompile is deployed at `0x1C00000000000000000000000000000000000005` at the T15 boundary. It is separate from the TIP-1022 registry at `0xFDC0000000000000000000000000000000000000`. The zone registry stores only TIP-1094 master IDs, does not change the L1 registration API, and is never consulted when resolving a TIP-1022 virtual address. -The zone node and the prover MUST execute the same registry implementation. Calls follow the zone's existing direct-call-only precompile rules, transaction admission and fee metering. +The zone node and the prover MUST execute the same registry implementation. Calls follow the zone's existing direct-call-only precompile rules, transaction admission, and fee metering. `registerMaster` takes the recipient and a salt and returns a master ID ([Interfaces](#zone-registry)). Registration is permissionless: the caller need not be the recipient, and no recipient signature is needed. Registration gives the caller no authority over the recipient, its funds or address issuance. A third party can pay for registration before the recipient has any funds, and a recipient's own registration transaction may use sponsorship where the zone supports it. @@ -214,30 +217,30 @@ requestHash = keccak256(abi.encodePacked( )) ``` -The domain is the exact ASCII string `TEMPO-ZVDA-MASTER-v1`, with no terminator. Its `-v1` versions the request format and is unrelated to key versions. `zoneId` is the executing zone's configured 4-byte big-endian ID, not a caller-supplied value. `recipient` is exactly 20 bytes and `salt` exactly 32 bytes. Neither `msg.sender` nor transaction order affects `requestHash`. The hash includes the recipient, so a copied request cannot redirect a registration. +The domain is the exact ASCII string `TEMPO-ZVDA-MASTER-v1`, with no terminator. Its `-v1` versions the request format and is unrelated to key versions. `zoneId` is the executing zone's configured 4-byte big-endian ID, not a caller-supplied value. `recipient` is exactly 20 bytes and `salt` exactly 32 bytes. Neither `msg.sender` nor transaction order affects `requestHash`. Because the hash includes the recipient, a copied request cannot redirect a registration. ### ID allocation The registry assigns IDs in order from `0x00000000` through `0xFFFFFFFF`. A proof-covered `uint64 nextMasterId` starts at zero and can hold the exhausted value `0x100000000` without wrapping. `registerMaster` runs these steps: 1. Revert with `InvalidMasterAddress()` if `recipient` is zero, a TIP-20 token address, a TIP-1022 virtual address, or a deposit address. -2. If `requestHash` already has a record, return its ID. Do not advance the counter, write storage or emit an event. +2. If `requestHash` already has a record, return its ID. Do not advance the counter, write storage, or emit an event. 3. Revert with `MasterIdSpaceExhausted()` if `nextMasterId == 0x100000000`. 4. Assign the 4-byte big-endian value of `nextMasterId`. Store the recipient binding and the request record, then increment the counter. These writes MUST be atomic. Emit `MasterRegistered(recipient, masterId)`. -New IDs depend on execution order. Recipients MUST use the ID the registry assigned, from their `MasterRegistered` logs or a `registerMaster` simulation for themselves, and MUST NOT predict an ID. Deriving IDs from a recipient-bound hash with grinding would make them predictable, but clients would pay for grinding and retry collisions in the 4-byte space. Copying a request is harmless: it maps to the same ID, bound to the same recipient. +New IDs depend on execution order. Recipients MUST use the ID the registry assigned, from their `MasterRegistered` logs or a `registerMaster` simulation for themselves, and MUST NOT predict an ID. Deriving IDs from a recipient-bound hash with grinding would let clients predict them, but clients would pay for grinding and retry collisions in the 4-byte space. Copying a request is harmless: it maps to the same ID, bound to the same recipient. -Each master ID binds permanently to one recipient. No call can request, overwrite, delete, rotate or reassign an ID or its binding. Sequential allocation prevents ID collisions. Several IDs MAY bind to one recipient through different salts; there is no one-ID-per-address or one-ID-per-recipient rule. ID `0x00000000` is valid. An unregistered ID is represented by a zero recipient. IDs are never reused, so a zone has a lifetime limit of 4,294,967,296 registrations. Master IDs are independent of key versions: one ID has aliases under every initialized version. +Each master ID binds permanently to one recipient. No call can request, overwrite, delete, rotate, or reassign an ID or its binding. Sequential allocation prevents ID collisions. Several IDs MAY bind to one recipient through different salts; there is no one-ID-per-address or one-ID-per-recipient rule. ID `0x00000000` is valid. An unregistered ID is represented by a zero recipient. IDs are never reused, so a zone has a lifetime limit of 4,294,967,296 registrations. Master IDs are independent of key versions: one ID has aliases under every initialized version. IDs come from one shared counter, so any account can infer allocation order and the registration count, and a submitter can learn the ID of a registration it sponsors by reading the counter around it. Deposit addresses expose neither. ### Registry confidentiality -Registry lookup is internal to native execution and the authenticated issuance service. The precompile has no public getter and no enumeration API. Storage and proof RPCs, traces, receipts, logs, errors and simulations MUST NOT expose another recipient's registration to an unauthorized user or to Tempo observers. Registration calldata and results are confidential zone data. Implementations MUST NOT publish a registration event or mapping on Tempo. The zone's `MasterRegistered` log is served only to its recipient ([Issuing addresses](#issuing-addresses)). +Registry lookup is internal to native execution and the authenticated issuance service. The precompile has no public getter and no enumeration API. Storage and proof RPCs, traces, receipts, logs, errors, and simulations MUST NOT expose another recipient's registration to an unauthorized user or to Tempo observers. Registration calldata and results are confidential zone data. Implementations MUST NOT publish a registration event or mapping on Tempo. The zone's `MasterRegistered` log is served only to its recipient ([Deriving addresses](#deriving-addresses)). The native inbox and the prover read the proof-covered mapping internally, without a public getter call or an EVM2 cross-contract storage read. A missing or invalid registry witness invalidates execution. It is not evidence that an ID is unregistered. -A submitter knows the recipient and salt of its request and may learn the assigned ID. Even with the ID it cannot derive the recipient's addresses or see the recipient's private activity. A registration does not show that the recipient agreed to it, or that the submitter owns the recipient. +A submitter knows the recipient and salt of its request and may learn the assigned ID. Even with the ID it cannot derive the recipient's addresses or see the recipient's private activity. A registration also does not show that the recipient agreed to it, or that the submitter owns the recipient. ## Issuing addresses @@ -249,7 +252,7 @@ The RPC uses the zone's existing authorization tokens. The caller is the token's ### Finding master IDs -A recipient finds its master IDs in its `MasterRegistered(recipient, masterId)` logs, which the registry emits the first time a master ID is assigned and the redacted RPC serves only to `recipient` (topic 1). Recipients MUST take their IDs from these logs, not from a simulation, since allocation depends on execution order. The redacted RPC refuses `eth_call`, `eth_estimateGas` and gas-estimating `eth_fillTransaction` of `registerMaster` unless the recipient is the caller, so simulations do not confirm another recipient's registrations; a submitter can still learn the ID of a registration it sponsors ([ID allocation](#id-allocation)). +A recipient finds its master IDs in its `MasterRegistered(recipient, masterId)` logs, which the registry emits the first time a master ID is assigned and the redacted RPC serves only to `recipient` (topic 1). Recipients MUST take their IDs from these logs, not from a simulation, since allocation depends on execution order. The redacted RPC refuses `eth_call`, `eth_estimateGas`, and gas-estimating `eth_fillTransaction` of `registerMaster` unless the recipient is the caller, so simulations do not confirm another recipient's registrations; a submitter can still learn the ID of a registration it sponsors, as above. ### Deriving addresses @@ -259,7 +262,7 @@ A `null` or absent `version` selects the highest initialized version. Any versio ### Choosing user tags -Clients SHOULD NOT choose user tags at random: with 65,536 tags, random picks repeat long before the space is used up. Clients SHOULD allocate tags in order without reuse. Wallets and apps that share a master ID SHOULD coordinate allocation, or use separate master IDs. Encryption hides the order. When a master ID runs out of tags, register another ID instead of wrapping the counter. Rotation does not reset tag allocation: reissuing tag `t` under a new version gives the same customer a new address. +Clients SHOULD NOT choose user tags at random. With 65,536 tags, random picks repeat long before the space is used up due to the Birthday Paradox. Clients SHOULD allocate tags in order without reuse. Wallets and apps that share a master ID SHOULD coordinate allocation, or use separate master IDs. Encryption hides the order. When a master ID runs out of tags, register another ID instead of wrapping the counter. Rotation does not reset tag allocation: reissuing tag `t` under a new version gives the same customer a new address. Reusing an address is valid, but it links payments and can make attribution ambiguous. @@ -274,10 +277,10 @@ Tempo intercepts exactly `transfer`, `transferFrom`, `transferWithMemo`, `transf For a transfer to a deposit address, Tempo MUST: 1. Revert with `UnsupportedAddressVersion(uint8)` if the version is `0x00`. Revert with `ZoneUnregistered(uint32)` if `zoneId` does not resolve to a registered portal. -2. Run the entrypoint's usual balance, pause, allowance and spending-limit checks. TIP-403 checks the sender where it applies, and checks the portal as the Tempo recipient. TIP-1028 checks the portal using the operation's ordinary originator. A blocked TIP-1028 receive policy reverts the transfer; it does not divert escrow to `ReceivePolicyGuard`. +2. Run the entrypoint's usual balance, pause, allowance, and spending-limit checks. TIP-403 checks the sender where it applies, and checks the portal as the Tempo recipient. TIP-1028 checks the portal using the operation's ordinary originator. A blocked TIP-1028 receive policy reverts the transfer; it does not divert escrow to `ReceivePolicyGuard`. 3. Revert if the amount does not fit the portal's `uint128` amount field. 4. Debit `from` and credit the portal. Never credit the deposit address itself. -5. Call the portal's `depositVirtual`. If it fails, revert the whole transfer, including balance changes, fees, allowances and events. +5. Call the portal's `depositVirtual`. If it fails, revert the whole transfer, including balance changes, fees, allowances, and events. The hidden recipient is checked only inside the zone. @@ -287,7 +290,7 @@ The portal derives the token from `msg.sender` and MUST verify that the caller i ### Portal checks -`depositVirtual` receives the tokens already credited and MUST NOT pull them again. Its `originator` is the debited account; for `transferFrom`, that is the owner, not the spender. `hasMemo` is true only for memo-bearing entrypoints, even when the memo is zero. When `hasMemo` is false, `memo` MUST be zero. One flag replaces separate memo and no-memo deposit types, which would duplicate the queue entry and API. There is no refund-address field: a failed deposit refunds `originator`. +`depositVirtual` receives the tokens already credited and MUST NOT pull them again. Its `originator` is the debited account. For `transferFrom`, that is the owner, not the spender. `hasMemo` is true only for memo-bearing entrypoints, even when the memo is zero. When `hasMemo` is false, `memo` MUST be zero. One flag replaces separate memo and no-memo deposit types, which would duplicate the queue entry and API. There is no refund-address field: a failed deposit refunds `originator`. The portal MUST run these checks in order, reverting at the first failure: @@ -295,7 +298,7 @@ The portal MUST run these checks in order, reverting at the first failure: 2. The magic bytes and its own zone ID. Otherwise revert with `InvalidVirtualDeposit()`. 3. `version` is nonzero and at least the minimum accepted version. Otherwise revert with `AddressVersionRetired(uint8)`. 4. `originator` is not a zone portal (`0x5AD0…` prefix). Otherwise revert with `InvalidBouncebackRecipient()`. A portal is the originator only when a withdrawal pays out to a deposit address; reverting makes the payout fail on Tempo so the withdrawal bounces back to its fallback recipient, instead of queuing a deposit whose refund no one could claim. -5. The existing deposit checks: portal and token pauses, token enablement, depositor membership, minimum amount and fees. Depositor membership applies to `originator`, never to the routing call's caller. The existing refund-recipient validation applies to `originator`, which is also the refund recipient. A callback gateway therefore cannot originate a virtual deposit under access control: the gateway exception covers depositors, not refund recipients. All other access rules stay in force. +5. The existing deposit checks: portal and token pauses, token enablement, depositor membership, minimum amount, and fees. Depositor membership applies to `originator`, never to the routing call's caller. The existing refund-recipient validation applies to `originator`, which is also the refund recipient. A callback gateway therefore cannot originate a virtual deposit under access control: the gateway exception covers depositors, not refund recipients. All other access rules stay in force. The fee is TIP-1171's deposit fee, operational plus congestion. A plain transfer cannot pass `maxFee`, so it accepts only the operational fee, like the legacy deposit signatures: while a congestion fee applies, the transfer reverts with `FeeTooHigh` and moves no funds. The one deposit a withdrawal callback may return pays no congestion fee. @@ -303,7 +306,7 @@ The fee is TIP-1171's deposit fee, operational plus congestion. A plain transfer This TIP appends `ZoneVirtual = 2` to the `DepositType` enum. `WithdrawalBounceBack = 0` and the ECIES `Deposit = 1` keep their values. Existing type values and payloads MUST NOT be reinterpreted. -The portal deducts and pays the existing deposit fee, builds a `VirtualDeposit` with the net amount, and appends exactly one entry: +The portal deducts and pays the existing deposit fee. It then builds a `VirtualDeposit` with the net amount and appends exactly one entry: ``` currentDepositQueueHash = keccak256(abi.encode( @@ -328,7 +331,7 @@ These events come before the portal's fee-transfer events and `VirtualDepositMad The native inbox consumes the authenticated queue in its existing order. The ECIES decoder does not change. A deposit address is not converted into an ECIES payload: each decoder produces a recipient, and both feed the same mint and failure handling. For a virtual deposit, the inbox: 1. Checks the `rejected` flag. If it is set, the inbox refunds `originator` and skips the remaining steps. -2. Checks the magic bytes, a nonzero version and a matching zone ID. +2. Checks the magic bytes, a nonzero version, and a matching zone ID. 3. Loads the committed key for that version and decrypts the 6-byte ciphertext. 4. Looks up the master ID in the zone registry, in the execution state at that point. 5. Mints to the recipient through the existing zone mint path: `mint` when `hasMemo` is false, `mintWithMemo` otherwise. @@ -347,11 +350,11 @@ The lookup is covered by the zone state witness, not an L1 registry proof. The i The mint runs the ordinary zone recipient checks, including TIP-403 and the TIP-1028 precheck that prevents diverting a deposit into `ReceivePolicyGuard`. A successful virtual deposit credits exactly the registered recipient. The user tag is attribution metadata only. -Tempo-side checks cover the transfer's sender and the portal, not the hidden recipient. Inside the zone, the TIP-1028 precheck and the mint use `ZoneInbox` (`0x1c00000000000000000000000000000000000001`) as the sender, as for existing deposits. A recipient's sender allowlist therefore accepts or rejects the inbox as a whole and cannot tell individual depositors apart on this path. The zone still checks the recipient's TIP-403 authorization and receive policy before crediting. +Tempo-side checks cover the transfer's sender and the portal, not the hidden recipient. Inside the zone, the TIP-1028 precheck and the mint use `ZoneInbox` (`0x1c00000000000000000000000000000000000001`) as the sender, as for existing deposits. A recipient's sender allowlist therefore accepts or rejects the inbox as a whole. It cannot tell individual depositors apart on this path. The zone still checks the recipient's TIP-403 authorization and receive policy before crediting. ### Deposit failures and execution failures -Any of these selects the committed failure action ([Failures and refunds](#failures-and-refunds)): an invalid address encoding, a version with no initialized key at processing time (refunded with `KeyUnconfigured`), an unregistered master ID, or a caught recipient or mint rejection. Only the last one has a recipient, so only it emits `VirtualDepositFailed`; the others refund silently, like a rejected ECIES deposit. A failed mint's partial state MUST be rolled back before the failure is recorded. +Any of these selects the committed failure action (see [Failures and refunds](#failures-and-refunds)): an invalid address encoding, a version with no initialized key at processing time (refunded with `KeyUnconfigured`), an unregistered master ID, or a caught recipient or mint rejection. Only the last one has a recipient, so only it emits `VirtualDepositFailed`; the others refund silently, like a rejected ECIES deposit. A failed mint's partial state MUST be rolled back before the failure is recorded. Execution-system failures are different. A missing or invalid witness, an inconsistent queue payload, out-of-gas, or a missing key for an initialized version invalidates the system transaction or the batch. Such a failure MUST NOT become a recipient failure or cancel a valid deposit. @@ -362,7 +365,7 @@ Execution-system failures are different. A missing or invalid witness, an incons | Existing ECIES deposit | Existing refund to its `tempoRefundRecipient` | | Virtual deposit | Existing refund to `originator` | -A failed virtual deposit calls the existing inbox-only outbox bounce-back operation with the token, the net amount and `originator`. After the batch settles, the portal attempts the refund and charges the existing processing fee when it can collect it. It parks undeliverable amounts in its existing refund registry. Membership, token pauses and receive-policy changes can delay delivery or require a later claim. They never cause a second zone mint or a second bounce-back. +A failed virtual deposit calls the existing inbox-only outbox bounce-back operation with the token, the net amount, and `originator`. After the batch settles, the portal attempts the refund and charges the existing processing fee when it can collect it. It parks undeliverable amounts in its existing refund registry. Membership, token pauses, and receive-policy changes can delay delivery or require a later claim. They never cause a second zone mint or a second bounce-back. TIP-1028's `ReceivePolicyGuard` cannot hold a failed deposit inside the zone, because its recovery authority exists only on Tempo. @@ -370,24 +373,24 @@ TIP-1028's `ReceivePolicyGuard` cannot hold a failed deposit inside the zone, be A recipient reads the outcome of each deposit through the redacted RPC's existing private `eth_getLogs` over the inbox's result events, with the same [authorization](#authorization) as address derivation. -`VirtualDepositProcessed` and `VirtualDepositFailed` index the resolved recipient `to` first. The redacted RPC serves them through `eth_getLogs`, filters and receipts only to that recipient, and only when the zone inbox emitted them. The caller filters by topic 0 and its own address in topic 1. Both carry the originator, token, net amount, master ID and user tag. `VirtualDepositProcessed` also carries the version and memo. The originator is never served them unless it is also the recipient (a self-funded deposit), because they name the recipient behind the address it paid. +`VirtualDepositProcessed` and `VirtualDepositFailed` index the resolved recipient `to` first. The redacted RPC serves them through `eth_getLogs`, filters, and receipts only to that recipient, and only when the zone inbox emitted them. The caller filters by topic 0 and its own address in topic 1. Both carry the originator, token, net amount, master ID, and user tag. `VirtualDepositProcessed` also carries the version and memo. The originator is never served them unless it is also the recipient (a self-funded deposit), because they name the recipient behind the address it paid. A recipient sees a failed deposit only if lookup resolved to it before the failure. Failures that never identified a recipient (sequencer rejections, invalid encodings, unconfigured keys, unregistered master IDs) have a zero `to` and are served to no one. `VirtualDepositFailed` means a refund was enqueued, not that it was delivered on Tempo; the existing refund records track that. ## Changes to other components -- **TIP-1022.** L1 master registration MUST reject deposit addresses. If an older L1 master matches the format, TIP-1022 resolution reverts. The zone registry rejects deposit addresses, zero, TIP-1022 virtual addresses and token addresses as recipients. Neither resolver forwards into the other. -- **TIP-20 inside a zone.** All seven recipient-bearing entrypoints reject deposit addresses as destinations with `InvalidRecipient()`: the five intercepted on Tempo, plus `mint` and `mintWithMemo`. Withdrawal requests reject a deposit address as `to` with `InvalidWithdrawalRecipient()`, and as fallback recipient with `InvalidFallbackRecipient()`. Refund-recipient fields, reward recipients and literal policy-subject operations also reject them. Zero is not a valid refund address. +- **TIP-1022.** L1 master registration MUST reject deposit addresses. If an older L1 master matches the format, TIP-1022 resolution reverts. The zone registry rejects deposit addresses, zero, TIP-1022 virtual addresses, and token addresses as recipients. Neither resolver forwards into the other. +- **TIP-20 inside a zone.** All seven recipient-bearing entrypoints reject deposit addresses as destinations with `InvalidRecipient()`: the five intercepted on Tempo, plus `mint` and `mintWithMemo`. Withdrawal requests reject a deposit address as `to` with `InvalidWithdrawalRecipient()`, and as fallback recipient with `InvalidFallbackRecipient()`. Refund-recipient fields, reward recipients, and literal policy-subject operations also reject them. Zero is not a valid refund address. - **TIP-1034.** From T15, channel `open` rejects a deposit address as payee with `InvalidPayee()`. A channel payout is not one of the routed transfer entrypoints, and a deposit address can never submit vouchers, so such a channel could never pay out. Channels opened before T15 are unaffected: their payouts to a payee in the deposit-address format stay literal TIP-20 credits, since such an address had no owner before T15 either. -- **Literal addresses.** Approvals and transaction origination keep literal-address semantics. The reservation does not prove that no account or contract exists at a deposit address. This TIP does not sweep, route or burn any balance an address held before T15. -- **TIP-1180.** When identity enforcement is on, a virtual deposit is checked like any deposit: from the L1 `originator` to the recipient found in the zone registry, after the lookup and before the mint. A denied deposit is refunded to `originator` with reason `MintFailed`. That refund is public on Tempo, so, like issuer-policy probing, a sender can learn whether its originator is allowed to pay the hidden recipient. +- **Literal addresses.** Approvals and transaction origination keep literal-address semantics. The reservation does not prove that no account or contract exists at a deposit address. This TIP does not sweep, route, or burn any balance an address held before T15. +- **TIP-1180.** When identity enforcement is on, a virtual deposit is checked like any deposit: from the L1 `originator` to the recipient found in the zone registry, after the lookup and before the mint. A denied deposit is refunded to `originator` with reason `MintFailed`. That refund is public on Tempo, so, like issuer-policy probing, a sender can learn whether its originator is allowed to pay the hidden recipient. The portal keeps the minimum accepted version in its own slot at the end of the portal layout. - **ECIES deposits.** Unchanged, including the encrypted memo, except that `tempoRefundRecipient` cannot be a deposit address. The portal reverts such a deposit with `InvalidBouncebackRecipient()`, as it does for a TIP-1022 virtual address: a parked refund is claimed by the address it is parked under, which a deposit address can never be. ## Execution budget -Each FF1 decryption costs a fixed `ZVDA_DECRYPT_GAS = 10_000`, independent of the key, plaintext and ciphertext. Registry storage, existing policy reads and the mint cost extra. +Each FF1 decryption costs a fixed `ZVDA_DECRYPT_GAS = 10_000`, independent of the key, plaintext, and ciphertext. Registry storage, existing policy reads, and the mint cost extra. -Registration meters its fixed-size hash, input and storage operations normally. Key initialization uses ordinary system-call input and storage metering. Tempo routing and queueing use normal native and EVM gas. +Registration meters its fixed-size hash, input, and storage operations normally. Key initialization uses ordinary system-call input and storage metering. Tempo routing and queueing use normal native and EVM gas. A `ZoneVirtual` entry counts as one deposit in TIP-1171's per-block limit. A block of `DEPOSITS_PER_BUCKET` virtual entries, each taking the worst case (decode, decrypt, a successful registry lookup, a failed policy check and mint, then the refund), MUST fit the zone system-transaction budget. @@ -505,8 +508,6 @@ Zone registry precompile: A new request pays ordinary hash, counter, and new-storage costs. Ordinary fees and zone admission are what limit state growth and ID exhaustion. -Portal: the minimum accepted version takes its own slot at the end of the portal layout. - Native inbox: the address keys are `mapping(uint8 version => bytes32 key)`, declared after the existing inbox fields. A zero key means the version is not initialized, so `initializeVirtualAddressKey` rejects a zero key. ### RPC methods @@ -536,13 +537,13 @@ Each vector MUST round-trip. The version-2 and version-10 vectors reuse the vers | Integration | What changes | |---|---| -| Sending wallets and exchanges | A plain TIP-20 transfer to a deposit address works with no custom payload. The transfer can succeed on Tempo and still fail in the zone; the refund then arrives later, minus fees, at the debited account ([Failures and refunds](#failures-and-refunds)). Untested risk: exchange withdrawal systems may not expect late refunds, or transfers that revert with `FeeTooHigh` while a congestion fee applies ([Portal checks](#portal-checks)). | +| Sending wallets and exchanges | A plain TIP-20 transfer to a deposit address works with no custom payload. The transfer can succeed on Tempo and still fail in the zone. The refund then arrives later, minus fees, at the debited account ([Failures and refunds](#failures-and-refunds)). Untested risk: exchange withdrawal systems may not expect late refunds, or transfers that revert with `FeeTooHigh` while a congestion fee applies ([Portal checks](#portal-checks)). | | Routers and forwarding contracts | A refund goes to the debited account, not to the router's end user. Routers must handle late refunds and claims, and may be unable to attribute a refund to the user it belongs to. Use the ECIES API with an explicit `tempoRefundRecipient` when that control is needed. | | Token issuers | `mint` and `mintWithMemo` to a deposit address revert with `InvalidRecipient()` ([Routing on Tempo](#routing-on-tempo)). Mint to yourself, then transfer. | | Receiving businesses | Register once per zone and wait for settlement before requesting addresses ([Issuing addresses](#issuing-addresses)). Reissue addresses after a key rotation. | | Zone operators | Running a T15 zone includes giving the sequencers each new key, with its version, before it is rotated in, and keeping every key with protected backups ([Key versions](#key-versions)). | | Zones using the sequencer-side depositor allowlist | The allowlist rejects virtual deposits from unlisted originators or to unlisted recipients by setting `rejected`. They're refunded to `originator` ([Sequencer rejection](#sequencer-rejection)). | -| Future portal deposit authorizations | A plain transfer cannot carry a signed deposit authorization, so any later authorization mode for the portal needs its own rule for virtual deposits. | +| Future portal deposit authorizations | Deduction: a plain transfer cannot carry a signed deposit authorization. Any later authorization mode for the portal needs its own rule for virtual deposits. | | ECIES depositors | `tempoRefundRecipient` cannot be a deposit address; the portal reverts such a deposit with `InvalidBouncebackRecipient()`. | | Zone wallets | Zone TIP-20 transfers to a deposit address revert with `InvalidRecipient()`. Withdrawals reject one as `to` or fallback recipient ([Changes to other components](#changes-to-other-components)). | | TIP-1034 channel payers | From T15, `open` rejects a deposit-address payee with `InvalidPayee()`. Channels opened earlier are unaffected. | @@ -567,7 +568,7 @@ Operator runbooks cover key initialization, witness and replica confidentiality, | `VirtualDepositMade` | Portal | Was a transfer to a deposit address queued, for how much, with what fee and deposit number? | | `AddressVersionsRetired` | Portal | Which key versions does this portal still accept? | | `VirtualAddressKeyInitialized` | Native inbox (zone) | Which key versions has the zone initialized, and in which block? | -| `Transfer`, `TransferWithMemo` | TIP-20 | Which deposit address did the sender pay? ([Transfer events](#transfer-events)) | +| `Transfer`, `TransferWithMemo` | TIP-20 | Which deposit address did the sender pay? (see [Transfer events](#transfer-events)) | Evidence for each stage: @@ -579,9 +580,9 @@ Evidence for each stage: | Refund delivered or parked | Existing refund events distinguish a delivered refund from a parked claim. | | Key initialized or rotated | `VirtualAddressKeyInitialized(version)` from the inbox. Recipients see the change in the version `zone_deriveDepositAddresses` returns. | -This TIP does not specify how a sender matches a refund on Tempo to the deposit it reverses. +Missing evidence: this TIP does not specify how a sender matches a refund on Tempo to the deposit it reverses. -Public events and errors MUST NOT contain decrypted identifiers, failure reasons or key material. The inbox emits `VirtualDepositProcessed` for a credit and `VirtualDepositFailed` for a failed mint, and nothing for earlier failures. Both are served only to the resolved recipient ([Deposit results](#deposit-results)). System and witness failures are reported separately and never produce a committed failure result. +Public events and errors MUST NOT contain decrypted identifiers, failure reasons, or key material. The inbox emits `VirtualDepositProcessed` for a credit and `VirtualDepositFailed` for a failed mint, and nothing for earlier failures. Both are served only to the resolved recipient ([Deposit results](#deposit-results)). System and witness failures are reported separately and never produce a committed failure result. # Threat Model @@ -589,25 +590,25 @@ The most consequential attack is **issuer-policy probing**. A token's TIP-403 po Any accepted token's controller can probe any deposit address, including through a token the zone accepts after the address was issued. ECIES deposits leak more weakly: the controller gets one observation per deposit someone else makes, while deposit addresses let it probe whenever it likes. Zones should accept only tokens with trusted issuers and policy controllers, which reduces the risk but does not remove it. Private failure reasons, delays or fees do not help, because the refund itself is public. Closing the attack needs private failure handling inside the zone, which this TIP does not provide. -The sequencer-side allowlist leaks in a similar way. Anyone can already learn whether a known account is listed by sending it an ECIES deposit and watching for a refund. A deposit address adds a new leak: whether its hidden owner is listed right now. The prober cannot change the list, but every listing or delisting is a fresh probe: if an address switches between refunded and credited right after account `X` is listed or delisted, `X` is its owner. When few accounts change at once, this identifies the owner outright. The prober must wait for list changes and pay a deposit and refund fee per probe, so the leak is slower than issuer-policy probing, but it does not need a malicious issuer. Zones that list and delist often should treat deposit-address ownership as visible to anyone willing to pay those fees. +The sequencer-side allowlist leaks in a similar way. Anyone can learn whether a known account is listed by sending it an ECIES deposit and watching for a refund; that already holds today. A deposit address adds a new leak: whether its hidden owner is listed right now. The prober cannot change the list, but every listing or delisting is a fresh probe. If an address switches between refunded and credited right after account `X` is listed or delisted, `X` is its owner. When few accounts change at once, this identifies the owner outright. The prober must wait for list changes and pay a deposit and refund fee per probe, so the leak is slower than issuer-policy probing, but it does not need a malicious issuer. Zones that list and delist often should treat deposit-address ownership as visible to anyone willing to pay those fees. | Actor | Capability and trust | Boundary check and failure consequence | |---|---|---| -| Tempo observer or depositor | Sees the zone, version, token, amount, sender, address and memo of every deposit. Trusted with nothing. | FF1 encryption and the confidential registry ([Address format](#address-format), [Registry confidentiality](#registry-confidentiality)). It can link reuse of one address, but not learn its master ID or recipient. | +| Tempo observer or depositor | Sees the zone, version, token, amount, sender, address, and memo of every deposit. Trusted with nothing. | FF1 encryption and the confidential registry ([Address format](#address-format), [Registry confidentiality](#registry-confidentiality)). It can link reuse of one address, but not learn its master ID or recipient. | | Token policy controller | Sets the token's TIP-403 policy, which the zone applies to the hidden recipient. Trusted not to probe recipients. | None. It can identify address owners by probing (above). Zones limit exposure by accepting only trusted tokens. | -| Registration submitter | Chooses the recipient and salt of its own request and pays for it. Trusted with nothing. | The request hash binds the recipient, and issuance needs the recipient's authorization ([ID allocation](#id-allocation), [Authorization](#authorization)). It can use up IDs and infer allocation order, but cannot choose an ID, take over a binding, redirect funds or issue addresses. | -| Operator, sequencer and other key holders | Hold every FF1 key and the registry, sequence blocks and run the RPC. Trusted to keep keys and the registry confidential. | Recipient selection is proof-covered with no sequencer input ([Processing in the zone](#processing-in-the-zone)). A malicious operator can withhold service, disclose keys and mappings, or reject any deposit with `rejected` (refunded to `originator`), but can't change a recipient or a key. | +| Registration submitter | Chooses the recipient and salt of its own request and pays for it. Trusted with nothing. | The request hash binds the recipient, and issuance needs the recipient's authorization ([ID allocation](#id-allocation), [Authorization](#authorization)). It can use up IDs and infer allocation order, but cannot choose an ID, take over a binding, redirect funds, or issue addresses. | +| Operator, sequencer, and other key holders | Hold every FF1 key and the registry, sequence blocks, and run the RPC. Trusted to keep keys and the registry confidential. | Recipient selection is proof-covered with no sequencer input ([Processing in the zone](#processing-in-the-zone)). A malicious operator can withhold service, disclose keys and mappings, or reject any deposit with `rejected` (refunded to `originator`), but can't change a recipient or a key. | | Issuance service | Returns addresses to recipients. Trusted to return the requested master's address. | Only authentication of the service. A malicious service can hand out an address for the wrong master; nothing in the address lets the recipient check it. | | Portal admin | Retires key versions. Trusted to retire versions only after recipients migrate. | Retirement reverts new transfers on Tempo before funds move and leaves queued deposits alone ([Retiring versions](#retiring-versions)). A careless admin can break issued addresses, but cannot strand queued funds or lower the minimum version again. | -A leaked key reveals the master ID and tag behind every address under that version, past and future, and with one known master-ID-to-recipient binding links every address under that master to that recipient. A version has no forward secrecy; rotation limits the exposure to the leaked version ([Rotation](#rotation)). +A leaked key reveals the master ID and tag behind every address under that version, past and future. With one known master-ID-to-recipient binding, it links every address under that master to that recipient. A version has no forward secrecy. Rotation limits the exposure to the leaked version (see [Rotation](#rotation)). The FF1 keys protect privacy. Committed execution protects recipient selection once an address is issued. Apart from the sequencer's `rejected` flag, deleting a local key or withholding a witness cannot legitimately turn a configured address's deposit into a refund. Proof verification and confidential-state handling must keep these cases apart. Residual risks: -- **Corrupted addresses.** Every 6-byte ciphertext decrypts to some plaintext. With `N` registered master IDs, a random ciphertext under an initialized version resolves to some registered master with probability `N / 2^32`, before recipient checks, so a corrupted address can credit the wrong recipient. Including the zone and version in the tweak changes the permutation, but does not authenticate the address. This TIP adds no checksum: FF1 provides confidentiality and invertibility, not authentication. Recipients must distribute addresses through authenticated channels, and senders must keep the complete address. -- **Linkability.** Each version has `2^48` addresses, and each master ID has 65,536 tags per version. Deterministic derivation reveals address reuse. Amounts, timing, public memos and outside knowledge can also link deposits. Public enumeration of a candidate master's tags would reveal its address set, which is why issuance requires authentication. Keep private attribution out of public memos. +- **Corrupted addresses.** Every 6-byte ciphertext decrypts to some plaintext. With `N` registered master IDs, a random ciphertext under an initialized version resolves to some registered master with probability `N / 2^32`, before recipient checks. A corrupted address can therefore credit the wrong recipient. Including the zone and version in the tweak changes the permutation, but does not authenticate the address. This TIP adds no checksum. FF1 provides confidentiality and invertibility, not authentication. Recipients must distribute addresses through authenticated channels, and senders must keep the complete address. +- **Linkability.** Each version has `2^48` addresses, and each master ID has 65,536 tags per version. Deterministic derivation reveals address reuse. Amounts, timing, public memos, and outside knowledge can also link deposits. Public enumeration of a candidate master's tags would reveal its address set, which is why issuance requires authentication. Keep private attribution out of public memos. - **ID exhaustion and state growth.** Registration needs no proof of work, so registration fees and zone admission must cover state growth and the permanent 4,294,967,296-registration cap. Wider IDs would not remove this risk. Exhaustion stops new registrations only; existing master IDs keep working. - **Disclosure by the operator.** A malicious operator or a public export can reveal registry mappings. Registrations and their execution data otherwise share the zone's confidentiality boundary.