Mixer

​

getFetchClaimableUtxosFunction

function getFetchClaimableUtxosFunction(
  args: GetFetchClaimableUtxosFunctionArgs,
  deps?: GetFetchClaimableUtxosFunctionDeps,
): FetchClaimableUtxosFunction

​

GetFetchClaimableUtxosFunctionArgs

• client: IUmbraClient - Must have indexerApiEndpoint configured.

​

GetFetchClaimableUtxosFunctionDeps

• fetchUtxoData?: FetchUtxoDataFunction - Override the default indexer UTXO data fetcher.
• fetchMerkleProof?: FetchMerkleProofFunction - Override the default indexer Merkle proof fetcher.
• aesDecryptor?: AesDecryptorFunction - Override the AES-256-GCM decryptor used for receiver-claimable UTXOs.
• x25519GetSharedSecret?: (privateKey: X25519PrivateKey, publicKey: X25519PublicKey) => Uint8Array - Override the X25519 shared secret derivation.

​

Returns

type FetchClaimableUtxosFunction = (
  treeIndex: number,
  startInsertionIndex: number,
  endInsertionIndex?: number,
) => Promise<ClaimableUtxoResult>

• treeIndex: number - The mixer tree index to scan.
• startInsertionIndex: number - Inclusive start of the UTXO insertion range to scan.
• endInsertionIndex?: number - Exclusive end of the range. Defaults to the current tree size.

​

ClaimableUtxoResult

interface ClaimableUtxoResult {
  ephemeral: ClaimableUtxoData[];
  receiver: ClaimableUtxoData[];
  publicEphemeral: ClaimableUtxoData[];
  publicReceiver: ClaimableUtxoData[];
}

• ephemeral - Self-claimable UTXOs created via MPC (from encrypted balance).
• receiver - Receiver-claimable UTXOs created via MPC (from encrypted balance), addressed to the caller.
• publicEphemeral - Self-claimable UTXOs created without MPC (from public balance).
• publicReceiver - Receiver-claimable UTXOs created without MPC (from public balance), addressed to the caller.

​

ClaimableUtxoData

• merkleRoot: U256LeBytes - The Merkle root at the time this UTXO’s proof was fetched (little-endian bytes).
• merklePath: U256LeBytes[] - Sibling hashes forming the Merkle inclusion proof (little-endian bytes).
• leafIndex: U128 - The UTXO’s leaf index in the Indexed Merkle Tree.
• amount: U64 - Token amount in base units.
• destinationAddress: Address - The Umbra-registered owner who can claim this UTXO.
• depositModifiedGenerationIndex: U128 - Generation index encoded in the deposit.
• version: U64 - Protocol version of the UTXO.
• commitmentIndex: U128 - Commitment index used in key derivation.
• senderAddressLow: U128 - Low 128 bits of the sender address (for the ZK circuit).
• senderAddressHigh: U128 - High 128 bits of the sender address.
• relayerFixedSolFees: U64 - Fixed SOL fees paid to relayer (in lamports).
• mintAddressLow: U128 - Low 128 bits of the mint address.
• mintAddressHigh: U128 - High 128 bits of the mint address.
• timestamp: TimestampComponents - UTXO creation timestamp components for TVK derivation.
• purpose: number - Caller-defined purpose tag.
• h1CircuitProvableOnChainDataHash: U256LeBytes - H1 hash for the ZK circuit public inputs (little-endian bytes).
• h1SmartProgramProvableOnChainDataHash: U256LeBytes - H1 hash for the on-chain verifier (little-endian bytes).

​

Errors

​

Example

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

const fetchUtxos = getFetchClaimableUtxosFunction({ client });

// Scan tree 0 from insertion index 0 to 1000
const result = await fetchUtxos(0, 0, 1000);

console.log("Self-claimable (ephemeral):", result.ephemeral.length);
console.log("Received UTXOs:", result.receiver.length);

​

getClaimSelfClaimableUtxoIntoEncryptedBalanceFunction

function getClaimSelfClaimableUtxoIntoEncryptedBalanceFunction(
  args: GetClaimSelfClaimableUtxoIntoEncryptedBalanceFunctionArgs,
  deps: GetClaimSelfClaimableUtxoIntoEncryptedBalanceFunctionDeps,
): ClaimSelfClaimableUtxoIntoEncryptedBalanceFunction

​

