@veilo/sdk-core 0.1.17 → 0.4.0

package/SHIELD_INTEGRATION.md

@@ -0,0 +1,143 @@
+# Wallet-agnostic shielding
+
+`shield()` builds an unsigned Solana v0 transaction that moves funds from any
+signing wallet into Veilo's privacy pool. The wallet that pays and the Veilo
+account that owns the resulting private note are independent.
+
+This is a build API, like Jupiter's transaction APIs. The SDK proves, encrypts,
+and assembles. Your application asks its wallet to sign, submits the signed
+bytes, confirms them, and handles retry.
+
+## Security model
+
+- `signer.publicKey` is the transaction fee payer and public funding source.
+- `owner.veiloPublicKey` controls spending the private note.
+- `owner.noteViewingKey` controls detecting and decrypting the note during a
+  chain scan.
+- The SDK never receives a signer secret key.
+- The compact note cipher is embedded in the on-chain instruction, so note
+  recovery does not depend on a webhook or a later relayer callback.
+
+The two owner keys must belong to the same Veilo account. If they do not, the
+note is spendable but invisible to its owner. Always use `resolveShieldOwner()`;
+construct an owner manually only when you can prove the pairing yourself.
+
+## Complete flow
+
+```ts
+import { Connection, PublicKey } from "@solana/web3.js";
+import {
+  createTransactionProver,
+  finalizeShield,
+  mapShieldError,
+  rebuild,
+  resolveShieldOwner,
+  shield,
+} from "@veilo/sdk-core";
+
+const connection = new Connection(RPC_URL, "confirmed");
+const owner = await resolveShieldOwner({ username: "alice" });
+const prover = createTransactionProver({
+  wasmPath: TRANSACTION_WASM_URL,
+  zkeyPath: TRANSACTION_ZKEY_URL,
+});
+
+let result = await shield({
+  connection,
+  amount: 5_000_000n, // base units
+  mint: new PublicKey(USDC_MINT),
+  owner,
+  signer: { publicKey: wallet.publicKey },
+  prover,
+});
+
+async function signAndSubmit() {
+  const signed = await wallet.signTransaction(result.transaction);
+  const signature = await connection.sendRawTransaction(signed.serialize(), {
+    maxRetries: 0,
+  });
+
+  const confirmation = await connection.confirmTransaction(
+    {
+      signature,
+      blockhash: result.blockhash,
+      lastValidBlockHeight: result.lastValidBlockHeight,
+    },
+    "confirmed",
+  );
+  if (confirmation.value.err) throw confirmation.value.err;
+  return signature;
+}
+
+let signature: string;
+try {
+  signature = await signAndSubmit();
+} catch (cause) {
+  const error = mapShieldError(cause);
+  if (error.retryable !== "rebuild") throw error;
+
+  // Reuses the proof and note; only the blockhash and deadline are refreshed.
+  result = await rebuild(result, { connection });
+  signature = await signAndSubmit(); // the rebuilt transaction needs a new signature
+}
+
+const finalized = await finalizeShield({
+  connection,
+  signature,
+  note: result.note,
+  owner,
+  commitment: "finalized",
+});
+
+console.log(finalized.leafIndex, finalized.treeId);
+```
+
+`predictedLeafIndex` is informational only. Concurrent deposits can move the
+actual index before your transaction lands. Persist `finalized.leafIndex`, which
+comes from this transaction's `CommitmentEvent`.
+
+## Preflight and wallet UX
+
+Preflight runs before the 10–30 second proof and checks pool limits, token
+ownership and balance, ATA state, and the SOL needed by the transaction. If an
+SPL token account has any delegate—even with a delegated amount of zero—the
+program rejects it. `TOKEN_ACCOUNT_DELEGATED` includes a `remedy` with the
+`Revoke` instruction the wallet can sign before retrying.
+
+The wallet may describe the Veilo instruction as an unknown program. Show the
+amount and destination in your own review screen before opening the wallet so
+the signer can verify what it is authorizing.
+
+## SOL requirements
+
+The signer pays:
+
+- the amount itself for native SOL shields;
+- the normal transaction and priority fees; and
+- rent for two nullifier-marker accounts (about 0.00192 SOL at current rent).
+
+The program fixes the marker payer to the signer. A zero-SOL wallet therefore
+cannot use this path, even for an SPL token shield and even if another service
+would sponsor the transaction fee. This API does not provide a gasless mode.
+
+## Retry decisions
+
+Use `mapShieldError()` and branch on `retryable`:
+
+| Error | Retry class | Action |
+|---|---|---|
+| `BLOCKHASH_EXPIRED`, `DEADLINE_EXPIRED` | `rebuild` | Call `rebuild()`, sign again, submit again. |
+| `ROOT_STALE` | `reshield` | Call `shield()` again; a fresh proof is required. |
+| `NULLIFIER_COLLISION` | `none` | Treat as already submitted and check the original signature. |
+| Preflight and configuration errors | `none` | Correct the stated condition before retrying. |
+
+`ShieldProofCache` is public and JSON-serializable. `ShieldNote` is secret. Do
+not store or transmit the note in the clear, and do not bundle it with the proof
+cache merely because the cache is safe to move between processes.
+
+## Optional mailbox delivery
+
+`finalizeShield()` returns an encrypted `blob` suitable for `/notes/save`.
+Supplying `recipientWalletPublicKey` gives faster mailbox delivery and push
+notifications, but records a sender-to-recipient association at the relayer.
+Omitting it keeps discovery chain-only and preserves that privacy boundary.

