diff --git a/tips/tip-1094.md b/tips/tip-1094.md index 5a02b14d3e..9ac052bca7 100644 --- a/tips/tip-1094.md +++ b/tips/tip-1094.md @@ -19,21 +19,12 @@ Upon TIP-20 detecting a transfer to a Zone Virtual Deposit Address, the protocol ## 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. +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 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. +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. 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. - -### 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. - - ## Assumptions | Assumption | If violated | @@ -43,13 +34,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 | @@ -81,13 +73,13 @@ Each step has one party that can authorize it, and the checks that limit them ar | 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 @@ -191,9 +183,17 @@ 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 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. -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. +### 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 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. ## Registering a recipient @@ -203,9 +203,9 @@ A native zone registry precompile is deployed at `0x1C00000000000000000000000000 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 @@ -244,7 +244,23 @@ A submitter knows the recipient and salt of its request and may learn the assign ## 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 + +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, as above. + +### 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 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. @@ -252,9 +268,11 @@ Reusing an address is valid, but it links payments and can make attribution ambi ## 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: @@ -266,7 +284,9 @@ For a transfer to a deposit address, Tempo MUST: 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 @@ -294,7 +314,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,16 +326,6 @@ 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: @@ -326,20 +336,28 @@ The native inbox consumes the authenticated queue in its existing order. The ECI 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. -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 (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. -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 | @@ -351,23 +369,9 @@ A failed virtual deposit calls the existing inbox-only outbox bounce-back operat 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. - -### 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 +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. @@ -531,8 +535,6 @@ 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)). | @@ -540,12 +542,14 @@ All rows describe specified behavior unless marked otherwise. No implementation | 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)). | +| 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 | 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. | +# Tooling + SDKs expose: - permissionless registration, with random salt generation and no grinding; @@ -553,7 +557,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. @@ -584,7 +588,7 @@ Public events and errors MUST NOT contain decrypted identifiers, failure reasons 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. @@ -595,7 +599,7 @@ The sequencer-side allowlist leaks in a similar way. Anyone can learn whether a | 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)).