@veilo/sdk-core 0.3.3 → 0.4.0

package/dist/src/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 utxo_js_1 = require("../utxo.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, utxo_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,
+    };
+}

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

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

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

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

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

package/dist/src/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/src/shield/owner.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveShieldOwner = resolveShieldOwner;
+exports.unsafeShieldOwner = unsafeShieldOwner;
+const web3_js_1 = require("@solana/web3.js");
+const relayer_js_1 = require("../relayer.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Owner resolution is a Veilo protocol service, not an integrator-selected
+ * transport. Keep the production endpoint and public encryption key inside the
+ * SDK so callers cannot accidentally resolve the two owner keys from different
+ * relayers.
+ *
+ * These values are public network coordinates, not credentials. In particular,
+ * never put a secret API key here: browser/mobile package contents are always
+ * inspectable. The two owner endpoints used below are intentionally public and
+ * return public key material only.
+ */
+const OWNER_RELAYER = new relayer_js_1.VeiloRelayerClient({
+    apiKey: "",
+    relayerPublicKey: "utVxnA7zax09qJCZ7UJsa8PAOoWLRcCwOkdxg/ZGmD4=",
+});
+/**
+ * Resolve a shield recipient into the pair of keys that must belong to the same
+ * account.
+ *
+ * This is the only mechanism that makes the owner invariant safe. A note's
+ * *spend* authority is a Poseidon field element and its *detection* authority is
+ * an Ed25519 wallet key; nothing on-chain relates them, and if an integrator
+ * sources them separately and gets them wrong, the note is spendable but
+ * permanently invisible — the funds are gone from the owner's view with no error
+ * raised anywhere in the stack.
+ *
+ * `GET /auth/veiloPublicKey` returns both halves in a single response, so
+ * routing through this function makes the pairing structural rather than a
+ * convention integrators are asked to remember.
+ *
+ * Prefer this over hand-building a {@link ShieldOwner} in all cases.
+ */
+async function resolveShieldOwner(target) {
+    const query = "username" in target
+        ? { username: target.username }
+        : {
+            publicKey: typeof target.publicKey === "string"
+                ? target.publicKey
+                : target.publicKey.toBase58(),
+        };
+    let response;
+    try {
+        response = await OWNER_RELAYER.getVeiloPublicKey(query);
+    }
+    catch (e) {
+        // A raw Solana address may not have a Veilo account yet. Provisioning is
+        // public and idempotent, and returns only the Poseidon spend key; the
+        // address we were given is the matching note-viewing key.
+        if ("publicKey" in target &&
+            (e?.status === 404 || (e instanceof relayer_js_1.VeiloApiError && e.status === 404))) {
+            const wallet = typeof target.publicKey === "string"
+                ? new web3_js_1.PublicKey(target.publicKey)
+                : target.publicKey;
+            const provisioned = await OWNER_RELAYER.preRegisterKey(wallet.toBase58());
+            if (!provisioned?.veiloPublicKey) {
+                throw new errors_js_1.ShieldError("UNKNOWN", "The relayer pre-registered the recipient but returned no Veilo public key.", { context: { publicKey: wallet.toBase58(), response: provisioned }, cause: e });
+            }
+            return {
+                veiloPublicKey: BigInt(provisioned.veiloPublicKey),
+                noteViewingKey: wallet,
+                acknowledgeOwnerInvariant: true,
+            };
+        }
+        // A pre-registered account is one someone else created on the recipient's
+        // behalf; the recipient has never proved ownership, so the relayer refuses
+        // to resolve it by username. Shielding to them still works, but the caller
+        // must address them by Solana address instead.
+        if (e?.body?.preRegistered ||
+            e?.details?.preRegistered ||
+            /preregistered/i.test(String(e?.message ?? ""))) {
+            throw new errors_js_1.ShieldError("UNKNOWN", `"${"username" in target ? target.username : "that account"}" is pre-registered ` +
+                `and cannot be resolved by username. Resolve it by Solana address instead — ` +
+                `resolveShieldOwner({ publicKey }).`, { context: { preRegistered: true }, cause: e });
+        }
+        throw e;
+    }
+    const veiloPublicKeyRaw = response?.veiloPublicKey;
+    const walletRaw = response?.pubK;
+    if (!veiloPublicKeyRaw || !walletRaw) {
+        throw new errors_js_1.ShieldError("UNKNOWN", `The relayer did not return both keys for this recipient ` +
+            `(veiloPublicKey=${!!veiloPublicKeyRaw}, pubK=${!!walletRaw}). ` +
+            `Shielding without both would create a note the owner cannot find.`, { context: { response } });
+    }
+    const noteViewingKey = new web3_js_1.PublicKey(walletRaw);
+    if ("publicKey" in target &&
+        !noteViewingKey.equals(typeof target.publicKey === "string"
+            ? new web3_js_1.PublicKey(target.publicKey)
+            : target.publicKey)) {
+        throw new errors_js_1.ShieldError("UNKNOWN", "The Veilo owner service returned a different wallet than the one requested. " +
+            "Shielding was stopped to prevent creating a note for the wrong recipient.", {
+            context: {
+                requested: typeof target.publicKey === "string"
+                    ? target.publicKey
+                    : target.publicKey.toBase58(),
+                returned: noteViewingKey.toBase58(),
+            },
+        });
+    }
+    return {
+        veiloPublicKey: BigInt(veiloPublicKeyRaw),
+        noteViewingKey,
+        // Safe to assert: both halves came from one response about one account.
+        acknowledgeOwnerInvariant: true,
+    };
+}
+/**
+ * Build a {@link ShieldOwner} from keys the caller already holds.
+ *
+ * Only correct when both keys provably belong to the same account. The explicit
+ * flag is not ceremony — it is the last checkpoint before a class of bug whose
+ * only symptom is a user's money quietly disappearing from their balance.
+ */
+function unsafeShieldOwner(params) {
+    return {
+        veiloPublicKey: params.veiloPublicKey,
+        noteViewingKey: params.noteViewingKey,
+        acknowledgeOwnerInvariant: true,
+    };
+}

package/dist/src/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;