@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/esm/relayer.js

@@ -1,238 +1,2 @@
-import nacl from "tweetnacl";
-// =============================================================================
-// Structured Error
-// =============================================================================
-/** Structured error thrown by VeiloRelayerClient on API failures. */
-export class VeiloApiError extends Error {
-    constructor(code, message, status) {
-        super(message);
-        this.name = "VeiloApiError";
-        this.code = code;
-        this.status = status;
-    }
-}
-const DEFAULT_RETRY = {
-    maxRetries: 3,
-    baseDelayMs: 1000,
-    retryableStatuses: [429, 502, 503, 504],
-};
-// =============================================================================
-// Base64 helpers (no dependency on tweetnacl-util)
-// =============================================================================
-function toBase64(bytes) {
-    if (typeof Buffer !== "undefined") {
-        return Buffer.from(bytes).toString("base64");
-    }
-    return btoa(String.fromCharCode(...bytes));
-}
-function fromBase64(str) {
-    if (typeof Buffer !== "undefined") {
-        return new Uint8Array(Buffer.from(str, "base64"));
-    }
-    const binary = atob(str);
-    const bytes = new Uint8Array(binary.length);
-    for (let i = 0; i < binary.length; i++)
-        bytes[i] = binary.charCodeAt(i);
-    return bytes;
-}
-// =============================================================================
-// Encryption
-// =============================================================================
-/**
- * Encrypt a JSON-serializable payload for the relayer using NaCl box.
- * Layout: [ephemeralPubKey (32)] [nonce (24)] [ciphertext (...)]
- */
-function encryptForRelayer(data, relayerPublicKey) {
-    const ephemeral = nacl.box.keyPair();
-    const message = new TextEncoder().encode(JSON.stringify(data));
-    const nonce = nacl.randomBytes(nacl.box.nonceLength);
-    const ciphertext = nacl.box(message, nonce, relayerPublicKey, ephemeral.secretKey);
-    const payload = new Uint8Array(ephemeral.publicKey.length + nonce.length + ciphertext.length);
-    payload.set(ephemeral.publicKey, 0);
-    payload.set(nonce, ephemeral.publicKey.length);
-    payload.set(ciphertext, ephemeral.publicKey.length + nonce.length);
-    return toBase64(payload);
-}
-// =============================================================================
-// Relayer Client
-// =============================================================================
-/**
- * HTTP client for the Veilo relayer API.
- *
- * Handles auth, notes, merkle, and encrypted transact endpoints with
- * automatic retry on transient failures and NaCl box payload encryption.
- *
- * @example
- * ```ts
- * const client = new VeiloRelayerClient({
- *   relayerUrl: "https://relayer.veilo.io",
- *   apiKey: "your-api-key",
- *   relayerPublicKey: "<base64 NaCl public key>",
- * });
- * const root = await client.getMerkleRoot("So111...");
- * ```
- */
-export class VeiloRelayerClient {
-    constructor(config, retry) {
-        this.baseUrl = config.relayerUrl.replace(/\/+$/, "");
-        this.apiKey = config.apiKey;
-        this.relayerPubKey = fromBase64(config.relayerPublicKey);
-        this.authToken = config.authToken;
-        this.retry = { ...DEFAULT_RETRY, ...retry };
-    }
-    /** Update the auth token (e.g. after register/restore). */
-    setAuthToken(token) {
-        this.authToken = token;
-    }
-    // ---------------------------------------------------------------------------
-    // Internal helpers
-    // ---------------------------------------------------------------------------
-    headers(authenticated) {
-        const h = {
-            "Content-Type": "application/json",
-            "x-api-key": this.apiKey,
-        };
-        if (authenticated && this.authToken) {
-            h["Authorization"] = `Bearer ${this.authToken}`;
-        }
-        return h;
-    }
-    async request(method, path, opts = {}) {
-        const url = `${this.baseUrl}/api${path}`;
-        const { body, authenticated = false, retryable = true } = opts;
-        const maxAttempts = retryable ? this.retry.maxRetries + 1 : 1;
-        let lastError;
-        for (let attempt = 0; attempt < maxAttempts; attempt++) {
-            if (attempt > 0) {
-                const delay = this.retry.baseDelayMs * Math.pow(2, attempt - 1) +
-                    Math.random() * 200;
-                await new Promise((r) => setTimeout(r, delay));
-            }
-            let res;
-            try {
-                res = await fetch(url, {
-                    method,
-                    headers: this.headers(authenticated),
-                    body: body != null ? JSON.stringify(body) : undefined,
-                });
-            }
-            catch (err) {
-                lastError = new VeiloApiError("NETWORK_ERROR", err.message || "Network request failed", 0);
-                continue;
-            }
-            const data = await res.json().catch(() => ({}));
-            if (res.ok && data.success !== false) {
-                return data;
-            }
-            lastError = new VeiloApiError(data.error || "UNKNOWN", data.message || data.error || `Request failed: ${res.status}`, res.status);
-            // Only retry on transient statuses
-            if (!this.retry.retryableStatuses.includes(res.status)) {
-                throw lastError;
-            }
-        }
-        throw lastError;
-    }
-    encrypt(data) {
-        return encryptForRelayer({
-            ...data,
-            timestamp: Date.now(),
-            nonce: toBase64(nacl.randomBytes(32)),
-        }, this.relayerPubKey);
-    }
-    // ---------------------------------------------------------------------------
-    // Auth
-    // ---------------------------------------------------------------------------
-    /** Request a signature challenge for wallet authentication. */
-    async getChallenge(walletPublicKey) {
-        return this.request("POST", "/auth/challenge", {
-            body: { walletPublicKey },
-        });
-    }
-    /** Register a new account with a signed challenge. Returns a JWT auth token. */
-    async register(data) {
-        return this.request("POST", "/auth/register", { body: data });
-    }
-    /** Restore an existing account using a signed challenge. Returns a JWT auth token. */
-    async restore(data) {
-        return this.request("POST", "/auth/restore", { body: data });
-    }
-    /** Check whether a username is available for registration. */
-    async checkUsername(username) {
-        return this.request("GET", `/auth/checkUsername?username=${encodeURIComponent(username)}`);
-    }
-    /** Look up a user's Veilo public key by username or wallet public key. */
-    async getVeiloPublicKey(params) {
-        const query = "username" in params && params.username
-            ? `username=${encodeURIComponent(params.username)}`
-            : `publicKey=${encodeURIComponent(params.publicKey)}`;
-        return this.request("GET", `/auth/veiloPublicKey?${query}`);
-    }
-    // ---------------------------------------------------------------------------
-    // Notes
-    // ---------------------------------------------------------------------------
-    /** Save an encrypted note to the relayer's database. */
-    async saveEncryptedNote(data) {
-        return this.request("POST", "/notes/save", { body: data });
-    }
-    /** Query encrypted notes for the authenticated user. Requires auth token. */
-    async queryEncryptedNotes(params = {}) {
-        return this.request("POST", "/notes/query", {
-            body: params,
-            authenticated: true,
-        });
-    }
-    /** Delete all stored data for the authenticated user. Requires auth token. */
-    async deleteUserData() {
-        return this.request("POST", "/notes/delete", { authenticated: true });
-    }
-    // ---------------------------------------------------------------------------
-    // Merkle
-    // ---------------------------------------------------------------------------
-    /** Fetch the current Merkle root for a pool, optionally filtered by mint and tree ID. */
-    async getMerkleRoot(mintAddress, treeId) {
-        const params = new URLSearchParams();
-        if (mintAddress)
-            params.append("mintAddress", mintAddress);
-        if (treeId !== undefined)
-            params.append("treeId", treeId.toString());
-        const qs = params.toString();
-        return this.request("GET", `/merkle/root${qs ? `?${qs}` : ""}`);
-    }
-    /** Fetch the full Merkle tree (all leaves) for a pool. */
-    async getMerkleTree(mintAddress, treeId) {
-        const params = new URLSearchParams();
-        if (mintAddress)
-            params.append("mintAddress", mintAddress);
-        if (treeId !== undefined)
-            params.append("treeId", treeId.toString());
-        const qs = params.toString();
-        return this.request("GET", `/merkle/tree${qs ? `?${qs}` : ""}`);
-    }
-    // ---------------------------------------------------------------------------
-    // Transact (encrypted payloads)
-    // ---------------------------------------------------------------------------
-    /** Submit an encrypted withdrawal request to the relayer. Not retried on failure. */
-    async submitWithdraw(data) {
-        const encryptedPayload = this.encrypt(data);
-        return this.request("POST", "/transact/withdra", {
-            body: { encryptedPayload },
-            retryable: false,
-        });
-    }
-    /** Submit an encrypted private transfer request. Not retried on failure. */
-    async submitPrivateTransfer(data) {
-        const encryptedPayload = this.encrypt(data);
-        return this.request("POST", "/transact/private-transfer", {
-            body: { encryptedPayload },
-            retryable: false,
-        });
-    }
-    /** Submit an encrypted private swap request. Not retried on failure. */
-    async submitPrivateSwap(data) {
-        const encryptedPayload = this.encrypt(data);
-        return this.request("POST", "/transact/private-swap", {
-            body: { encryptedPayload },
-            retryable: false,
-        });
-    }
-}
+// Backward-compatible entry point. Relayer responsibilities live in src/relayer.
+export * from "./relayer/index.js";