package/config.d.ts

@@ -0,0 +1,2 @@
+// Stub for legacy resolvers — see config.js
+export * from "./dist/cjs/config.js";

package/config.js

@@ -0,0 +1,4 @@
+// Stub for legacy resolvers (TypeScript moduleResolution: "node", older bundlers)
+// that ignore the "exports" map. Modern resolvers use "./config" from package.json
+// exports and never reach this file.
+module.exports = require("./dist/cjs/config.js");

package/dist/cjs/client.d.ts

@@ -0,0 +1,407 @@
+import * as anchor from "@coral-xyz/anchor";
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { PublicKey, Transaction, Keypair } from "@solana/web3.js";
+import { TransactionProofStruct, TransactionProofBuilder, ExtData } from "./proof.js";
+import { SerializedUTXO, InputUTXO } from "./utxo.js";
+import { MerkleTree } from "./merkle.js";
+import { PrivacyConfigAccount } from "./config.js";
+/**
+ * Get pool PDAs for a given mint address.
+ * Note: All seeds use "v3" suffix.
+ */
+export declare function getPoolPdas(programId: PublicKey, mintAddress: PublicKey): {
+    config: anchor.web3.PublicKey;
+    vault: anchor.web3.PublicKey;
+    nullifiers: anchor.web3.PublicKey;
+};
+/**
+ * Get the note tree PDA for a specific tree ID.
+ */
+export declare function getNoteTreePda(programId: PublicKey, mintAddress: PublicKey, treeId: number): PublicKey;
+/**
+ * Get the global config PDA.
+ */
+export declare function getGlobalConfigPda(programId: PublicKey): PublicKey;
+/**
+ * Get the nullifier marker PDA for a specific nullifier.
+ * NOTE: Nullifier markers are global (no tree_id) to prevent cross-tree double-spend.
+ */
+export declare function getNullifierMarkerPda(programId: PublicKey, mintAddress: PublicKey, nullifier: Uint8Array): PublicKey;
+/**
+ * Fetch and decode the on-chain PrivacyConfig account for a pool.
+ */
+export declare function fetchPoolConfig<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<PrivacyConfigAccount>;
+/**
+ * Check whether a nullifier has been spent on-chain.
+ * Returns true if the nullifier marker PDA exists (funds already spent).
+ */
+export declare function checkNullifierSpent<T extends Idl>(program: Program<T>, mintAddress: PublicKey, nullifier: Uint8Array): Promise<boolean>;
+/** On-chain tree utilization info */
+export type TreeInfo = {
+    treeId: number;
+    leafCount: number;
+    capacity: number;
+    utilizationPercent: number;
+    remainingCapacity: number;
+    isFull: boolean;
+    treePDA: PublicKey;
+};
+/**
+ * Fetch utilization info for a specific tree.
+ * Returns null if the tree does not exist yet.
+ */
+export declare function getTreeInfo<T extends Idl>(program: Program<T>, mintAddress: PublicKey, treeId: number): Promise<TreeInfo | null>;
+/**
+ * Fetch utilization info for all trees in a pool.
+ */
+export declare function getAllTreeInfo<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<TreeInfo[]>;
+/**
+ * Find the best tree to deposit into.
+ *
+ * Strategy (matches veilo-dapp):
+ * 1. Discard full trees.
+ * 2. Prefer the LOWEST tree ID with remaining capacity ≥ minCapacity (default 0.01%).
+ * 3. Ensures trees fill sequentially: 0 → 1 → 2 → …
+ * 4. Fallback to the tree with the most remaining capacity.
+ */
+export declare function getBestTreeForDeposit<T extends Idl>(program: Program<T>, mintAddress: PublicKey, minCapacity?: number): Promise<TreeInfo | null>;
+/**
+ * Convert a Solana/Anchor transaction error into a user-friendly message.
+ * Maps privacy_pool program error codes (6000–6060) to readable strings.
+ * Mirrors relayer-server/src/controllers/transaction.helpers.ts `parseOnChainError`.
+ */
+export declare function parseOnChainError(error: any): string;
+/**
+ * Initialize the global config (one-time setup).
+ */
+export declare function initializeGlobalConfig<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    payer: Keypair;
+}): Promise<void>;
+/**
+ * Initialize a privacy pool with the new parameters.
+ * Creates the first merkle tree (tree ID 0).
+ */
+export declare function initializePool<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    payer: Keypair;
+    feeBps: number;
+    mintAddress: PublicKey;
+    minDepositAmount?: bigint;
+    maxDepositAmount?: bigint;
+    minWithdrawAmount?: bigint;
+    maxWithdrawAmount?: bigint;
+}): Promise<void>;
+/**
+ * Update pool configuration.
+ */
+export declare function updatePoolConfig<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    mintAddress: PublicKey;
+    minDepositAmount?: bigint;
+    maxDepositAmount?: bigint;
+    minWithdrawAmount?: bigint;
+    maxWithdrawAmount?: bigint;
+    feeBps?: number;
+    feeErrorMarginBps?: number;
+    minWithdrawalFee?: bigint;
+    minSwapFee?: bigint;
+    swapFeeBps?: number;
+}): Promise<void>;
+/**
+ * Add a new Merkle tree to the pool.
+ * The treeId must equal the current num_trees value in the pool config.
+ */
+export declare function addMerkleTree<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    mintAddress: PublicKey;
+    treeId: number;
+}): Promise<void>;
+/**
+ * Get the pool configuration account.
+ */
+export declare function getPoolConfig<T extends Idl>(program: Program<T>, mintAddress: PublicKey): Promise<PrivacyConfigAccount>;
+/**
+ * Add a relayer to the pool.
+ */
+export declare function addRelayer<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    mintAddress: PublicKey;
+    newRelayer: PublicKey;
+}): Promise<void>;
+/**
+ * Set the paused state of a pool.
+ */
+export declare function setPaused<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+    mintAddress: PublicKey;
+    paused: boolean;
+}): Promise<void>;
+/**
+ * Execute a transaction on the privacy pool.
+ * This is the low-level function that calls the on-chain `transact` instruction.
+ *
+ * @param publicAmount - Positive for deposits, negative for withdrawals, 0 for transfers
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where output commitments will be inserted
+ */
+export declare function transact<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    recipient: PublicKey;
+    mintAddress: PublicKey;
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    publicAmount: bigint;
+    inputNullifiers: [Uint8Array, Uint8Array];
+    outputCommitments: [Uint8Array, Uint8Array];
+    extData: ExtData;
+    proof: TransactionProofStruct;
+    /** Unix timestamp after which the tx is invalid. Defaults to 0 (no deadline). */
+    deadline?: bigint;
+    vaultTokenAccount?: PublicKey;
+    userTokenAccount?: PublicKey;
+    recipientTokenAccount?: PublicKey;
+    relayerTokenAccount?: PublicKey;
+}): Promise<string>;
+/**
+ * Result of a deposit operation, produced by `DepositBuild.commit()` after the
+ * caller has successfully submitted the deposit transaction on-chain.
+ */
+export type DepositResult = {
+    /** The output UTXOs created by the deposit */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /** The leaf indices where the UTXOs were inserted */
+    leafIndices: [number, number];
+    /** The new Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * The return of `deposit()`. Instead of submitting the transaction itself,
+ * `deposit()` hands back an unsigned {@link Transaction} so the caller can
+ * sign it with whatever wallet they control (Solana wallet-adapter, Ledger,
+ * anchor NodeWallet, etc.) and submit it on their own terms.
+ *
+ * Usage pattern (browser / wallet-adapter):
+ *
+ *     const { transaction, commit } = await deposit({ ... });
+ *     const signed = await wallet.signTransaction(transaction);
+ *     const sig = await connection.sendRawTransaction(signed.serialize());
+ *     await connection.confirmTransaction(sig, "confirmed");
+ *     const result = commit();   // updates the local tree, returns DepositResult
+ */
+export type DepositBuild = {
+    /**
+     * Unsigned {@link Transaction} for the deposit. `feePayer` and
+     * `recentBlockhash` are already populated, so the caller only needs to sign
+     * and send.
+     */
+    transaction: Transaction;
+    /**
+     * Output UTXOs created by this deposit. Safe to read before submission —
+     * the commitment values are deterministic from the circuit inputs and do
+     * not depend on the on-chain result.
+     */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /**
+     * Inserts the two output commitments into the local {@link MerkleTree} and
+     * returns the receipt. Call this **only after** the on-chain transaction
+     * has been confirmed — deferring the insert keeps the local tree
+     * consistent with chain state if the submission fails.
+     *
+     * Calling `commit()` more than once is unsupported and will corrupt the
+     * local tree.
+     */
+    commit: () => DepositResult;
+};
+/**
+ * Build an unsigned deposit {@link Transaction} for the privacy pool.
+ *
+ * For deposits, we use zero input UTXOs (amount=0) and create output UTXOs
+ * with the deposit amount. `publicAmount` is positive. The caller is
+ * responsible for signing and submitting the returned transaction, and then
+ * calling `commit()` once it confirms.
+ *
+ * @param amount - Amount to deposit in lamports/token units
+ * @param recipientPubkey - UTXO public key that will own the deposited funds
+ * @param treeId - The tree ID to deposit into (defaults to 0)
+ */
+export declare function deposit<T extends Idl>(params: {
+    program: Program<T>;
+    /**
+     * Account that will pay for and sign the deposit transaction. Only
+     * `publicKey` is read — `deposit()` never touches a secret key. A browser
+     * wallet-adapter wallet, a Node `anchor.Wallet`, or a raw `Keypair` are all
+     * structurally acceptable.
+     */
+    depositor: {
+        publicKey: PublicKey;
+    };
+    amount: bigint;
+    mintAddress: PublicKey;
+    recipientPubkey: bigint;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    treeId?: number;
+    extData?: Partial<ExtData>;
+}): Promise<DepositBuild>;
+/**
+ * Result of a withdrawal operation.
+ */
+export type WithdrawResult = {
+    /** Change UTXO (remaining balance) */
+    changeUTXO: SerializedUTXO;
+    /** Leaf index of the change UTXO */
+    leafIndex: number;
+    /** New Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * Withdraw funds from the privacy pool.
+ *
+ * For withdrawals, we spend input UTXOs and create change output UTXOs.
+ * The publicAmount is negative (funds flowing out).
+ *
+ * @param withdrawAmount - Amount to withdraw in lamports/token units
+ * @param inputUTXOs - The UTXOs being spent
+ * @param changePubkey - UTXO public key for the change output
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where change outputs will be inserted
+ */
+export declare function withdraw<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    recipient: PublicKey;
+    mintAddress: PublicKey;
+    inputUTXOs: [InputUTXO, InputUTXO];
+    changePubkey: bigint;
+    withdrawAmount: bigint;
+    fee: bigint;
+    refund: bigint;
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+}): Promise<WithdrawResult>;
+/**
+ * Result of a private transfer operation.
+ */
+export type TransferResult = {
+    /** Output UTXOs created by the transfer */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /** Leaf indices where the UTXOs were inserted */
+    leafIndices: [number, number];
+    /** New Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * Execute a private transfer within the pool.
+ *
+ * For transfers, the publicAmount is 0 (no funds enter or leave the pool).
+ * Input amounts must equal output amounts.
+ *
+ * @param inputUTXOs - The UTXOs being spent
+ * @param outputPubkeys - UTXO public keys for the recipients
+ * @param outputAmounts - Amounts for each output (must sum to input total)
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where output commitments will be inserted
+ */
+export declare function privateTransfer<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    mintAddress: PublicKey;
+    inputUTXOs: [InputUTXO, InputUTXO];
+    outputPubkeys: [bigint, bigint];
+    outputAmounts: [bigint, bigint];
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    fee?: bigint;
+}): Promise<TransferResult>;
+/**
+ * Update the global config.
+ * Currently takes no extra args — only admin verification.
+ */
+export declare function updateGlobalConfig<T extends Idl>(params: {
+    program: Program<T>;
+    admin: anchor.Wallet;
+}): Promise<void>;
+/**
+ * Get the swap executor PDA.
+ * Seeds: ["swap_executor", source_mint, dest_mint, input_nullifier_0, relayer]
+ */
+export declare function getSwapExecutorPda(programId: PublicKey, sourceMint: PublicKey, destMint: PublicKey, inputNullifier0: Uint8Array, relayer: PublicKey): PublicKey;
+/**
+ * Build the `fund_native_source` instruction that pre-funds the swap executor
+ * with native SOL from the source vault. Only for native SOL source pools.
+ *
+ * This instruction MUST be the first instruction in the same atomic transaction
+ * as `transactSwap`. Call `transactSwap` directly — it handles this internally.
+ */
+export declare function fundNativeSource<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    inputNullifier0: Uint8Array;
+    swapAmount: bigint;
+}): Promise<anchor.web3.TransactionInstruction>;
+/**
+ * Swap proof struct (same encoding as TransactionProofStruct).
+ */
+export type SwapProofStruct = TransactionProofStruct;
+/**
+ * Swap params committed to in the ZK proof.
+ */
+export type SwapParams = {
+    minAmountOut: bigint;
+    deadline: bigint;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    destAmount: bigint;
+    /** SHA-256 of raw swap instruction bytes; use all-zeros for CPMM/AMM swaps. */
+    swapDataHash: Uint8Array;
+};
+/**
+ * Execute an atomic cross-pool private swap.
+ *
+ * For native SOL source pools (`sourceMint === NATIVE_SOL_MINT`), this function
+ * automatically prepends the `fund_native_source` instruction in the same
+ * transaction so the on-chain atomicity requirement is always satisfied.
+ *
+ * @param swapProgram          - Jupiter/Raydium CPMM/AMM program ID
+ * @param swapData             - Raw DEX instruction bytes
+ */
+export declare function transactSwap<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    sourceMint: PublicKey;
+    destMint: PublicKey;
+    sourceRoot: Uint8Array;
+    sourceTreeId: number;
+    destTreeId: number;
+    inputNullifiers: [Uint8Array, Uint8Array];
+    outputCommitments: [Uint8Array, Uint8Array];
+    proof: SwapProofStruct;
+    swapParams: SwapParams;
+    swapAmount: bigint;
+    swapData: Buffer;
+    extData: ExtData;
+    sourceVaultTokenAccount: PublicKey;
+    sourceMintAccount: PublicKey;
+    destVaultTokenAccount: PublicKey;
+    destMintAccount: PublicKey;
+    relayerTokenAccount: PublicKey;
+    swapProgram: PublicKey;
+    jupiterEventAuthority: PublicKey;
+}): Promise<string>;