@veilo/sdk-core 0.1.17 → 0.4.0

package/dist/esm/shield/finalize.js

@@ -0,0 +1,83 @@
+import * as anchor from "@coral-xyz/anchor";
+import { PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID } from "../program.js";
+import { encryptBlindMailboxNote } from "../utxo.js";
+import { bigIntToBytesBE } from "../poseidon.js";
+import { ShieldError } from "./errors.js";
+/**
+ * Read the authoritative leaf index for a landed shield, and produce the
+ * mailbox blob for optional relayer delivery.
+ *
+ * ## Why this is a separate step
+ *
+ * Every existing deposit implementation records `tree.nextIndex` read *before*
+ * submission as the note's leaf index. Under concurrent deposits into the same
+ * tree that value is wrong, and it is wrong permanently — the stored index is
+ * what a later withdrawal builds its Merkle path from, so the note becomes
+ * unspendable through the normal path.
+ *
+ * That race is rare for a single wallet and constant for an SDK: a platform
+ * batching shields for many users will hit it routinely. So `shield()` reports
+ * only a `predictedLeafIndex`, and the real one is read here from the
+ * transaction's own `CommitmentEvent` after it confirms.
+ *
+ * ## What is optional
+ *
+ * Everything, strictly. The note is recoverable from chain data alone via the
+ * on-chain compact cipher, so a caller that skips finalization has not lost the
+ * funds — only the fast path to finding them. Persist nothing that depends on a
+ * leaf index without calling this first.
+ */
+export async function finalizeShield(params) {
+    const { connection, signature, note, owner, programId = PRIVACY_POOL_PROGRAM_ID, commitment = "confirmed", } = params;
+    const tx = await connection.getTransaction(signature, {
+        commitment: commitment === "finalized" ? "finalized" : "confirmed",
+        maxSupportedTransactionVersion: 0,
+    });
+    if (!tx) {
+        throw new ShieldError("UNKNOWN", `Transaction ${signature} not found at ${commitment} commitment. ` +
+            `If it was just submitted, wait for confirmation and retry.`, { context: { signature } });
+    }
+    if (tx.meta?.err) {
+        throw new ShieldError("UNKNOWN", `Transaction ${signature} failed on-chain; there is no note to finalize.`, { context: { signature, err: tx.meta.err } });
+    }
+    const parser = new anchor.EventParser(programId, new anchor.BorshCoder(PRIVACY_POOL_IDL));
+    const wantCommitment = Buffer.from(note.commitment).toString("hex");
+    let match = null;
+    for (const event of parser.parseLogs(tx.meta?.logMessages ?? [])) {
+        if (event.name !== "CommitmentEvent" && event.name !== "commitmentEvent")
+            continue;
+        const data = event.data;
+        const emitted = Buffer.from(data.commitment).toString("hex");
+        if (emitted === wantCommitment) {
+            match = data;
+            break;
+        }
+    }
+    if (!match) {
+        throw new ShieldError("UNKNOWN", `Transaction ${signature} landed but emitted no CommitmentEvent for this note's ` +
+            `commitment. The note may belong to a different transaction.`, { context: { signature, commitment: wantCommitment } });
+    }
+    const leafIndex = Number(match.leafIndex ?? match.leaf_index);
+    const treeId = Number(match.treeId ?? match.tree_id ?? note.treeId);
+    const newRoot = new Uint8Array(match.newRoot ?? match.new_root);
+    // Mailbox copy. Sending this to the relayer with a `recipientWalletPublicKey`
+    // buys instant delivery and a push notification, at the cost of writing the
+    // sender→recipient association into the relayer's database AND removing the
+    // note from the chain-recovery feed. For shield-to-someone-else, chain-only
+    // discovery is usually the better default — see the plan's Phase 3 note.
+    const blob = encryptBlindMailboxNote(owner.noteViewingKey.toBytes(), {
+        blinding: bigIntToBytesBE(note.blinding),
+        leafIndex,
+        commitment: note.commitment,
+        amount: note.amount,
+        mintAddress: note.mint.toBase58(),
+        treeId,
+    });
+    return {
+        leafIndex,
+        newRoot,
+        treeId,
+        slot: tx.slot,
+        blob,
+    };
+}