package/dist/esm/retry.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Configuration for retry behavior on Solana RPC calls.
+ */
+export interface RpcRetryPolicy {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    baseDelayMs: number;
+    /** Maximum delay cap in ms (default: 10000) */
+    maxDelayMs: number;
+}
+export declare const DEFAULT_RPC_RETRY: RpcRetryPolicy;
+/**
+ * Execute an async function with retries on transient RPC failures.
+ *
+ * Retries on: BlockhashNotFound, HTTP 429/502/503/504, timeouts, connection resets.
+ * Does NOT retry on: program errors (6xxx), signature verification failures, or other
+ * deterministic errors that would fail again.
+ *
+ * @param fn      The async operation to execute
+ * @param policy  Retry configuration (uses sensible defaults if omitted)
+ * @returns       The result of the async operation
+ *
+ * @example
+ * ```ts
+ * const txSig = await withRpcRetry(
+ *   () => program.methods.transact(...).accounts({...}).signers([...]).rpc(),
+ *   { maxRetries: 5 },
+ * );
+ * ```
+ */
+export declare function withRpcRetry<T>(fn: () => Promise<T>, policy?: Partial<RpcRetryPolicy>): Promise<T>;

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

@@ -0,0 +1,87 @@
+import { AddressLookupTableAccount, Connection, PublicKey } from "@solana/web3.js";
+import type { AltSource, ShieldCachePort } from "./types.js";
+/**
+ * Address lookup table handling for the shield path.
+ *
+ * The ALT is not an optimisation here — it is load-bearing. A `transact` carries
+ * 847 bytes of instruction data across 16 accounts, which is ~1500 bytes as a
+ * legacy transaction and therefore unlandable. Compressing the constant pool
+ * accounts to 1-byte indices is what brings it to ~1163 and leaves room for
+ * Phantom's Lighthouse guard instructions.
+ */
+/**
+ * The shared, team-owned deposit table.
+ *
+ * Deliberately shared rather than per-wallet: creating a per-wallet table costs
+ * the signer an extra signature and unrecoverable rent, which is unacceptable to
+ * ask of an external wallet shielding once, and impossible to ask of a
+ * third-party platform's managed wallet.
+ */
+export declare const SHARED_DEPOSIT_ALT: PublicKey;
+/** Mints the shared table is provisioned for. */
+export declare const SHARED_ALT_MINTS: {
+    symbol: string;
+    mint: PublicKey;
+}[];
+/**
+ * Load the shared table, and verify it actually covers this shield.
+ *
+ * The verification is the important part. Coverage is an *operational* property,
+ * not a code property: the table is populated by a script, and if a mint or a
+ * tree is missing, every one of its accounts falls back to a 32-byte static key
+ * and the transaction silently grows past 1232. Failing here with a list of the
+ * missing addresses is far better than failing at `signTransaction` with
+ * "transaction too large" and no indication why.
+ */
+export declare function sharedDepositAlt(address?: PublicKey, opts?: {
+    cache?: ShieldCachePort;
+    verifyCoverage?: boolean;
+}): AltSource;
+/** Use a table the caller already loaded. Skips both the RPC call and the coverage check. */
+export declare function explicitAlt(account: AddressLookupTableAccount): AltSource;
+type NamedKey = {
+    label: string;
+    address: PublicKey;
+};
+/**
+ * Accounts that must be in the table for a shield of `mint` into `outputTreeId`
+ * to fit.
+ *
+ * The signer, the two nullifier markers, and the user's token account are
+ * deliberately excluded: markers are unique per transaction and the others are
+ * per-user, so none can live in a shared table. They are the static keys the
+ * size budget accounts for.
+ */
+export declare function requiredAltKeys(params: {
+    mint: PublicKey;
+    outputTreeId: number;
+    programId?: PublicKey;
+}): NamedKey[];
+/**
+ * Everything the shared table should contain across every supported mint and
+ * every tree up to `maxTreeId`.
+ *
+ * Exported so this can be asserted in CI. The table currently only covers tree 0
+ * per mint, which means the size budget quietly loses 32 bytes of headroom the
+ * day tree 0 fills and `getBestTreeForDeposit` starts returning tree 1. That is
+ * a scheduled failure, and this function is how it gets caught before a user
+ * finds it.
+ */
+export declare function expectedDepositAltKeys(params: {
+    mints?: PublicKey[];
+    maxTreeId?: number;
+    programId?: PublicKey;
+}): Promise<NamedKey[]>;
+/** Diff the on-chain table against {@link expectedDepositAltKeys}. */
+export declare function auditDepositAlt(connection: Connection, params?: {
+    address?: PublicKey;
+    mints?: PublicKey[];
+    maxTreeId?: number;
+    programId?: PublicKey;
+}): Promise<{
+    ok: boolean;
+    present: number;
+    missing: NamedKey[];
+    extra: string[];
+}>;
+export {};

