@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/cjs/shield/preflight.d.ts

@@ -0,0 +1,30 @@
+import { Connection, PublicKey } from "@solana/web3.js";
+import type { PreflightOptions, ShieldCachePort } from "./types.js";
+/**
+ * Checks that run before the prover.
+ *
+ * Proving costs 10–30 seconds. Every check here is a single RPC call, and each
+ * one pre-empts an on-chain failure whose message tells the user nothing they
+ * can act on. The delegate check is the clearest example: the program requires
+ * `user_token.delegate.is_none()`, so anyone who ever approved a DEX has a
+ * permanently broken deposit path that reports only "Invalid token account
+ * authority" — with no hint that revoking a delegate would fix it.
+ *
+ * These are advisory in the sense that the chain enforces them anyway. They are
+ * not advisory in the sense that skipping them produces a materially worse
+ * product.
+ */
+export declare function preflightShield(params: {
+    connection: Connection;
+    amount: bigint;
+    mint: PublicKey;
+    signer: {
+        publicKey: PublicKey;
+        tokenAccount: PublicKey;
+    };
+    programId?: PublicKey;
+    options?: PreflightOptions;
+    cache?: ShieldCachePort;
+    computeUnitLimit?: number;
+    computeUnitPriceMicroLamports?: number;
+}): Promise<void>;

package/dist/cjs/shield/preflight.js

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

package/dist/cjs/shield/shield.d.ts

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