@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/cjs/shield/alt.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHARED_ALT_MINTS = exports.SHARED_DEPOSIT_ALT = void 0;
+exports.sharedDepositAlt = sharedDepositAlt;
+exports.explicitAlt = explicitAlt;
+exports.requiredAltKeys = requiredAltKeys;
+exports.expectedDepositAltKeys = expectedDepositAltKeys;
+exports.auditDepositAlt = auditDepositAlt;
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const pdas_js_1 = require("../accounts/pdas.js");
+const program_js_1 = require("../program.js");
+const config_js_1 = require("../config.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Address lookup table handling for the shield path.
+ *
+ * The ALT is not an optimisation here — it is load-bearing. A `transact` carries
+ * 847 bytes of instruction data across 16 accounts, which is ~1500 bytes as a
+ * legacy transaction and therefore unlandable. Compressing the constant pool
+ * accounts to 1-byte indices is what brings it to ~1163 and leaves room for
+ * Phantom's Lighthouse guard instructions.
+ */
+/**
+ * The shared, team-owned deposit table.
+ *
+ * Deliberately shared rather than per-wallet: creating a per-wallet table costs
+ * the signer an extra signature and unrecoverable rent, which is unacceptable to
+ * ask of an external wallet shielding once, and impossible to ask of a
+ * third-party platform's managed wallet.
+ */
+exports.SHARED_DEPOSIT_ALT = new web3_js_1.PublicKey("3x2JxCgAPmv4U4EJonFBntm1q4W3xzpnB6aT1tCvxftk");
+/** Mints the shared table is provisioned for. */
+exports.SHARED_ALT_MINTS = [
+    { symbol: "SOL", mint: config_js_1.NATIVE_SOL_MINT },
+    { symbol: "USDC", mint: new web3_js_1.PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v") },
+    { symbol: "USDT", mint: new web3_js_1.PublicKey("Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB") },
+    { symbol: "USD1", mint: new web3_js_1.PublicKey("USD1ttGY1N17NEEHLmELoaybftRBUSErhqYiQzvEmuB") },
+    { symbol: "JUP", mint: new web3_js_1.PublicKey("JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN") },
+    { symbol: "ARX", mint: new web3_js_1.PublicKey("ARXwZkNAtzPfdcoqQiduJn8EPv9fKiDfGn2KyggyDrFs") },
+];
+const ALT_CACHE_TTL_MS = 10 * 60000;
+/**
+ * Load the shared table, and verify it actually covers this shield.
+ *
+ * The verification is the important part. Coverage is an *operational* property,
+ * not a code property: the table is populated by a script, and if a mint or a
+ * tree is missing, every one of its accounts falls back to a 32-byte static key
+ * and the transaction silently grows past 1232. Failing here with a list of the
+ * missing addresses is far better than failing at `signTransaction` with
+ * "transaction too large" and no indication why.
+ */
+function sharedDepositAlt(address = exports.SHARED_DEPOSIT_ALT, opts = {}) {
+    return {
+        async resolve({ connection, mint, outputTreeId, programId }) {
+            const key = `alt:${address.toBase58()}`;
+            let account = await opts.cache?.get(key);
+            if (!account) {
+                // "finalized" so every RPC the signer's wallet might simulate against
+                // has already seen the table. A table read at "processed" can be
+                // invisible to the wallet's own simulator.
+                const res = await connection.getAddressLookupTable(address, {
+                    commitment: "finalized",
+                });
+                if (!res.value) {
+                    throw new errors_js_1.ShieldError("ALT_NOT_FOUND", `Deposit address lookup table ${address.toBase58()} was not found at ` +
+                        `finalized commitment. Without it a shield cannot fit in 1232 bytes.`, { context: { address: address.toBase58() } });
+                }
+                account = res.value;
+                await opts.cache?.set(key, account, ALT_CACHE_TTL_MS);
+            }
+            if (opts.verifyCoverage !== false) {
+                const missing = missingCoverage(account, {
+                    mint,
+                    outputTreeId,
+                    programId,
+                });
+                if (missing.length > 0) {
+                    throw new errors_js_1.ShieldError("ALT_INCOMPLETE", `The deposit lookup table does not cover this shield: ${missing.length} ` +
+                        `required account(s) are absent, so the transaction would exceed 1232 ` +
+                        `bytes. Extend the table before shielding this mint/tree.`, {
+                        context: {
+                            alt: address.toBase58(),
+                            mint: mint.toBase58(),
+                            outputTreeId,
+                            missing: missing.map((m) => `${m.label} (${m.address.toBase58()})`),
+                        },
+                    });
+                }
+            }
+            return account;
+        },
+    };
+}
+/** Use a table the caller already loaded. Skips both the RPC call and the coverage check. */
+function explicitAlt(account) {
+    return { async resolve() { return account; } };
+}
+/**
+ * Accounts that must be in the table for a shield of `mint` into `outputTreeId`
+ * to fit.
+ *
+ * The signer, the two nullifier markers, and the user's token account are
+ * deliberately excluded: markers are unique per transaction and the others are
+ * per-user, so none can live in a shared table. They are the static keys the
+ * size budget accounts for.
+ */
+function requiredAltKeys(params) {
+    const programId = params.programId ?? program_js_1.PRIVACY_POOL_PROGRAM_ID;
+    const { config, vault, nullifiers } = (0, pdas_js_1.getPoolPdas)(programId, params.mint);
+    const keys = [
+        { label: "programId", address: programId },
+        { label: "computeBudgetProgram", address: web3_js_1.ComputeBudgetProgram.programId },
+        { label: "systemProgram", address: web3_js_1.SystemProgram.programId },
+        { label: "globalConfig", address: (0, pdas_js_1.getGlobalConfigPda)(programId) },
+        { label: "config", address: config },
+        { label: "vault", address: vault },
+        { label: "nullifiers", address: nullifiers },
+        { label: "inputTree(0)", address: (0, pdas_js_1.getNoteTreePda)(programId, params.mint, 0) },
+    ];
+    if (params.outputTreeId !== 0) {
+        keys.push({
+            label: `outputTree(${params.outputTreeId})`,
+            address: (0, pdas_js_1.getNoteTreePda)(programId, params.mint, params.outputTreeId),
+        });
+    }
+    if (!params.mint.equals(config_js_1.NATIVE_SOL_MINT)) {
+        keys.push({ label: "tokenProgram", address: spl_token_1.TOKEN_PROGRAM_ID }, {
+            label: "vaultAta",
+            address: (0, spl_token_1.getAssociatedTokenAddressSync)(params.mint, vault, true),
+        });
+    }
+    return keys;
+}
+function missingCoverage(account, params) {
+    const present = new Set(account.state.addresses.map((a) => a.toBase58()));
+    return requiredAltKeys(params).filter((k) => !present.has(k.address.toBase58()));
+}
+/**
+ * Everything the shared table should contain across every supported mint and
+ * every tree up to `maxTreeId`.
+ *
+ * Exported so this can be asserted in CI. The table currently only covers tree 0
+ * per mint, which means the size budget quietly loses 32 bytes of headroom the
+ * day tree 0 fills and `getBestTreeForDeposit` starts returning tree 1. That is
+ * a scheduled failure, and this function is how it gets caught before a user
+ * finds it.
+ */
+async function expectedDepositAltKeys(params) {
+    const programId = params.programId ?? program_js_1.PRIVACY_POOL_PROGRAM_ID;
+    const mints = params.mints ?? exports.SHARED_ALT_MINTS.map((m) => m.mint);
+    const maxTreeId = params.maxTreeId ?? 4;
+    const out = [
+        { label: "programId", address: programId },
+        { label: "computeBudgetProgram", address: web3_js_1.ComputeBudgetProgram.programId },
+        { label: "systemProgram", address: web3_js_1.SystemProgram.programId },
+        { label: "tokenProgram", address: spl_token_1.TOKEN_PROGRAM_ID },
+        { label: "globalConfig", address: (0, pdas_js_1.getGlobalConfigPda)(programId) },
+    ];
+    for (const mint of mints) {
+        const label = mint.equals(config_js_1.NATIVE_SOL_MINT) ? "SOL" : mint.toBase58().slice(0, 4);
+        const { config, vault, nullifiers } = (0, pdas_js_1.getPoolPdas)(programId, mint);
+        out.push({ label: `${label}.config`, address: config }, { label: `${label}.vault`, address: vault }, { label: `${label}.nullifiers`, address: nullifiers });
+        for (let t = 0; t <= maxTreeId; t++) {
+            out.push({
+                label: `${label}.tree(${t})`,
+                address: (0, pdas_js_1.getNoteTreePda)(programId, mint, t),
+            });
+        }
+        if (!mint.equals(config_js_1.NATIVE_SOL_MINT)) {
+            out.push({
+                label: `${label}.vaultAta`,
+                address: await (0, spl_token_1.getAssociatedTokenAddress)(mint, vault, true),
+            });
+        }
+    }
+    return out;
+}
+/** Diff the on-chain table against {@link expectedDepositAltKeys}. */
+async function auditDepositAlt(connection, params = {}) {
+    const address = params.address ?? exports.SHARED_DEPOSIT_ALT;
+    const res = await connection.getAddressLookupTable(address, {
+        commitment: "finalized",
+    });
+    if (!res.value) {
+        throw new errors_js_1.ShieldError("ALT_NOT_FOUND", `Deposit ALT ${address.toBase58()} not found`, { context: { address: address.toBase58() } });
+    }
+    const present = new Set(res.value.state.addresses.map((a) => a.toBase58()));
+    const expected = await expectedDepositAltKeys(params);
+    const expectedSet = new Set(expected.map((e) => e.address.toBase58()));
+    const missing = expected.filter((e) => !present.has(e.address.toBase58()));
+    const extra = [...present].filter((p) => !expectedSet.has(p));
+    return { ok: missing.length === 0, present: present.size, missing, extra };
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Compute budget and transaction size constants for the shield path.
+ *
+ * These numbers are empirical and load-bearing. They are constants rather than
+ * inline literals so a future program change that invalidates them has one
+ * place to be fixed and one place to be read.
+ */
+/**
+ * Compute unit limit reserved for a shield.
+ *
+ * Measured usage for a deposit is ~377k CU; 700k leaves roughly 2× headroom
+ * while staying low enough that Phantom's Lighthouse guard still fits its own
+ * instructions alongside ours.
+ *
+ * Do NOT raise this to 1.4M (what the stale `client.ts` `deposit()` reserves).
+ * An oversized CU reservation is one of the signals that makes Phantom render
+ * the transaction with a malicious-dApp warning.
+ *
+ * Ported from veilo-dapp/features/transactions/handleDeposit.ts:673-681.
+ */
+export declare const SHIELD_COMPUTE_UNIT_LIMIT = 700000;
+/** Typical measured usage. If real usage approaches the limit above, revisit both. */
+export declare const SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL = 377000;
+/** Default priority fee. Set to 0 to omit the instruction entirely (saves ~40 bytes). */
+export declare const SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS = 50000;
+/** Solana's hard cap on a serialized transaction, signatures included. */
+export declare const MAX_TRANSACTION_BYTES = 1232;
+/** One ed25519 signature: 64 bytes plus the compact-array length prefix. */
+export declare const SIGNATURE_BYTES = 65;
+/**
+ * `NullifierMarker::LEN` (privacy-program .../lib.rs:415). Two markers are
+ * created per transact and paid for by the signer — see the note on sponsorship
+ * in the module docs of `shield.ts`.
+ */
+export declare const NULLIFIER_MARKER_ACCOUNT_BYTES = 10;
+/** Markers created per `transact` — one per circuit input. */
+export declare const NULLIFIER_MARKERS_PER_TRANSACT = 2;
+/** Default validity window for the on-chain `deadline` argument. */
+export declare const DEFAULT_DEADLINE_SECONDS = 3600;
+/**
+ * Serialized size of the `transact` instruction data, for reference:
+ *
+ *   8   discriminator
+ *  32   root
+ *   2   input_tree_id
+ *   2   output_tree_id
+ *   8   public_amount
+ *  32   ext_data_hash
+ *  32   mint_address
+ * 128   2 nullifiers + 2 commitments
+ *   8   deadline
+ * 112   ExtData (recipient, relayer, fee, refund, claimant)
+ * 256   Groth16 proof (a:64, b:128, c:64)
+ * 227   Option<NoteCiphers> (1 tag + 226)
+ * ---
+ * 847
+ *
+ * With 16 accounts this cannot fit in a legacy transaction (~1500 bytes), which
+ * is why the shield path is v0-with-ALT and not optional.
+ */
+export declare const TRANSACT_INSTRUCTION_DATA_BYTES = 847;

package/dist/cjs/shield/computeBudget.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Compute budget and transaction size constants for the shield path.
+ *
+ * These numbers are empirical and load-bearing. They are constants rather than
+ * inline literals so a future program change that invalidates them has one
+ * place to be fixed and one place to be read.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRANSACT_INSTRUCTION_DATA_BYTES = exports.DEFAULT_DEADLINE_SECONDS = exports.NULLIFIER_MARKERS_PER_TRANSACT = exports.NULLIFIER_MARKER_ACCOUNT_BYTES = exports.SIGNATURE_BYTES = exports.MAX_TRANSACTION_BYTES = exports.SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS = exports.SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL = exports.SHIELD_COMPUTE_UNIT_LIMIT = void 0;
+/**
+ * Compute unit limit reserved for a shield.
+ *
+ * Measured usage for a deposit is ~377k CU; 700k leaves roughly 2× headroom
+ * while staying low enough that Phantom's Lighthouse guard still fits its own
+ * instructions alongside ours.
+ *
+ * Do NOT raise this to 1.4M (what the stale `client.ts` `deposit()` reserves).
+ * An oversized CU reservation is one of the signals that makes Phantom render
+ * the transaction with a malicious-dApp warning.
+ *
+ * Ported from veilo-dapp/features/transactions/handleDeposit.ts:673-681.
+ */
+exports.SHIELD_COMPUTE_UNIT_LIMIT = 700000;
+/** Typical measured usage. If real usage approaches the limit above, revisit both. */
+exports.SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL = 377000;
+/** Default priority fee. Set to 0 to omit the instruction entirely (saves ~40 bytes). */
+exports.SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS = 50000;
+/** Solana's hard cap on a serialized transaction, signatures included. */
+exports.MAX_TRANSACTION_BYTES = 1232;
+/** One ed25519 signature: 64 bytes plus the compact-array length prefix. */
+exports.SIGNATURE_BYTES = 65;
+/**
+ * `NullifierMarker::LEN` (privacy-program .../lib.rs:415). Two markers are
+ * created per transact and paid for by the signer — see the note on sponsorship
+ * in the module docs of `shield.ts`.
+ */
+exports.NULLIFIER_MARKER_ACCOUNT_BYTES = 10;
+/** Markers created per `transact` — one per circuit input. */
+exports.NULLIFIER_MARKERS_PER_TRANSACT = 2;
+/** Default validity window for the on-chain `deadline` argument. */
+exports.DEFAULT_DEADLINE_SECONDS = 3600;
+/**
+ * Serialized size of the `transact` instruction data, for reference:
+ *
+ *   8   discriminator
+ *  32   root
+ *   2   input_tree_id
+ *   2   output_tree_id
+ *   8   public_amount
+ *  32   ext_data_hash
+ *  32   mint_address
+ * 128   2 nullifiers + 2 commitments
+ *   8   deadline
+ * 112   ExtData (recipient, relayer, fee, refund, claimant)
+ * 256   Groth16 proof (a:64, b:128, c:64)
+ * 227   Option<NoteCiphers> (1 tag + 226)
+ * ---
+ * 847
+ *
+ * With 16 accounts this cannot fit in a legacy transaction (~1500 bytes), which
+ * is why the shield path is v0-with-ALT and not optional.
+ */
+exports.TRANSACT_INSTRUCTION_DATA_BYTES = 847;

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

@@ -0,0 +1,58 @@
+import { TransactionInstruction } from "@solana/web3.js";
+/**
+ * Error taxonomy for the shield path.
+ *
+ * `parseOnChainError` already turns program codes into readable sentences. What
+ * it does not give you is a *decision*: can this be retried, and how? That is
+ * what integrators actually need, because the three retry classes have wildly
+ * different costs:
+ *
+ *   - `rebuild`  — reuse the proof, new blockhash. Milliseconds.
+ *   - `reshield` — the proof is stale, prove again. 10–30 seconds.
+ *   - `none`     — retrying cannot help; something must change first.
+ */
+export type ShieldRetryClass = "rebuild" | "reshield" | "none";
+export type ShieldErrorCode = "POOL_NOT_FOUND" | "POOL_PAUSED" | "AMOUNT_BELOW_MINIMUM" | "AMOUNT_ABOVE_MAXIMUM" | "TREE_FULL" | "INSUFFICIENT_SOL" | "INSUFFICIENT_TOKEN_BALANCE" | "TOKEN_ACCOUNT_MISSING" | "TOKEN_ACCOUNT_WRONG_MINT" | "TOKEN_ACCOUNT_WRONG_OWNER" | "TOKEN_ACCOUNT_DELEGATED" | "TOKEN_ACCOUNT_FROZEN" | "VAULT_ATA_MISSING" | "ALT_NOT_FOUND" | "ALT_INCOMPLETE" | "TX_TOO_LARGE" | "OWNER_INVARIANT_UNACKNOWLEDGED" | "UNRESOLVED_ACCOUNT" | "BLOCKHASH_EXPIRED" | "DEADLINE_EXPIRED" | "ROOT_STALE" | "NULLIFIER_COLLISION" | "COMPUTE_BUDGET_EXCEEDED" | "PROOF_REJECTED" | "UNKNOWN";
+export type ShieldErrorRemedy = {
+    /** Human-readable description of what would fix this. */
+    description: string;
+    /** Instructions that, once executed, clear the condition. */
+    instructions: TransactionInstruction[];
+};
+export declare class ShieldError extends Error {
+    readonly code: ShieldErrorCode;
+    /** Program error code (6000–6060) when this was derived from a chain error. */
+    readonly programCode?: number;
+    /** Whether and how a retry can succeed. */
+    readonly retryable: ShieldRetryClass;
+    /** Machine-readable detail: which account, what value, what was expected. */
+    readonly context?: Record<string, unknown>;
+    /** Present when the condition is fixable by executing instructions first. */
+    readonly remedy?: ShieldErrorRemedy;
+    readonly cause?: unknown;
+    constructor(code: ShieldErrorCode, message: string, opts?: {
+        programCode?: number;
+        retryable?: ShieldRetryClass;
+        context?: Record<string, unknown>;
+        remedy?: ShieldErrorRemedy;
+        cause?: unknown;
+    });
+}
+/** Extract a privacy_pool program error code from an arbitrary thrown value. */
+export declare function extractProgramCode(error: any): number | null;
+/**
+ * Map a submission failure onto the taxonomy.
+ *
+ * Two mappings here are not obvious and are worth stating plainly:
+ *
+ * **Nullifier collision means "already landed", not "already spent."** The
+ * marker PDAs are `init`, not `init_if_needed`, so a second submission of the
+ * same shield fails at account resolution. For a deposit the nullifiers derive
+ * from freshly generated random keys, so a genuine collision is impossible —
+ * in practice this only ever means the first attempt succeeded. Telling a user
+ * their funds were "already spent" here would be alarming and wrong.
+ *
+ * **`UnknownRoot` is recoverable but not by `rebuild()`.** The proof commits to
+ * the root, so a stale root needs a fresh proof, not a fresh blockhash.
+ */
+export declare function mapShieldError(error: unknown): ShieldError;

package/dist/cjs/shield/errors.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ShieldError = void 0;
+exports.extractProgramCode = extractProgramCode;
+exports.mapShieldError = mapShieldError;
+const errors_js_1 = require("../accounts/errors.js");
+class ShieldError extends Error {
+    constructor(code, message, opts = {}) {
+        super(message);
+        this.name = "ShieldError";
+        this.code = code;
+        this.programCode = opts.programCode;
+        this.retryable = opts.retryable ?? "none";
+        this.context = opts.context;
+        this.remedy = opts.remedy;
+        this.cause = opts.cause;
+    }
+}
+exports.ShieldError = ShieldError;
+/** Extract a privacy_pool program error code from an arbitrary thrown value. */
+function extractProgramCode(error) {
+    const raw = (error?.message ?? error?.toString() ?? "").toLowerCase();
+    const hex = raw.match(/custom program error:\s*0x([0-9a-f]+)/);
+    if (hex)
+        return parseInt(hex[1], 16);
+    const num = raw.match(/error number:\s*(\d+)/);
+    if (num)
+        return parseInt(num[1], 10);
+    if (typeof error?.error?.errorCode?.number === "number") {
+        return error.error.errorCode.number;
+    }
+    return null;
+}
+/**
+ * Map a submission failure onto the taxonomy.
+ *
+ * Two mappings here are not obvious and are worth stating plainly:
+ *
+ * **Nullifier collision means "already landed", not "already spent."** The
+ * marker PDAs are `init`, not `init_if_needed`, so a second submission of the
+ * same shield fails at account resolution. For a deposit the nullifiers derive
+ * from freshly generated random keys, so a genuine collision is impossible —
+ * in practice this only ever means the first attempt succeeded. Telling a user
+ * their funds were "already spent" here would be alarming and wrong.
+ *
+ * **`UnknownRoot` is recoverable but not by `rebuild()`.** The proof commits to
+ * the root, so a stale root needs a fresh proof, not a fresh blockhash.
+ */
+function mapShieldError(error) {
+    if (error instanceof ShieldError)
+        return error;
+    const err = error;
+    const raw = (err?.message ?? String(err ?? "")).toLowerCase();
+    const programCode = extractProgramCode(err);
+    const readable = (0, errors_js_1.parseOnChainError)(err);
+    if (programCode !== null) {
+        switch (programCode) {
+            case 6000:
+                return new ShieldError("POOL_PAUSED", readable, { programCode, cause: err });
+            case 6007:
+                return new ShieldError("ROOT_STALE", "The Merkle root this shield was proven against is no longer in the on-chain " +
+                    "history. Build a new shield — the proof cannot be reused.", { programCode, retryable: "reshield", cause: err });
+            case 6012:
+                return new ShieldError("PROOF_REJECTED", readable, { programCode, cause: err });
+            case 6013:
+                return new ShieldError("TREE_FULL", readable, {
+                    programCode,
+                    retryable: "reshield",
+                    cause: err,
+                });
+            case 6017:
+                return new ShieldError("TOKEN_ACCOUNT_WRONG_MINT", readable, {
+                    programCode,
+                    cause: err,
+                });
+            case 6029:
+                return new ShieldError("TOKEN_ACCOUNT_DELEGATED", "The source token account has an active delegate. Revoke it, then shield again.", { programCode, cause: err });
+            case 6033:
+                return new ShieldError("TOKEN_ACCOUNT_WRONG_OWNER", "The source token account is not owned by the signing wallet.", { programCode, cause: err });
+            case 6035:
+                return new ShieldError("AMOUNT_BELOW_MINIMUM", readable, { programCode, cause: err });
+            case 6036:
+                return new ShieldError("AMOUNT_ABOVE_MAXIMUM", readable, { programCode, cause: err });
+            case 6050:
+                return new ShieldError("VAULT_ATA_MISSING", readable, { programCode, cause: err });
+            case 6005:
+            case 6046:
+            case 6052:
+                return new ShieldError("NULLIFIER_COLLISION", ALREADY_SHIELDED_MESSAGE, {
+                    programCode,
+                    cause: err,
+                });
+            case 6060:
+                return new ShieldError("DEADLINE_EXPIRED", "The shield's deadline passed before it landed. Rebuild it — the proof is still valid.", { programCode, retryable: "rebuild", cause: err });
+            default:
+                return new ShieldError("UNKNOWN", readable, { programCode, cause: err });
+        }
+    }
+    // Non-program failures.
+    if (raw.includes("block height exceeded") ||
+        raw.includes("blockhash not found") ||
+        err?.name === "TransactionExpiredBlockheightExceededError") {
+        return new ShieldError("BLOCKHASH_EXPIRED", "The blockhash expired before the shield landed. Rebuild it — the proof is still valid.", { retryable: "rebuild", cause: err });
+    }
+    if (raw.includes("already in use")) {
+        return new ShieldError("NULLIFIER_COLLISION", ALREADY_SHIELDED_MESSAGE, { cause: err });
+    }
+    if (raw.includes("exceeded cus") ||
+        raw.includes("computational budget exceeded") ||
+        raw.includes("exceeded compute")) {
+        return new ShieldError("COMPUTE_BUDGET_EXCEEDED", `The shield exceeded its compute budget. Real usage has grown past the reserved ` +
+            `limit — SHIELD_COMPUTE_UNIT_LIMIT needs revisiting.`, { cause: err });
+    }
+    if (raw.includes("too large") || raw.includes("transaction too large")) {
+        return new ShieldError("TX_TOO_LARGE", readable, { cause: err });
+    }
+    return new ShieldError("UNKNOWN", readable, { cause: err });
+}
+const ALREADY_SHIELDED_MESSAGE = "This shield has already been submitted — check the transaction signature before " +
+    "retrying. (The nullifier markers already exist on-chain, which for a deposit means " +
+    "the original transaction landed; it does not mean the funds were spent.)";

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

@@ -0,0 +1,45 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import type { ShieldNote, ShieldOwner } from "./types.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 declare function finalizeShield(params: {
+    connection: Connection;
+    signature: string;
+    note: ShieldNote;
+    owner: ShieldOwner;
+    programId?: PublicKey;
+    /** Defaults to "confirmed". Use "finalized" if the index will be persisted. */
+    commitment?: "confirmed" | "finalized";
+}): Promise<{
+    leafIndex: number;
+    newRoot: Uint8Array;
+    treeId: number;
+    slot: number;
+    /** Encrypted note blob, ready for POST /notes/save if the caller wants mailbox delivery. */
+    blob: {
+        ephemeralPublicKey: Uint8Array;
+        encryptedBlob: string;
+    };
+}>;

package/dist/cjs/shield/finalize.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.finalizeShield = finalizeShield;
+const anchor = __importStar(require("@coral-xyz/anchor"));
+const program_js_1 = require("../program.js");
+const mailbox_js_1 = require("../notes/mailbox.js");
+const poseidon_js_1 = require("../poseidon.js");
+const errors_js_1 = require("./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.
+ */
+async function finalizeShield(params) {
+    const { connection, signature, note, owner, programId = program_js_1.PRIVACY_POOL_PROGRAM_ID, commitment = "confirmed", } = params;
+    const tx = await connection.getTransaction(signature, {
+        commitment: commitment === "finalized" ? "finalized" : "confirmed",
+        maxSupportedTransactionVersion: 0,
+    });
+    if (!tx) {
+        throw new errors_js_1.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 errors_js_1.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(program_js_1.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 errors_js_1.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 = (0, mailbox_js_1.encryptBlindMailboxNote)(owner.noteViewingKey.toBytes(), {
+        blinding: (0, poseidon_js_1.bigIntToBytesBE)(note.blinding),
+        leafIndex,
+        commitment: note.commitment,
+        amount: note.amount,
+        mintAddress: note.mint.toBase58(),
+        treeId,
+    });
+    return {
+        leafIndex,
+        newRoot,
+        treeId,
+        slot: tx.slot,
+        blob,
+    };
+}