package/dist/esm/shield/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Wallet-agnostic shielding.
+ *
+ * `shield()` builds an unsigned transaction that deposits public funds into the
+ * privacy pool, creating a note owned by an arbitrary recipient. Any external
+ * wallet — a browser extension, or a third-party platform's managed wallet —
+ * signs and submits it. The SDK never touches a secret key.
+ *
+ * ```ts
+ * const owner = await resolveShieldOwner({ username: "alice" });
+ * const { transaction, note, proofCache } = await shield({
+ *   connection, amount, mint, owner,
+ *   signer: { publicKey: wallet.publicKey },
+ *   prover: createTransactionProver(artifacts),
+ * });
+ *
+ * const signed = await wallet.signTransaction(transaction);
+ * const sig = await connection.sendRawTransaction(signed.serialize());
+ * ```
+ *
+ * On blockhash expiry, `rebuild(result, { connection })` re-assembles with a
+ * fresh blockhash and deadline without re-proving.
+ */
+export { shield, rebuild, serializeProofCache, deserializeProofCache } from "./shield.js";
+export { resolveShieldOwner, unsafeShieldOwner } from "./owner.js";
+export { finalizeShield } from "./finalize.js";
+export { preflightShield } from "./preflight.js";
+export { buildTransactInstruction, TRANSACT_ACCOUNT_NAMES } from "./ix.js";
+export type { TransactAccounts, TransactArgs } from "./ix.js";
+export { sharedDepositAlt, explicitAlt, auditDepositAlt, expectedDepositAltKeys, requiredAltKeys, SHARED_DEPOSIT_ALT, SHARED_ALT_MINTS, } from "./alt.js";
+export { onChainTreeSource, staticTreeSource, memoryCache, noCache } from "./ports.js";
+export { ShieldError, mapShieldError, extractProgramCode, } from "./errors.js";
+export type { ShieldErrorCode, ShieldRetryClass, ShieldErrorRemedy } from "./errors.js";
+export { SHIELD_COMPUTE_UNIT_LIMIT, SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS, SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL, MAX_TRANSACTION_BYTES, SIGNATURE_BYTES, TRANSACT_INSTRUCTION_DATA_BYTES, NULLIFIER_MARKER_ACCOUNT_BYTES, NULLIFIER_MARKERS_PER_TRANSACT, DEFAULT_DEADLINE_SECONDS, } from "./computeBudget.js";
+export type { ShieldOwner, ShieldSigner, ShieldParams, ShieldResult, ShieldNote, ShieldProofCache, ShieldQuote, TreeSource, AltSource, ShieldCachePort, DepositTarget, PreflightOptions, } from "./types.js";

package/dist/esm/shield/index.js

@@ -0,0 +1,32 @@
+/**
+ * Wallet-agnostic shielding.
+ *
+ * `shield()` builds an unsigned transaction that deposits public funds into the
+ * privacy pool, creating a note owned by an arbitrary recipient. Any external
+ * wallet — a browser extension, or a third-party platform's managed wallet —
+ * signs and submits it. The SDK never touches a secret key.
+ *
+ * ```ts
+ * const owner = await resolveShieldOwner({ username: "alice" });
+ * const { transaction, note, proofCache } = await shield({
+ *   connection, amount, mint, owner,
+ *   signer: { publicKey: wallet.publicKey },
+ *   prover: createTransactionProver(artifacts),
+ * });
+ *
+ * const signed = await wallet.signTransaction(transaction);
+ * const sig = await connection.sendRawTransaction(signed.serialize());
+ * ```
+ *
+ * On blockhash expiry, `rebuild(result, { connection })` re-assembles with a
+ * fresh blockhash and deadline without re-proving.
+ */
+export { shield, rebuild, serializeProofCache, deserializeProofCache } from "./shield.js";
+export { resolveShieldOwner, unsafeShieldOwner } from "./owner.js";
+export { finalizeShield } from "./finalize.js";
+export { preflightShield } from "./preflight.js";
+export { buildTransactInstruction, TRANSACT_ACCOUNT_NAMES } from "./ix.js";
+export { sharedDepositAlt, explicitAlt, auditDepositAlt, expectedDepositAltKeys, requiredAltKeys, SHARED_DEPOSIT_ALT, SHARED_ALT_MINTS, } from "./alt.js";
+export { onChainTreeSource, staticTreeSource, memoryCache, noCache } from "./ports.js";
+export { ShieldError, mapShieldError, extractProgramCode, } from "./errors.js";
+export { SHIELD_COMPUTE_UNIT_LIMIT, SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS, SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL, MAX_TRANSACTION_BYTES, SIGNATURE_BYTES, TRANSACT_INSTRUCTION_DATA_BYTES, NULLIFIER_MARKER_ACCOUNT_BYTES, NULLIFIER_MARKERS_PER_TRANSACT, DEFAULT_DEADLINE_SECONDS, } from "./computeBudget.js";

