@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/cjs/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/cjs/shield/index.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DEADLINE_SECONDS = exports.NULLIFIER_MARKERS_PER_TRANSACT = exports.NULLIFIER_MARKER_ACCOUNT_BYTES = exports.TRANSACT_INSTRUCTION_DATA_BYTES = exports.SIGNATURE_BYTES = exports.MAX_TRANSACTION_BYTES = exports.SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL = exports.SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS = exports.SHIELD_COMPUTE_UNIT_LIMIT = exports.extractProgramCode = exports.mapShieldError = exports.ShieldError = exports.noCache = exports.memoryCache = exports.staticTreeSource = exports.onChainTreeSource = exports.SHARED_ALT_MINTS = exports.SHARED_DEPOSIT_ALT = exports.requiredAltKeys = exports.expectedDepositAltKeys = exports.auditDepositAlt = exports.explicitAlt = exports.sharedDepositAlt = exports.TRANSACT_ACCOUNT_NAMES = exports.buildTransactInstruction = exports.preflightShield = exports.finalizeShield = exports.unsafeShieldOwner = exports.resolveShieldOwner = exports.deserializeProofCache = exports.serializeProofCache = exports.rebuild = exports.shield = void 0;
+var shield_js_1 = require("./shield.js");
+Object.defineProperty(exports, "shield", { enumerable: true, get: function () { return shield_js_1.shield; } });
+Object.defineProperty(exports, "rebuild", { enumerable: true, get: function () { return shield_js_1.rebuild; } });
+Object.defineProperty(exports, "serializeProofCache", { enumerable: true, get: function () { return shield_js_1.serializeProofCache; } });
+Object.defineProperty(exports, "deserializeProofCache", { enumerable: true, get: function () { return shield_js_1.deserializeProofCache; } });
+var owner_js_1 = require("./owner.js");
+Object.defineProperty(exports, "resolveShieldOwner", { enumerable: true, get: function () { return owner_js_1.resolveShieldOwner; } });
+Object.defineProperty(exports, "unsafeShieldOwner", { enumerable: true, get: function () { return owner_js_1.unsafeShieldOwner; } });
+var finalize_js_1 = require("./finalize.js");
+Object.defineProperty(exports, "finalizeShield", { enumerable: true, get: function () { return finalize_js_1.finalizeShield; } });
+var preflight_js_1 = require("./preflight.js");
+Object.defineProperty(exports, "preflightShield", { enumerable: true, get: function () { return preflight_js_1.preflightShield; } });
+var ix_js_1 = require("./ix.js");
+Object.defineProperty(exports, "buildTransactInstruction", { enumerable: true, get: function () { return ix_js_1.buildTransactInstruction; } });
+Object.defineProperty(exports, "TRANSACT_ACCOUNT_NAMES", { enumerable: true, get: function () { return ix_js_1.TRANSACT_ACCOUNT_NAMES; } });
+var alt_js_1 = require("./alt.js");
+Object.defineProperty(exports, "sharedDepositAlt", { enumerable: true, get: function () { return alt_js_1.sharedDepositAlt; } });
+Object.defineProperty(exports, "explicitAlt", { enumerable: true, get: function () { return alt_js_1.explicitAlt; } });
+Object.defineProperty(exports, "auditDepositAlt", { enumerable: true, get: function () { return alt_js_1.auditDepositAlt; } });
+Object.defineProperty(exports, "expectedDepositAltKeys", { enumerable: true, get: function () { return alt_js_1.expectedDepositAltKeys; } });
+Object.defineProperty(exports, "requiredAltKeys", { enumerable: true, get: function () { return alt_js_1.requiredAltKeys; } });
+Object.defineProperty(exports, "SHARED_DEPOSIT_ALT", { enumerable: true, get: function () { return alt_js_1.SHARED_DEPOSIT_ALT; } });
+Object.defineProperty(exports, "SHARED_ALT_MINTS", { enumerable: true, get: function () { return alt_js_1.SHARED_ALT_MINTS; } });
+var ports_js_1 = require("./ports.js");
+Object.defineProperty(exports, "onChainTreeSource", { enumerable: true, get: function () { return ports_js_1.onChainTreeSource; } });
+Object.defineProperty(exports, "staticTreeSource", { enumerable: true, get: function () { return ports_js_1.staticTreeSource; } });
+Object.defineProperty(exports, "memoryCache", { enumerable: true, get: function () { return ports_js_1.memoryCache; } });
+Object.defineProperty(exports, "noCache", { enumerable: true, get: function () { return ports_js_1.noCache; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "ShieldError", { enumerable: true, get: function () { return errors_js_1.ShieldError; } });
+Object.defineProperty(exports, "mapShieldError", { enumerable: true, get: function () { return errors_js_1.mapShieldError; } });
+Object.defineProperty(exports, "extractProgramCode", { enumerable: true, get: function () { return errors_js_1.extractProgramCode; } });
+var computeBudget_js_1 = require("./computeBudget.js");
+Object.defineProperty(exports, "SHIELD_COMPUTE_UNIT_LIMIT", { enumerable: true, get: function () { return computeBudget_js_1.SHIELD_COMPUTE_UNIT_LIMIT; } });
+Object.defineProperty(exports, "SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS", { enumerable: true, get: function () { return computeBudget_js_1.SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS; } });
+Object.defineProperty(exports, "SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL", { enumerable: true, get: function () { return computeBudget_js_1.SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL; } });
+Object.defineProperty(exports, "MAX_TRANSACTION_BYTES", { enumerable: true, get: function () { return computeBudget_js_1.MAX_TRANSACTION_BYTES; } });
+Object.defineProperty(exports, "SIGNATURE_BYTES", { enumerable: true, get: function () { return computeBudget_js_1.SIGNATURE_BYTES; } });
+Object.defineProperty(exports, "TRANSACT_INSTRUCTION_DATA_BYTES", { enumerable: true, get: function () { return computeBudget_js_1.TRANSACT_INSTRUCTION_DATA_BYTES; } });
+Object.defineProperty(exports, "NULLIFIER_MARKER_ACCOUNT_BYTES", { enumerable: true, get: function () { return computeBudget_js_1.NULLIFIER_MARKER_ACCOUNT_BYTES; } });
+Object.defineProperty(exports, "NULLIFIER_MARKERS_PER_TRANSACT", { enumerable: true, get: function () { return computeBudget_js_1.NULLIFIER_MARKERS_PER_TRANSACT; } });
+Object.defineProperty(exports, "DEFAULT_DEADLINE_SECONDS", { enumerable: true, get: function () { return computeBudget_js_1.DEFAULT_DEADLINE_SECONDS; } });

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

@@ -0,0 +1,54 @@
+import { PublicKey, TransactionInstruction } from "@solana/web3.js";
+import type { TransactionProofStruct } from "../proofs/types.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/cjs/shield/ix.js

@@ -0,0 +1,119 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRANSACT_ACCOUNT_NAMES = void 0;
+exports.buildTransactInstruction = buildTransactInstruction;
+const anchor = __importStar(require("@coral-xyz/anchor"));
+const web3_js_1 = require("@solana/web3.js");
+const program_js_1 = require("../program.js");
+const errors_js_1 = require("./errors.js");
+const computeBudget_js_1 = require("./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 = program_js_1.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. */
+exports.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.
+ */
+function buildTransactInstruction(accounts, args, programId = program_js_1.PRIVACY_POOL_PROGRAM_ID) {
+    const keys = IDL_TRANSACT.accounts.map((a) => {
+        const pubkey = accounts[a.name];
+        if (!pubkey) {
+            throw new errors_js_1.ShieldError("UNRESOLVED_ACCOUNT", `The IDL declares account "${a.name}" for transact, but it was not resolved. ` +
+                `Expected accounts: ${exports.TRANSACT_ACCOUNT_NAMES.join(", ")}`, { context: { missing: a.name, supplied: Object.keys(accounts) } });
+        }
+        return {
+            pubkey,
+            isWritable: !!a.writable,
+            isSigner: !!a.signer,
+        };
+    });
+    const coder = new BorshInstructionCoder(program_js_1.PRIVACY_POOL_IDL);
+    const data = coder.encode("transact", toBorshArgs(args));
+    if (data.length !== computeBudget_js_1.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 ` +
+            `${computeBudget_js_1.TRANSACT_INSTRUCTION_DATA_BYTES}. The shield size budget may no longer hold.`);
+    }
+    return new web3_js_1.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/cjs/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/cjs/shield/owner.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveShieldOwner = resolveShieldOwner;
+exports.unsafeShieldOwner = unsafeShieldOwner;
+const web3_js_1 = require("@solana/web3.js");
+const client_js_1 = require("../relayer/client.js");
+const errors_js_1 = require("../relayer/errors.js");
+const errors_js_2 = require("./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 client_js_1.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.
+ */
+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 errors_js_1.VeiloApiError && e.status === 404))) {
+            const wallet = typeof target.publicKey === "string"
+                ? new web3_js_1.PublicKey(target.publicKey)
+                : target.publicKey;
+            const provisioned = await OWNER_RELAYER.preRegisterKey(wallet.toBase58());
+            if (!provisioned?.veiloPublicKey) {
+                throw new errors_js_2.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 errors_js_2.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 errors_js_2.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 web3_js_1.PublicKey(walletRaw);
+    if ("publicKey" in target &&
+        !noteViewingKey.equals(typeof target.publicKey === "string"
+            ? new web3_js_1.PublicKey(target.publicKey)
+            : target.publicKey)) {
+        throw new errors_js_2.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.
+ */
+function unsafeShieldOwner(params) {
+    return {
+        veiloPublicKey: params.veiloPublicKey,
+        noteViewingKey: params.noteViewingKey,
+        acknowledgeOwnerInvariant: true,
+    };
+}

package/dist/cjs/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/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 pdas_js_1 = require("../accounts/pdas.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, pdas_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, pdas_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() { },
+    };
+}