Stellar Privacy Pool: End-to-End Integration Guide

npm install @auditable/privacy-pool-zk-sdk

import { PrivacyPoolSDK } from "@auditable/privacy-pool-zk-sdk";

const sdk = await PrivacyPoolSDK.init({
  wasmBinary: await fetch("/pkg/client_sdk_wasm_bg.wasm").then((r) => r.arrayBuffer()),
  circuitWasm: await fetch("/assets/main.wasm").then((r) => r.arrayBuffer()),
  zkey: await fetch("/assets/main_final.zkey").then((r) => r.arrayBuffer()),
});

import { PrivacyPoolSDK } from "@auditable/privacy-pool-zk-sdk";

// Build the message the user must sign with their Stellar wallet
const message = PrivacyPoolSDK.buildStealthAddressSignMessage(stellarAddress);

// Request the signature from the connected wallet
const signature = await wallet.signMessage(message);

// Derive the stpl1 stealth address from the signature
const stealthAddress = await sdk.generateStealthAddressFromStellarSignature(signature);
// stealthAddress is a Bech32 string beginning with "stpl1"

// Generate a new private coin (for deposits)
const coin = await sdk.generateCoin();

// Or generate a coin tied to a recipient's stealth address via ECDH
const coinWithSecret = await sdk.generateCoinWithSharedSecret(recipientStealthAddress);

// Read the current pool state from the contract (commitments, roots, etc.),
// then build the Merkle witness for the coin you want to spend
const witness = await sdk.buildWithdrawMerkleWitness({
  coin: coinToSpend,
  commitments: poolCommitments,   // fetched from contract via get_commitments()
  treeDepth: poolTreeDepth,        // fetched from contract via get_merkle_depth()
});

// Withdrawal proof
const proofResult = await sdk.proveWithdrawal({
  coin: coinToSpend,
  witness,
  publicWithdrawAddress: destinationStellarAddress,
  outputCoins: [], // private output coins if performing a transfer
});

// General transaction proof
const txProofResult = await sdk.proveTransaction({
  inputCoins: [coinToSpend],
  outputCoins: [newCoin],
  witness,
  publicDepositAmount: 0n,
  publicWithdrawAmount: withdrawAmount,
  publicWithdrawAddress: destinationStellarAddress,
});

// Serialize for the Soroban call
const proofBytes = sdk.proofToHex(proofResult.proof);
const pubSignalBytes = sdk.publicToHex(proofResult.publicSignals);

// The encoded bytes bundle the encrypted audit payload for the Arcane scanner.
// Construct this using the audit encoding utilities provided by your Arcane
// application setup — the exact format is defined by your decoding key configuration.
const encoded: Uint8Array = buildAuditEncodedPayload({
  proofResult,
  assetId,
  arcaneEncodingKey,
});

import * as StellarSdk from "@stellar/stellar-sdk";

// Build the Soroban contract call
const operation = contract.call(
  "transact",
  StellarSdk.nativeToScVal(stellarAddress, { type: "address" }), // from
  StellarSdk.nativeToScVal(Buffer.from(proofBytes, "hex")),       // proof_bytes
  StellarSdk.nativeToScVal(Buffer.from(pubSignalBytes, "hex")),   // pub_signals_bytes
  StellarSdk.nativeToScVal(Buffer.from(encoded)),                 // encoded
);

// Build, sign, and submit the transaction
const tx = new StellarSdk.TransactionBuilder(sourceAccount, { fee, networkPassphrase })
  .addOperation(operation)
  .setTimeout(30)
  .build();

const signedTx = await wallet.signTransaction(tx.toXDR());
const result = await server.sendTransaction(
  StellarSdk.TransactionBuilder.fromXDR(signedTx, networkPassphrase)
);