package/dist/esm/shield/ix.d.ts

@@ -0,0 +1,54 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import type { TransactionProofStruct } from "../proof.js";
+/**
+ * `transact` instruction assembly, driven by the IDL rather than by a
+ * hand-written account list.
+ *
+ * Every existing deposit implementation spells out all sixteen accounts by hand
+ * in an `accountsStrict({...})` literal. That works until the IDL changes, at
+ * which point a silently misordered or missing account produces a runtime
+ * failure that is very hard to trace. Here the account list and the ordering
+ * come from the IDL itself, and an unresolved name throws at build time.
+ *
+ * Building the instruction directly also means no Anchor `Provider` and no
+ * `Wallet` — which is the whole point of a wallet-agnostic shield.
+ */
+/** Account names the IDL declares for `transact`, in order. */
+export type TransactAccounts = Record<string, PublicKey>;
+export type TransactArgs = {
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    publicAmount: bigint;
+    extDataHash: Uint8Array;
+    mintAddress: PublicKey;
+    inputNullifiers: [Uint8Array, Uint8Array];
+    outputCommitments: [Uint8Array, Uint8Array];
+    deadline: bigint;
+    extData: {
+        recipient: PublicKey;
+        relayer: PublicKey;
+        fee: bigint;
+        refund: bigint;
+        claimant: PublicKey;
+    };
+    proof: TransactionProofStruct;
+    noteCiphers: {
+        note0EphemeralKey: Uint8Array;
+        note0Encrypted: Uint8Array;
+        note0ViewTag: number;
+        note1EphemeralKey: Uint8Array;
+        note1Encrypted: Uint8Array;
+        note1ViewTag: number;
+    } | null;
+};
+/** Account names in IDL order. Exported so callers can see what must be resolved. */
+export declare const TRANSACT_ACCOUNT_NAMES: string[];
+/**
+ * Build the `transact` instruction.
+ *
+ * @throws ShieldError('UNRESOLVED_ACCOUNT') if the IDL declares an account the
+ *         caller did not supply — a loud failure is the point, because the
+ *         alternative is a misordered account list that fails opaquely on-chain.
+ */
+export declare function buildTransactInstruction(accounts: TransactAccounts, args: TransactArgs, programId?: PublicKey): TransactionInstruction;

package/dist/esm/shield/ix.js

