```json
{
"mcpServers": {
"tempo": {
"url": "https://mcp.tempo.xyz"
}
}
}
```
Watching for deposits...
}
```
```tsx twoslash [wagmi.config.ts] filename="wagmi.config.ts"
// @noErrors
// [!include ~/snippets/wagmi.config.ts:setup]
```
:::
::::
## Transfer memo recipes
### Exchange deposit reconciliation
As an exchange, use a single master hot wallet for all customer deposits. Customers include their customer ID as the memo, and you credit their account by parsing the event.
```ts
import { Actions } from 'viem/tempo'
import { parseUnits, stringToHex, pad } from 'viem'
// Customer deposits with their customer ID
await Actions.token.transferSync(walletClient, {
token: tokenAddress,
to: exchangeHotWallet,
amount: parseUnits('500', 6),
memo: pad(stringToHex('CUST-12345'), { size: 32 }),
})
```
### Payroll batch payments
Batch multiple payments in a single Tempo transaction with employee IDs in each memo for clear accounting records.
```ts
import { Abis } from 'viem/tempo'
import { encodeFunctionData, parseUnits, stringToHex, pad } from 'viem'
const calls = employees.map(emp => ({
to: tokenAddress,
data: encodeFunctionData({
abi: Abis.TIP20,
functionName: 'transferWithMemo',
args: [emp.wallet, parseUnits(emp.salary, 6), pad(stringToHex(emp.id), { size: 32 })]
})
}))
await walletClient.sendCalls({ calls })
```
### Refund address in memo
Include a refund address in the memo so the recipient knows where to send funds if a reversal is needed.
```ts
import { Actions } from 'viem/tempo'
import { parseUnits, stringToHex, pad } from 'viem'
const refundMemo = pad(stringToHex('REFUND 0x742d35Cc6634C0532925a3b8'), { size: 32 })
await Actions.token.transferSync(walletClient, {
token: tokenAddress,
to: merchantAddress,
amount: parseUnits('100', 6),
memo: refundMemo,
})
```
## Transfer memo best practices
### Use consistent memo formats
Establish a naming convention for your memos (e.g., `CUST-{id}`, `INV-{number}`, `REFUND-{id}`) to make parsing and filtering reliable across your system.
### Keep memos under 32 bytes
Memos are `bytes32` values. Use `toHex(string, { size: 32 })` to convert strings—if your string exceeds 32 bytes, it will be truncated. For longer references, store the full data offchain and use a hash or short ID as the memo.
### Index memos for efficient queries
The `TransferWithMemo` event has `memo` as an indexed parameter. Use `getLogs` with the `args` filter to query transactions by memo without scanning all events.
```ts
import { parseAbiItem, stringToHex, pad } from 'viem'
const logs = await client.getLogs({
address: tokenAddress,
event: parseAbiItem('event TransferWithMemo(address indexed from, address indexed to, uint256 value, bytes32 indexed memo)'),
args: { memo: pad(stringToHex('INV-12345'), { size: 32 }) },
})
```
## Transfer memo learning resources
{create.data && ( // [!code ++]
)
}
```
```tsx twoslash [config.ts] filename="config.ts"
// @noErrors
import { createConfig, http } from 'wagmi'
import { tempo } from 'viem/chains'
import { tempoWallet } from 'wagmi/connectors'
export const config = createConfig({
chains: [tempo],
connectors: [tempoWallet()],
transports: {
[tempo.id]: http(),
},
})
```
:::
### Next steps after creating a stablecoin
Now that you have created your first stablecoin, you can now:
* [Add your token to the Token List](/docs/quickstart/tokenlist#adding-a-new-token) so it appears in wallets, explorers, and other apps on Tempo
* learn the [Best Practices](#stablecoin-creation-best-practices) below
* follow a guide on how to [mint](/docs/guide/issuance/mint-stablecoins) and [more](/docs/guide/issuance/manage-stablecoin) with your stablecoin.
::::
## Stablecoin creation best practices
### Stablecoin creation loading state
When the user is creating a stablecoin, we should show loading state to indicate that the process is happening.
We can use the `isPending` property from the `useCreateSync` hook to show pending state to the user on our "Create" button.
```tsx
```
### Stablecoin creation error handling
If an error unexpectedly occurs, we should display an error message to the user.
We can use the `error` property from the `useCreateSync` hook to show error state to the user.
```tsx twoslash
// @noErrors
export function CreateStablecoin() {
// ...
if (create.error) // [!code ++]
return {/* [!code ++] */}
{create.data.name} created successfully! {/* [!code ++] */}
{/* [!code ++] */}
View receipt {/* [!code ++] */}
{/* [!code ++] */}
{/* [!code ++] */}
)} {/* [!code ++] */}
Error: {create.error.message}
{/* [!code ++] */}
// ...
}
```
## Stablecoin creation learning resources
setRecipient(e.target.value)}
placeholder="0x..."
/>
setMemo(e.target.value)}
placeholder="INV-12345"
/>
{/* [!code hl] */}
)
}
```
```tsx twoslash [config.ts] filename="config.ts"
// @noErrors
import { createConfig, http } from 'wagmi'
import { tempo } from 'viem/chains'
import { tempoWallet } from 'wagmi/connectors'
export const config = createConfig({
chains: [tempo],
connectors: [tempoWallet()],
transports: {
[tempo.id]: http(),
},
})
```
```solidity [Solidity]
TIP20 token = TIP20(0x20c0000000000000000000000000000000000004);
// Mint 1,000 tokens to the treasury (USD has 6 decimals)
address treasuryAddress = 0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef;
token.mint(treasuryAddress, 1_000_000_000);
// Mint with a memo for tracking
token.mintWithMemo(
treasuryAddress,
1_000_000_000,
keccak256("Q1_2024_TREASURY_ALLOCATION")
);
```
```rust [Rust]
use alloy::{
primitives::{address, keccak256, U256},
providers::ProviderBuilder,
};
use tempo_alloy::{TempoNetwork, contracts::precompiles::ITIP20};
#[tokio::main]
async fn main() -> Result<(), Box
setMemo(e.target.value)}
placeholder="INV-12345"
/>
{/* [!code hl] */}
)
}
```
```tsx twoslash [config.ts] filename="config.ts"
// @noErrors
import { createConfig, http } from 'wagmi'
import { tempo } from 'viem/chains'
import { tempoWallet } from 'wagmi/connectors'
export const config = createConfig({
chains: [tempo],
connectors: [tempoWallet()],
transports: {
[tempo.id]: http(),
},
})
```
```solidity [Solidity]
TIP20 token = TIP20(0x20c0000000000000000000000000000000000004);
// Burn 100 tokens from your own balance
token.burn(100_000_000);
// Burn with a memo for tracking
token.burnWithMemo(100_000_000, keccak256("REDEMPTION_Q1_2024"));
```
```rust [Rust]
use alloy::{
primitives::{address, keccak256, U256},
providers::ProviderBuilder,
};
use tempo_alloy::{TempoNetwork, contracts::precompiles::ITIP20};
#[tokio::main]
async fn main() -> Result<(), Box
setRecipient(e.target.value)}
placeholder="0x..."
/>
setMemo(e.target.value)}
placeholder="INV-12345"
/>
{/* [!code hl] */}
)
}
```
```tsx twoslash [config.ts] filename="config.ts"
// @noErrors
import { createConfig, http } from 'wagmi'
import { tempo } from 'viem/chains'
import { tempoWallet } from 'wagmi/connectors'
export const config = createConfig({
chains: [tempo],
connectors: [tempoWallet()],
transports: {
[tempo.id]: http(),
},
})
```
```solidity [Solidity]
ITIP20 token = ITIP20(0x20c0000000000000000000000000000000000001); // AlphaUSD
address yourToken = 0x20c0000000000000000000000000000000000004; // Your issued stablecoin
address recipient = 0xbeefcafe54750903ac1c8909323af7beb21ea2cb;
// Send payment using your token for fees
IFeeManager feeManager = IFeeManager(TIP_FEE_MANAGER_ADDRESS);
feeManager.setTransactionFeeToken(yourToken);
token.transfer(recipient, 100_000_000);
```
```rust [Rust]
use alloy::{
primitives::{address, U256},
providers::ProviderBuilder,
};
use tempo_alloy::{
TempoNetwork,
contracts::precompiles::{ITIPFeeAMM, TIP_FEE_MANAGER_ADDRESS},
};
#[tokio::main]
async fn main() -> Result<(), Box
{hasIssuerRole !== undefined && ( // [!code ++]
)
}
```
```tsx twoslash [config.ts] filename="config.ts"
// @noErrors
import { createConfig, http } from 'wagmi'
import { tempo } from 'viem/chains'
import { tempoWallet } from 'wagmi/connectors'
export const config = createConfig({
chains: [tempo],
connectors: [tempoWallet()],
transports: {
[tempo.id]: http(),
},
})
```
:::
### Revoke the stablecoin issuer role
Revoke roles from addresses when you need to remove their permissions.
{/* [!code ++] */}
Treasury {hasIssuerRole ? 'has' : 'does not have'} the issuer role // [!code ++]
{/* [!code ++] */}
)} // [!code ++]
{/* [!code ++] */}
{hasIssuerRole !== undefined && (
)
}
```
```tsx twoslash [config.ts] filename="config.ts"
// @noErrors
import { createConfig, http } from 'wagmi'
import { tempo } from 'viem/chains'
import { tempoWallet } from 'wagmi/connectors'
export const config = createConfig({
chains: [tempo],
connectors: [tempoWallet()],
transports: {
[tempo.id]: http(),
},
})
```
:::
::::
## Stablecoin management recipes
### Set the stablecoin logo
Set or update the token's on-chain [`logoURI`](/docs/protocol/tip20/spec#logo-uri) so wallets and explorers can read the icon directly from the token contract via `logoURI()`. This requires the **`DEFAULT_ADMIN_ROLE`** and is done by calling `setLogoURI(string newLogoURI)` on the token. For the recommended format, use a square, rasterized PNG or WebP (max 256 bytes; `https`, `http`, `ipfs`, or `data` scheme).
### Set the stablecoin supply cap
Limit the maximum total supply of your token. Setting supply caps requires the **`DEFAULT_ADMIN_ROLE`**. The new cap cannot be less than the current total supply.
Treasury {hasIssuerRole ? 'has' : 'does not have'} the issuer role
)}
User token reserves: {formatUnits(pool?.reserveUserToken ?? 0n, 6)}
Validator token reserves: {formatUnits(pool?.reserveValidatorToken ?? 0n, 6)}
User token reserves: {formatUnits(pool?.reserveUserToken ?? 0n, 6)}
Validator token reserves: {formatUnits(pool?.reserveValidatorToken ?? 0n, 6)}
{/* [!code ++] */}
LP token balance: {formatUnits(balance ?? 0n, 6)}
{/* [!code ++] */}
User token reserves: {formatUnits(pool?.reserveUserToken ?? 0n, 6)}
Validator token reserves: {formatUnits(pool?.reserveValidatorToken ?? 0n, 6)}
LP token balance: {formatUnits(balance ?? 0n, 6)}
User token reserves: {formatUnits(pool?.reserveUserToken ?? 0n, 6)}
Validator token reserves: {formatUnits(pool?.reserveValidatorToken ?? 0n, 6)}
{/* [!code ++] */}
{swaps.map((swap, i) => (
)
}
```
```ts twoslash [wagmi.config.ts]
// @noErrors
import { tempo } from 'viem/chains'
import { createConfig, http } from 'wagmi'
import { tempoWallet } from 'wagmi/connectors'
export const config = createConfig({
connectors: [tempoWallet()],
chains: [tempo],
multiInjectedProviderDiscovery: false,
transports: {
[tempo.id]: http(),
},
})
```
:::
### Rebalance pools
You can rebalance pools by swapping validator tokens for accumulated user tokens at a fixed rate. Rebalancing restores validator token reserves and enables continued fee conversions. Learn more [here](/docs/protocol/fees/spec-fee-amm#swap-mechanisms).
:::code-group
```tsx twoslash [RebalancePool.tsx]
// @noErrors
import { Hooks } from 'wagmi/tempo'
import { formatUnits, parseUnits } from 'viem'
import { useConnection } from 'wagmi'
const userToken = '0x20c0000000000000000000000000000000000002' // BetaUSD
const validatorToken = '0x20c0000000000000000000000000000000000001' // AlphaUSD
function RebalancePool() {
const { address } = useConnection()
const { data: pool } = Hooks.amm.usePool({
userToken,
validatorToken,
})
const rebalance = Hooks.amm.useRebalanceSwapSync() // [!code hl]
return (
Swap: {swap.amountIn} → {swap.amountOut} (LP revenue: {swap.revenue})
))}
User token reserves: {formatUnits(pool?.reserveUserToken ?? 0n, 6)}
Validator token reserves: {formatUnits(pool?.reserveValidatorToken ?? 0n, 6)}
{ /* [!code hl] */ }
Quote: {formatUnits(quote, 6)}
}
```
```tsx twoslash [Sell.tsx]
// @noErrors
import { Hooks } from 'wagmi/tempo'
import { formatUnits, parseUnits } from 'viem'
const alphaUsd = '0x20c0000000000000000000000000000000000001'
const betaUsd = '0x20c0000000000000000000000000000000000002'
function Sell() {
const amount = parseUnits('10', 6)
// How much BetaUSD will I receive for 10 AlphaUSD? // [!code hl]
const { data: quote } = Hooks.dex.useSellQuote({ // [!code hl]
tokenIn: alphaUsd, // [!code hl]
tokenOut: betaUsd, // [!code hl]
amountIn: amount, // [!code hl]
}) // [!code hl]
return Quote: {formatUnits(quote, 6)}
}
```
:::
### Calculate slippage tolerance
Set appropriate slippage based on your quote to protect against unfavorable price movements.
:::code-group
```tsx twoslash [Buy.tsx]
// @noErrors
import { Hooks } from 'wagmi/tempo'
import { formatUnits, parseUnits } from 'viem'
const alphaUsd = '0x20c0000000000000000000000000000000000001'
const betaUsd = '0x20c0000000000000000000000000000000000002'
function Buy() {
const amount = parseUnits('10', 6)
// How much AlphaUSD do I need to spend to receive 10 BetaUSD?
const { data: quote } = Hooks.dex.useBuyQuote({
tokenIn: alphaUsd,
tokenOut: betaUsd,
amountOut: amount,
})
// [!code ++] Calculate 0.5% slippage tolerance
const slippageTolerance = 0.005 // [!code ++]
const maxAmountIn = quote // [!code ++]
? quote * BigInt(Math.floor((1 + slippageTolerance) * 1000)) / 1000n // [!code ++]
: 0n // [!code ++]
return (
Quote: {formatUnits(quote, 6)}
Max input (0.5% slippage): {formatUnits(maxAmountIn, 6)}
{/* [!code ++] */}
Quote: {formatUnits(quote, 6)}
Min output (0.5% slippage): {formatUnits(minAmountOut, 6)}
{/* [!code ++] */}
Quote: {formatUnits(quote, 6)}
Max input (0.5% slippage): {formatUnits(maxAmountIn, 6)}
{/* [!code ++] */}
Quote: {formatUnits(quote, 6)}
Min output (0.5% slippage): {formatUnits(minAmountOut, 6)}
{/* [!code ++] */}
Quote: {formatUnits(quote, 6)}
Max input (0.5% slippage): {formatUnits(maxAmountIn, 6)}
Quote: {formatUnits(quote, 6)}
Min output (0.5% slippage): {formatUnits(minAmountOut, 6)}
Not enough liquidity available. Try a smaller amount.
}
return Error: {error.message}
}
if (!quote) {
return Loading quote...
}
return Quote: {quote.toString()}
}
```
## Stablecoin swap best practices
### Always get quotes before swapping
Query the expected price before executing a swap to ensure you're getting a fair rate and to set appropriate slippage protection.
### Set appropriate slippage protection
Use `minAmountOut` or `maxAmountIn` to protect against unfavorable price movements between quoting and execution.
## Stablecoin swap learning resources
This means:
* you keep one deposit address per customer
* the master wallet receives the balance directly
* no sweep transaction is needed
* no separate TIP-20 balance is created for each deposit address
Forwarding happens inside the same TIP-20 precompile call that processes the transfer — there is no second transaction or additional token movement. The only extra cost is a single storage read (SLOAD) to look up the registered master wallet in the virtual-address registry.
## The mental model
A virtual address is not a second wallet. It is a deposit alias for one canonical wallet.
The important idea is simple: the virtual address is for routing and attribution, while the master wallet is where the TIP-20 balance actually lives.
## Address format
A virtual address is still a normal 20-byte EVM address. The [specification](https://github.com/tempoxyz/tempo/blob/main/tips/tip-1022.md) gives those 20 bytes a specific layout:
```text
0x | masterId (4 bytes) | VIRTUAL_MAGIC (10 bytes) | userTag (6 bytes)
```
Example:
```text
0x2612766c fdfdfdfdfdfdfdfdfdfd 000000000001
```
Where:
| Part | Size | Purpose |
| --- | --- | --- |
| `masterId` | 4 bytes | identifies which registered master wallet should receive the funds |
| `VIRTUAL_MAGIC` | 10 bytes | marks the address as virtual so TIP-20 can recognize it |
| `userTag` | 6 bytes | operator-chosen routing or attribution value |
TIP-20 recognizes a virtual address by the fixed 10-byte middle marker. It then uses the leading `masterId` to resolve the registered wallet and leaves the trailing `userTag` available for operator-side attribution.
## What happens when someone sends funds
When a sender transfers a covered TIP-20 token to a virtual address, the TIP-20 precompile detects the virtual format, looks up the registered master, and credits that master wallet.
USDX, USDY"] TE --> Z2["Zone 2
pathUSD, ..."] end `} /> The sequencer runs a Tempo node with one or more zone nodes attached. Each zone node: * Synchronizes the zone's view of Tempo Mainnet each time a Tempo Mainnet block finalizes * Executes zone transactions using privately submitted transactions and the zone's own state * Produces batches proving state transitions on the zone and posts them to Tempo Mainnet * Watches for deposits by monitoring Zone Portal events on Tempo Mainnet, and creates corresponding transactions on the zone once the block finalizes * Watches for withdrawals on the zone and submits transactions to Tempo Mainnet processing them once the batch has been proven ## Contract Architecture The system consists of contracts on both Tempo Mainnet and within each Tempo Zone.
(deposits)"] ZO["ZoneOutbox
(withdrawals)"] -- "withdrawals" --> ZP subgraph TEMPO["Tempo Mainnet"] ZF["ZoneFactory
(deploys)"] ZP ZM["ZoneMessenger
(callbacks)"] end subgraph ZONE["Zone"] TS["TempoState
(Tempo Mainnet view)"] ZI ZO end `} /> ### Tempo Contracts * **`ZoneFactory`** deploys new Tempo Zones. Each zone gets its own Zone Portal and Zone Messenger contracts with deterministic addresses. * **`ZonePortal`** is the central bridge contract. It locks all deposited tokens, verifies validity proofs, and processes withdrawals. The Zone Portal contract maintains the authoritative state: which deposits have been made, which batches have been proven, and which withdrawals are pending. * **`ZoneMessenger`** handles withdrawals that include callbacks. When a user wants to withdraw tokens and trigger a contract call atomically, the messenger executes both operations together. If the callback fails, the entire withdrawal reverts and funds bounce back to the zone. ### Zone Predeploys Tempo Zones have four system contract predeploys at fixed addresses: | Contract | Address | Purpose | |----------|---------|---------| | `TempoState` | `0x1c00...0000` | Stores the zone's view of Tempo Mainnet. The sequencer updates this with Tempo Mainnet block headers, allowing zone contracts to read Tempo Mainnet state within proofs. | | `ZoneInbox` | `0x1c00...0001` | Processes incoming deposits. Mints tokens to recipients and validates that processed deposits match what the Zone Portal contract expects. | | `ZoneOutbox` | `0x1c00...0002` | Handles withdrawal requests. Users burn their zone tokens here and specify a Tempo Mainnet recipient. | | `ZoneConfig` | `0x1c00...0003` | Central configuration. Reads sequencer and token registry from Tempo Mainnet. | ## Creating a Zone Tempo Zones are created through the `ZoneFactory`: 1. Choose a TIP-20 token to serve as the zone's initial asset. 2. Select a verifier contract (ZK prover or TEE attestor). 3. Designate a sequencer address. 4. Call `ZoneFactory.createZone()` with these parameters. The factory deploys a new `ZonePortal` and `ZoneMessenger` for the Tempo Zone. The zone itself runs as a separate chain with the system contracts deployed at genesis. The sequencer can enable additional TIP-20 tokens at any time via `ZonePortal.enableToken()`. ### Chain ID Each Tempo Zone has a unique EIP-155 chain ID derived deterministically from its onchain zone ID: ``` chain_id = 421700000 + zone_id ``` The prefix `4217` corresponds to the Tempo Mainnet chain ID. This ensures replay protection between Tempo Zones. A transaction signed for one zone cannot be replayed on another. ## Sequencer Transfer The sequencer can transfer control to a new address via a two-step process on Tempo Mainnet: 1. Current sequencer calls `ZonePortal.transferSequencer(newSequencer)` to nominate a new sequencer. 2. New sequencer calls `ZonePortal.acceptSequencer()` to accept the transfer. Sequencer management occurs on Tempo Mainnet. Zone-side system contracts read the sequencer from Tempo Mainnet via `ZoneConfig`, which queries `TempoState` to get the sequencer address from the finalized `ZonePortal` storage. ## Trust Model Tempo Zones make explicit tradeoffs between trust and performance: | What You Trust | What Could Go Wrong | |---|---| | Sequencer for liveness | The Tempo Zone halts if the sequencer stops. | | Sequencer for inclusion and ordering | Transactions (including withdrawals) can be excluded or reordered. | | Sequencer for privacy | The sequencer can see all transactions on the Tempo Zone. | | Sequencer for data | Reconstructing the state of the Tempo Zone without the sequencer is impossible. | | Sequencer + verifier for correctness | If a critical safety bug exists in the verifier or proving system, and the sequencer is malicious, they could exploit it to steal funds. | The sequencer cannot steal funds or forge state transitions. Validity proofs prevent this. However, the sequencer can halt the zone entirely, censor specific users, or reorder transactions for MEV. Failed withdrawals always bounce back to the zone `fallbackRecipient`, ensuring users retain their funds. TIP-403 policy changes or token pauses on Tempo Mainnet will cause affected withdrawals to bounce back rather than block the queue. # Accounts :::info Tempo Zones is still in early development and is available for testing purposes on Tempo Testnet only. While Tempo Zones are in this stage, expect breaking changes to the design and implementation. Do not use this in production. If you're interested in working with Tempo Labs as a design partner on the development of Tempo Zones, contact us at [tempo.xyz/contact](https://tempo.xyz/contact). ::: Tempo Zones enforce account privacy at two complementary layers: the EVM execution level and the [RPC access control](/docs/protocol/zones/rpc) level. Neither is sufficient alone. * **Execution alone is insufficient.** Without RPC restrictions, a caller could use `eth_getStorageAt` to read TIP-20 balance mapping slots directly, bypassing `balanceOf` access control. * **RPC alone is insufficient.** Without execution-level changes, a caller could use `eth_call` to invoke a contract that reads another account's balance and returns it, bypassing RPC-level filtering. This page covers the execution-level protections. For the RPC layer, see the [RPC specification](/docs/protocol/zones/rpc). ## Private Balances On Tempo Mainnet, anyone can read any account's balance. On a Tempo Zone, `balanceOf(address)` enforces caller restrictions for TIP-20s: * If `msg.sender == account`, the call succeeds and returns the balance. * If `msg.sender` is the sequencer, the call succeeds (required for block production and fee accounting). * Otherwise, the call reverts with `Unauthorized()`. Enforcing this at the contract level (not just the RPC layer) ensures that even onchain composition cannot leak balances. A contract on the Tempo Zone cannot read and emit another account's balance. ## Private Allowances The `allowance(owner, spender)` function is similarly restricted: * If `msg.sender == owner` or `msg.sender == spender`, the call succeeds. * If `msg.sender` is the sequencer, the call succeeds. * Otherwise, the call reverts with `Unauthorized()`. A non-zero allowance reveals that `owner` has interacted with `spender`, a relationship that should be private. Restricting reads to the two parties involved preserves standard TIP-20 (ERC-20) approval flows without leaking relationship information. Public views like `totalSupply()`, `name()`, `symbol()`, and `decimals()` remain unrestricted. ## Related Specifications Tempo Zones also charge fixed gas costs for TIP-20 operations to prevent gas-based side channels. See [Execution & Gas](/docs/protocol/zones/execution#fixed-gas-costs) for details. Tempo Zones currently disable contract creation (`CREATE` and `CREATE2`). See [Execution & Gas](/docs/protocol/zones/execution#contract-creation-disabled) for details. # Zone Bridging :::info Tempo Zones is still in early development and is available for testing purposes on Tempo Testnet only. While Tempo Zones are in this stage, expect breaking changes to the design and implementation. Do not use this in production. If you're interested in working with Tempo Labs as a design partner on the development of Tempo Zones, contact us at [tempo.xyz/contact](https://tempo.xyz/contact). ::: Tempo Zones use Tempo-centric bridging for cross-chain operations: deposits flow from Tempo into a zone, and withdrawals flow from a zone back to Tempo with optional callbacks for composability.  Above is an example of the type of complex transaction that can remain privacy-preserving via Tempo Zones, while performing operations such as bridging, deposits & sends, and withdrawals. Learn more about [encrypted deposits](#encrypted-deposits) and [verifiable withdrawals](#verifiable-withdrawals) below. ## Deposits (Tempo → Zone) 1. User calls `ZonePortal.deposit(token, to, amount, memo)` on Tempo, specifying which enabled TIP-20 to deposit. 2. The Zone Portal contract validates the token is enabled and deposits are active, deducts the [deposit fee](/docs/protocol/zones/execution#deposit-fees), locks the funds, and appends a deposit to the queue. 3. The sequencer observes `DepositMade` events and processes deposits in order via `ZoneInbox.advanceTempo()`, minting the corresponding zone-side TIP-20 to the recipient. 4. A batch proof must prove the zone correctly processed deposits by validating the Tempo state read inside the proof. ### Encrypted Deposits For privacy-sensitive use cases, users can make encrypted deposits where the recipient and memo are encrypted using the sequencer's public key. Only the sequencer can decrypt and credit the correct recipient on the zone. **What's public vs. private:** | Field | Visibility | Reason | |-------|------------|--------| | `token` | Public | Needed for locked token accounting | | `sender` | Public | Needed for potential refunds if decryption fails | | `amount` | Public | Needed for onchain locked token accounting | | `to` | Encrypted | Only sequencer knows recipient | | `memo` | Encrypted | Only sequencer knows payment context | The encryption uses ECIES with secp256k1: 1. Sequencer publishes a secp256k1 encryption public key via `setSequencerEncryptionKey()` with a proof of possession. 2. User generates an ephemeral keypair and derives a shared secret via ECDH. 3. User encrypts `(to || memo)` with AES-256-GCM using the derived key. 4. User calls `depositEncrypted(token, amount, keyIndex, encryptedPayload)` on the Zone Portal contract. If decryption fails (invalid ciphertext, wrong key), the zone mints tokens to the `sender`'s address on the zone. The Tempo Mainnet funds remain locked in the Zone Portal contract. This ensures chain progress is never blocked by invalid encrypted deposits. ## Withdrawals (Zone → Tempo) Users withdraw by creating a withdrawal request on the zone. Withdrawals are processed in two steps: 1. **Batch submission.** The sequencer calls `finalizeWithdrawalBatch()` at the end of the final block in a batch. This constructs the withdrawal hash chain and writes the `withdrawalQueueHash` and `withdrawalBatchIndex` to state. The proof validates this state and adds withdrawals to Tempo's queue. 2. **Withdrawal processing.** The sequencer calls `processWithdrawal()` on Tempo to process withdrawals from the queue's oldest slot. ### Composable Withdrawals Withdrawals support callbacks to Tempo contracts via the `ZoneMessenger`. When `gasLimit > 0`, the messenger: 1. Transfers tokens from the Zone Portal contract to the target via `transferFrom`. 2. Calls the target with the provided `callbackData`. Both operations are atomic. If the callback reverts, the transfer reverts too. Receiving contracts implement `IWithdrawalReceiver` and verify `msg.sender == zoneMessenger` to authenticate calls. This enables direct composition with DEX swaps, staking, or cross-zone deposits. ```solidity interface IWithdrawalReceiver { function onWithdrawalReceived( bytes32 senderTag, address token, uint128 amount, bytes calldata callbackData ) external returns (bytes4); } ``` ### Withdrawal Failure and Bounce-Back Withdrawals can fail if the token transfer or callback reverts (out of gas, TIP-403 policy, token pause, etc.). When a withdrawal fails, the Zone Portal contract bounces back the funds by re-depositing into the same zone to the withdrawal's `fallbackRecipient`: * The withdrawal is **popped unconditionally** from the queue, even on failure. * A new deposit is enqueued for the `fallbackRecipient` on the zone. * The sequencer keeps the processing fee regardless of success or failure. This ensures failed withdrawals never block the queue and users always retain their funds. ### Verifiable Withdrawals Zone transactions are private: transaction data is not published on Tempo Mainnet. To protect sender privacy during withdrawal processing on Tempo Mainnet, the plaintext `sender` is replaced with a commitment: ``` senderTag = keccak256(abi.encodePacked(sender, txHash)) ``` The `txHash` acts as a blinding factor known only to the sender and sequencer. The sender can selectively disclose their identity by revealing `txHash` to any party, who verifies it against the `senderTag`. For automated disclosure, the sender can specify a `revealTo` public key. The sequencer encrypts `(sender, txHash)` to that key using ECDH, populating the `encryptedSender` field in the Tempo Mainnet-facing withdrawal struct. This enables cross-zone transfers where the destination zone's sequencer can automatically attribute incoming deposits. # Zone RPC :::info Tempo Zones is still in early development and is available for testing purposes on Tempo Testnet only. While Tempo Zones are in this stage, expect breaking changes to the design and implementation. Do not use this in production. If you're interested in working with Tempo Labs as a design partner on the development of Tempo Zones, contact us at [tempo.xyz/contact](https://tempo.xyz/contact). ::: The zone RPC starts from the standard Ethereum JSON-RPC and restricts it to enforce privacy guarantees. Every RPC request must include an authorization token that proves the caller controls a Tempo account and scopes all responses to that account. ## Authorization Tokens Authorization tokens are short-lived credentials (maximum 1 month) signed by the caller's Tempo account key. Tempo accounts support multiple signature types (secp256k1, P256, WebAuthn), and accounts with Access Keys via the `AccountKeychain` precompile can use those keys to authenticate. The signed message includes: * `"TempoZoneRPC"` magic prefix for domain separation * Spec version, zone ID, and chain ID for replay protection (zone 0 can be used to allow access to all zones) * Issuance and expiry timestamps Tokens are sent via the `X-Authorization-Token` HTTP header on every request. ## Method Access Control Each JSON-RPC method falls into one of four categories: Available to any authenticated caller: | Method | Access Type | Notes | |--------|-------------|-------| | `eth_chainId` | Allowed | Zone chain ID | | `eth_blockNumber` | Allowed | Latest block number | | `eth_gasPrice` | Allowed | Current gas price | | `eth_maxPriorityFeePerGas` | Allowed | Current priority fee | | `eth_feeHistory` | Allowed | Fee history | | `eth_getBlockByNumber` | Allowed | Block headers **without transaction details** | | `eth_getBlockByHash` | Allowed | Block headers **without transaction details** | | `eth_subscribe("newHeads")` | Allowed | Block headers with `logsBloom` zeroed | | `eth_syncing` | Allowed | Sync status | | `eth_coinbase` | Allowed | Sequencer address | | `net_version` | Allowed | Network ID | | `net_listening` | Allowed | Node status | | `web3_clientVersion` | Allowed | Client version | | `web3_sha3` | Allowed | Pure Keccak-256 hash | | `eth_getBalance` | Scoped | Returns balance for the authenticated account only. Queries for other accounts return `0x0`. | | `eth_getTransactionCount` | Scoped | Returns nonce for the authenticated account only. Other accounts return `0x0`. | | `eth_call` | Scoped | Executes with `from` set to the authenticated account. [Execution-level privacy](/docs/protocol/zones/accounts) enforces `balanceOf` access control at the contract level. | | `eth_estimateGas` | Scoped | Only allowed when `from` equals the authenticated account. | | `eth_getTransactionByHash` | Scoped | Returns the transaction only if the authenticated account is the sender. Returns `null` otherwise. | | `eth_getTransactionReceipt` | Scoped | Returns the receipt only if the authenticated account is the sender. Logs are filtered (see [Event Filtering](#event-filtering)). | | `eth_sendRawTransaction` | Scoped | Validates that the transaction sender matches the authenticated account. | | `eth_getLogs` | Scoped | Filtered to TIP-20 events where the authenticated account is a relevant party (see [Event Filtering](#event-filtering)). | | `eth_getFilterLogs` | Scoped | Same filtering as `eth_getLogs`. | | `eth_getFilterChanges` | Scoped | Same filtering. Only returns new events since last poll. | | `eth_newFilter` | Scoped | Creates a filter implicitly scoped to the authenticated account. | | `eth_subscribe("logs")` | Scoped | Subscription scoped to the authenticated account. | | `eth_newBlockFilter` | Scoped | Returns new block hashes. | | `eth_uninstallFilter` | Scoped | Removes a previously created filter. | **Error vs. silent response**: Methods where the user explicitly provides a mismatched parameter (`eth_sendRawTransaction` with wrong sender, `eth_call` with wrong `from`) return explicit errors, since the user already knows the address they supplied and the error leaks nothing. Methods that query *about* other accounts return silent dummy values (`0x0`, `null`, empty results) instead of errors; an error would reveal "this data exists but you can't see it." ### Restricted (sequencer-only) | Method | Reason | |--------|--------| | `eth_getStorageAt` | Raw storage reads bypass all access control | | `eth_getCode` | No legitimate non-sequencer use case | | `eth_createAccessList` | Reveals storage layout | | `eth_getBlockByNumber` (with `true`) | Full block with all transactions | | `eth_getBlockByHash` (with `true`) | Full block with all transactions | | `eth_getBlockTransactionCountByNumber` | Transaction counts reveal activity levels | | `eth_getBlockTransactionCountByHash` | Same as above | | `eth_getTransactionByBlockNumberAndIndex` | Arbitrary transaction access | | `eth_getTransactionByBlockHashAndIndex` | Same as above | | `debug_*`, `admin_*`, `txpool_*` | All debug, admin, and txpool namespaces | ### Disabled | Method | Reason | |--------|--------| | `eth_getProof` | Merkle proofs leak state trie structure | | `eth_newPendingTransactionFilter` | Mempool observation | | `eth_subscribe("newPendingTransactions")` | Mempool observation | | Mining-related methods | Tempo Zones have no mining | Any method not explicitly listed returns error code `-32601` (method not found), ensuring new methods are not accidentally exposed. ## Timing Side Channels Scoped methods that fetch data before checking authorization have a mandatory **100 ms minimum response time**. This ensures that `eth_getTransactionByHash` for a non-existent transaction hash and for another user's transaction have indistinguishable response times, preventing existence probing. Methods that need the speed bump: | Method | Reason | |--------|--------| | `eth_getTransactionByHash` | Must fetch the transaction to check if sender matches | | `eth_getTransactionReceipt` | Must fetch the receipt to check the sender | | `eth_getLogs` | Response time correlates with total log volume, not just the caller's logs | | `eth_getFilterLogs` | Same as `eth_getLogs` | | `eth_getFilterChanges` | Same as `eth_getLogs` | Methods that do **not** need the speed bump include `eth_getBalance` and `eth_getTransactionCount` (address checked before any data fetch), `eth_call` and `eth_estimateGas` (`from` validated before execution), and `eth_sendRawTransaction` (sender verified during decoding). ## Block Responses Block headers returned to non-sequencer callers are sanitized: * `transactions` is always an empty array. * `logsBloom` is replaced with a zero Bloom. The real Bloom filter would allow probing whether a specific address had activity in a block. * All other header fields (`number`, `hash`, `gasUsed`, `stateRoot`, etc.) are returned normally. ## Event Filtering Log queries are restricted to TIP-20 events where the authenticated account is a relevant party: | Event | Visible if | |-------|-----------| | `Transfer` | `from == caller` OR `to == caller` | | `Approval` | `owner == caller` OR `spender == caller` | | `TransferWithMemo` | `from == caller` OR `to == caller` | | `Mint` | `to == caller` | | `Burn` | `from == caller` | All other event topics (system events, role events, configuration events) are filtered out. ## Zone-Specific RPC Methods | Method | Access | Description | |--------|--------|-------------| | `zone_getAuthorizationTokenInfo` | Any authenticated | Returns the authenticated account address and token expiry | | `zone_getZoneInfo` | Any authenticated | Returns zone metadata: `zoneId`, `zoneTokens`, `sequencer`, `chainId` | | `zone_getDepositStatus` | Scoped | Returns whether deposits from a given Tempo block have been processed, filtered to the caller's deposits | ## Error Codes | Code | Message | Meaning | |------|---------|---------| | `-32001` | Authorization token required | No authorization token provided | | `-32002` | Authorization token expired | The authorization token has expired | | `-32003` | Transaction rejected | Transaction sender does not match authenticated account | | `-32004` | Account mismatch | The `from` field does not match the authenticated account | | `-32005` | Sequencer only | Method requires sequencer access | | `-32006` | Method disabled | Method is not available on zones | # Execution & Gas :::info Tempo Zones is still in early development and is available for testing purposes on Tempo Testnet only. While Tempo Zones are in this stage, expect breaking changes to the design and implementation. Do not use this in production. If you're interested in working with Tempo Labs as a design partner on the development of Tempo Zones, contact us at [tempo.xyz/contact](https://tempo.xyz/contact). ::: This page specifies how Tempo Zones handle gas accounting, fee collection, and token management. For deposit and withdrawal flows, see the [bridging specification](/docs/protocol/zones/bridging). For balance visibility and access control rules, see the [accounts specification](/docs/protocol/zones/accounts). ## Fee Tokens Tempo Zones reuse Tempo fee units and gas accounting. Each transaction includes a `feeToken` field. Any enabled TIP-20 token with USD currency is valid for gas payment. The sequencer accepts all enabled tokens directly, so no Fee AMM is needed. ## Deposit Fees Deposits charge a fixed processing fee in the deposited token: ``` fee = FIXED_DEPOSIT_GAS × zoneGasRate ``` `FIXED_DEPOSIT_GAS` is fixed at 100,000 gas. The sequencer configures `zoneGasRate` through `ZonePortal.setZoneGasRate()`. The fee is deducted from the deposit amount and paid to the sequencer on Tempo Mainnet. ## Withdrawal Fees Withdrawals charge a processing fee in the withdrawn token: ``` fee = gasLimit × tempoGasRate ``` The user specifies `gasLimit` to cover processing and any callback execution. The sequencer configures `tempoGasRate` through `ZoneOutbox.setTempoGasRate()`. ## Fixed Gas Costs All user-facing TIP-20 transfer and approval operations cost exactly 100,000 gas. This removes gas-based information leaks tied to storage state. On a standard EVM chain, gas varies based on whether a transfer writes to a previously empty storage slot, revealing whether the recipient has received tokens before. Fixed costs eliminate that side channel. | Function | Gas Cost | |----------|----------| | `transfer(to, amount)` | 100,000 | | `transferFrom(from, to, amount)` | 100,000 | | `transferWithMemo(to, amount, memo)` | 100,000 | | `transferFromWithMemo(from, to, amount, memo)` | 100,000 | | `approve(spender, amount)` | 100,000 | System functions (`systemTransferFrom`, `transferFeePreTx`, `transferFeePostTx`) retain standard gas costs. Only restricted system callers can invoke them, so the gas side channel does not apply. ## Contract Creation Disabled Tempo Zones currently disable the `CREATE` and `CREATE2` opcodes. Each Tempo Zone runs a fixed set of system contracts and predeploys. Any transaction that attempts contract creation reverts. ## Token Management  The sequencer manages which TIP-20 tokens are available on a Tempo Zone: | Function | Behavior | |----------|----------| | `enableToken(token)` | Enables a TIP-20 token for bridging and gas payment. Irreversible. | | `pauseDeposits(token)` | Stops new deposits for the token. Withdrawals continue. | | `resumeDeposits(token)` | Restarts deposits for a previously paused token. | Once enabled, a token cannot be disabled. This preserves withdrawals for that token, subject to the token's own compliance policy. Tokens on the Tempo Zone use the same address as their Tempo Mainnet counterpart. `ZoneInbox` mints on deposit, `ZoneOutbox` burns on withdrawal. No mechanism exists to create new tokens on the Tempo Zone. # Zone Proving :::info Tempo Zones is still in early development and is available for testing purposes on Tempo Testnet only. While Tempo Zones are in this stage, expect breaking changes to the design and implementation. Do not use this in production. If you're interested in working with Tempo Labs as a design partner on the development of Tempo Zones, contact us at [tempo.xyz/contact](https://tempo.xyz/contact). ::: :::warning The zone prover is not yet live. This page describes the planned design. The prover will be added in a future release. ::: Zone settlement uses validity proofs to verify correct execution. The prover implements a pure state transition function in Rust with `no_std` compatibility, allowing it to run in both ZKVMs (SP1) and TEEs (SGX/TDX). ## Batch Submission The sequencer posts batches to Tempo Mainnet via `submitBatch` on the portal. Each batch covers one or more zone blocks and includes: | Field | Description | |-------|-------------| | `tempoBlockNumber` | Tempo block the zone committed to (from zone's TempoState) | | `recentTempoBlockNumber` | Optional recent block for ancestry proof (`0` = direct lookup) | | `blockTransition` | Zone block hash transition (`prevBlockHash` → `nextBlockHash`) | | `depositQueueTransition` | Deposit queue processing progress | | `withdrawalQueueHash` | Hash chain of withdrawals for this batch (`0` if none) | | `verifierConfig` | Opaque payload for the verifier (domain separation / attestation) | | `proof` | Validity proof or TEE attestation | The portal verifies that `prevBlockHash` matches the stored `blockHash`, calls the verifier, and on success updates `withdrawalBatchIndex`, `blockHash`, `lastSyncedTempoBlockNumber`, and adds withdrawals to the queue. ## Verifier Interface The verifier is abstracted behind a minimal interface. ZK systems and TEE attesters implement the same contract: ```solidity interface IVerifier { function verify( uint64 tempoBlockNumber, uint64 anchorBlockNumber, bytes32 anchorBlockHash, uint64 expectedWithdrawalBatchIndex, address sequencer, BlockTransition calldata blockTransition, DepositQueueTransition calldata depositQueueTransition, bytes32 withdrawalQueueHash, bytes calldata verifierConfig, bytes calldata proof ) external view returns (bool); } ``` The proof verifies that: 1. Valid state transition from `prevBlockHash` to `nextBlockHash`. 2. Zone committed to `tempoBlockNumber` via TempoState. 3. Anchor block hash matches (direct or ancestry mode). 4. `ZoneOutbox.lastBatch()` has the correct `withdrawalBatchIndex` and `withdrawalQueueHash`. 5. Deposit processing is correct (validated via Tempo state read inside proof). 6. Zone block `beneficiary` matches the registered sequencer. ## State Transition Function The prover takes a complete witness of zone blocks and their dependencies, executes the EVM state transitions, and outputs commitments for on-chain verification: ```rust pub fn prove_zone_batch(witness: BatchWitness) -> Result