viem 2.55.0 → 2.55.2

package/tempo/actions/zone.ts

@@ -6,7 +6,18 @@ import * as Secp256k1 from 'ox/Secp256k1'
 import { TokenId, ZoneId, ZoneRpcAuthentication } from 'ox/tempo'
 import type { Account } from '../../accounts/types.js'
 import { parseAccount } from '../../accounts/utils/parseAccount.js'
+import {
+  type MulticallErrorType,
+  type MulticallParameters,
+  multicall,
+} from '../../actions/public/multicall.js'
 import { readContract } from '../../actions/public/readContract.js'
+import {
+  type PrepareTransactionRequestErrorType,
+  type PrepareTransactionRequestRequest,
+  type PrepareTransactionRequestReturnType,
+  prepareTransactionRequest,
+} from '../../actions/wallet/prepareTransactionRequest.js'
 import {
   type SendTransactionReturnType,
   sendTransaction,
@@ -16,17 +27,30 @@ import type { Client } from '../../clients/createClient.js'
 import type { Transport } from '../../clients/transports/createTransport.js'
 import { zeroHash } from '../../constants/bytes.js'
 import type { BaseErrorType } from '../../errors/base.js'
-import type { Chain } from '../../types/chain.js'
-import type { Compute } from '../../types/utils.js'
+import type { Chain, GetChainParameter } from '../../types/chain.js'
+import type { Compute, UnionOmit } from '../../types/utils.js'
 import type { RequestErrorType } from '../../utils/buildRequest.js'
+import { type ObserveErrorType, observe } from '../../utils/observe.js'
+import { type PollErrorType, poll } from '../../utils/poll.js'
+import { withResolvers } from '../../utils/promise/withResolvers.js'
+import { stringify } from '../../utils/stringify.js'
 import * as Abis from '../Abis.js'
 import * as Addresses from '../Addresses.js'
+import {
+  WaitForDepositStatusTimeoutError,
+  type WaitForDepositStatusTimeoutErrorType,
+} from '../errors.js'
 import type {
   GetAccountParameter,
   ReadParameters,
   WriteParameters,
+  WriteSyncParameters,
 } from '../internal/types.js'
-import { defineCall, pickWriteParameters } from '../internal/utils.js'
+import {
+  defineCall,
+  pickWriteParameters,
+  pickWriteSyncParameters,
+} from '../internal/utils.js'
 import * as Storage from '../Storage.js'
 import type { TransactionReceipt } from '../Transaction.js'
 import * as ZoneAbis from '../zones/Abis.js'
@@ -43,6 +67,8 @@ export type EncryptedPayload = {
 export type PreparedEncryptedDeposit = {
   /** Amount of tokens to deposit. */
   amount: bigint
+  /** Refund recipient on the parent chain if the deposit bounces. */
+  bouncebackRecipient: Address
   /** Parent chain ID (e.g. `42431` for moderato). */
   chainId: number
   /** Encrypted deposit payload. */
@@ -57,6 +83,19 @@ export type PreparedEncryptedDeposit = {
   zoneId: number
 }
 
+export type PreparedEncryptedDepositRecipient = {
+  /** Parent chain ID (e.g. `42431` for moderato). */
+  chainId: number
+  /** Encrypted recipient and memo payload. */
+  encrypted: EncryptedPayload
+  /** Encryption key index from the portal contract. */
+  keyIndex: bigint
+  /** Zone portal address on the parent chain. */
+  portalAddress: Address
+  /** Zone ID (e.g. `7`). */
+  zoneId: number
+}
+
 /**
  * Deposits tokens into a zone on the parent Tempo chain.
  * Batches approve and deposit into a single transaction.
@@ -98,14 +137,19 @@ export async function deposit<
   const { account = client.account, ...rest } = parameters
 
   const account_ = account ? parseAccount(account) : undefined
-  if (!account) throw new Error('`account` is required.')
-
-  const recipient = parameters.recipient ?? account_?.address
-  if (!recipient) throw new Error('`recipient` is required.')
-
-  const args = { ...parameters, chainId, recipient }
+  if (!account_) throw new Error('`account` is required.')
+
+  const recipient = parameters.recipient ?? account_.address
+  const bouncebackRecipient = parameters.bouncebackRecipient ?? account_.address
+  const args = {
+    ...parameters,
+    bouncebackRecipient,
+    chainId,
+    recipient,
+  }
   return sendTransaction(client, {
     ...rest,
+    account,
     calls: deposit.calls(args),
   } as never) as never
 }
@@ -115,7 +159,9 @@ export namespace deposit {
     chain extends Chain | undefined = Chain | undefined,
     account extends Account | undefined = Account | undefined,
   > = WriteParameters<chain, account> &
-    Omit<Args, 'chainId' | 'recipient'> & {
+    Omit<Args, 'bouncebackRecipient' | 'chainId' | 'recipient'> & {
+      /** Refund recipient on the parent chain. @default `account.address` */
+      bouncebackRecipient?: Address | undefined
       /** Recipient address in the zone. @default `account.address` */
       recipient?: Address | undefined
     }
@@ -123,10 +169,14 @@ export namespace deposit {
   export type Args = {
     /** Amount of tokens to deposit. */
     amount: bigint
+    /** Refund recipient on the parent chain if the deposit bounces. */
+    bouncebackRecipient: Address
     /** Parent chain ID (e.g. `42431` for moderato). */
     chainId: number
     /** Optional deposit memo. @default `0x00...00` */
     memo?: Hex.Hex | undefined
+    /** Zone portal address. @default resolved via the portal registry. */
+    portalAddress?: Address | undefined
     /** Recipient address in the zone. */
     recipient: Address
     /** Token address or ID to deposit. */
@@ -147,22 +197,31 @@ export namespace deposit {
    * @returns The calls.
    */
   export function calls(args: Args) {
-    const { amount, chainId, memo = zeroHash, recipient, token, zoneId } = args
-    const portalAddress = getPortalAddress(chainId, zoneId)
-    return [
-      defineCall({
-        address: TokenId.toAddress(token),
-        abi: Abis.tip20,
-        functionName: 'approve',
-        args: [portalAddress, amount],
-      }),
-      defineCall({
-        address: portalAddress,
-        abi: ZoneAbis.zonePortal,
-        functionName: 'deposit',
-        args: [TokenId.toAddress(token), recipient, amount, memo],
-      }),
-    ]
+    const {
+      amount,
+      bouncebackRecipient,
+      chainId,
+      memo = zeroHash,
+      recipient,
+      token,
+      zoneId,
+    } = args
+    const portalAddress =
+      args.portalAddress ?? getPortalAddress(chainId, zoneId)
+    const tokenAddress = TokenId.toAddress(token)
+    const approveCall = defineCall({
+      address: tokenAddress,
+      abi: Abis.tip20,
+      functionName: 'approve',
+      args: [portalAddress, amount],
+    })
+    const depositCall = defineCall({
+      address: portalAddress,
+      abi: ZoneAbis.zonePortal,
+      functionName: 'deposit',
+      args: [tokenAddress, recipient, amount, memo, bouncebackRecipient],
+    })
+    return [approveCall, depositCall]
   }
 }
 
@@ -211,14 +270,19 @@ export async function depositSync<
   } = parameters
 
   const account_ = account ? parseAccount(account) : undefined
-  if (!account) throw new Error('`account` is required.')
-
-  const recipient = parameters.recipient ?? account_?.address
-  if (!recipient) throw new Error('`recipient` is required.')
-
-  const args = { ...parameters, chainId, recipient }
+  if (!account_) throw new Error('`account` is required.')
+
+  const recipient = parameters.recipient ?? account_.address
+  const bouncebackRecipient = parameters.bouncebackRecipient ?? account_.address
+  const args = {
+    ...parameters,
+    bouncebackRecipient,
+    chainId,
+    recipient,
+  }
   const receipt = await sendTransactionSync(client, {
     ...rest,
+    account,
     throwOnReceiptRevert,
     calls: deposit.calls(args),
   } as never)
@@ -242,6 +306,121 @@ export namespace depositSync {
   export type ErrorType = BaseErrorType
 }
 
+/**
+ * Gets the active sequencer encryption key for a zone.
+ *
+ * @example
+ * ```ts
+ * import { createClient, http } from 'viem'
+ * import { tempoModerato } from 'viem/chains'
+ * import { Actions } from 'viem/tempo'
+ *
+ * const client = createClient({
+ *   chain: tempoModerato,
+ *   transport: http(),
+ * })
+ *
+ * const { keyIndex, publicKey } = await Actions.zone.getEncryptionKey(client, {
+ *   zoneId: 7,
+ * })
+ * ```
+ *
+ * @param client - Public client connected to the parent Tempo chain.
+ * @param parameters - Zone encryption key parameters.
+ * @returns The active encryption key and its zero-based index.
+ */
+export async function getEncryptionKey<chain extends Chain | undefined>(
+  client: Client<Transport, chain>,
+  parameters: getEncryptionKey.Parameters,
+): Promise<getEncryptionKey.ReturnValue> {
+  const chainId = client.chain?.id
+  if (!chainId) throw new Error('`chain` is required.')
+
+  const { account, portalAddress: portalAddress_, zoneId, ...rest } = parameters
+  const portalAddress = portalAddress_ ?? getPortalAddress(chainId, zoneId)
+  const [keyCountResult, publicKeyResult] = await multicall(client, {
+    ...rest,
+    account: account ? parseAccount(account).address : undefined,
+    allowFailure: true,
+    batchSize: 0,
+    contracts: getEncryptionKey.calls({ portalAddress }),
+    deployless: true,
+  })
+
+  if (keyCountResult.status === 'failure') throw keyCountResult.error
+  const keyCount = keyCountResult.result
+  if (keyCount === 0n || publicKeyResult.status === 'failure')
+    throw keyCount === 0n
+      ? new Error('No sequencer encryption key configured.')
+      : publicKeyResult.error
+  const [x, prefix] = publicKeyResult.result
+  PublicKey.assert({ prefix, x: Hex.toBigInt(x) }, { compressed: true })
+  return {
+    keyIndex: keyCount - 1n,
+    publicKey: { prefix: prefix as 2 | 3, x },
+  }
+}
+
+export namespace getEncryptionKey {
+  export type Parameters = UnionOmit<
+    MulticallParameters,
+    | 'allowFailure'
+    | 'account'
+    | 'batchSize'
+    | 'contracts'
+    | 'deployless'
+    | 'multicallAddress'
+  > &
+    Args & {
+      /** Account used for the contract reads. */
+      account?: Account | Address | undefined
+    }
+
+  export type Args = {
+    /** Zone portal address. @default resolved via the portal registry. */
+    portalAddress?: Address | undefined
+    /** Zone ID (e.g. `7`). */
+    zoneId: number
+  }
+
+  export type ReturnValue = Compute<{
+    /** Zero-based encryption key index. */
+    keyIndex: bigint
+    /** Active sequencer encryption public key. */
+    publicKey: {
+      /** SEC1 compressed public key prefix. */
+      prefix: 2 | 3
+      x: Hex.Hex
+    }
+  }>
+
+  export type ErrorType =
+    | MulticallErrorType
+    | PublicKey.assert.ErrorType
+    | BaseErrorType
+
+  /**
+   * Defines calls to the encryption key count and active sequencer key.
+   *
+   * @param args - Arguments.
+   * @returns The calls.
+   */
+  export function calls(args: { portalAddress: Address }) {
+    return [
+      defineCall({
+        address: args.portalAddress,
+        abi: ZoneAbis.zonePortal,
+        functionName: 'encryptionKeyCount',
+      }),
+      defineCall({
+        address: args.portalAddress,
+        abi: ZoneAbis.zonePortal,
+        functionName: 'sequencerEncryptionKey',
+      }),
+    ] as const
+  }
+}
+
 /**
  * Deposits tokens into a zone on the parent Tempo chain with encrypted
  * recipient and memo. Batches approve and depositEncrypted into a single
@@ -284,7 +463,9 @@ export async function encryptedDeposit<
   const { account = client.account, ...rest } = parameters
 
   const account_ = account ? parseAccount(account) : undefined
-  if (!account) throw new Error('`account` is required.')
+  if (!account_) throw new Error('`account` is required.')
+
+  const bouncebackRecipient = parameters.bouncebackRecipient ?? account_.address
 
   if ('encrypted' in parameters) {
     if (parameters.chainId !== chainId) {
@@ -294,22 +475,27 @@ export async function encryptedDeposit<
     }
     return sendTransaction(client, {
       ...pickWriteParameters(parameters as never),
-      calls: encryptedDeposit.calls(parameters),
+      calls: encryptedDeposit.calls({
+        ...parameters,
+        bouncebackRecipient,
+      }),
     } as never) as never
   }
 
-  const recipient = parameters.recipient ?? account_?.address
-  if (!recipient) throw new Error('`recipient` is required.')
+  const recipient = parameters.recipient ?? account_.address
 
   const prepared = await encryptedDeposit.prepare(client, {
     amount: parameters.amount,
+    bouncebackRecipient,
     memo: parameters.memo,
+    portalAddress: parameters.portalAddress,
     recipient,
     token: parameters.token,
     zoneId: parameters.zoneId,
   })
   return sendTransaction(client, {
     ...rest,
+    account,
     calls: encryptedDeposit.calls(prepared),
   } as never) as never
 }
@@ -320,7 +506,16 @@ export namespace encryptedDeposit {
     account extends Account | undefined = Account | undefined,
   > = WriteParameters<chain, account> &
     (
-      | (Omit<Args, 'chainId' | 'encrypted' | 'keyIndex' | 'recipient'> & {
+      | (Omit<
+          Args,
+          | 'bouncebackRecipient'
+          | 'chainId'
+          | 'encrypted'
+          | 'keyIndex'
+          | 'recipient'
+        > & {
+          /** Refund recipient on the parent chain. @default `account.address` */
+          bouncebackRecipient?: Address | undefined
           /** Recipient address in the zone. @default `account.address` */
           recipient?: Address | undefined
         })
@@ -330,6 +525,8 @@ export namespace encryptedDeposit {
   export type Args = {
     /** Amount of tokens to deposit. */
     amount: bigint
+    /** Refund recipient on the parent chain if the deposit bounces. */
+    bouncebackRecipient: Address
     /** Parent chain ID (e.g. `42431` for moderato). */
     chainId: number
     /** Encrypted deposit payload. */
@@ -338,6 +535,8 @@ export namespace encryptedDeposit {
     keyIndex: bigint
     /** Optional deposit memo. @default `0x00...00` */
     memo?: Hex.Hex | undefined
+    /** Zone portal address. @default resolved via the portal registry. */
+    portalAddress?: Address | undefined
     /** Recipient address in the zone. */
     recipient: Address
     /** Token address or ID to deposit. */
@@ -368,6 +567,7 @@ export namespace encryptedDeposit {
    * const prepared = await Actions.zone.encryptedDeposit.prepare(client, {
    *   token: '0x20c0...0001',
    *   amount: 1_000_000n,
+   *   bouncebackRecipient: '0x...',
    *   recipient: '0x...',
    *   zoneId: 7,
    * })
@@ -387,41 +587,38 @@ export namespace encryptedDeposit {
     const chainId = client.chain?.id
     if (!chainId) throw new Error('`chain` is required.')
 
-    const { amount, memo, recipient, token, zoneId, ...rest } = parameters
-    const portalAddress = getPortalAddress(chainId, zoneId)
-
-    const [publicKey, keyIndex] = await Promise.all([
-      readContract(client, {
-        ...rest,
-        address: portalAddress,
-        abi: ZoneAbis.zonePortal,
-        functionName: 'sequencerEncryptionKey',
-      }),
-      readContract(client, {
-        ...rest,
-        address: portalAddress,
-        abi: ZoneAbis.zonePortal,
-        functionName: 'encryptionKeyCount',
-      }),
-    ])
+    const {
+      amount,
+      bouncebackRecipient,
+      memo,
+      portalAddress: portalAddress_,
+      recipient,
+      token,
+      zoneId,
+      ...rest
+    } = parameters
+    const portalAddress = portalAddress_ ?? getPortalAddress(chainId, zoneId)
 
-    if (keyIndex === 0n) {
-      throw new Error('No sequencer encryption key configured.')
-    }
+    const { keyIndex, publicKey } = await getEncryptionKey(client, {
+      ...rest,
+      portalAddress,
+      zoneId,
+    })
 
     const encrypted = await encryptDepositPayload(
-      { x: publicKey[0], yParity: publicKey[1] },
+      publicKey,
       recipient,
       portalAddress,
-      keyIndex - 1n,
+      keyIndex,
       memo,
     )
 
     return {
       amount,
+      bouncebackRecipient,
       chainId,
       encrypted,
-      keyIndex: keyIndex - 1n,
+      keyIndex,
       portalAddress,
       token,
       zoneId,
@@ -434,8 +631,12 @@ export namespace encryptedDeposit {
     export type Args = {
       /** Amount of tokens to deposit. */
       amount: bigint
+      /** Refund recipient on the parent chain if the deposit bounces. */
+      bouncebackRecipient: Address
       /** Optional deposit memo. @default `0x00...00` */
       memo?: Hex.Hex | undefined
+      /** Zone portal address. @default resolved via the portal registry. */
+      portalAddress?: Address | undefined
       /** Recipient address in the zone. */
       recipient: Address
       /** Token address or ID to deposit. */
@@ -446,7 +647,94 @@ export namespace encryptedDeposit {
 
     export type ReturnValue = PreparedEncryptedDeposit
 
-    export type ErrorType = RequestErrorType | BaseErrorType
+    export type ErrorType = getEncryptionKey.ErrorType | BaseErrorType
+  }
+
+  /**
+   * Prepares encrypted Zone recipient instructions without constructing a token
+   * deposit.
+   *
+   * Use this when another contract or service controls the token movement and
+   * only needs the ZonePortal `keyIndex` and encrypted recipient payload.
+   *
+   * @example
+   * ```ts
+   * import { createClient, http } from 'viem'
+   * import { tempoModerato } from 'viem/chains'
+   * import { Actions } from 'viem/tempo'
+   *
+   * const client = createClient({
+   *   chain: tempoModerato,
+   *   transport: http(),
+   * })
+   *
+   * const recipient = await Actions.zone.encryptedDeposit.prepareRecipient(client, {
+   *   recipient: '0x...',
+   *   zoneId: 7,
+   * })
+   * ```
+   *
+   * @param client - Public client connected to the parent Tempo chain.
+   * @param parameters - Encrypted recipient preparation parameters.
+   * @returns Prepared encrypted recipient instructions.
+   */
+  export async function prepareRecipient<
+    chain extends Chain | undefined,
+    account extends Account | undefined,
+  >(
+    client: Client<Transport, chain, account>,
+    parameters: prepareRecipient.Parameters,
+  ): Promise<prepareRecipient.ReturnValue> {
+    const chainId = client.chain?.id
+    if (!chainId) throw new Error('`chain` is required.')
+
+    const {
+      memo,
+      portalAddress: portalAddress_,
+      recipient,
+      zoneId,
+      ...rest
+    } = parameters
+    const portalAddress = portalAddress_ ?? getPortalAddress(chainId, zoneId)
+    const { keyIndex, publicKey } = await getEncryptionKey(client, {
+      ...rest,
+      portalAddress,
+      zoneId,
+    })
+    const encrypted = await encryptDepositPayload(
+      publicKey,
+      recipient,
+      portalAddress,
+      keyIndex,
+      memo,
+    )
+
+    return {
+      chainId,
+      encrypted,
+      keyIndex,
+      portalAddress,
+      zoneId,
+    }
+  }
+
+  export namespace prepareRecipient {
+    export type Parameters = ReadParameters & Args
+
+    export type Args = {
+      /** Optional deposit memo. @default `0x00...00` */
+      memo?: Hex.Hex | undefined
+      /** Zone portal address. @default resolved via the portal registry. */
+      portalAddress?: Address | undefined
+      /** Recipient address in the zone. */
+      recipient: Address
+      /** Zone ID (e.g. `7`). */
+      zoneId: number
+    }
+
+    export type ReturnValue = PreparedEncryptedDepositRecipient
+
+    export type ErrorType = getEncryptionKey.ErrorType | BaseErrorType
   }
 
   /**
@@ -456,33 +744,44 @@ export namespace encryptedDeposit {
    * @returns The calls.
    */
   export function calls(args: Args | PreparedEncryptedDeposit) {
-    const { amount, chainId, encrypted, keyIndex, token, zoneId } = args
-    const portalAddress = getPortalAddress(chainId, zoneId)
-    return [
-      defineCall({
-        address: TokenId.toAddress(token),
-        abi: Abis.tip20,
-        functionName: 'approve',
-        args: [portalAddress, amount],
-      }),
-      defineCall({
-        address: portalAddress,
-        abi: ZoneAbis.zonePortal,
-        functionName: 'depositEncrypted',
-        args: [
-          TokenId.toAddress(token),
-          amount,
-          keyIndex,
-          {
-            ephemeralPubkeyX: encrypted.ephemeralPubkeyX,
-            ephemeralPubkeyYParity: encrypted.ephemeralPubkeyYParity,
-            ciphertext: encrypted.ciphertext,
-            nonce: encrypted.nonce,
-            tag: encrypted.tag,
-          },
-        ],
-      }),
-    ]
+    const {
+      amount,
+      bouncebackRecipient,
+      chainId,
+      encrypted,
+      keyIndex,
+      token,
+      zoneId,
+    } = args
+    const portalAddress =
+      args.portalAddress ?? getPortalAddress(chainId, zoneId)
+    const tokenAddress = TokenId.toAddress(token)
+    const encryptedPayload = {
+      ephemeralPubkeyX: encrypted.ephemeralPubkeyX,
+      ephemeralPubkeyYParity: encrypted.ephemeralPubkeyYParity,
+      ciphertext: encrypted.ciphertext,
+      nonce: encrypted.nonce,
+      tag: encrypted.tag,
+    }
+    const approveCall = defineCall({
+      address: tokenAddress,
+      abi: Abis.tip20,
+      functionName: 'approve',
+      args: [portalAddress, amount],
+    })
+    const depositCall = defineCall({
+      address: portalAddress,
+      abi: ZoneAbis.zonePortal,
+      functionName: 'depositEncrypted',
+      args: [
+        tokenAddress,
+        amount,
+        keyIndex,
+        encryptedPayload,
+        bouncebackRecipient,
+      ],
+    })
+    return [approveCall, depositCall]
   }
 }
 
@@ -531,7 +830,9 @@ export async function encryptedDepositSync<
   } = parameters
 
   const account_ = account ? parseAccount(account) : undefined
-  if (!account) throw new Error('`account` is required.')
+  if (!account_) throw new Error('`account` is required.')
+
+  const bouncebackRecipient = parameters.bouncebackRecipient ?? account_.address
 
   if ('encrypted' in parameters) {
     if (parameters.chainId !== chainId) {
@@ -541,24 +842,30 @@ export async function encryptedDepositSync<
     }
     const receipt = await sendTransactionSync(client, {
       ...pickWriteParameters(parameters as never),
+      ...pickWriteSyncParameters(parameters as never),
       throwOnReceiptRevert,
-      calls: encryptedDeposit.calls(parameters),
+      calls: encryptedDeposit.calls({
+        ...parameters,
+        bouncebackRecipient,
+      }),
     } as never)
     return { receipt }
   }
 
-  const recipient = parameters.recipient ?? account_?.address
-  if (!recipient) throw new Error('`recipient` is required.')
+  const recipient = parameters.recipient ?? account_.address
 
   const prepared = await encryptedDeposit.prepare(client, {
     amount: parameters.amount,
+    bouncebackRecipient,
     memo: parameters.memo,
+    portalAddress: parameters.portalAddress,
     recipient,
     token: parameters.token,
     zoneId: parameters.zoneId,
   })
   const receipt = await sendTransactionSync(client, {
     ...rest,
+    account,
     throwOnReceiptRevert,
     calls: encryptedDeposit.calls(prepared),
   } as never)
@@ -569,7 +876,8 @@ export namespace encryptedDepositSync {
   export type Parameters<
     chain extends Chain | undefined = Chain | undefined,
     account extends Account | undefined = Account | undefined,
-  > = encryptedDeposit.Parameters<chain, account>
+  > = encryptedDeposit.Parameters<chain, account> &
+    WriteSyncParameters<chain, account>
 
   export type Args = encryptedDeposit.Args
 
@@ -742,7 +1050,118 @@ export namespace getDepositStatus {
 }
 
 /**
- * Returns the fee required for a withdrawal from a zone, given a gas limit.
+ * Waits for a Tempo block's deposits to be processed by a zone.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'viem'
+ * import { Actions } from 'viem/tempo'
+ * import { http, zoneModerato } from 'viem/tempo/zones'
+ *
+ * const client = createClient({
+ *   chain: zoneModerato(7),
+ *   transport: http(),
+ * })
+ *
+ * const status = await Actions.zone.waitForDepositStatus(client, {
+ *   tempoBlockNumber: 42n,
+ * })
+ * ```
+ *
+ * @param client - Zone client.
+ * @param parameters - Tempo block number and polling options.
+ * @returns The processed deposit status.
+ */
+export async function waitForDepositStatus<
+  chain extends Chain | undefined,
+  account extends Account | undefined,
+>(
+  client: Client<Transport, chain, account>,
+  parameters: waitForDepositStatus.Parameters,
+): Promise<waitForDepositStatus.ReturnType> {
+  const {
+    pollingInterval = client.pollingInterval,
+    tempoBlockNumber,
+    timeout = 60_000,
+  } = parameters
+  const observerId = stringify([
+    'waitForDepositStatus',
+    client.uid,
+    tempoBlockNumber,
+  ])
+  const { promise, reject, resolve } =
+    withResolvers<waitForDepositStatus.ReturnType>()
+
+  let timer: ReturnType<typeof setTimeout> | undefined
+  let unobserve: () => void
+  const cleanup = () => {
+    clearTimeout(timer)
+    unobserve()
+  }
+  const resolve_ = (status: waitForDepositStatus.ReturnType) => {
+    cleanup()
+    resolve(status)
+  }
+  const reject_ = (error: unknown) => {
+    cleanup()
+    reject(error)
+  }
+
+  unobserve = observe(
+    observerId,
+    { reject: reject_, resolve: resolve_ },
+    (emit) => {
+      const unpoll = poll(
+        async () => {
+          try {
+            const status = await getDepositStatus(client, { tempoBlockNumber })
+            if (!status.processed) return
+            unpoll()
+            emit.resolve(status)
+          } catch (error) {
+            unpoll()
+            emit.reject(error)
+          }
+        },
+        {
+          emitOnBegin: true,
+          interval: pollingInterval,
+        },
+      )
+
+      return unpoll
+    },
+  )
+
+  timer = timeout
+    ? setTimeout(() => {
+        reject_(new WaitForDepositStatusTimeoutError({ tempoBlockNumber }))
+      }, timeout)
+    : undefined
+
+  return await promise
+}
+
+export namespace waitForDepositStatus {
+  export type Parameters = getDepositStatus.Parameters & {
+    /** Polling frequency in milliseconds. @default `client.pollingInterval` */
+    pollingInterval?: number | undefined
+    /** Timeout in milliseconds. @default `60_000` */
+    timeout?: number | undefined
+  }
+
+  export type ReturnType = getDepositStatus.ReturnType
+
+  export type ErrorType =
+    | getDepositStatus.ErrorType
+    | ObserveErrorType
+    | PollErrorType
+    | WaitForDepositStatusTimeoutErrorType
+}
+
+/**
+ * Returns the fee required for a withdrawal from a zone, given a callback gas
+ * limit.
  *
  * The client must be connected to the **zone chain**.
  *
@@ -761,7 +1180,7 @@ export namespace getDepositStatus {
  * ```
  *
  * @param client - Zone client.
- * @param parameters - Optional gas limit parameter.
+ * @param parameters - Optional callback gas limit parameter.
  * @returns The withdrawal fee as a bigint.
  */
 export async function getWithdrawalFee<
@@ -771,20 +1190,20 @@ export async function getWithdrawalFee<
   client: Client<Transport, chain, account>,
   parameters: getWithdrawalFee.Parameters = {},
 ): Promise<getWithdrawalFee.ReturnType> {
-  const { gas = 0n, ...rest } = parameters
+  const { callbackGas = 0n, ...rest } = parameters
   return readContract(client, {
     ...rest,
     address: Addresses.zoneOutbox,
     abi: ZoneAbis.zoneOutbox,
     functionName: 'calculateWithdrawalFee',
-    args: [gas],
+    args: [callbackGas],
   })
 }
 
 export namespace getWithdrawalFee {
   export type Parameters = ReadParameters & {
-    /** Gas limit for the withdrawal callback. @default `0n` */
-    gas?: bigint | undefined
+    /** Gas limit reserved for the withdrawal callback on the parent chain. @default `0n` */
+    callbackGas?: bigint | undefined
   }
 
   export type ReturnType = bigint
@@ -887,7 +1306,7 @@ export async function requestWithdrawal<
   client: Client<Transport, chain, account>,
   parameters: requestWithdrawal.Parameters<chain, account>,
 ): Promise<requestWithdrawal.ReturnValue> {
-  const { account = client.account, ...rest } = parameters
+  const { account = client.account } = parameters
 
   const account_ = account ? parseAccount(account) : undefined
   if (!account) throw new Error('`account` is required.')
@@ -897,7 +1316,7 @@ export async function requestWithdrawal<
 
   const args = { ...parameters, to }
   return sendTransaction(client, {
-    ...rest,
+    ...pickWriteParameters(parameters as never),
     calls: requestWithdrawal.calls(args),
   } as never) as never
 }
@@ -915,12 +1334,12 @@ export namespace requestWithdrawal {
   export type Args = {
     /** Amount of tokens to withdraw. */
     amount: bigint
+    /** Gas limit reserved for the withdrawal callback on the parent chain. @default `0n` */
+    callbackGas?: bigint | undefined
     /** Optional callback data for the recipient. @default `'0x'` */
     data?: Hex.Hex | undefined
     /** Fallback address if callback fails. @default `to` */
     fallbackRecipient?: Address | undefined
-    /** Gas limit reserved for the withdrawal callback on the parent chain. @default `0n` */
-    gas?: bigint | undefined
     /** Optional withdrawal memo. @default `0x00...00` */
     memo?: Hex.Hex | undefined
     /** Recipient address on the parent Tempo chain. */
@@ -943,9 +1362,9 @@ export namespace requestWithdrawal {
   export function calls(args: Args) {
     const {
       amount,
+      callbackGas = 0n,
       data = '0x',
       fallbackRecipient = args.to,
-      gas = 0n,
       memo = zeroHash,
       to,
       token,
@@ -966,7 +1385,7 @@ export namespace requestWithdrawal {
           to,
           amount,
           memo,
-          gas,
+          callbackGas,
           fallbackRecipient,
           data,
           '0x',
@@ -974,8 +1393,166 @@ export namespace requestWithdrawal {
       }),
     ]
   }
+
+  /**
+   * Prepares a zone withdrawal transaction request without broadcasting it.
+   *
+   * Use this to inspect or modify the populated ZoneOutbox transaction request
+   * and its maximum transaction fee before submitting a withdrawal.
+   *
+   * @example
+   * ```ts
+   * import { createClient } from 'viem'
+   * import { http, zoneModerato } from 'viem/tempo/zones'
+   * import { Actions } from 'viem/tempo'
+   *
+   * const client = createClient({
+   *   chain: zoneModerato(7),
+   *   transport: http(),
+   * })
+   *
+   * const prepared = await Actions.zone.requestWithdrawal.prepare(client, {
+   *   token: '0x20c0...0001',
+   *   amount: 1_000_000n,
+   *   to: '0x...',
+   * })
+   *
+   * console.log(prepared.maxFee)
+   * console.log(prepared.request.gas)
+   * ```
+   *
+   * @param client - Zone client.
+   * @param parameters - Withdrawal preparation parameters.
+   * @returns The prepared transaction request, maximum fee, and withdrawal details.
+   */
+  export async function prepare<
+    chain extends Chain | undefined,
+    account extends Account | undefined,
+    chainOverride extends Chain | undefined = undefined,
+    accountOverride extends Account | Address | undefined = undefined,
+  >(
+    client: Client<Transport, chain, account>,
+    parameters: prepare.Parameters<
+      chain,
+      account,
+      chainOverride,
+      accountOverride
+    >,
+  ): Promise<
+    prepare.ReturnType<chain, account, chainOverride, accountOverride>
+  > {
+    const {
+      account = client.account,
+      amount,
+      callbackGas = 0n,
+      data = '0x',
+      fallbackRecipient,
+      memo = zeroHash,
+      to: to_,
+      token,
+      ...transactionRequest
+    } = parameters
+
+    const account_ = account ? parseAccount(account) : undefined
+    const to = to_ ?? account_?.address
+    if (!to) throw new Error('`to` is required.')
+
+    const request = await prepareTransactionRequest(client, {
+      ...transactionRequest,
+      account,
+      calls: requestWithdrawal.calls({
+        amount,
+        callbackGas,
+        data,
+        fallbackRecipient,
+        memo,
+        to,
+        token,
+      }),
+    } as never)
+    const feePerGas = request.maxFeePerGas ?? request.gasPrice
+    if (typeof request.gas !== 'bigint' || typeof feePerGas !== 'bigint')
+      throw new Error('Prepared transaction fee parameters are unavailable.')
+    const maxFee = ceilDiv(request.gas * feePerGas, 1_000_000_000_000n)
+
+    return {
+      amount,
+      callbackGas,
+      data,
+      fallbackRecipient: fallbackRecipient ?? to,
+      maxFee,
+      memo,
+      request,
+      to,
+      token,
+    } as never
+  }
+
+  export namespace prepare {
+    export type Parameters<
+      chain extends Chain | undefined = Chain | undefined,
+      account extends Account | undefined = Account | undefined,
+      chainOverride extends Chain | undefined = Chain | undefined,
+      accountOverride extends Account | Address | undefined =
+        | Account
+        | Address
+        | undefined,
+    > = UnionOmit<
+      WriteParameters<chain, account>,
+      'account' | 'chain' | 'throwOnReceiptRevert'
+    > &
+      GetAccountParameter<account, accountOverride, false> &
+      GetChainParameter<chain, chainOverride> &
+      PrepareArgs
+
+    export type PrepareArgs = Omit<Args, 'to'> & {
+      /** Recipient address on the parent Tempo chain. @default `account.address` */
+      to?: Address | undefined
+    }
+
+    export type ReturnType<
+      chain extends Chain | undefined = Chain | undefined,
+      account extends Account | undefined = Account | undefined,
+      chainOverride extends Chain | undefined = Chain | undefined,
+      accountOverride extends Account | Address | undefined =
+        | Account
+        | Address
+        | undefined,
+    > = Compute<{
+      /** Amount of tokens to withdraw. */
+      amount: bigint
+      /** Gas limit reserved for the callback on the parent chain. */
+      callbackGas: bigint
+      /** Callback data for the recipient. */
+      data: Hex.Hex
+      /** Fallback address if the callback fails. */
+      fallbackRecipient: Address
+      /** Maximum Zone transaction fee in fee-token base units. */
+      maxFee: bigint
+      /** Withdrawal memo. */
+      memo: Hex.Hex
+      /** Prepared Zone transaction request. */
+      request: PrepareTransactionRequestReturnType<
+        chain,
+        account,
+        chainOverride,
+        accountOverride,
+        PrepareTransactionRequestRequest<chain, chainOverride> & {
+          calls: WithdrawalCalls
+        }
+      >
+      /** Recipient address on the parent Tempo chain. */
+      to: Address
+      /** Token address or ID to withdraw. */
+      token: TokenId.TokenIdOrAddress
+    }>
+
+    export type ErrorType = PrepareTransactionRequestErrorType | BaseErrorType
+  }
 }
 
+type WithdrawalCalls = ReturnType<typeof requestWithdrawal.calls>
+
 /**
  * Requests a withdrawal from a zone to the parent Tempo chain and waits for
  * the transaction receipt.
@@ -1010,11 +1587,7 @@ export async function requestWithdrawalSync<
   client: Client<Transport, chain, account>,
   parameters: requestWithdrawalSync.Parameters<chain, account>,
 ): Promise<requestWithdrawalSync.ReturnValue> {
-  const {
-    account = client.account,
-    throwOnReceiptRevert = true,
-    ...rest
-  } = parameters
+  const { account = client.account, throwOnReceiptRevert = true } = parameters
 
   const account_ = account ? parseAccount(account) : undefined
   if (!account) throw new Error('`account` is required.')
@@ -1024,7 +1597,8 @@ export async function requestWithdrawalSync<
 
   const args = { ...parameters, to }
   const receipt = await sendTransactionSync(client, {
-    ...rest,
+    ...pickWriteParameters(parameters as never),
+    ...pickWriteSyncParameters(parameters as never),
     calls: requestWithdrawal.calls(args),
     throwOnReceiptRevert,
   } as never)
@@ -1035,7 +1609,8 @@ export namespace requestWithdrawalSync {
   export type Parameters<
     chain extends Chain | undefined = Chain | undefined,
     account extends Account | undefined = Account | undefined,
-  > = requestWithdrawal.Parameters<chain, account>
+  > = requestWithdrawal.Parameters<chain, account> &
+    WriteSyncParameters<chain, account>
 
   export type Args = requestWithdrawal.Args
 
@@ -1086,7 +1661,7 @@ export async function requestVerifiableWithdrawal<
   client: Client<Transport, chain, account>,
   parameters: requestVerifiableWithdrawal.Parameters<chain, account>,
 ): Promise<requestVerifiableWithdrawal.ReturnValue> {
-  const { account = client.account, ...rest } = parameters
+  const { account = client.account } = parameters
 
   const account_ = account ? parseAccount(account) : undefined
   if (!account) throw new Error('`account` is required.')
@@ -1096,7 +1671,7 @@ export async function requestVerifiableWithdrawal<
 
   const args = { ...parameters, to }
   return sendTransaction(client, {
-    ...rest,
+    ...pickWriteParameters(parameters as never),
     calls: requestVerifiableWithdrawal.calls(args),
   } as never) as never
 }
@@ -1130,9 +1705,9 @@ export namespace requestVerifiableWithdrawal {
   export function calls(args: Args) {
     const {
       amount,
+      callbackGas = 0n,
       data = '0x',
       fallbackRecipient = args.to,
-      gas = 0n,
       memo = zeroHash,
       revealTo,
       to,
@@ -1154,7 +1729,7 @@ export namespace requestVerifiableWithdrawal {
           to,
           amount,
           memo,
-          gas,
+          callbackGas,
           fallbackRecipient,
           data,
           revealTo,
@@ -1199,11 +1774,7 @@ export async function requestVerifiableWithdrawalSync<
   client: Client<Transport, chain, account>,
   parameters: requestVerifiableWithdrawalSync.Parameters<chain, account>,
 ): Promise<requestVerifiableWithdrawalSync.ReturnValue> {
-  const {
-    account = client.account,
-    throwOnReceiptRevert = true,
-    ...rest
-  } = parameters
+  const { account = client.account, throwOnReceiptRevert = true } = parameters
 
   const account_ = account ? parseAccount(account) : undefined
   if (!account) throw new Error('`account` is required.')
@@ -1213,7 +1784,8 @@ export async function requestVerifiableWithdrawalSync<
 
   const args = { ...parameters, to }
   const receipt = await sendTransactionSync(client, {
-    ...rest,
+    ...pickWriteParameters(parameters as never),
+    ...pickWriteSyncParameters(parameters as never),
     calls: requestVerifiableWithdrawal.calls(args),
     throwOnReceiptRevert,
   } as never)
@@ -1224,7 +1796,8 @@ export namespace requestVerifiableWithdrawalSync {
   export type Parameters<
     chain extends Chain | undefined = Chain | undefined,
     account extends Account | undefined = Account | undefined,
-  > = requestVerifiableWithdrawal.Parameters<chain, account>
+  > = requestVerifiableWithdrawal.Parameters<chain, account> &
+    WriteSyncParameters<chain, account>
 
   export type Args = requestVerifiableWithdrawal.Args
 
@@ -1284,6 +1857,8 @@ export async function signAuthorizationToken<
   const chain = parameters.chain ?? client.chain
   if (!chain) throw new Error('`signAuthorizationToken` requires a chain.')
 
+  const zoneId = parameters.zoneId ?? ZoneId.fromChainId(chain.id)
+
   const account_ = account ? parseAccount(account) : undefined
   if (!account_ || !account_.sign)
     throw new Error('`account` with `sign` is required.')
@@ -1294,7 +1869,7 @@ export async function signAuthorizationToken<
     chainId: chain.id,
     expiresAt,
     issuedAt,
-    zoneId: ZoneId.fromChainId(chain.id),
+    zoneId,
   })
 
   const payload = ZoneRpcAuthentication.getSignPayload(authentication)
@@ -1326,6 +1901,8 @@ export namespace signAuthorizationToken {
     issuedAt?: number | undefined
     /** Storage to persist the token. @default sessionStorage (web) or memory (server). */
     storage?: Storage.Storage | undefined
+    /** Zone ID to scope the token to (`0` for unscoped). @default derived from `chain.id`. */
+    zoneId?: number | undefined
   }
 
   export type ReturnType = {
@@ -1342,14 +1919,14 @@ export namespace signAuthorizationToken {
  * @internal
  */
 async function encryptDepositPayload(
-  publicKey: { x: Hex.Hex; yParity: number },
+  publicKey: { prefix: 2 | 3; x: Hex.Hex },
   recipient: Address,
   portalAddress: Address,
   keyIndex: bigint,
   memo: Hex.Hex = zeroHash,
 ): Promise<EncryptedPayload> {
   const sequencerPublicKey = PublicKey.from({
-    prefix: publicKey.yParity,
+    prefix: publicKey.prefix,
     x: Hex.toBigInt(publicKey.x),
   })
 
@@ -1429,3 +2006,7 @@ function buildDepositHkdfInfo(
     Bytes.from(ephemeralPubkeyX),
   )
 }
+
+function ceilDiv(numerator: bigint, denominator: bigint) {
+  return (numerator + denominator - 1n) / denominator
+}