Skip to main content

​
Overview

The deposit operation moves tokens from a user’s public Associated Token Account (ATA) into their encrypted balance. After a successful deposit, the balance is hidden on-chain.
1

Transfer from Public ATA

Tokens are moved from the user’s Associated Token Account (ATA) into the Shielded Pool - an on-chain SPL or Token-2022 custody account controlled by the Umbra program.
2

Fee Deduction

Protocol fees and any Token-2022 transfer fees are subtracted from the incoming amount. The net amount is what gets credited to the encrypted balance.
3

Credit Encrypted Balance

The net amount is added to the destination user’s encrypted balance. The balance is hidden on-chain - it can only be decrypted by the Arcium MPC network and, in Shared mode, by the user’s own X25519 key.
The user must be registered before depositing. An EncryptedUserAccount PDA must exist for their wallet address.
Deposit transactions are publicly visible on-chain. The depositor’s wallet address, the destination address, and the gross transfer amount are all readable from the transaction. Only the resulting encrypted balance is hidden - the act of shielding itself is not private.

​
Usage

import { getPublicBalanceToEncryptedBalanceDirectDepositorFunction } from "@umbra-privacy/sdk";

const deposit = getPublicBalanceToEncryptedBalanceDirectDepositorFunction({ client });

const result = await deposit(
  destinationAddress,  // whose encrypted balance to credit
  mint,                // SPL or Token-2022 mint address
  transferAmount,      // amount in native token units (U64)
  options?,            // optional
);

​
Parameters

​
destinationAddress
Address
required
The wallet address whose encrypted balance is credited. This is usually client.signer.address (depositing to yourself), but you can deposit into any registered user’s account - the funds will be encrypted under their X25519 key.
​
mint
Address
required
The SPL token mint address. Works with any standard SPL token and Token-2022 mints (see Token-2022 Support for transfer fee handling).
​
transferAmount
bigint
required
The gross amount to transfer, in the token’s native units (accounting for decimals). For example, 1_000_000n for 1 USDC (6 decimals). Protocol fees and Token-2022 transfer fees are subtracted from this amount before the encrypted balance is credited.
​
options.priorityFees
bigint
default:"0n"
Additional compute unit price in microlamports. Increase this if transactions are timing out during periods of high network congestion.
​
options.purpose
number
default:"0"
A purpose flag stored alongside the deposit. Reserved for protocol use; leave at 0 unless instructed otherwise.
​
options.optionalData
Uint8Array
32 bytes of arbitrary metadata stored with the deposit. Defaults to all zeros.
​
options.awaitCallback
boolean
default:"true"
Whether to wait for the Arcium MPC callback transaction to confirm before resolving. When true, the returned DepositResult includes callbackSignature and callbackElapsedMs. When false, returns immediately after the handler (queue) transaction confirms.
​
options.skipPreflight
boolean
default:"false"
Skip Solana transaction preflight simulation. Useful when preflight nodes are behind.
​
options.maxRetries
number
Maximum number of times the RPC node should retry sending the transaction.
​
options.accountInfoCommitment
Commitment
default:"\"confirmed\""
Commitment level used for RPC account reads during deposit preparation. Overrides the default on a per-call basis.
​
options.epochInfoCommitment
Commitment
default:"\"confirmed\""
Commitment level used for fetching epoch info (Token-2022 transfer fee schedule). Overrides the default on a per-call basis.

​
Return Value

Returns a Promise<DepositResult>. The DepositResult object contains:
  • queueSignature - The transaction signature of the handler (queue computation) transaction.
  • callbackStatus - The outcome of computation monitoring: "finalized", "pruned", or "timed-out". Present when awaitCallback is true (the default).
  • callbackSignature - The transaction signature of the Arcium MPC callback transaction. Present when callbackStatus is "finalized".
  • callbackElapsedMs - Wall-clock milliseconds spent waiting for the callback. Present when awaitCallback is true.
  • rentClaimSignature - Transaction signature for reclaiming rent from the computation account. Attempted regardless of callback outcome.
  • rentClaimError - Error encountered during rent reclaim, if any. The deposit itself still succeeded.
Deposits follow the dual-instruction pattern - the SDK submits the handler transaction, waits for Arcium to complete the MPC computation, then waits for the callback transaction to confirm.

​
Encryption Mode Selection

The SDK automatically selects the correct instruction variant based on the state of the destination user’s account:
  • New MXE-only balance - destination has no X25519 key registered; first deposit
  • Existing MXE-only balance - destination has no X25519 key; balance already exists
  • New Shared balance - destination has X25519 key registered; first deposit
  • Existing Shared balance - destination has X25519 key; balance already exists
You do not need to specify the mode manually.

​
Protocol Fees

Fees are deducted from the transferAmount before crediting the encrypted balance. The amount credited is: 
credited = transferAmount - baseFee - floor((transferAmount - baseFee) * commissionBps / 10000)
Protocol fee configuration is set on-chain by the pool admin and may vary per pool. The current default is a small fixed base fee plus a 0.3% commission.
In most cases, direct deposits from your own ATA to your own encrypted balance carry zero protocol fees - the baseFee and commissionBps are both set to 0 for standard self-shielding. Fees may apply for deposits routed through relayers or for specific pool configurations.

​
Example: Self-Deposit

import { getPublicBalanceToEncryptedBalanceDirectDepositorFunction } from "@umbra-privacy/sdk";

const deposit = getPublicBalanceToEncryptedBalanceDirectDepositorFunction({ client });

// Deposit 100 USDC into your own encrypted balance
const USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
const ONE_HUNDRED_USDC = 100_000_000n; // 6 decimals

const result = await deposit(client.signer.address, USDC, ONE_HUNDRED_USDC);
console.log("Queue signature:", result.queueSignature);
console.log("Callback signature:", result.callbackSignature);

​
Example: Deposit to Another User

You can shield tokens directly into another registered user’s encrypted balance: 
const RECIPIENT = "GsbwXfJraMomNxBcpR3DBFyKCCmN9SKGzKFJBNKxRFkT";

const result = await deposit(RECIPIENT, USDC, ONE_HUNDRED_USDC);
The tokens are encrypted under the recipient’s X25519 key. Only they can withdraw them.

​
Error Handling

Deposit errors include a stage field identifying where the failure occurred: 
import { isEncryptedDepositError } from "@umbra-privacy/sdk/errors";

try {
  await deposit(destinationAddress, mint, amount);
} catch (err) {
  if (isEncryptedDepositError(err)) {
    switch (err.stage) {
      case "validation":
        // Invalid arguments - check destinationAddress, mint, amount
        break;
      case "mint-fetch":
        // Could not fetch mint account - check RPC connectivity and mint address
        break;
      case "fee-calculation":
        // Token-2022 transfer fee calculation failed
        break;
      case "account-fetch":
        // Could not fetch the destination user account or token account
        break;
      case "transaction-send":
        // Transaction submitted but confirmation failed - may still have landed
        break;
      default:
        // Other stages: pda-derivation, instruction-build, transaction-build,
        // transaction-compile, transaction-sign, transaction-validate
        console.error("Deposit failed at stage:", err.stage, err);
    }
  }
}
See Error Handling for a full reference.