@@ -0,0 +1,82 @@
+import * as anchor from "@coral-xyz/anchor";
+import { TransactionInstruction, } from "@solana/web3.js";
+import { PRIVACY_POOL_IDL, PRIVACY_POOL_PROGRAM_ID } from "../program.js";
+import { ShieldError } from "./errors.js";
+import { TRANSACT_INSTRUCTION_DATA_BYTES } from "./computeBudget.js";
+// Anchor is CommonJS and does not expose BN as a detectable named export to
+// Node ESM. Pull both runtime values from the namespace so CJS and ESM agree.
+const { BN, BorshInstructionCoder } = anchor;
+const IDL_TRANSACT = PRIVACY_POOL_IDL.instructions.find((i) => i.name === "transact");
+if (!IDL_TRANSACT) {
+    throw new Error("privacy_pool IDL has no `transact` instruction");
+}
+/** Account names in IDL order. Exported so callers can see what must be resolved. */
+export const TRANSACT_ACCOUNT_NAMES = IDL_TRANSACT.accounts.map((a) => a.name);
+/**
+ * Build the `transact` instruction.
+ *
+ * @throws ShieldError('UNRESOLVED_ACCOUNT') if the IDL declares an account the
+ *         caller did not supply — a loud failure is the point, because the
+ *         alternative is a misordered account list that fails opaquely on-chain.
+ */
+export function buildTransactInstruction(accounts, args, programId = PRIVACY_POOL_PROGRAM_ID) {
+    const keys = IDL_TRANSACT.accounts.map((a) => {
+        const pubkey = accounts[a.name];
+        if (!pubkey) {
+            throw new ShieldError("UNRESOLVED_ACCOUNT", `The IDL declares account "${a.name}" for transact, but it was not resolved. ` +
+                `Expected accounts: ${TRANSACT_ACCOUNT_NAMES.join(", ")}`, { context: { missing: a.name, supplied: Object.keys(accounts) } });
+        }
+        return {
+            pubkey,
+            isWritable: !!a.writable,
+            isSigner: !!a.signer,
+        };
+    });
+    const coder = new BorshInstructionCoder(PRIVACY_POOL_IDL);
+    const data = coder.encode("transact", toBorshArgs(args));
+    if (data.length !== TRANSACT_INSTRUCTION_DATA_BYTES) {
+        // Not fatal — the size budget assertion downstream is authoritative — but a
+        // change here means the size arithmetic in computeBudget.ts is stale.
+        console.warn(`[veilo] transact instruction data is ${data.length} bytes, expected ` +
+            `${TRANSACT_INSTRUCTION_DATA_BYTES}. The shield size budget may no longer hold.`);
+    }
+    return new TransactionInstruction({ programId, keys, data });
+}
+/** Anchor's Borsh coder wants camelCase field names, BNs, and plain arrays. */
+function toBorshArgs(args) {
+    return {
+        root: Array.from(args.root),
+        input_tree_id: args.inputTreeId,
+        output_tree_id: args.outputTreeId,
+        public_amount: new BN(args.publicAmount.toString()),
+        ext_data_hash: Array.from(args.extDataHash),
+        mint_address: args.mintAddress,
+        input_nullifier_0: Array.from(args.inputNullifiers[0]),
+        input_nullifier_1: Array.from(args.inputNullifiers[1]),
+        output_commitment_0: Array.from(args.outputCommitments[0]),
+        output_commitment_1: Array.from(args.outputCommitments[1]),
+        deadline: new BN(args.deadline.toString()),
+        ext_data: {
+            recipient: args.extData.recipient,
+            relayer: args.extData.relayer,
+            fee: new BN(args.extData.fee.toString()),
+            refund: new BN(args.extData.refund.toString()),
+            claimant: args.extData.claimant,
+        },
+        proof: {
+            proof_a: args.proof.proofA,
+            proof_b: args.proof.proofB,
+            proof_c: args.proof.proofC,
+        },
+        note_ciphers: args.noteCiphers
+            ? {
+                note0_ephemeral_key: Array.from(args.noteCiphers.note0EphemeralKey),
+                note0_encrypted: Array.from(args.noteCiphers.note0Encrypted),
+                note0_view_tag: args.noteCiphers.note0ViewTag,
+                note1_ephemeral_key: Array.from(args.noteCiphers.note1EphemeralKey),
+                note1_encrypted: Array.from(args.noteCiphers.note1Encrypted),
+                note1_view_tag: args.noteCiphers.note1ViewTag,
+            }
+            : null,
+    };
+}

package/dist/esm/shield/owner.d.ts

@@ -0,0 +1,36 @@
+import { PublicKey } from "@solana/web3.js";
+import type { ShieldOwner } from "./types.js";
+/**
+ * Resolve a shield recipient into the pair of keys that must belong to the same
+ * account.
+ *
+ * This is the only mechanism that makes the owner invariant safe. A note's
+ * *spend* authority is a Poseidon field element and its *detection* authority is
+ * an Ed25519 wallet key; nothing on-chain relates them, and if an integrator
+ * sources them separately and gets them wrong, the note is spendable but
+ * permanently invisible — the funds are gone from the owner's view with no error
+ * raised anywhere in the stack.
+ *
+ * `GET /auth/veiloPublicKey` returns both halves in a single response, so
+ * routing through this function makes the pairing structural rather than a
+ * convention integrators are asked to remember.
+ *
+ * Prefer this over hand-building a {@link ShieldOwner} in all cases.
+ */
+export declare function resolveShieldOwner(target: {
+    username: string;
+} | {
+    publicKey: string | PublicKey;
+}): Promise<ShieldOwner>;
+/**
+ * Build a {@link ShieldOwner} from keys the caller already holds.
+ *
+ * Only correct when both keys provably belong to the same account. The explicit
+ * flag is not ceremony — it is the last checkpoint before a class of bug whose
+ * only symptom is a user's money quietly disappearing from their balance.
+ */
+export declare function unsafeShieldOwner(params: {
+    veiloPublicKey: bigint;
+    noteViewingKey: PublicKey;
+    acknowledgeOwnerInvariant: true;
+}): ShieldOwner;

