@veilo/sdk-core 0.3.3 → 0.4.0

package/dist/esm/shield/shield.js

@@ -0,0 +1,492 @@
+import { ComputeBudgetProgram, PublicKey, SystemProgram, TransactionMessage, VersionedTransaction, } from "@solana/web3.js";
+import { TOKEN_PROGRAM_ID, getAssociatedTokenAddress } from "@solana/spl-token";
+import { PRIVACY_POOL_PROGRAM_ID } from "../program.js";
+import { getGlobalConfigPda, getNoteTreePda, getNullifierMarkerPda, getPoolPdas, } from "../client.js";
+import { MERKLE_TREE_DEPTH, NATIVE_SOL_MINT } from "../config.js";
+import { bigIntToBytesBE, bytesToBigIntBE, BN254_FR_MODULUS, } from "../poseidon.js";
+import { poseidonZeroChain } from "../merkle.js";
+import { createUTXO, createOwnedZeroUTXO, generateKeypair, } from "../utxo.js";
+import { computeExtDataHash, encodeSnarkjsProofToTransactionProof, prepareTransactionInputs, } from "../proof.js";
+import { createCompactNoteCipher, emptyNoteCipher } from "../compactNote.js";
+import { buildTransactInstruction } from "./ix.js";
+import { sharedDepositAlt } from "./alt.js";
+import { memoryCache, onChainTreeSource } from "./ports.js";
+import { preflightShield } from "./preflight.js";
+import { ShieldError, mapShieldError } from "./errors.js";
+import { DEFAULT_DEADLINE_SECONDS, MAX_TRANSACTION_BYTES, NULLIFIER_MARKERS_PER_TRANSACT, NULLIFIER_MARKER_ACCOUNT_BYTES, SHIELD_COMPUTE_UNIT_LIMIT, SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS, SIGNATURE_BYTES, } from "./computeBudget.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 async function shield(params) {
+    const { connection, amount, owner, signer, prover, mint = NATIVE_SOL_MINT, programId = PRIVACY_POOL_PROGRAM_ID, computeUnitLimit = SHIELD_COMPUTE_UNIT_LIMIT, computeUnitPriceMicroLamports = SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS, deadlineSeconds = DEFAULT_DEADLINE_SECONDS, } = params;
+    if (amount <= 0n) {
+        throw new ShieldError("UNKNOWN", `shield amount must be positive, got ${amount}`);
+    }
+    // The owner invariant cannot be verified by anything on-chain or in the type
+    // system: if `veiloPublicKey` and `noteViewingKey` belong to different people
+    // the note is spendable-but-invisible and the funds are gone from the owner's
+    // view with no error anywhere. `resolveShieldOwner()` sets this flag because
+    // it fetches both halves from one response and can therefore guarantee they
+    // match. Anyone hand-building an owner is asserting they did the same.
+    if (!owner.acknowledgeOwnerInvariant) {
+        throw new ShieldError("OWNER_INVARIANT_UNACKNOWLEDGED", "ShieldOwner was constructed by hand. `veiloPublicKey` (spend authority) and " +
+            "`noteViewingKey` (detection authority) MUST belong to the same account — if " +
+            "they do not, the note is spendable but permanently invisible to its owner. " +
+            "Use resolveShieldOwner() to obtain both from a single source, or set " +
+            "`acknowledgeOwnerInvariant: true` if you have verified them yourself.");
+    }
+    const cache = params.cache ?? memoryCache();
+    const treeSource = params.treeSource ?? onChainTreeSource(connection, programId);
+    const altSource = params.alt ?? sharedDepositAlt(undefined, { cache });
+    const isToken = !mint.equals(NATIVE_SOL_MINT);
+    const userTokenAccount = isToken
+        ? (signer.tokenAccount ?? (await getAssociatedTokenAddress(mint, signer.publicKey)))
+        : signer.publicKey;
+    // --- 1. Pre-flight ---------------------------------------------------------
+    // Before the prover, which costs 10-30 seconds. Every check here is one RPC
+    // call, and each one pre-empts an on-chain failure whose error message would
+    // tell the user nothing actionable.
+    if (params.preflight !== false) {
+        await preflightShield({
+            connection,
+            amount,
+            mint,
+            signer: { publicKey: signer.publicKey, tokenAccount: userTokenAccount },
+            programId,
+            options: typeof params.preflight === "object" ? params.preflight : {},
+            cache,
+            computeUnitLimit,
+            computeUnitPriceMicroLamports,
+        });
+    }
+    // --- 2. Target tree and root ----------------------------------------------
+    const target = await treeSource.getDepositTarget(mint);
+    const treeCapacity = 2 ** MERKLE_TREE_DEPTH;
+    if (target.outputNextIndex >= treeCapacity) {
+        throw new ShieldError("TREE_FULL", `Merkle tree ${target.outputTreeId} is full (${target.outputNextIndex}/${treeCapacity} leaves).`, {
+            retryable: "reshield",
+            context: {
+                treeId: target.outputTreeId,
+                nextIndex: target.outputNextIndex,
+                capacity: treeCapacity,
+            },
+        });
+    }
+    // --- 3. Outputs ------------------------------------------------------------
+    // Output 0 carries the value and is owned by the recipient. Output 1 is a
+    // zero-value dummy the 2-in-2-out circuit requires.
+    const outputNote = createUTXO({
+        amount,
+        pubkey: owner.veiloPublicKey,
+        mintAddress: mint,
+    });
+    const dummyOutput = createUTXO({
+        amount: 0n,
+        pubkey: generateKeypair().publicKey,
+        mintAddress: mint,
+    });
+    // --- 4. Dummy inputs -------------------------------------------------------
+    // Two INDEPENDENT keypairs. Reusing one (as the stale client.ts `deposit()`
+    // does) only avoids the program's DuplicateNullifiers check by accident of
+    // blinding randomness; two keys make it structural.
+    const zeroChain = poseidonZeroChain(22).slice(0, 22);
+    const dummyInputs = [
+        toDummyInput(createOwnedZeroUTXO(generateKeypair().privateKey, mint), zeroChain),
+        toDummyInput(createOwnedZeroUTXO(generateKeypair().privateKey, mint), zeroChain),
+    ];
+    // --- 5. ExtData ------------------------------------------------------------
+    // For a deposit these slots carry no payment semantics — no fee is taken and
+    // nothing is withdrawn — but they are bound into the proof via ext_data_hash,
+    // so they must match exactly what goes on-chain.
+    const extData = {
+        recipient: signer.publicKey,
+        relayer: signer.publicKey,
+        fee: 0n,
+        refund: 0n,
+        claimant: SystemProgram.programId,
+    };
+    const extDataHash = computeExtDataHash(extData);
+    // --- 6. Prove --------------------------------------------------------------
+    const circuitInputs = prepareTransactionInputs({
+        inputUTXOs: dummyInputs,
+        outputUTXOs: [outputNote, dummyOutput],
+        root: target.inputRoot,
+        publicAmount: amount,
+        extData,
+        mintAddress: mint,
+    });
+    let proof;
+    try {
+        proof = encodeSnarkjsProofToTransactionProof(await prover(circuitInputs));
+    }
+    catch (e) {
+        throw mapShieldError(e);
+    }
+    // --- 7. Encrypt the note to its owner --------------------------------------
+    // Encrypted to `noteViewingKey`, which may be a completely different party
+    // from the signer. This is what makes shield-to-someone-else work.
+    const compact = createCompactNoteCipher(owner.noteViewingKey.toBytes(), bigIntToBytesBE(outputNote.blinding), amount);
+    const empty = emptyNoteCipher();
+    // --- 8. Resolve accounts ---------------------------------------------------
+    const accounts = resolveTransactAccounts({
+        programId,
+        mint,
+        signer: signer.publicKey,
+        userTokenAccount,
+        inputTreeId: target.inputTreeId,
+        outputTreeId: target.outputTreeId,
+        inputNullifiers: circuitInputs.inputNullifiers,
+        vaultTokenAccount: isToken
+            ? await getAssociatedTokenAddress(mint, getPoolPdas(programId, mint).vault, true)
+            : getPoolPdas(programId, mint).vault,
+        isToken,
+    });
+    // --- 9. Cache everything needed to rebuild ---------------------------------
+    const alt = await altSource.resolve({
+        connection,
+        mint,
+        outputTreeId: target.outputTreeId,
+        programId,
+    });
+    const proofCache = {
+        version: 1,
+        programId: programId.toBase58(),
+        mint: mint.toBase58(),
+        signer: signer.publicKey.toBase58(),
+        altAddress: alt.key.toBase58(),
+        inputTreeId: target.inputTreeId,
+        outputTreeId: target.outputTreeId,
+        root: hex(target.inputRoot),
+        publicAmount: amount.toString(),
+        extData: {
+            recipient: extData.recipient.toBase58(),
+            relayer: extData.relayer.toBase58(),
+            fee: extData.fee.toString(),
+            refund: extData.refund.toString(),
+            claimant: extData.claimant.toBase58(),
+        },
+        extDataHash: hex(extDataHash),
+        inputNullifiers: [
+            hex(circuitInputs.inputNullifiers[0]),
+            hex(circuitInputs.inputNullifiers[1]),
+        ],
+        outputCommitments: [hex(outputNote.commitment), hex(dummyOutput.commitment)],
+        proof,
+        noteCiphers: {
+            note0EphemeralKey: hex(compact.ephemeralPublicKey),
+            note0Encrypted: hex(compact.compactBlob),
+            note0ViewTag: compact.viewTag,
+            note1EphemeralKey: hex(empty.ephemeralPublicKey),
+            note1Encrypted: hex(empty.compactBlob),
+            note1ViewTag: empty.viewTag,
+        },
+        accounts: Object.fromEntries(Object.entries(accounts).map(([k, v]) => [k, v.toBase58()])),
+        computeUnitLimit,
+    };
+    const note = {
+        commitment: outputNote.commitment,
+        blinding: outputNote.blinding,
+        amount,
+        ownerVeiloPublicKey: owner.veiloPublicKey,
+        mint,
+        treeId: target.outputTreeId,
+        compact,
+    };
+    // --- 10. Assemble ----------------------------------------------------------
+    const blockhash = params.blockhash ?? (await connection.getLatestBlockhash("confirmed"));
+    const deadline = BigInt(Math.floor(Date.now() / 1000) + deadlineSeconds);
+    const built = buildFromCache({
+        cache: proofCache,
+        alt,
+        blockhash,
+        deadline,
+        computeUnitPriceMicroLamports,
+    });
+    const estimatedRentLamports = await rentForNullifierMarkers(connection, cache);
+    return {
+        transaction: built.transaction,
+        blockhash: blockhash.blockhash,
+        lastValidBlockHeight: blockhash.lastValidBlockHeight,
+        deadline,
+        note,
+        predictedLeafIndex: target.outputNextIndex,
+        quote: {
+            serializedSize: built.serializedSize,
+            computeUnitLimit,
+            computeUnitPriceMicroLamports,
+            estimatedFeeLamports: 5000n +
+                (BigInt(computeUnitLimit) * BigInt(computeUnitPriceMicroLamports)) / 1000000n,
+            estimatedRentLamports,
+        },
+        proofCache,
+    };
+}
+/**
+ * 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 async function rebuild(result, opts = {}) {
+    const cache = result.proofCache;
+    const blockhash = opts.blockhash ??
+        (opts.connection
+            ? await opts.connection.getLatestBlockhash("confirmed")
+            : (() => {
+                throw new ShieldError("UNKNOWN", "rebuild() needs either a `connection` or an explicit `blockhash`");
+            })());
+    const alt = opts.alt ??
+        (opts.connection
+            ? await sharedDepositAlt(new PublicKey(cache.altAddress), {
+                verifyCoverage: false,
+            }).resolve({
+                connection: opts.connection,
+                mint: new PublicKey(cache.mint),
+                outputTreeId: cache.outputTreeId,
+                programId: new PublicKey(cache.programId),
+            })
+            : (() => {
+                throw new ShieldError("UNKNOWN", "rebuild() needs either a `connection` or an explicit `alt`");
+            })());
+    const deadline = BigInt(Math.floor(Date.now() / 1000) + (opts.deadlineSeconds ?? DEFAULT_DEADLINE_SECONDS));
+    const priceMicroLamports = opts.computeUnitPriceMicroLamports ?? result.quote.computeUnitPriceMicroLamports;
+    const built = buildFromCache({
+        cache,
+        alt,
+        blockhash,
+        deadline,
+        computeUnitPriceMicroLamports: priceMicroLamports,
+    });
+    return {
+        ...result,
+        transaction: built.transaction,
+        blockhash: blockhash.blockhash,
+        lastValidBlockHeight: blockhash.lastValidBlockHeight,
+        deadline,
+        quote: {
+            ...result.quote,
+            serializedSize: built.serializedSize,
+            computeUnitPriceMicroLamports: priceMicroLamports,
+        },
+    };
+}
+/**
+ * The single place a shield transaction is assembled and size-checked.
+ *
+ * Both `shield()` and `rebuild()` route through here so there is exactly one
+ * message layout and exactly one size assertion — the failure mode this guards
+ * against (a transaction that is 40 bytes too large) is otherwise diagnosed as
+ * an opaque wallet error with no indication of which account caused it.
+ */
+function buildFromCache(params) {
+    const { cache, alt, blockhash, deadline, computeUnitPriceMicroLamports } = params;
+    const programId = new PublicKey(cache.programId);
+    const signer = new PublicKey(cache.signer);
+    const accounts = Object.fromEntries(Object.entries(cache.accounts).map(([k, v]) => [k, new PublicKey(v)]));
+    const transactIx = buildTransactInstruction(accounts, {
+        root: unhex(cache.root),
+        inputTreeId: cache.inputTreeId,
+        outputTreeId: cache.outputTreeId,
+        publicAmount: BigInt(cache.publicAmount),
+        extDataHash: unhex(cache.extDataHash),
+        mintAddress: new PublicKey(cache.mint),
+        inputNullifiers: [unhex(cache.inputNullifiers[0]), unhex(cache.inputNullifiers[1])],
+        outputCommitments: [
+            unhex(cache.outputCommitments[0]),
+            unhex(cache.outputCommitments[1]),
+        ],
+        deadline,
+        extData: {
+            recipient: new PublicKey(cache.extData.recipient),
+            relayer: new PublicKey(cache.extData.relayer),
+            fee: BigInt(cache.extData.fee),
+            refund: BigInt(cache.extData.refund),
+            claimant: new PublicKey(cache.extData.claimant),
+        },
+        proof: cache.proof,
+        noteCiphers: {
+            note0EphemeralKey: unhex(cache.noteCiphers.note0EphemeralKey),
+            note0Encrypted: unhex(cache.noteCiphers.note0Encrypted),
+            note0ViewTag: cache.noteCiphers.note0ViewTag,
+            note1EphemeralKey: unhex(cache.noteCiphers.note1EphemeralKey),
+            note1Encrypted: unhex(cache.noteCiphers.note1Encrypted),
+            note1ViewTag: cache.noteCiphers.note1ViewTag,
+        },
+    }, programId);
+    const instructions = [
+        ComputeBudgetProgram.setComputeUnitLimit({ units: cache.computeUnitLimit }),
+    ];
+    // A zero price omits the instruction entirely — worth ~40 bytes when the
+    // budget is tight (the gasless path relies on exactly this).
+    if (computeUnitPriceMicroLamports > 0) {
+        instructions.push(ComputeBudgetProgram.setComputeUnitPrice({
+            microLamports: computeUnitPriceMicroLamports,
+        }));
+    }
+    instructions.push(transactIx);
+    const message = new TransactionMessage({
+        payerKey: signer,
+        recentBlockhash: blockhash.blockhash,
+        instructions,
+    }).compileToV0Message([alt]);
+    const transaction = new VersionedTransaction(message);
+    // Measure the message separately and add the one-signature wire section.
+    // VersionedTransaction.serialize() cannot be used for diagnostics here: it
+    // serializes through a fixed-size buffer and can throw `encoding overruns`
+    // before we get a chance to report which ALT keys were missing.
+    const serializedSize = serializedMessageSize(message) + SIGNATURE_BYTES;
+    if (serializedSize > MAX_TRANSACTION_BYTES) {
+        const staticKeys = message.staticAccountKeys.map((k) => k.toBase58());
+        const inAlt = new Set(alt.state.addresses.map((a) => a.toBase58()));
+        throw new ShieldError("TX_TOO_LARGE", `Shield transaction is ${serializedSize} bytes, over the ${MAX_TRANSACTION_BYTES} ` +
+            `limit by ${serializedSize - MAX_TRANSACTION_BYTES}. ` +
+            `${staticKeys.length} account(s) could not be compressed into the lookup table.`, {
+            context: {
+                serializedSize,
+                limit: MAX_TRANSACTION_BYTES,
+                alt: alt.key.toBase58(),
+                uncompressedKeys: staticKeys.filter((k) => !inAlt.has(k)),
+            },
+        });
+    }
+    return { transaction, serializedSize };
+}
+/** Exact v0 message wire size without serializing into web3.js' 1232-byte buffer. */
+function serializedMessageSize(message) {
+    const staticKeys = message.staticAccountKeys.length;
+    const instructions = message.compiledInstructions;
+    const lookups = message.addressTableLookups;
+    return (1 + // v0 prefix
+        3 + // message header
+        shortVecSize(staticKeys) +
+        staticKeys * 32 +
+        32 + // recent blockhash
+        shortVecSize(instructions.length) +
+        instructions.reduce((sum, ix) => sum +
+            1 + // program id index
+            shortVecSize(ix.accountKeyIndexes.length) +
+            ix.accountKeyIndexes.length +
+            shortVecSize(ix.data.length) +
+            ix.data.length, 0) +
+        shortVecSize(lookups.length) +
+        lookups.reduce((sum, lookup) => sum +
+            32 +
+            shortVecSize(lookup.writableIndexes.length) +
+            lookup.writableIndexes.length +
+            shortVecSize(lookup.readonlyIndexes.length) +
+            lookup.readonlyIndexes.length, 0));
+}
+/** Number of bytes used by Solana's short-vector length prefix. */
+function shortVecSize(value) {
+    let size = 1;
+    while (value >= 0x80) {
+        value >>>= 7;
+        size++;
+    }
+    return size;
+}
+// -- helpers ------------------------------------------------------------------
+/**
+ * Wrap a zero-value UTXO as a circuit input.
+ *
+ * The path elements are the Poseidon zero chain and the index is 0. Neither is
+ * constrained — the circuit disables its Merkle check for zero-amount inputs —
+ * but the witness still has to be well-formed and the right length.
+ */
+function toDummyInput(utxo, zeroChain) {
+    return {
+        ...utxo,
+        pathIndex: 0,
+        pathElements: zeroChain,
+        privateKey: utxo.privateKey,
+    };
+}
+function resolveTransactAccounts(params) {
+    const { programId, mint, signer } = params;
+    const { config, vault, nullifiers } = getPoolPdas(programId, mint);
+    return {
+        config,
+        global_config: getGlobalConfigPda(programId),
+        vault,
+        input_tree: getNoteTreePda(programId, mint, params.inputTreeId),
+        output_tree: getNoteTreePda(programId, mint, params.outputTreeId),
+        nullifiers,
+        nullifier_marker_0: getNullifierMarkerPda(programId, mint, params.inputNullifiers[0]),
+        nullifier_marker_1: getNullifierMarkerPda(programId, mint, params.inputNullifiers[1]),
+        relayer: signer,
+        // For a deposit nothing is withdrawn, so `recipient` is just the signer.
+        // Pointing the unused token slots at accounts already in the transaction
+        // keeps them from costing 32 static bytes each.
+        recipient: signer,
+        vault_token_account: params.vaultTokenAccount,
+        user_token_account: params.userTokenAccount,
+        recipient_token_account: params.userTokenAccount,
+        relayer_token_account: params.userTokenAccount,
+        token_program: params.isToken ? TOKEN_PROGRAM_ID : SystemProgram.programId,
+        system_program: SystemProgram.programId,
+    };
+}
+async function rentForNullifierMarkers(connection, cache) {
+    const key = `rent:${NULLIFIER_MARKER_ACCOUNT_BYTES}`;
+    let per = await cache.get(key);
+    if (per === undefined) {
+        per = await connection.getMinimumBalanceForRentExemption(NULLIFIER_MARKER_ACCOUNT_BYTES);
+        await cache.set(key, per, 60 * 60000);
+    }
+    return BigInt(per) * BigInt(NULLIFIER_MARKERS_PER_TRANSACT);
+}
+const hex = (u) => Buffer.from(u).toString("hex");
+const unhex = (s) => new Uint8Array(Buffer.from(s, "hex"));
+/** Serialize a proof cache for transport between processes. Contains no secrets. */
+export function serializeProofCache(cache) {
+    return JSON.stringify(cache);
+}
+export function deserializeProofCache(json) {
+    const parsed = JSON.parse(json);
+    if (parsed?.version !== 1) {
+        throw new ShieldError("UNKNOWN", `unsupported ShieldProofCache version: ${parsed?.version}`);
+    }
+    return parsed;
+}
+/** Re-exported for callers that want the raw field arithmetic. */
+export { bytesToBigIntBE, BN254_FR_MODULUS };

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

