Mixer

Documentation Index

Fetch the complete documentation index at: https://sdk.umbraprivacy.com/llms.txt

Use this file to discover all available pages before exploring further.

​

getClaimableUtxoScannerFunction

function getClaimableUtxoScannerFunction(
  args: GetClaimableUtxoScannerFunctionArgs,
  deps?: GetClaimableUtxoScannerFunctionDeps,
): ClaimableUtxoScannerFunction

​

GetClaimableUtxoScannerFunctionArgs

• client: IUmbraClient - Must have indexerApiEndpoint configured.

​

GetClaimableUtxoScannerFunctionDeps

• 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 ClaimableUtxoScannerFunction = (
  treeIndex: U32,
  startInsertionIndex: U32,
  endInsertionIndex?: U32,
) => Promise<ScannedUtxoResult>

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

​

ScannedUtxoResult

interface ScannedUtxoResult {
  selfBurnable: ClaimableUtxoData[];
  received: ClaimableUtxoData[];
  publicSelfBurnable: ClaimableUtxoData[];
  publicReceived: ClaimableUtxoData[];
}

• selfBurnable - UTXOs you created yourself (from encrypted balance). You can burn these.
• received - UTXOs sent to you by others (from encrypted balance), addressed to the caller.
• publicSelfBurnable - UTXOs you created yourself (from public balance). You can burn these.
• publicReceived - UTXOs sent to you by others (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 { getClaimableUtxoScannerFunction } from "@umbra-privacy/sdk";

const scanUtxos = getClaimableUtxoScannerFunction({ client });

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

console.log("Self-burnable UTXOs:", result.selfBurnable.length);
console.log("Received UTXOs:", result.received.length);

​

getSelfClaimableUtxoToEncryptedBalanceClaimerFunction

function getSelfClaimableUtxoToEncryptedBalanceClaimerFunction(
  args: GetSelfClaimableUtxoToEncryptedBalanceClaimerFunctionArgs,
  deps: GetSelfClaimableUtxoToEncryptedBalanceClaimerFunctionDeps,
): SelfClaimableUtxoToEncryptedBalanceClaimerFunction

​

GetSelfClaimableUtxoToEncryptedBalanceClaimerFunctionArgs

• client: IUmbraClient

​

GetSelfClaimableUtxoToEncryptedBalanceClaimerFunctionDeps

• 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 SelfClaimableUtxoToEncryptedBalanceClaimerFunction = (
  utxos: readonly ClaimableUtxoData[],
  optionalData?: OptionalData32,
) => Promise<ClaimUtxoIntoEncryptedBalanceResult>

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

​

Errors

​

getSelfClaimableUtxoToPublicBalanceClaimerFunction

function getSelfClaimableUtxoToPublicBalanceClaimerFunction(
  args: GetSelfClaimableUtxoToPublicBalanceClaimerFunctionArgs,
  deps: GetSelfClaimableUtxoToPublicBalanceClaimerFunctionDeps,
): SelfClaimableUtxoToPublicBalanceClaimerFunction

​

Returns

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

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

​

Errors

​

getReceiverClaimableUtxoToEncryptedBalanceClaimerFunction

function getReceiverClaimableUtxoToEncryptedBalanceClaimerFunction(
  args: GetReceiverClaimableUtxoToEncryptedBalanceClaimerFunctionArgs,
  deps: GetReceiverClaimableUtxoToEncryptedBalanceClaimerFunctionDeps,
): ReceiverClaimableUtxoToEncryptedBalanceClaimerFunction

​

Returns

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

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

​

Errors

​

Full Mixer Flow Example

import {
  getClaimableUtxoScannerFunction,
  getSelfClaimableUtxoToEncryptedBalanceClaimerFunction,
  getReceiverClaimableUtxoToEncryptedBalanceClaimerFunction,
} from "@umbra-privacy/sdk";
import { getSelfClaimableUtxoToEncryptedBalanceClaimerProver, getReceiverClaimableUtxoToEncryptedBalanceClaimerProver } from "@umbra-privacy/web-zk-prover";

// Build functions (once)
const scanUtxos = getClaimableUtxoScannerFunction({ client });
const claimSelf = getSelfClaimableUtxoToEncryptedBalanceClaimerFunction(
  { client },
  { zkProver: getSelfClaimableUtxoToEncryptedBalanceClaimerProver() },
);
const claimReceived = getReceiverClaimableUtxoToEncryptedBalanceClaimerFunction(
  { client },
  { zkProver: getReceiverClaimableUtxoToEncryptedBalanceClaimerProver() },
);

// Fetch claimable UTXOs
const { selfBurnable, received } = await scanUtxos(0, 0, 1000);

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

​

FetchUtxosError

​

ClaimUtxoError