GetClaimSelfClaimableUtxoIntoEncryptedBalanceFunctionArgs

• client: IUmbraClient

​

GetClaimSelfClaimableUtxoIntoEncryptedBalanceFunctionDeps

• zkProver: IZkProverForClaimSelfClaimableUtxo - Required. Groth16 prover for the claim circuit.
• accountInfoProvider?: AccountInfoProviderFunction
• blockhashProvider?: GetLatestBlockhash
• transactionForwarder?: TransactionForwarder
• Additional cryptographic dependency overrides (key derivation, Poseidon, Rescue - all optional).

​

Returns

type ClaimSelfClaimableUtxoIntoEncryptedBalanceFunction = (
  utxos: readonly ClaimableUtxoData[],
  optionalData?: OptionalData32,
) => Promise<ClaimUtxoIntoEncryptedBalanceResult>

• utxos: readonly ClaimableUtxoData[] - Array of claimable UTXOs from getFetchClaimableUtxosFunction. Use UTXOs from result.ephemeral.
• optionalData?: OptionalData32 - Optional 32-byte caller metadata.

​

Errors

​

getClaimSelfClaimableUtxoIntoPublicBalanceFunction

function getClaimSelfClaimableUtxoIntoPublicBalanceFunction(
  args: GetClaimSelfClaimableUtxoIntoPublicBalanceFunctionArgs,
  deps: GetClaimSelfClaimableUtxoIntoPublicBalanceFunctionDeps,
): ClaimSelfClaimableUtxoIntoPublicBalanceFunction

​

Returns

type ClaimSelfClaimableUtxoIntoPublicBalanceFunction = (
  utxos: readonly ClaimableUtxoData[],
  optionalData?: OptionalData32,
) => Promise<ClaimUtxoIntoPublicBalanceResult>

• utxos: readonly ClaimableUtxoData[] - Array of claimable UTXOs. Use UTXOs from result.ephemeral or result.publicEphemeral.
• optionalData?: OptionalData32 - Optional 32-byte caller metadata.

​

Errors

​

getClaimReceiverClaimableUtxoIntoEncryptedBalanceFunction

function getClaimReceiverClaimableUtxoIntoEncryptedBalanceFunction(
  args: GetClaimReceiverClaimableUtxoIntoEncryptedBalanceFunctionArgs,
  deps: GetClaimReceiverClaimableUtxoIntoEncryptedBalanceFunctionDeps,
): ClaimReceiverClaimableUtxoIntoEncryptedBalanceFunction

​

Returns

type ClaimReceiverClaimableUtxoIntoEncryptedBalanceFunction = (
  utxos: readonly ClaimableUtxoData[],
  optionalData?: OptionalData32,
) => Promise<ClaimUtxoIntoEncryptedBalanceResult>

• utxos: readonly ClaimableUtxoData[] - Array of claimable UTXOs. Use UTXOs from result.receiver or result.publicReceiver.
• optionalData?: OptionalData32 - Optional 32-byte caller metadata.

​

Errors

​

Full Mixer Flow Example

import {
  getFetchClaimableUtxosFunction,
  getClaimSelfClaimableUtxoIntoEncryptedBalanceFunction,
  getClaimReceiverClaimableUtxoIntoEncryptedBalanceFunction,
} from "@umbra-privacy/sdk";
import { getClaimEphemeralIntoEtaProver, getClaimReceiverIntoEtaProver } from "@umbra-privacy/web-zk-prover";

// Build functions (once)
const fetchUtxos = getFetchClaimableUtxosFunction({ client });
const claimSelf = getClaimSelfClaimableUtxoIntoEncryptedBalanceFunction(
  { client },
  { zkProver: getClaimEphemeralIntoEtaProver() },
);
const claimReceived = getClaimReceiverClaimableUtxoIntoEncryptedBalanceFunction(
  { client },
  { zkProver: getClaimReceiverIntoEtaProver() },
);

// Fetch claimable UTXOs
const { ephemeral, receiver } = await fetchUtxos(0, 0, 1000);

// Claim each one
if (ephemeral.length > 0) {
  const result = await claimSelf(ephemeral);
  console.log("Claimed self UTXOs:", result.signatures);
}
if (receiver.length > 0) {
  const result = await claimReceived(receiver);
  console.log("Claimed received UTXOs:", result.signatures);
}

​

FetchUtxosError

​

ClaimUtxoError