package/dist/esm/shield/owner.js

@@ -0,0 +1,122 @@
+import { PublicKey } from "@solana/web3.js";
+import { VeiloApiError, VeiloRelayerClient } from "../relayer.js";
+import { ShieldError } from "./errors.js";
+/**
+ * Owner resolution is a Veilo protocol service, not an integrator-selected
+ * transport. Keep the production endpoint and public encryption key inside the
+ * SDK so callers cannot accidentally resolve the two owner keys from different
+ * relayers.
+ *
+ * These values are public network coordinates, not credentials. In particular,
+ * never put a secret API key here: browser/mobile package contents are always
+ * inspectable. The two owner endpoints used below are intentionally public and
+ * return public key material only.
+ */
+const OWNER_RELAYER = new VeiloRelayerClient({
+    apiKey: "",
+    relayerPublicKey: "utVxnA7zax09qJCZ7UJsa8PAOoWLRcCwOkdxg/ZGmD4=",
+});
+/**
+ * Resolve a shield recipient into the pair of keys that must belong to the same
+ * account.
+ *
+ * This is the only mechanism that makes the owner invariant safe. A note's
+ * *spend* authority is a Poseidon field element and its *detection* authority is
+ * an Ed25519 wallet key; nothing on-chain relates them, and if an integrator
+ * sources them separately and gets them wrong, the note is spendable but
+ * permanently invisible — the funds are gone from the owner's view with no error
+ * raised anywhere in the stack.
+ *
+ * `GET /auth/veiloPublicKey` returns both halves in a single response, so
+ * routing through this function makes the pairing structural rather than a
+ * convention integrators are asked to remember.
+ *
+ * Prefer this over hand-building a {@link ShieldOwner} in all cases.
+ */
+export async function resolveShieldOwner(target) {
+    const query = "username" in target
+        ? { username: target.username }
+        : {
+            publicKey: typeof target.publicKey === "string"
+                ? target.publicKey
+                : target.publicKey.toBase58(),
+        };
+    let response;
+    try {
+        response = await OWNER_RELAYER.getVeiloPublicKey(query);
+    }
+    catch (e) {
+        // A raw Solana address may not have a Veilo account yet. Provisioning is
+        // public and idempotent, and returns only the Poseidon spend key; the
+        // address we were given is the matching note-viewing key.
+        if ("publicKey" in target &&
+            (e?.status === 404 || (e instanceof VeiloApiError && e.status === 404))) {
+            const wallet = typeof target.publicKey === "string"
+                ? new PublicKey(target.publicKey)
+                : target.publicKey;
+            const provisioned = await OWNER_RELAYER.preRegisterKey(wallet.toBase58());
+            if (!provisioned?.veiloPublicKey) {
+                throw new ShieldError("UNKNOWN", "The relayer pre-registered the recipient but returned no Veilo public key.", { context: { publicKey: wallet.toBase58(), response: provisioned }, cause: e });
+            }
+            return {
+                veiloPublicKey: BigInt(provisioned.veiloPublicKey),
+                noteViewingKey: wallet,
+                acknowledgeOwnerInvariant: true,
+            };
+        }
+        // A pre-registered account is one someone else created on the recipient's
+        // behalf; the recipient has never proved ownership, so the relayer refuses
+        // to resolve it by username. Shielding to them still works, but the caller
+        // must address them by Solana address instead.
+        if (e?.body?.preRegistered ||
+            e?.details?.preRegistered ||
+            /preregistered/i.test(String(e?.message ?? ""))) {
+            throw new ShieldError("UNKNOWN", `"${"username" in target ? target.username : "that account"}" is pre-registered ` +
+                `and cannot be resolved by username. Resolve it by Solana address instead — ` +
+                `resolveShieldOwner({ publicKey }).`, { context: { preRegistered: true }, cause: e });
+        }
+        throw e;
+    }
+    const veiloPublicKeyRaw = response?.veiloPublicKey;
+    const walletRaw = response?.pubK;
+    if (!veiloPublicKeyRaw || !walletRaw) {
+        throw new ShieldError("UNKNOWN", `The relayer did not return both keys for this recipient ` +
+            `(veiloPublicKey=${!!veiloPublicKeyRaw}, pubK=${!!walletRaw}). ` +
+            `Shielding without both would create a note the owner cannot find.`, { context: { response } });
+    }
+    const noteViewingKey = new PublicKey(walletRaw);
+    if ("publicKey" in target &&
+        !noteViewingKey.equals(typeof target.publicKey === "string"
+            ? new PublicKey(target.publicKey)
+            : target.publicKey)) {
+        throw new ShieldError("UNKNOWN", "The Veilo owner service returned a different wallet than the one requested. " +
+            "Shielding was stopped to prevent creating a note for the wrong recipient.", {
+            context: {
+                requested: typeof target.publicKey === "string"
+                    ? target.publicKey
+                    : target.publicKey.toBase58(),
+                returned: noteViewingKey.toBase58(),
+            },
+        });
+    }
+    return {
+        veiloPublicKey: BigInt(veiloPublicKeyRaw),
+        noteViewingKey,
+        // Safe to assert: both halves came from one response about one account.
+        acknowledgeOwnerInvariant: true,
+    };
+}
+/**
+ * Build a {@link ShieldOwner} from keys the caller already holds.
+ *
+ * Only correct when both keys provably belong to the same account. The explicit
+ * flag is not ceremony — it is the last checkpoint before a class of bug whose
+ * only symptom is a user's money quietly disappearing from their balance.
+ */
+export function unsafeShieldOwner(params) {
+    return {
+        veiloPublicKey: params.veiloPublicKey,
+        noteViewingKey: params.noteViewingKey,
+        acknowledgeOwnerInvariant: true,
+    };
+}

