@veilo/sdk-core 0.3.3 → 0.4.0

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>;

package/dist/esm/shield/preflight.js

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

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

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