@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/cjs/shield/shield.js

@@ -0,0 +1,500 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BN254_FR_MODULUS = exports.bytesToBigIntBE = void 0;
+exports.shield = shield;
+exports.rebuild = rebuild;
+exports.serializeProofCache = serializeProofCache;
+exports.deserializeProofCache = deserializeProofCache;
+const web3_js_1 = require("@solana/web3.js");
+const spl_token_1 = require("@solana/spl-token");
+const program_js_1 = require("../program.js");
+const pdas_js_1 = require("../accounts/pdas.js");
+const config_js_1 = require("../config.js");
+const poseidon_js_1 = require("../poseidon.js");
+Object.defineProperty(exports, "bytesToBigIntBE", { enumerable: true, get: function () { return poseidon_js_1.bytesToBigIntBE; } });
+Object.defineProperty(exports, "BN254_FR_MODULUS", { enumerable: true, get: function () { return poseidon_js_1.BN254_FR_MODULUS; } });
+const merkle_js_1 = require("../merkle.js");
+const model_js_1 = require("../notes/model.js");
+const transaction_js_1 = require("../proofs/transaction.js");
+const encoding_js_1 = require("../proofs/encoding.js");
+const compactNote_js_1 = require("../compactNote.js");
+const ix_js_1 = require("./ix.js");
+const alt_js_1 = require("./alt.js");
+const ports_js_1 = require("./ports.js");
+const preflight_js_1 = require("./preflight.js");
+const errors_js_1 = require("./errors.js");
+const computeBudget_js_1 = require("./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.
+ */
+async function shield(params) {
+    const { connection, amount, owner, signer, prover, mint = config_js_1.NATIVE_SOL_MINT, programId = program_js_1.PRIVACY_POOL_PROGRAM_ID, computeUnitLimit = computeBudget_js_1.SHIELD_COMPUTE_UNIT_LIMIT, computeUnitPriceMicroLamports = computeBudget_js_1.SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS, deadlineSeconds = computeBudget_js_1.DEFAULT_DEADLINE_SECONDS, } = params;
+    if (amount <= 0n) {
+        throw new errors_js_1.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 errors_js_1.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 ?? (0, ports_js_1.memoryCache)();
+    const treeSource = params.treeSource ?? (0, ports_js_1.onChainTreeSource)(connection, programId);
+    const altSource = params.alt ?? (0, alt_js_1.sharedDepositAlt)(undefined, { cache });
+    const isToken = !mint.equals(config_js_1.NATIVE_SOL_MINT);
+    const userTokenAccount = isToken
+        ? (signer.tokenAccount ?? (await (0, spl_token_1.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 (0, preflight_js_1.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 ** config_js_1.MERKLE_TREE_DEPTH;
+    if (target.outputNextIndex >= treeCapacity) {
+        throw new errors_js_1.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 = (0, model_js_1.createUTXO)({
+        amount,
+        pubkey: owner.veiloPublicKey,
+        mintAddress: mint,
+    });
+    const dummyOutput = (0, model_js_1.createUTXO)({
+        amount: 0n,
+        pubkey: (0, model_js_1.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 = (0, merkle_js_1.poseidonZeroChain)(22).slice(0, 22);
+    const dummyInputs = [
+        toDummyInput((0, model_js_1.createOwnedZeroUTXO)((0, model_js_1.generateKeypair)().privateKey, mint), zeroChain),
+        toDummyInput((0, model_js_1.createOwnedZeroUTXO)((0, model_js_1.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: web3_js_1.SystemProgram.programId,
+    };
+    const extDataHash = (0, transaction_js_1.computeExtDataHash)(extData);
+    // --- 6. Prove --------------------------------------------------------------
+    const circuitInputs = (0, transaction_js_1.prepareTransactionInputs)({
+        inputUTXOs: dummyInputs,
+        outputUTXOs: [outputNote, dummyOutput],
+        root: target.inputRoot,
+        publicAmount: amount,
+        extData,
+        mintAddress: mint,
+    });
+    let proof;
+    try {
+        proof = (0, encoding_js_1.encodeSnarkjsProofToTransactionProof)(await prover(circuitInputs));
+    }
+    catch (e) {
+        throw (0, errors_js_1.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 = (0, compactNote_js_1.createCompactNoteCipher)(owner.noteViewingKey.toBytes(), (0, poseidon_js_1.bigIntToBytesBE)(outputNote.blinding), amount);
+    const empty = (0, compactNote_js_1.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 (0, spl_token_1.getAssociatedTokenAddress)(mint, (0, pdas_js_1.getPoolPdas)(programId, mint).vault, true)
+            : (0, pdas_js_1.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.
+ */
+async function rebuild(result, opts = {}) {
+    const cache = result.proofCache;
+    const blockhash = opts.blockhash ??
+        (opts.connection
+            ? await opts.connection.getLatestBlockhash("confirmed")
+            : (() => {
+                throw new errors_js_1.ShieldError("UNKNOWN", "rebuild() needs either a `connection` or an explicit `blockhash`");
+            })());
+    const alt = opts.alt ??
+        (opts.connection
+            ? await (0, alt_js_1.sharedDepositAlt)(new web3_js_1.PublicKey(cache.altAddress), {
+                verifyCoverage: false,
+            }).resolve({
+                connection: opts.connection,
+                mint: new web3_js_1.PublicKey(cache.mint),
+                outputTreeId: cache.outputTreeId,
+                programId: new web3_js_1.PublicKey(cache.programId),
+            })
+            : (() => {
+                throw new errors_js_1.ShieldError("UNKNOWN", "rebuild() needs either a `connection` or an explicit `alt`");
+            })());
+    const deadline = BigInt(Math.floor(Date.now() / 1000) + (opts.deadlineSeconds ?? computeBudget_js_1.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 web3_js_1.PublicKey(cache.programId);
+    const signer = new web3_js_1.PublicKey(cache.signer);
+    const accounts = Object.fromEntries(Object.entries(cache.accounts).map(([k, v]) => [k, new web3_js_1.PublicKey(v)]));
+    const transactIx = (0, ix_js_1.buildTransactInstruction)(accounts, {
+        root: unhex(cache.root),
+        inputTreeId: cache.inputTreeId,
+        outputTreeId: cache.outputTreeId,
+        publicAmount: BigInt(cache.publicAmount),
+        extDataHash: unhex(cache.extDataHash),
+        mintAddress: new web3_js_1.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 web3_js_1.PublicKey(cache.extData.recipient),
+            relayer: new web3_js_1.PublicKey(cache.extData.relayer),
+            fee: BigInt(cache.extData.fee),
+            refund: BigInt(cache.extData.refund),
+            claimant: new web3_js_1.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 = [
+        web3_js_1.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(web3_js_1.ComputeBudgetProgram.setComputeUnitPrice({
+            microLamports: computeUnitPriceMicroLamports,
+        }));
+    }
+    instructions.push(transactIx);
+    const message = new web3_js_1.TransactionMessage({
+        payerKey: signer,
+        recentBlockhash: blockhash.blockhash,
+        instructions,
+    }).compileToV0Message([alt]);
+    const transaction = new web3_js_1.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) + computeBudget_js_1.SIGNATURE_BYTES;
+    if (serializedSize > computeBudget_js_1.MAX_TRANSACTION_BYTES) {
+        const staticKeys = message.staticAccountKeys.map((k) => k.toBase58());
+        const inAlt = new Set(alt.state.addresses.map((a) => a.toBase58()));
+        throw new errors_js_1.ShieldError("TX_TOO_LARGE", `Shield transaction is ${serializedSize} bytes, over the ${computeBudget_js_1.MAX_TRANSACTION_BYTES} ` +
+            `limit by ${serializedSize - computeBudget_js_1.MAX_TRANSACTION_BYTES}. ` +
+            `${staticKeys.length} account(s) could not be compressed into the lookup table.`, {
+            context: {
+                serializedSize,
+                limit: computeBudget_js_1.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 } = (0, pdas_js_1.getPoolPdas)(programId, mint);
+    return {
+        config,
+        global_config: (0, pdas_js_1.getGlobalConfigPda)(programId),
+        vault,
+        input_tree: (0, pdas_js_1.getNoteTreePda)(programId, mint, params.inputTreeId),
+        output_tree: (0, pdas_js_1.getNoteTreePda)(programId, mint, params.outputTreeId),
+        nullifiers,
+        nullifier_marker_0: (0, pdas_js_1.getNullifierMarkerPda)(programId, mint, params.inputNullifiers[0]),
+        nullifier_marker_1: (0, pdas_js_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 ? spl_token_1.TOKEN_PROGRAM_ID : web3_js_1.SystemProgram.programId,
+        system_program: web3_js_1.SystemProgram.programId,
+    };
+}
+async function rentForNullifierMarkers(connection, cache) {
+    const key = `rent:${computeBudget_js_1.NULLIFIER_MARKER_ACCOUNT_BYTES}`;
+    let per = await cache.get(key);
+    if (per === undefined) {
+        per = await connection.getMinimumBalanceForRentExemption(computeBudget_js_1.NULLIFIER_MARKER_ACCOUNT_BYTES);
+        await cache.set(key, per, 60 * 60000);
+    }
+    return BigInt(per) * BigInt(computeBudget_js_1.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. */
+function serializeProofCache(cache) {
+    return JSON.stringify(cache);
+}
+function deserializeProofCache(json) {
+    const parsed = JSON.parse(json);
+    if (parsed?.version !== 1) {
+        throw new errors_js_1.ShieldError("UNKNOWN", `unsupported ShieldProofCache version: ${parsed?.version}`);
+    }
+    return parsed;
+}