@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/esm/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/esm/shield/errors.js

@@ -0,0 +1,115 @@
+import { parseOnChainError } from "../accounts/errors.js";
+export 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;
+    }
+}
+/** Extract a privacy_pool program error code from an arbitrary thrown value. */
+export 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.
+ */
+export 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 = 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/esm/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/esm/shield/finalize.js

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

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

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

package/dist/esm/shield/index.js

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

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

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

package/dist/esm/shield/ix.js

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

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

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