@@ -0,0 +1,202 @@
+import { AddressLookupTableAccount, Connection, PublicKey, VersionedTransaction } from "@solana/web3.js";
+import type { TransactionProofBuilder, TransactionProofStruct } from "../proof.js";
+import type { CompactNoteCipher } from "../compactNote.js";
+/**
+ * Who owns the resulting note. Both halves are required and neither is derived
+ * from the other:
+ *
+ *  - `veiloPublicKey` is the Poseidon field element bound into the output
+ *    commitment. It is the **spending** authority.
+ *  - `noteViewingKey` is the Ed25519 wallet key the compact cipher is encrypted
+ *    to. It is the **detection** authority.
+ *
+ * If these two belong to different people, the note is *spendable but
+ * invisible*: the owner can never find it, so the funds are effectively gone.
+ * Nothing on-chain and nothing in this type can detect that — which is why
+ * `resolveShieldOwner()` exists and why hand-constructing this requires an
+ * explicit acknowledgement.
+ *
+ * See veilo-browser-extension/.../privateStealthWallet.ts:403-415 for the
+ * production comment describing this failure mode.
+ */
+export type ShieldOwner = {
+    veiloPublicKey: bigint;
+    noteViewingKey: PublicKey;
+    /**
+     * Set automatically by {@link resolveShieldOwner}, which fetches both halves
+     * from a single relayer response and can therefore guarantee they match.
+     *
+     * Hand-built owners must set this explicitly — it is the only mechanism
+     * standing between an integration mistake and silent fund loss.
+     */
+    acknowledgeOwnerInvariant?: true;
+};
+/**
+ * Who signs and pays. Public key only — the SDK never receives a secret key.
+ *
+ * The signer is unavoidably the fee payer, the funding source, and the payer of
+ * ~0.00192 SOL of nullifier-marker rent (the program hardcodes
+ * `payer = relayer` on both marker accounts). A wallet with no SOL cannot
+ * shield through this path regardless of who submits the transaction.
+ */
+export type ShieldSigner = {
+    publicKey: PublicKey;
+    /**
+     * Source token account for SPL shields. Defaults to the signer's canonical
+     * ATA. Must be owned by `publicKey` with no delegate set.
+     */
+    tokenAccount?: PublicKey;
+};
+/** Where the target tree and its root come from. */
+export interface TreeSource {
+    getDepositTarget(mint: PublicKey): Promise<DepositTarget>;
+}
+export type DepositTarget = {
+    /** Always 0 — the tree whose root the dummy inputs nominally prove against. */
+    inputTreeId: number;
+    /** 32-byte root, read from that tree's on-chain root history. */
+    inputRoot: Uint8Array;
+    /** Tree the new commitments are appended to. */
+    outputTreeId: number;
+    /** `nextIndex` at build time. A prediction — see `predictedLeafIndex`. */
+    outputNextIndex: number;
+};
+/** Where the address lookup table comes from. */
+export interface AltSource {
+    resolve(ctx: {
+        connection: Connection;
+        mint: PublicKey;
+        outputTreeId: number;
+        programId: PublicKey;
+    }): Promise<AddressLookupTableAccount>;
+}
+/**
+ * Caching for values that are stable across builds (the ALT account, rent
+ * exemption minimums, pool config).
+ *
+ * Deliberately an interface: the three production deposit implementations
+ * differ on exactly this axis — `localStorage`, `chrome.storage`, and
+ * `AsyncStorage` — and none of them belongs in a published SDK.
+ */
+export interface ShieldCachePort {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+}
+export type PreflightOptions = {
+    /** Skip the SPL token-account inspection (owner, delegate, balance). */
+    skipTokenAccount?: boolean;
+    /** Skip the signer balance check. */
+    skipBalance?: boolean;
+    /** Skip pool state checks (paused, min/max, tree capacity). */
+    skipPoolState?: boolean;
+};
+export type ShieldParams = {
+    connection: Connection;
+    /** Net amount to shield, in base units. No fee is taken on deposits. */
+    amount: bigint;
+    /** Defaults to native SOL. */
+    mint?: PublicKey;
+    owner: ShieldOwner;
+    signer: ShieldSigner;
+    /** Proof generation. `createTransactionProver(artifacts)` satisfies this. */
+    prover: TransactionProofBuilder;
+    treeSource?: TreeSource;
+    alt?: AltSource;
+    cache?: ShieldCachePort;
+    programId?: PublicKey;
+    computeUnitLimit?: number;
+    /** Set to 0 to omit the priority-fee instruction entirely. */
+    computeUnitPriceMicroLamports?: number;
+    deadlineSeconds?: number;
+    /** Supply to avoid an RPC round-trip; otherwise fetched just before compiling. */
+    blockhash?: {
+        blockhash: string;
+        lastValidBlockHeight: number;
+    };
+    preflight?: boolean | PreflightOptions;
+};
+/**
+ * The recoverable secret material for the note this shield creates.
+ *
+ * SECRET. Anyone holding this can locate the note. It must never be persisted
+ * server-side in the clear or transmitted alongside {@link ShieldProofCache},
+ * which is deliberately public.
+ */
+export type ShieldNote = {
+    commitment: Uint8Array;
+    blinding: bigint;
+    amount: bigint;
+    ownerVeiloPublicKey: bigint;
+    mint: PublicKey;
+    treeId: number;
+    compact: CompactNoteCipher;
+};
+/**
+ * Everything needed to re-assemble the transaction with a fresh blockhash.
+ *
+ * PUBLIC and JSON-serializable by construction: it carries no blinding, no
+ * private key, and no note plaintext. A platform can build server-side, ship
+ * this to a client for signature, and rebuild in a different process without
+ * ever moving a secret.
+ */
+export type ShieldProofCache = {
+    version: 1;
+    programId: string;
+    mint: string;
+    signer: string;
+    altAddress: string;
+    inputTreeId: number;
+    outputTreeId: number;
+    root: string;
+    publicAmount: string;
+    extData: {
+        recipient: string;
+        relayer: string;
+        fee: string;
+        refund: string;
+        claimant: string;
+    };
+    extDataHash: string;
+    inputNullifiers: [string, string];
+    outputCommitments: [string, string];
+    proof: TransactionProofStruct;
+    noteCiphers: {
+        note0EphemeralKey: string;
+        note0Encrypted: string;
+        note0ViewTag: number;
+        note1EphemeralKey: string;
+        note1Encrypted: string;
+        note1ViewTag: number;
+    };
+    /** Resolved instruction accounts, keyed by IDL account name. */
+    accounts: Record<string, string>;
+    computeUnitLimit: number;
+};
+export type ShieldQuote = {
+    /** Serialized size including the signature. Must be <= 1232. */
+    serializedSize: number;
+    computeUnitLimit: number;
+    computeUnitPriceMicroLamports: number;
+    estimatedFeeLamports: bigint;
+    /** Nullifier-marker rent, permanently burned by the signer. */
+    estimatedRentLamports: bigint;
+};
+export type ShieldResult = {
+    /** UNSIGNED. The caller signs and submits — this SDK never broadcasts. */
+    transaction: VersionedTransaction;
+    blockhash: string;
+    lastValidBlockHeight: number;
+    deadline: bigint;
+    note: ShieldNote;
+    /**
+     * Leaf index the output commitment is *expected* to land at.
+     *
+     * A prediction, read before submission. Under concurrent deposits into the
+     * same tree it will be wrong. Use `finalizeShield()` to read the authoritative
+     * index from the confirmed transaction's `CommitmentEvent` before persisting
+     * anything that depends on it.
+     */
+    predictedLeafIndex: number;
+    quote: ShieldQuote;
+    proofCache: ShieldProofCache;
+};