<!-- tempo-docs-context -->
> Source: [/docs/protocol/zones/bridging](https://tempo.com/developers/docs/protocol/zones/bridging.md)
> Section: [Zones](https://tempo.com/developers/docs/zones.md). Connect to a Zone and work with private balances, deposits, and withdrawals. Zones is live on Mainnet; see the introduction to set up a Zone. Earlier testnet sandbox guides describe a separate integration.
> [Documentation index](https://tempo.com/developers/llms.txt) · [Docs skill](https://tempo.com/developers/SKILL.md)

> Tempo MCP: Use `search`, `find_pages`, `read_page`, and `code` at `https://mcp.tempo.xyz` for Tempo and related documentation.
> If an indexed page is missing or reflects an older site, read this site’s [documentation index](https://tempo.com/developers/llms.txt) and Markdown pages directly.

# Bridging

The portal (`ZonePortal`) connects a Zone's private ledger to tokens on Tempo.

## Overview

Deposits lock tokens in the portal and credit a private account. Withdrawals burn the Zone-side tokens and release the backing assets to a Tempo recipient.

Both flows settle in stages. Deposits enter the Zone after Tempo finality. Withdrawals reach Tempo after their batch is accepted. Bridge amounts are public, and the account ledger stays private.

<span id="deposits-tempo--zone" />

## Deposits

A deposit moves tokens from Tempo into a Zone. It starts on Tempo and finishes when `ZoneInbox` processes it inside the Zone. The recipient and memo are encrypted to the operator. The token, amount, and public depositor stay visible on Tempo.

A Tempo account encrypts recipient details and submits a deposit. ZonePortal checks the request, locks backing assets, and queues the net deposit. After Tempo finality, ZoneInbox decrypts and processes it, then credits the recipient’s private balance.

1. User calls `ZonePortal.depositEncrypted(token, amount, keyIndex, encryptedPayload, tempoRefundRecipient)` on Tempo. `deposit` is an alias with the same encrypted-only arguments. There's no plaintext recipient entry point.
2. The portal validates the token, encryption key, refund recipient, and configured access rules. It checks that deposits are active and deducts the [deposit fee](https://tempo.com/developers/docs/protocol/zones/execution#deposit-fees). It then locks the funds and appends a deposit to the queue.
3. The sequencer observes `DepositMade` events and processes deposits in order via `ZoneInbox.advanceTempo()`. This mints the corresponding Zone-side TIP-20 token to the recipient.
4. Batch submission confirms deposit progress on the portal. The stateless proof function replays deposit processing against witnessed Tempo state, within the [current settlement verification limits](https://tempo.com/developers/docs/protocol/zones/proving).

### Encrypted Deposits

All user deposits encrypt the recipient and memo using the operator's published encryption key. Nodes that hold the corresponding private key can decrypt the deposit. They then credit its recipient on the Zone.

The deposit fields have this visibility:

| Field | Visibility | Reason |
|-------|------------|--------|
| `token` | Public | Needed for locked token accounting |
| `sender` | Public | Tempo account or gateway making the deposit |
| `tempoRefundRecipient` | Public | Receives a failed-deposit refund on Tempo |
| `amount` | Public | Needed for onchain locked token accounting |
| `to` | Encrypted | Only holders of the decryption key know the recipient |
| `memo` | Encrypted | Only holders of the decryption key know the 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, tempoRefundRecipient)` on the portal.

The inbox verifies a Chaum–Pedersen proof of the ECDH shared secret before decrypting. Ciphertext authentication can fail, or the Zone can be unable to mint to the recipient. In either case, the inbox queues a refund to `tempoRefundRecipient` on Tempo. The refund deducts the configured bounce-back fee when that fee can be collected.

If the Tempo transfer fails, the portal records `refunds(token, owner)`. The recipient recovers it through `claimRefund(token)` once the applicable restrictions permit it.

<span id="withdrawals-zone--tempo" />

## Withdrawals

A withdrawal moves tokens from a Zone back to Tempo. It starts with a request to `ZoneOutbox`, which burns the Zone-side amount and records the public recipient. The sequencer includes the request in a batch before the portal can deliver the tokens on Tempo.

ZoneOutbox burns the Zone tokens and queues a withdrawal. The operator finalizes the withdrawal queue and submits signed batch commitments. ZonePortal checks the certificate, continuity, and configured verifier before accepting the batch. The queued withdrawal is then processed to deliver tokens or invoke a callback on Tempo.

1. **Batch submission:** The sequencer calls `finalizeWithdrawalBatch()` at the end of the final block in a batch. This constructs the withdrawal hash chain. It writes the `withdrawalQueueHash` and `withdrawalBatchIndex` to state. An accepted portal batch commits this state and adds withdrawals to Tempo's queue. The [verifier interface](https://tempo.com/developers/docs/protocol/zones/proving#verifier-interface) sets the certificate checks, execution validation, and current verifier behavior.
2. **Withdrawal processing:** The sequencer calls `processWithdrawals(withdrawals, remainingQueue)` on Tempo to process withdrawals in FIFO order.

### Composable Withdrawals

Withdrawals support callbacks to Tempo contracts via `ZoneMessenger`. When `gasLimit > 0`, the messenger:

1. Receives tokens from the portal, then transfers them to the target.
2. Calls the target with the provided `callbackData`.

Both operations are atomic. If the callback reverts, the transfer reverts too. Receiving contracts:

* Implement `IWithdrawalReceiver`.
* Verify `msg.sender == zoneMessenger`.
* Validate `zoneId` and `sourcePortal` against the intended source Zone.

This enables direct composition with DEX swaps, staking, or cross-Zone deposits.

```solidity
interface IWithdrawalReceiver {
    function onWithdrawalReceived(
        uint32 zoneId,
        address sourcePortal,
        bytes32 senderTag,
        address token,
        uint128 amount,
        bytes calldata callbackData
    ) external returns (bytes4);
}
```

Callback data is limited to 1,024 bytes and callback gas to 10,000,000. When gateway enforcement is enabled, the target must have the portal's `CallbackGateway` role. In closed-access mode, a successful callback must append a deposit to the source portal. Registered gateways are trusted to return the intended assets and amounts. Cross-Zone callbacks therefore depend on the source Zone's access configuration.

### Withdrawal Failure and Bounce-Back

A withdrawal fails if the token transfer or callback reverts. Causes include running out of gas, a TIP-403 policy, or a token pause. When a withdrawal fails, the portal bounces back the funds. It re-deposits them into the same Zone to the withdrawal's Zone-side `zoneFallbackRecipient`. Tempo sees only a `fallbackNonce`. The outbox resolves that nonce to the private recipient:

* The withdrawal is **popped unconditionally** from the queue, even on failure.
* A new deposit is enqueued carrying the fallback nonce. The inbox resolves it and attempts to mint to the Zone recipient.
* The withdrawal fee isn't refunded on a failed delivery.
* If policy or a pause blocks the bounce-back mint, the inbox records a pending refund. The recipient can call `ZoneInbox.claimRefund(token)` once minting is permitted.

Delivery failures don't block subsequent withdrawals. Processing can still wait for deposit-queue capacity. The T13 portal limits outstanding deposits and reserves capacity for callback deposits and bounce-backs. Refund claims remain subject to the applicable token and account restrictions.

### Verifiable Withdrawals

Zone transactions are private, so transaction data isn't published on Tempo. Withdrawal processing on Tempo replaces the plaintext `sender` with a commitment. This protects sender privacy:

```solidity
senderTag = keccak256(abi.encodePacked(sender, txHash, fallbackNonce))
```

The `txHash` acts as a blinding factor, a secret value that hides `sender` inside the commitment. Only the sender and sequencer know it. The sender can selectively disclose their identity by revealing `txHash` to any party. That party verifies it against the `senderTag` using the withdrawal's public `fallbackNonce`.

For automated disclosure, the sender can specify a `revealTo` public key. The sequencer encrypts `(sender, txHash)` to that key using ECDH. This populates the `encryptedSender` field in the Tempo-facing withdrawal struct. The destination Zone's sequencer can then attribute incoming cross-Zone deposits automatically.

## Related

[Deposit Into a Zone](https://tempo.com/developers/docs/zones/deposit): Use for funding a private account through the portal on Tempo.

[Withdraw From a Zone](https://tempo.com/developers/docs/zones/withdraw): Use for moving funds from a Zone back to Tempo.

[Execution and Gas](https://tempo.com/developers/docs/protocol/zones/execution): Covers fee tokens, deposit and withdrawal fees, fixed gas costs, and token management.

[Proving and Settlement](https://tempo.com/developers/docs/protocol/zones/proving): Covers batch acceptance, execution validation, and verification guarantees.

[Architecture](https://tempo.com/developers/docs/protocol/zones/architecture): Covers portals, private ledgers, contract roles, and the settlement lifecycle.