package/dist/esm/shield/ports.d.ts

@@ -0,0 +1,43 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import type { DepositTarget, ShieldCachePort, TreeSource } from "./types.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.
+ */
+/**
+ * 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.
+ */
+export declare function onChainTreeSource(connection: Connection, programId?: PublicKey): TreeSource;
+/**
+ * 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.
+ */
+export declare function staticTreeSource(target: DepositTarget): TreeSource;
+/**
+ * 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.
+ */
+export declare function memoryCache(): ShieldCachePort;
+/** A cache that never stores anything. Useful for tests that assert fetch counts. */
+export declare function noCache(): ShieldCachePort;

package/dist/esm/shield/ports.js

@@ -0,0 +1,147 @@
+import { createReadonlyVeiloProgram, PRIVACY_POOL_PROGRAM_ID } from "../program.js";
+import { getNoteTreePda, getPoolPdas } from "../client.js";
+import { MERKLE_TREE_DEPTH } from "../config.js";
+import { ShieldError } from "./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.
+ */
+export function onChainTreeSource(connection, programId = PRIVACY_POOL_PROGRAM_ID) {
+    return {
+        async getDepositTarget(mint) {
+            const program = createReadonlyVeiloProgram(connection);
+            const { config } = getPoolPdas(programId, mint);
+            const cfg = await program.account.privacyConfig.fetch(config);
+            const numTrees = Number(cfg.numTrees);
+            if (!Number.isInteger(numTrees) || numTrees <= 0) {
+                throw new 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) => getNoteTreePda(programId, mint, treeId));
+            const infos = await connection.getMultipleAccountsInfo(treePdas, {
+                commitment: "confirmed",
+            });
+            const capacity = 2 ** 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 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 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.
+ */
+export 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.
+ */
+export 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. */
+export function noCache() {
+    return {
+        async get() { return undefined; },
+        async set() { },
+    };
+}

package/dist/esm/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>;