earn.privateDeposit

Withdraws assets from a private Zone, deposits them into an Earn vault, and returns the Earn shares to an encrypted Zone recipient.

Usage

Prepare the encrypted callback with a parent Tempo client, then submit the withdrawal with the Zone client.

import { Actions } from 'viem/tempo'
import { client as parentClient } from './viem.config'
import { client as zoneClient } from './zones.config'
 
const prepared = await Actions.earn.privateDeposit.prepare(parentClient, {
  assetAmount: 100_000_000n,
  gateway: '0x0000000000000000000000000000000000000001',
  recipient: zoneClient.account.address,
  recoveryRecipient: parentClient.account.address,
  shareAmountMin: 99_500_000n,
  vault: '0x0000000000000000000000000000000000000002',
  zoneId: 7,
})
 
const { receipt, senderTag } = await zoneClient.earn.privateDepositSync(prepared)
{ transactionHash: '0x1234...abcd', ... }

import { Account, Client } from 'viem/tempo'
 
export const client = Client.create({
  account: Account.fromSecp256k1('0x...'),
})

import { Account, Client } from 'viem/tempo'
import { http, zoneModerato } from 'viem/tempo/zones'
 
export const client = Client.create({
  account: Account.fromSecp256k1('0x...'),
  chain: zoneModerato(7),
  transport: http(),
})

The synchronous action confirms the Zone withdrawal. Use earn.waitForPrivateDeposit to wait for the parent-chain vault deposit. senderTag identifies the corresponding parent-chain WithdrawalProcessed event.

Asynchronous Usage

Use earn.privateDeposit to return the Zone transaction hash immediately.

import { Actions } from 'viem/tempo'
import { client as parentClient } from './viem.config'
import { client as zoneClient } from './zones.config'
 
const prepared = await Actions.earn.privateDeposit.prepare(parentClient, {
  assetAmount: 100_000_000n,
  gateway: '0x0000000000000000000000000000000000000001',
  recipient: zoneClient.account.address,
  recoveryRecipient: parentClient.account.address,
  shareAmountMin: 99_500_000n,
  vault: '0x0000000000000000000000000000000000000002',
  zoneId: 7,
})
 
const hash = await zoneClient.earn.privateDeposit(prepared)
0x1234...abcd

Bound the Asset Conversion

Each gateway is permanently scoped to one private asset and one vault asset. It converts the private asset into the vault asset through its configured token authority before depositing. Set vaultAssetAmountMin to bound that conversion independently from the Earn share bound.

import { Actions } from 'viem/tempo'
import { client as parentClient } from './viem.config'
import { client as zoneClient } from './zones.config'
 
const prepared = await Actions.earn.privateDeposit.prepare(parentClient, {
  assetAmount: 100_000_000n,
  gateway: '0x0000000000000000000000000000000000000001',
  recipient: zoneClient.account.address,
  recoveryRecipient: parentClient.account.address,
  shareAmountMin: 98_500_000n,
  vault: '0x0000000000000000000000000000000000000003',
  vaultAssetAmountMin: 99_000_000n,
  zoneId: 7,
})

The conversion is fixed at gateway deployment. It cannot select another token or route from callback data. Omitting vaultAssetAmountMin requires the converted vault assets to equal assetAmount.

Return Type

type ReturnType = {
  receipt: TransactionReceipt
  senderTag: Hash
}

The asynchronous action returns the transaction hash instead.

Prepare Return Type

type PreparedZoneRequest = {
  actionId: Hex
  amount: bigint
  callbackGas: bigint
  chainId: number
  data: Hex
  fallbackRecipient: Address
  fromBlock: bigint
  memo?: Hex
  to: Address
  token: Address
  zoneId: number
}

Pass the prepared value directly to earn.privateDeposit or earn.privateDepositSync. The action checks that its parent and Zone chain IDs match the Zone client.

Prepare Parameters

actionId (optional)

• Type: Hex
• Default: A random bytes32 value

Correlation ID encoded in the gateway callback. Supply one when deterministic request preparation is needed.

assetAmount

• Type: bigint

Assets withdrawn from the Zone, in base units.

assetToken (optional)

• Type: Address
• Default: The gateway's private asset

Private asset withdrawn from the Zone. If provided, it must match the gateway's immutable private asset.

callbackGas (optional)

• Type: bigint
• Default: 10_000_000n

Gas reserved for the parent-chain gateway callback.

fallbackRecipient (optional)

• Type: Address
• Default: recoveryRecipient

Public recipient if the parent-chain gateway callback fails.

gateway

• Type: Address

Zone gateway that processes the parent-chain callback.

portalAddress (optional)

• Type: Address
• Default: Derived from zoneId

Source Zone portal on the parent chain.

recipient

• Type: Address

Encrypted Zone recipient for the returned Earn shares.

recoveryRecipient

• Type: Address

Public Tempo recipient if the encrypted return deposit fails.

returnMemo (optional)

• Type: Hex

Memo encrypted with the returned Zone deposit.

shareAmount (optional)

• Type: bigint

Quoted Earn share output. Provide it with slippageBps, or provide shareAmountMin instead.

shareAmountMin (optional)

• Type: bigint

Minimum Earn shares returned to the Zone.

slippageBps (optional)

• Type: number

Slippage tolerance below shareAmount, in basis points. For example, 50 means 0.5%.

vault

• Type: Address

Earn vault receiving the assets.

vaultAssetAmountMin (optional)

• Type: bigint
• Default: assetAmount

Minimum vault assets accepted after the gateway's fixed conversion. This bound works alongside the Earn share bound.

withdrawalMemo (optional)

• Type: Hex

Memo attached to the Zone withdrawal.

zoneId

• Type: number

Source Zone receiving the returned Earn shares.

blockNumber (optional)

• Type: bigint

Block number to read the state from.

blockOverrides (optional)

• Type: BlockOverrides

Block overrides to apply to the state.

blockTag (optional)

• Type: BlockTag

Block tag to read the state from.

stateOverride (optional)

• Type: StateOverride

State override to apply.

Transaction Parameters

account (optional)

• Type: Account | Address

Account that will be used to send the transaction.

feePayer (optional)

• Type: Account | boolean

Fee payer for the transaction (TIP-1 gas sponsorship).

Pass true to defer the fee token to an external fee payer (e.g. a relay), or a local Account to co-sign the transaction as the fee payer.

feeToken (optional)

• Type: Address | bigint

Fee token for the transaction.

Can be an unpaused USD-denominated TIP-20 token address or ID.

gas (optional)

• Type: bigint

Gas limit for the transaction.

keyAuthorization (optional)

• Type: KeyAuthorization

Signed key authorization to include with the transaction, authorizing an access key to act for the sending account.

maxFeePerGas (optional)

• Type: bigint

Max fee per gas for the transaction.

maxPriorityFeePerGas (optional)

• Type: bigint

Max priority fee per gas for the transaction.

nonce (optional)

• Type: number

Nonce for the transaction.

nonceKey (optional)

• Type: 'expiring' | 'random' | bigint

Nonce key for the transaction (TIP-1009 2D nonces).

Use 'expiring' to select an expiring nonce, which enables concurrent transaction submission without nonce ordering. Use 'random' to select a random key.

throwOnReceiptRevert (optional)

• Type: boolean
• Default: true

Whether a Sync action throws when the receipt reports a revert.

validAfter (optional)

• Type: number

Unix timestamp after which the transaction can be included.

validBefore (optional)

• Type: number

Unix timestamp before which the transaction must be included.