package/dist/esm/shield/alt.js

@@ -0,0 +1,186 @@
+import { ComputeBudgetProgram, PublicKey, SystemProgram, } from "@solana/web3.js";
+import { TOKEN_PROGRAM_ID, getAssociatedTokenAddress, getAssociatedTokenAddressSync, } from "@solana/spl-token";
+import { getGlobalConfigPda, getNoteTreePda, getPoolPdas, } from "../accounts/pdas.js";
+import { PRIVACY_POOL_PROGRAM_ID } from "../program.js";
+import { NATIVE_SOL_MINT } from "../config.js";
+import { ShieldError } from "./errors.js";
+/**
+ * Address lookup table handling for the shield path.
+ *
+ * The ALT is not an optimisation here — it is load-bearing. A `transact` carries
+ * 847 bytes of instruction data across 16 accounts, which is ~1500 bytes as a
+ * legacy transaction and therefore unlandable. Compressing the constant pool
+ * accounts to 1-byte indices is what brings it to ~1163 and leaves room for
+ * Phantom's Lighthouse guard instructions.
+ */
+/**
+ * The shared, team-owned deposit table.
+ *
+ * Deliberately shared rather than per-wallet: creating a per-wallet table costs
+ * the signer an extra signature and unrecoverable rent, which is unacceptable to
+ * ask of an external wallet shielding once, and impossible to ask of a
+ * third-party platform's managed wallet.
+ */
+export const SHARED_DEPOSIT_ALT = new PublicKey("3x2JxCgAPmv4U4EJonFBntm1q4W3xzpnB6aT1tCvxftk");
+/** Mints the shared table is provisioned for. */
+export const SHARED_ALT_MINTS = [
+    { symbol: "SOL", mint: NATIVE_SOL_MINT },
+    { symbol: "USDC", mint: new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v") },
+    { symbol: "USDT", mint: new PublicKey("Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB") },
+    { symbol: "USD1", mint: new PublicKey("USD1ttGY1N17NEEHLmELoaybftRBUSErhqYiQzvEmuB") },
+    { symbol: "JUP", mint: new PublicKey("JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN") },
+    { symbol: "ARX", mint: new PublicKey("ARXwZkNAtzPfdcoqQiduJn8EPv9fKiDfGn2KyggyDrFs") },
+];
+const ALT_CACHE_TTL_MS = 10 * 60000;
+/**
+ * Load the shared table, and verify it actually covers this shield.
+ *
+ * The verification is the important part. Coverage is an *operational* property,
+ * not a code property: the table is populated by a script, and if a mint or a
+ * tree is missing, every one of its accounts falls back to a 32-byte static key
+ * and the transaction silently grows past 1232. Failing here with a list of the
+ * missing addresses is far better than failing at `signTransaction` with
+ * "transaction too large" and no indication why.
+ */
+export function sharedDepositAlt(address = SHARED_DEPOSIT_ALT, opts = {}) {
+    return {
+        async resolve({ connection, mint, outputTreeId, programId }) {
+            const key = `alt:${address.toBase58()}`;
+            let account = await opts.cache?.get(key);
+            if (!account) {
+                // "finalized" so every RPC the signer's wallet might simulate against
+                // has already seen the table. A table read at "processed" can be
+                // invisible to the wallet's own simulator.
+                const res = await connection.getAddressLookupTable(address, {
+                    commitment: "finalized",
+                });
+                if (!res.value) {
+                    throw new ShieldError("ALT_NOT_FOUND", `Deposit address lookup table ${address.toBase58()} was not found at ` +
+                        `finalized commitment. Without it a shield cannot fit in 1232 bytes.`, { context: { address: address.toBase58() } });
+                }
+                account = res.value;
+                await opts.cache?.set(key, account, ALT_CACHE_TTL_MS);
+            }
+            if (opts.verifyCoverage !== false) {
+                const missing = missingCoverage(account, {
+                    mint,
+                    outputTreeId,
+                    programId,
+                });
+                if (missing.length > 0) {
+                    throw new ShieldError("ALT_INCOMPLETE", `The deposit lookup table does not cover this shield: ${missing.length} ` +
+                        `required account(s) are absent, so the transaction would exceed 1232 ` +
+                        `bytes. Extend the table before shielding this mint/tree.`, {
+                        context: {
+                            alt: address.toBase58(),
+                            mint: mint.toBase58(),
+                            outputTreeId,
+                            missing: missing.map((m) => `${m.label} (${m.address.toBase58()})`),
+                        },
+                    });
+                }
+            }
+            return account;
+        },
+    };
+}
+/** Use a table the caller already loaded. Skips both the RPC call and the coverage check. */
+export function explicitAlt(account) {
+    return { async resolve() { return account; } };
+}
+/**
+ * Accounts that must be in the table for a shield of `mint` into `outputTreeId`
+ * to fit.
+ *
+ * The signer, the two nullifier markers, and the user's token account are
+ * deliberately excluded: markers are unique per transaction and the others are
+ * per-user, so none can live in a shared table. They are the static keys the
+ * size budget accounts for.
+ */
+export function requiredAltKeys(params) {
+    const programId = params.programId ?? PRIVACY_POOL_PROGRAM_ID;
+    const { config, vault, nullifiers } = getPoolPdas(programId, params.mint);
+    const keys = [
+        { label: "programId", address: programId },
+        { label: "computeBudgetProgram", address: ComputeBudgetProgram.programId },
+        { label: "systemProgram", address: SystemProgram.programId },
+        { label: "globalConfig", address: getGlobalConfigPda(programId) },
+        { label: "config", address: config },
+        { label: "vault", address: vault },
+        { label: "nullifiers", address: nullifiers },
+        { label: "inputTree(0)", address: getNoteTreePda(programId, params.mint, 0) },
+    ];
+    if (params.outputTreeId !== 0) {
+        keys.push({
+            label: `outputTree(${params.outputTreeId})`,
+            address: getNoteTreePda(programId, params.mint, params.outputTreeId),
+        });
+    }
+    if (!params.mint.equals(NATIVE_SOL_MINT)) {
+        keys.push({ label: "tokenProgram", address: TOKEN_PROGRAM_ID }, {
+            label: "vaultAta",
+            address: getAssociatedTokenAddressSync(params.mint, vault, true),
+        });
+    }
+    return keys;
+}
+function missingCoverage(account, params) {
+    const present = new Set(account.state.addresses.map((a) => a.toBase58()));
+    return requiredAltKeys(params).filter((k) => !present.has(k.address.toBase58()));
+}
+/**
+ * Everything the shared table should contain across every supported mint and
+ * every tree up to `maxTreeId`.
+ *
+ * Exported so this can be asserted in CI. The table currently only covers tree 0
+ * per mint, which means the size budget quietly loses 32 bytes of headroom the
+ * day tree 0 fills and `getBestTreeForDeposit` starts returning tree 1. That is
+ * a scheduled failure, and this function is how it gets caught before a user
+ * finds it.
+ */
+export async function expectedDepositAltKeys(params) {
+    const programId = params.programId ?? PRIVACY_POOL_PROGRAM_ID;
+    const mints = params.mints ?? SHARED_ALT_MINTS.map((m) => m.mint);
+    const maxTreeId = params.maxTreeId ?? 4;
+    const out = [
+        { label: "programId", address: programId },
+        { label: "computeBudgetProgram", address: ComputeBudgetProgram.programId },
+        { label: "systemProgram", address: SystemProgram.programId },
+        { label: "tokenProgram", address: TOKEN_PROGRAM_ID },
+        { label: "globalConfig", address: getGlobalConfigPda(programId) },
+    ];
+    for (const mint of mints) {
+        const label = mint.equals(NATIVE_SOL_MINT) ? "SOL" : mint.toBase58().slice(0, 4);
+        const { config, vault, nullifiers } = getPoolPdas(programId, mint);
+        out.push({ label: `${label}.config`, address: config }, { label: `${label}.vault`, address: vault }, { label: `${label}.nullifiers`, address: nullifiers });
+        for (let t = 0; t <= maxTreeId; t++) {
+            out.push({
+                label: `${label}.tree(${t})`,
+                address: getNoteTreePda(programId, mint, t),
+            });
+        }
+        if (!mint.equals(NATIVE_SOL_MINT)) {
+            out.push({
+                label: `${label}.vaultAta`,
+                address: await getAssociatedTokenAddress(mint, vault, true),
+            });
+        }
+    }
+    return out;
+}
+/** Diff the on-chain table against {@link expectedDepositAltKeys}. */
+export async function auditDepositAlt(connection, params = {}) {
+    const address = params.address ?? SHARED_DEPOSIT_ALT;
+    const res = await connection.getAddressLookupTable(address, {
+        commitment: "finalized",
+    });
+    if (!res.value) {
+        throw new ShieldError("ALT_NOT_FOUND", `Deposit ALT ${address.toBase58()} not found`, { context: { address: address.toBase58() } });
+    }
+    const present = new Set(res.value.state.addresses.map((a) => a.toBase58()));
+    const expected = await expectedDepositAltKeys(params);
+    const expectedSet = new Set(expected.map((e) => e.address.toBase58()));
+    const missing = expected.filter((e) => !present.has(e.address.toBase58()));
+    const extra = [...present].filter((p) => !expectedSet.has(p));
+    return { ok: missing.length === 0, present: present.size, missing, extra };
+}

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

@@ -0,0 +1,61 @@
+/**
+ * Compute budget and transaction size constants for the shield path.
+ *
+ * These numbers are empirical and load-bearing. They are constants rather than
+ * inline literals so a future program change that invalidates them has one
+ * place to be fixed and one place to be read.
+ */
+/**
+ * Compute unit limit reserved for a shield.
+ *
+ * Measured usage for a deposit is ~377k CU; 700k leaves roughly 2× headroom
+ * while staying low enough that Phantom's Lighthouse guard still fits its own
+ * instructions alongside ours.
+ *
+ * Do NOT raise this to 1.4M (what the stale `client.ts` `deposit()` reserves).
+ * An oversized CU reservation is one of the signals that makes Phantom render
+ * the transaction with a malicious-dApp warning.
+ *
+ * Ported from veilo-dapp/features/transactions/handleDeposit.ts:673-681.
+ */
+export declare const SHIELD_COMPUTE_UNIT_LIMIT = 700000;
+/** Typical measured usage. If real usage approaches the limit above, revisit both. */
+export declare const SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL = 377000;
+/** Default priority fee. Set to 0 to omit the instruction entirely (saves ~40 bytes). */
+export declare const SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS = 50000;
+/** Solana's hard cap on a serialized transaction, signatures included. */
+export declare const MAX_TRANSACTION_BYTES = 1232;
+/** One ed25519 signature: 64 bytes plus the compact-array length prefix. */
+export declare const SIGNATURE_BYTES = 65;
+/**
+ * `NullifierMarker::LEN` (privacy-program .../lib.rs:415). Two markers are
+ * created per transact and paid for by the signer — see the note on sponsorship
+ * in the module docs of `shield.ts`.
+ */
+export declare const NULLIFIER_MARKER_ACCOUNT_BYTES = 10;
+/** Markers created per `transact` — one per circuit input. */
+export declare const NULLIFIER_MARKERS_PER_TRANSACT = 2;
+/** Default validity window for the on-chain `deadline` argument. */
+export declare const DEFAULT_DEADLINE_SECONDS = 3600;
+/**
+ * Serialized size of the `transact` instruction data, for reference:
+ *
+ *   8   discriminator
+ *  32   root
+ *   2   input_tree_id
+ *   2   output_tree_id
+ *   8   public_amount
+ *  32   ext_data_hash
+ *  32   mint_address
+ * 128   2 nullifiers + 2 commitments
+ *   8   deadline
+ * 112   ExtData (recipient, relayer, fee, refund, claimant)
+ * 256   Groth16 proof (a:64, b:128, c:64)
+ * 227   Option<NoteCiphers> (1 tag + 226)
+ * ---
+ * 847
+ *
+ * With 16 accounts this cannot fit in a legacy transaction (~1500 bytes), which
+ * is why the shield path is v0-with-ALT and not optional.
+ */
+export declare const TRANSACT_INSTRUCTION_DATA_BYTES = 847;

package/dist/esm/shield/computeBudget.js

@@ -0,0 +1,61 @@
+/**
+ * Compute budget and transaction size constants for the shield path.
+ *
+ * These numbers are empirical and load-bearing. They are constants rather than
+ * inline literals so a future program change that invalidates them has one
+ * place to be fixed and one place to be read.
+ */
+/**
+ * Compute unit limit reserved for a shield.
+ *
+ * Measured usage for a deposit is ~377k CU; 700k leaves roughly 2× headroom
+ * while staying low enough that Phantom's Lighthouse guard still fits its own
+ * instructions alongside ours.
+ *
+ * Do NOT raise this to 1.4M (what the stale `client.ts` `deposit()` reserves).
+ * An oversized CU reservation is one of the signals that makes Phantom render
+ * the transaction with a malicious-dApp warning.
+ *
+ * Ported from veilo-dapp/features/transactions/handleDeposit.ts:673-681.
+ */
+export const SHIELD_COMPUTE_UNIT_LIMIT = 700000;
+/** Typical measured usage. If real usage approaches the limit above, revisit both. */
+export const SHIELD_COMPUTE_UNITS_MEASURED_TYPICAL = 377000;
+/** Default priority fee. Set to 0 to omit the instruction entirely (saves ~40 bytes). */
+export const SHIELD_COMPUTE_UNIT_PRICE_MICRO_LAMPORTS = 50000;
+/** Solana's hard cap on a serialized transaction, signatures included. */
+export const MAX_TRANSACTION_BYTES = 1232;
+/** One ed25519 signature: 64 bytes plus the compact-array length prefix. */
+export const SIGNATURE_BYTES = 65;
+/**
+ * `NullifierMarker::LEN` (privacy-program .../lib.rs:415). Two markers are
+ * created per transact and paid for by the signer — see the note on sponsorship
+ * in the module docs of `shield.ts`.
+ */
+export const NULLIFIER_MARKER_ACCOUNT_BYTES = 10;
+/** Markers created per `transact` — one per circuit input. */
+export const NULLIFIER_MARKERS_PER_TRANSACT = 2;
+/** Default validity window for the on-chain `deadline` argument. */
+export const DEFAULT_DEADLINE_SECONDS = 3600;
+/**
+ * Serialized size of the `transact` instruction data, for reference:
+ *
+ *   8   discriminator
+ *  32   root
+ *   2   input_tree_id
+ *   2   output_tree_id
+ *   8   public_amount
+ *  32   ext_data_hash
+ *  32   mint_address
+ * 128   2 nullifiers + 2 commitments
+ *   8   deadline
+ * 112   ExtData (recipient, relayer, fee, refund, claimant)
+ * 256   Groth16 proof (a:64, b:128, c:64)
+ * 227   Option<NoteCiphers> (1 tag + 226)
+ * ---
+ * 847
+ *
+ * With 16 accounts this cannot fit in a legacy transaction (~1500 bytes), which
+ * is why the shield path is v0-with-ALT and not optional.
+ */
+export const TRANSACT_INSTRUCTION_DATA_BYTES = 847;