@veilo/sdk-core 0.3.3 → 0.4.0

package/dist/cjs/shield/ports.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onChainTreeSource = onChainTreeSource;
+exports.staticTreeSource = staticTreeSource;
+exports.memoryCache = memoryCache;
+exports.noCache = noCache;
+const program_js_1 = require("../program.js");
+const client_js_1 = require("../client.js");
+const config_js_1 = require("../config.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Injection points for the shield path.
+ *
+ * The three production deposit implementations (extension, wallet-app,
+ * veilo-dapp) are ~85% identical and diverge on exactly these axes: where
+ * proofs come from, where the tree comes from, which lookup table to use, and
+ * what to cache into. Making each an explicit port is what lets one
+ * implementation serve all of them — and lets a third-party integrator supply
+ * their own without forking anything.
+ *
+ * Proof generation is deliberately NOT redefined here: `TransactionProofBuilder`
+ * from `proof.ts` already has the right shape, and a second prover abstraction
+ * would be exactly the kind of duplication this module exists to avoid.
+ */
+// -- TreeSource ---------------------------------------------------------------
+/**
+ * Read the target tree and root directly from chain.
+ *
+ * Note the account decoding: `MerkleTreeAccount::EXPECTED_SIZE` (9107) does not
+ * match the size its declared fields sum to (8987), a 120-byte discrepancy that
+ * is unexplained. Until it is, hand-slicing this account at fixed byte offsets
+ * is unsafe. Anchor's coder reads declared fields from the front and ignores the
+ * tail, so `.fetch()` stays correct regardless.
+ */
+function onChainTreeSource(connection, programId = program_js_1.PRIVACY_POOL_PROGRAM_ID) {
+    return {
+        async getDepositTarget(mint) {
+            const program = (0, program_js_1.createReadonlyVeiloProgram)(connection);
+            const { config } = (0, client_js_1.getPoolPdas)(programId, mint);
+            const cfg = await program.account.privacyConfig.fetch(config);
+            const numTrees = Number(cfg.numTrees);
+            if (!Number.isInteger(numTrees) || numTrees <= 0) {
+                throw new errors_js_1.ShieldError("TREE_FULL", `Pool ${mint.toBase58()} has no deposit tree.`, { context: { mint: mint.toBase58(), numTrees } });
+            }
+            // Fetch every tree in one RPC call. The older getBestTreeForDeposit path
+            // fetched them serially, then fetched the chosen trees a second time.
+            const treePdas = Array.from({ length: numTrees }, (_, treeId) => (0, client_js_1.getNoteTreePda)(programId, mint, treeId));
+            const infos = await connection.getMultipleAccountsInfo(treePdas, {
+                commitment: "confirmed",
+            });
+            const capacity = 2 ** config_js_1.MERKLE_TREE_DEPTH;
+            const trees = infos.map((info, treeId) => {
+                if (!info)
+                    return null;
+                // Anchor camel-cases the IDL's `MerkleTreeAccount` name when it builds
+                // the Borsh account-layout map (the same key exposed as
+                // `program.account.merkleTreeAccount`).
+                const decoded = program.coder.accounts.decode("merkleTreeAccount", info.data);
+                const nextIndex = Number(decoded.nextIndex);
+                return {
+                    treeId,
+                    decoded,
+                    nextIndex,
+                    remainingCapacity: capacity - nextIndex,
+                };
+            });
+            const inputTree = trees[0];
+            if (!inputTree) {
+                throw new errors_js_1.ShieldError("POOL_NOT_FOUND", `Pool ${mint.toBase58()} is missing its input Merkle tree (tree 0).`, { context: { mint: mint.toBase58(), tree: treePdas[0].toBase58() } });
+            }
+            const available = trees.filter((tree) => !!tree && tree.nextIndex < capacity);
+            if (available.length === 0) {
+                throw new errors_js_1.ShieldError("TREE_FULL", `All ${numTrees} Merkle trees for ${mint.toBase58()} are full.`, { context: { mint: mint.toBase58(), numTrees, capacity } });
+            }
+            const minCapacity = Math.floor(capacity * 0.0001);
+            const preferred = available
+                .filter((tree) => tree.remainingCapacity >= minCapacity)
+                .sort((a, b) => a.treeId - b.treeId);
+            const outputTree = preferred[0] ??
+                available.sort((a, b) => b.remainingCapacity - a.remainingCapacity)[0];
+            return {
+                inputTreeId: 0,
+                inputRoot: extractRoot(inputTree.decoded),
+                outputTreeId: outputTree.treeId,
+                outputNextIndex: outputTree.nextIndex,
+            };
+        },
+    };
+}
+/**
+ * Fixed values, for tests and offline builds.
+ *
+ * Also the escape hatch for an integrator who already tracks the tree state and
+ * does not want the SDK making RPC calls on their behalf.
+ */
+function staticTreeSource(target) {
+    return { async getDepositTarget() { return target; } };
+}
+/**
+ * Read the root from a decoded `MerkleTreeAccount`.
+ *
+ * Uses `root_history[root_index]` rather than the `root` field. Both are written
+ * to the same value by `append` (merkle_tree.rs:108-111) so they agree, but the
+ * history read is what all three production implementations use and is therefore
+ * the one that is actually exercised against mainnet.
+ */
+function extractRoot(tree) {
+    const history = tree.rootHistory ?? tree.root_history;
+    const index = Number(tree.rootIndex ?? tree.root_index ?? 0);
+    if (Array.isArray(history) && history[index]) {
+        return new Uint8Array(history[index]);
+    }
+    const root = tree.root;
+    if (root)
+        return new Uint8Array(root);
+    throw new Error("could not read a Merkle root from the tree account");
+}
+// -- Cache --------------------------------------------------------------------
+/**
+ * In-memory cache with TTL. The default.
+ *
+ * Persistent storage is deliberately the caller's problem — `localStorage`,
+ * `chrome.storage`, and `AsyncStorage` are three different answers in three
+ * different apps, and none of them belongs in a published SDK.
+ */
+function memoryCache() {
+    const store = new Map();
+    return {
+        async get(key) {
+            const hit = store.get(key);
+            if (!hit)
+                return undefined;
+            if (hit.expiresAt !== 0 && hit.expiresAt < Date.now()) {
+                store.delete(key);
+                return undefined;
+            }
+            return hit.value;
+        },
+        async set(key, value, ttlMs) {
+            store.set(key, {
+                value,
+                expiresAt: ttlMs && ttlMs > 0 ? Date.now() + ttlMs : 0,
+            });
+        },
+    };
+}
+/** A cache that never stores anything. Useful for tests that assert fetch counts. */
+function noCache() {
+    return {
+        async get() { return undefined; },
+        async set() { },
+    };
+}

package/dist/cjs/shield/preflight.d.ts

@@ -0,0 +1,30 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import type { PreflightOptions, ShieldCachePort } from "./types.js";
+/**
+ * Checks that run before the prover.
+ *
+ * Proving costs 10–30 seconds. Every check here is a single RPC call, and each
+ * one pre-empts an on-chain failure whose message tells the user nothing they
+ * can act on. The delegate check is the clearest example: the program requires
+ * `user_token.delegate.is_none()`, so anyone who ever approved a DEX has a
+ * permanently broken deposit path that reports only "Invalid token account
+ * authority" — with no hint that revoking a delegate would fix it.
+ *
+ * These are advisory in the sense that the chain enforces them anyway. They are
+ * not advisory in the sense that skipping them produces a materially worse
+ * product.
+ */
+export declare function preflightShield(params: {
+    connection: Connection;
+    amount: bigint;
+    mint: PublicKey;
+    signer: {
+        publicKey: PublicKey;
+        tokenAccount: PublicKey;
+    };
+    programId?: PublicKey;
+    options?: PreflightOptions;
+    cache?: ShieldCachePort;
+    computeUnitLimit?: number;
+    computeUnitPriceMicroLamports?: number;
+}): Promise<void>;

package/dist/cjs/shield/preflight.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.preflightShield = preflightShield;
+const spl_token_1 = require("@solana/spl-token");
+const client_js_1 = require("../client.js");
+const program_js_1 = require("../program.js");
+const config_js_1 = require("../config.js");
+const errors_js_1 = require("./errors.js");
+const computeBudget_js_1 = require("./computeBudget.js");
+/**
+ * Checks that run before the prover.
+ *
+ * Proving costs 10–30 seconds. Every check here is a single RPC call, and each
+ * one pre-empts an on-chain failure whose message tells the user nothing they
+ * can act on. The delegate check is the clearest example: the program requires
+ * `user_token.delegate.is_none()`, so anyone who ever approved a DEX has a
+ * permanently broken deposit path that reports only "Invalid token account
+ * authority" — with no hint that revoking a delegate would fix it.
+ *
+ * These are advisory in the sense that the chain enforces them anyway. They are
+ * not advisory in the sense that skipping them produces a materially worse
+ * product.
+ */
+async function preflightShield(params) {
+    const { connection, amount, mint, signer, programId = program_js_1.PRIVACY_POOL_PROGRAM_ID, options = {}, } = params;
+    const isToken = !mint.equals(config_js_1.NATIVE_SOL_MINT);
+    // --- Pool state ------------------------------------------------------------
+    if (!options.skipPoolState) {
+        const program = (0, program_js_1.createReadonlyVeiloProgram)(connection);
+        const { config } = (0, client_js_1.getPoolPdas)(programId, mint);
+        let cfg;
+        try {
+            cfg = await program.account.privacyConfig.fetch(config);
+        }
+        catch (e) {
+            throw new errors_js_1.ShieldError("POOL_NOT_FOUND", `No privacy pool exists for mint ${mint.toBase58()}.`, { context: { mint: mint.toBase58(), config: config.toBase58() }, cause: e });
+        }
+        if (cfg.paused) {
+            throw new errors_js_1.ShieldError("POOL_PAUSED", "The pool is paused. Try again later.");
+        }
+        const min = BigInt(cfg.minDepositAmount?.toString() ?? "0");
+        const max = BigInt(cfg.maxDepositAmount?.toString() ?? "0");
+        if (min > 0n && amount < min) {
+            throw new errors_js_1.ShieldError("AMOUNT_BELOW_MINIMUM", `Amount ${amount} is below the pool minimum of ${min}.`, { context: { amount: amount.toString(), minimum: min.toString() } });
+        }
+        if (max > 0n && amount > max) {
+            throw new errors_js_1.ShieldError("AMOUNT_ABOVE_MAXIMUM", `Amount ${amount} exceeds the pool maximum of ${max}.`, { context: { amount: amount.toString(), maximum: max.toString() } });
+        }
+    }
+    // --- Source token account (SPL only) --------------------------------------
+    if (isToken && !options.skipTokenAccount) {
+        let account;
+        try {
+            account = await (0, spl_token_1.getAccount)(connection, signer.tokenAccount);
+        }
+        catch (e) {
+            if (e instanceof spl_token_1.TokenAccountNotFoundError || /could not find/i.test(String(e))) {
+                // Deliberately no "create the ATA" remedy: an ATA that does not exist
+                // holds zero tokens, so creating it would only move the failure to
+                // INSUFFICIENT_TOKEN_BALANCE. Say the true thing instead.
+                throw new errors_js_1.ShieldError("TOKEN_ACCOUNT_MISSING", `The signer has no token account for ${mint.toBase58()}, so there is nothing to shield.`, { context: { tokenAccount: signer.tokenAccount.toBase58() }, cause: e });
+            }
+            throw e;
+        }
+        if (!account.mint.equals(mint)) {
+            throw new errors_js_1.ShieldError("TOKEN_ACCOUNT_WRONG_MINT", `Token account ${signer.tokenAccount.toBase58()} holds ${account.mint.toBase58()}, not ${mint.toBase58()}.`, { context: { expected: mint.toBase58(), actual: account.mint.toBase58() } });
+        }
+        if (!account.owner.equals(signer.publicKey)) {
+            throw new errors_js_1.ShieldError("TOKEN_ACCOUNT_WRONG_OWNER", `Token account ${signer.tokenAccount.toBase58()} is owned by ${account.owner.toBase58()}, ` +
+                `not by the signing wallet. The program requires the signer to own the source account outright.`, {
+                context: {
+                    tokenAccount: signer.tokenAccount.toBase58(),
+                    owner: account.owner.toBase58(),
+                    signer: signer.publicKey.toBase58(),
+                },
+            });
+        }
+        if (account.isFrozen) {
+            throw new errors_js_1.ShieldError("TOKEN_ACCOUNT_FROZEN", `Token account ${signer.tokenAccount.toBase58()} is frozen.`, { context: { tokenAccount: signer.tokenAccount.toBase58() } });
+        }
+        // The program checks `delegate.is_none()`, NOT the delegated amount — so a
+        // stale delegate with zero allowance still fails. This is the single most
+        // common avoidable failure on this path, and it is entirely fixable.
+        if (account.delegate) {
+            throw new errors_js_1.ShieldError("TOKEN_ACCOUNT_DELEGATED", `Token account ${signer.tokenAccount.toBase58()} has an active delegate ` +
+                `(${account.delegate.toBase58()}). The pool rejects deposits from delegated ` +
+                `accounts even when the delegated amount is zero. Revoke the delegate, then shield.`, {
+                context: {
+                    tokenAccount: signer.tokenAccount.toBase58(),
+                    delegate: account.delegate.toBase58(),
+                    delegatedAmount: account.delegatedAmount.toString(),
+                },
+                remedy: {
+                    description: `Revoke the delegate on ${signer.tokenAccount.toBase58()}`,
+                    instructions: [
+                        (0, spl_token_1.createRevokeInstruction)(signer.tokenAccount, signer.publicKey),
+                    ],
+                },
+            });
+        }
+        if (account.amount < amount) {
+            throw new errors_js_1.ShieldError("INSUFFICIENT_TOKEN_BALANCE", `Token account holds ${account.amount} but ${amount} is required.`, { context: { balance: account.amount.toString(), required: amount.toString() } });
+        }
+        // The vault's ATA must already exist — the program requires the canonical
+        // one and will not create it.
+        const { vault } = (0, client_js_1.getPoolPdas)(programId, mint);
+        const vaultAta = await (0, spl_token_1.getAssociatedTokenAddress)(mint, vault, true);
+        const vaultInfo = await connection.getAccountInfo(vaultAta);
+        if (!vaultInfo) {
+            throw new errors_js_1.ShieldError("VAULT_ATA_MISSING", `The pool vault has no associated token account for ${mint.toBase58()}. ` +
+                `This is a pool provisioning issue, not something the signer can fix.`, { context: { vault: vault.toBase58(), vaultAta: vaultAta.toBase58() } });
+        }
+    }
+    // --- Signer balance --------------------------------------------------------
+    if (!options.skipBalance) {
+        const rentPer = await cachedRent(connection, params.cache);
+        const rent = BigInt(rentPer) * BigInt(computeBudget_js_1.NULLIFIER_MARKERS_PER_TRANSACT);
+        const computeUnitLimit = params.computeUnitLimit ?? computeBudget_js_1.SHIELD_COMPUTE_UNIT_LIMIT;
+        const computeUnitPriceMicroLamports = params.computeUnitPriceMicroLamports ?? computeBudget_js_1.SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS;
+        const priorityFee = (BigInt(computeUnitLimit) * BigInt(computeUnitPriceMicroLamports)) /
+            1000000n;
+        const baseFee = 5000n;
+        // The signer pays the marker rent regardless of the mint — it is SOL either
+        // way, and it is burned, not refunded.
+        const required = rent + priorityFee + baseFee + (isToken ? 0n : amount);
+        const balance = BigInt(await connection.getBalance(signer.publicKey));
+        if (balance < required) {
+            throw new errors_js_1.ShieldError("INSUFFICIENT_SOL", `The signing wallet has ${balance} lamports but needs ${required} ` +
+                `(${isToken ? "" : `${amount} shielded + `}${rent} nullifier-marker rent + ` +
+                `${priorityFee + baseFee} fees). Note that the marker rent is burned, not refunded, ` +
+                `and the program forces it onto the signer — it cannot be sponsored.`, {
+                context: {
+                    balance: balance.toString(),
+                    required: required.toString(),
+                    breakdown: {
+                        amount: isToken ? "0" : amount.toString(),
+                        nullifierMarkerRent: rent.toString(),
+                        priorityFee: priorityFee.toString(),
+                        baseFee: baseFee.toString(),
+                    },
+                },
+            });
+        }
+    }
+}
+async function cachedRent(connection, cache) {
+    const key = `rent:${computeBudget_js_1.NULLIFIER_MARKER_ACCOUNT_BYTES}`;
+    const hit = await cache?.get(key);
+    if (hit !== undefined)
+        return hit;
+    const value = await connection.getMinimumBalanceForRentExemption(computeBudget_js_1.NULLIFIER_MARKER_ACCOUNT_BYTES);
+    await cache?.set(key, value, 60 * 60000);
+    return value;
+}

package/dist/cjs/shield/shield.d.ts

@@ -0,0 +1,68 @@
+import { AddressLookupTableAccount, Connection } from "@solana/web3.js";
+import { bytesToBigIntBE, BN254_FR_MODULUS } from "../poseidon.js";
+import type { ShieldParams, ShieldProofCache, ShieldResult } from "./types.js";
+/**
+ * Build an unsigned transaction that shields public funds into the privacy pool.
+ *
+ * ## The contract
+ *
+ * This function builds. It does not sign, submit, confirm, or retry — those
+ * belong to whoever holds the key, exactly as with Jupiter's `/swap`. The
+ * returned `transaction` is unsigned; the caller signs it with whatever wallet
+ * they have and broadcasts it themselves.
+ *
+ * ## Why this can be handed to a third party
+ *
+ * Three properties make it safe to build a shield on behalf of a signer you do
+ * not control, and to shield to an owner who is not the signer:
+ *
+ *  1. **Deposits are permissionless.** The program gates its relayer allowlist
+ *     to `public_amount <= 0`, so any wallet can sign a deposit.
+ *  2. **No secrets are involved in building.** The proof for a deposit has no
+ *     real inputs, and the output commitment binds only the recipient's *public*
+ *     keys.
+ *  3. **The note rides on-chain.** `note_ciphers` travels inside the instruction,
+ *     so the recipient can find the note by scanning even if the platform that
+ *     submitted it never says a word.
+ *
+ * ## What the signer unavoidably pays
+ *
+ * The signer is the fee payer, the funding source, and the payer of two
+ * `NullifierMarker` rents (~0.00192 SOL, permanently burned — the program
+ * hardcodes `payer = relayer` on both). A wallet with zero SOL cannot shield
+ * through this path no matter who submits the transaction. Fee sponsorship is
+ * not achievable here: a second signature costs ~96 bytes against a budget with
+ * ~69 to spare, and would not cover the rent anyway.
+ */
+export declare function shield(params: ShieldParams): Promise<ShieldResult>;
+/**
+ * Re-assemble a shield with a fresh blockhash and deadline, reusing the proof.
+ *
+ * The Groth16 proof commits to the root, the public amount, `ext_data_hash`, the
+ * mint, the nullifiers and the commitments — none of which is time-dependent.
+ * `deadline` is a positional instruction argument, outside `ext_data_hash` and
+ * therefore outside the proof, so it can be refreshed too. That last part
+ * matters: a shield built at T and signed at T+59min needs a new deadline, not
+ * just a new blockhash.
+ *
+ * Costs one `getLatestBlockhash` and a message compile — no proving, no
+ * Poseidon, no account resolution.
+ *
+ * Does NOT recover from `ROOT_STALE`: a stale root invalidates the proof, so
+ * that case needs a fresh `shield()` call.
+ */
+export declare function rebuild(result: ShieldResult, opts?: {
+    connection?: Connection;
+    alt?: AddressLookupTableAccount;
+    blockhash?: {
+        blockhash: string;
+        lastValidBlockHeight: number;
+    };
+    deadlineSeconds?: number;
+    computeUnitPriceMicroLamports?: number;
+}): Promise<ShieldResult>;
+/** Serialize a proof cache for transport between processes. Contains no secrets. */
+export declare function serializeProofCache(cache: ShieldProofCache): string;
+export declare function deserializeProofCache(json: string): ShieldProofCache;
+/** Re-exported for callers that want the raw field arithmetic. */
+export { bytesToBigIntBE, BN254_FR_MODULUS };