@veilo/sdk-core 0.3.3 → 0.4.0

package/dist/esm/relayer.d.ts

@@ -0,0 +1,318 @@
+export interface VeiloRelayerConfig {
+    /** Base URL of the relayer. Defaults to Veilo's production service. */
+    relayerUrl?: string;
+    /** API key sent as x-api-key header */
+    apiKey: string;
+    /** Relayer's NaCl box public key (base64-encoded, 32 bytes) */
+    relayerPublicKey: string;
+    /** Optional JWT auth token for authenticated endpoints */
+    authToken?: string;
+}
+/** Structured error thrown by VeiloRelayerClient on API failures. */
+export declare class VeiloApiError extends Error {
+    code: string;
+    status: number;
+    details?: unknown;
+    constructor(code: string, message: string, status: number, details?: unknown);
+}
+/** Retry configuration for the relayer HTTP client. */
+export interface RetryPolicy {
+    /** Max number of retry attempts (default: 3) */
+    maxRetries: number;
+    /** Base delay in ms for exponential backoff (default: 1000) */
+    baseDelayMs: number;
+    /** HTTP status codes that trigger a retry (default: [429, 502, 503, 504]) */
+    retryableStatuses: number[];
+}
+export interface RelayerEncryptedNote {
+    noteId: string;
+    commitment: string;
+    ephemeralPublicKey: string;
+    encryptedBlob: string;
+    timestamp: number;
+    blockHeight?: number;
+    txSignature?: string;
+    spent?: boolean;
+    onchainId?: string;
+    spentTx?: string;
+    spentAt?: number;
+    compactEphemeralKey?: string | null;
+    compactBlob?: string | null;
+    viewTag?: number | null;
+    leafIndex?: number | null;
+    mintAddress?: string | null;
+    treeId?: number | null;
+}
+export interface QueryNotesRequest {
+    lastCheckedTimestamp?: number;
+    limit?: number;
+    offset?: number;
+    walletPublicKey?: string;
+}
+export interface QueryNotesResponse {
+    success: boolean;
+    notes: RelayerEncryptedNote[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface SaveEncryptedNoteRequest {
+    commitment: string;
+    ephemeralPublicKey: string;
+    encryptedBlob: string;
+    timestamp: number;
+    blockHeight?: number;
+    txSignature?: string;
+    recipientWalletPublicKey?: string;
+    compactEphemeralKey?: string | null;
+    compactBlob?: string | null;
+    viewTag?: number | null;
+    leafIndex?: number;
+    newRoot?: string;
+    mintAddress?: string;
+    treeId?: number;
+    amountRaw?: string;
+}
+export interface SaveEncryptedNoteResponse {
+    success: boolean;
+    noteId?: string;
+    message?: string;
+    error?: string;
+}
+export interface MerkleRootResponse {
+    success: boolean;
+    data: {
+        root: string;
+        nextIndex: number;
+        treeId: number;
+        onChainTreeId: number;
+        mintAddress: string;
+    };
+}
+export interface MerkleTreeResponse {
+    success: boolean;
+    data: {
+        treeId: number;
+        onChainTreeId: number;
+        mintAddress: string;
+        height: number;
+        nextIndex: number;
+        root: string;
+        totalCommitments: number;
+        leaves: Array<{
+            commitment: string;
+            index: number;
+            txSignature: string;
+            slot: number;
+            timestamp: string;
+        }>;
+        reconstructionInfo: {
+            instructions: string;
+            treeHeight: number;
+            hashFunction?: string;
+        };
+    };
+}
+export interface TransactNote {
+    commitment: string;
+    privateKey: string;
+    publicKey: string;
+    blinding: string;
+    amount: string;
+    nullifier: string;
+    leafIndex?: number;
+    noteId?: string;
+}
+export interface WithdrawRequest {
+    notes: TransactNote[];
+    recipient: string;
+    amount: string;
+    userPublicKey: string;
+    mintAddress: string;
+}
+export interface WithdrawResponse {
+    success: boolean;
+    message: string;
+    data?: {
+        withdrawRecipient: string;
+        withdrawAmount: number;
+        changeAmount: number;
+        changeNote: {
+            commitment: string;
+            privateKey: string;
+            publicKey: string;
+            blinding: string;
+            amount: string;
+            nullifier: string;
+        };
+        spentNoteIds?: string[];
+        txSignature?: string;
+    };
+}
+export interface PrivateTransferRequest {
+    notes: TransactNote[];
+    amount: string;
+    recipientUsername: string;
+    userPublicKey?: string;
+    mintAddress?: string;
+}
+export interface PrivateTransferResponse {
+    success: boolean;
+    message: string;
+    data?: {
+        recipient: string;
+        transferAmount: number;
+        senderChangeAmount: number;
+        txSignature: string;
+        recipientNote: {
+            commitment: string;
+            amount: string;
+            leafIndex: number;
+            savedNoteId: string;
+        };
+        senderChangeNote: {
+            commitment: string;
+            privateKey: string;
+            publicKey: string;
+            blinding: string;
+            amount: string;
+            leafIndex: number;
+            savedNoteId: string;
+        } | null;
+    };
+}
+export interface PrivateSwapRequest {
+    notes: TransactNote[];
+    sourceMintAddress: string;
+    destMintAddress: string;
+    sourceJupiterMint?: string;
+    destJupiterMint?: string;
+    swapAmountRaw: string;
+    minAmountOut: string;
+    slippageBps: number;
+    userPublicKey: string;
+    veiloPublicKey: string;
+}
+export interface PrivateSwapResponse {
+    success: boolean;
+    message: string;
+    data?: {
+        txSignature: string;
+        swapAmountRaw: string;
+        outputAmount: string;
+        minAmountOut: string;
+        changeAmount: string;
+    };
+}
+export interface ChallengeResponse {
+    success: boolean;
+    challenge: string;
+    expiresAt: number;
+}
+export interface RegisterRequest {
+    username: string;
+    walletPublicKey: string;
+    signature: string;
+    challenge: string;
+    veiloPublicKey: string;
+}
+export interface RegisterResponse {
+    success: boolean;
+    token: string;
+    message?: string;
+}
+export interface RestoreRequest {
+    walletPublicKey: string;
+    signature: string;
+    challenge: string;
+}
+export interface RestoreResponse {
+    success: boolean;
+    token: string;
+    username: string;
+    veiloPublicKey: string;
+}
+export interface CheckUsernameResponse {
+    success: boolean;
+    available: boolean;
+}
+export interface VeiloPublicKeyResponse {
+    success: boolean;
+    username: string;
+    pubK: string;
+    veiloPublicKey: string;
+}
+export interface PreRegisterKeyResponse {
+    success: boolean;
+    veiloPublicKey: string;
+}
+export interface DeleteUserDataResponse {
+    success: boolean;
+    message: string;
+    deletedCount?: number;
+}
+/**
+ * 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({
+ *   apiKey: "your-api-key",
+ *   relayerPublicKey: "<base64 NaCl public key>",
+ * });
+ * const root = await client.getMerkleRoot("So111...");
+ * ```
+ */
+export declare class VeiloRelayerClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly relayerPubKey;
+    private authToken;
+    private readonly retry;
+    constructor(config: VeiloRelayerConfig, retry?: Partial<RetryPolicy>);
+    /** Update the auth token (e.g. after register/restore). */
+    setAuthToken(token: string): void;
+    private headers;
+    private request;
+    private encrypt;
+    /** Request a signature challenge for wallet authentication. */
+    getChallenge(walletPublicKey: string): Promise<ChallengeResponse>;
+    /** Register a new account with a signed challenge. Returns a JWT auth token. */
+    register(data: RegisterRequest): Promise<RegisterResponse>;
+    /** Restore an existing account using a signed challenge. Returns a JWT auth token. */
+    restore(data: RestoreRequest): Promise<RestoreResponse>;
+    /** Check whether a username is available for registration. */
+    checkUsername(username: string): Promise<CheckUsernameResponse>;
+    /** Look up a user's Veilo public key by username or wallet public key. */
+    getVeiloPublicKey(params: {
+        username: string;
+        publicKey?: never;
+    } | {
+        publicKey: string;
+        username?: never;
+    }): Promise<VeiloPublicKeyResponse>;
+    /**
+     * Provision (or retrieve) the Veilo spend key paired with a Solana address.
+     * Public and idempotent; the response contains public key material only.
+     */
+    preRegisterKey(solanaAddress: string): Promise<PreRegisterKeyResponse>;
+    /** Save an encrypted note to the relayer's database. */
+    saveEncryptedNote(data: SaveEncryptedNoteRequest): Promise<SaveEncryptedNoteResponse>;
+    /** Query encrypted notes for the authenticated user. Requires auth token. */
+    queryEncryptedNotes(params?: QueryNotesRequest): Promise<QueryNotesResponse>;
+    /** Delete all stored data for the authenticated user. Requires auth token. */
+    deleteUserData(): Promise<DeleteUserDataResponse>;
+    /** Fetch the current Merkle root for a pool, optionally filtered by mint and tree ID. */
+    getMerkleRoot(mintAddress?: string, treeId?: number): Promise<MerkleRootResponse>;
+    /** Fetch the full Merkle tree (all leaves) for a pool. */
+    getMerkleTree(mintAddress?: string, treeId?: number): Promise<MerkleTreeResponse>;
+    /** Submit an encrypted withdrawal request to the relayer. Not retried on failure. */
+    submitWithdraw(data: WithdrawRequest): Promise<WithdrawResponse>;
+    /** Submit an encrypted private transfer request. Not retried on failure. */
+    submitPrivateTransfer(data: PrivateTransferRequest): Promise<PrivateTransferResponse>;
+    /** Submit an encrypted private swap request. Not retried on failure. */
+    submitPrivateSwap(data: PrivateSwapRequest): Promise<PrivateSwapResponse>;
+}

package/dist/esm/relayer.js

@@ -1,14 +1,16 @@
 import nacl from "tweetnacl";
+const DEFAULT_RELAYER_URL = "https://relayer-server.onrender.com";
 // =============================================================================
 // Structured Error
 // =============================================================================
 /** Structured error thrown by VeiloRelayerClient on API failures. */
 export class VeiloApiError extends Error {
-    constructor(code, message, status) {
+    constructor(code, message, status, details) {
         super(message);
         this.name = "VeiloApiError";
         this.code = code;
         this.status = status;
+        this.details = details;
     }
 }
 const DEFAULT_RETRY = {
@@ -65,7 +67,6 @@ function encryptForRelayer(data, relayerPublicKey) {
  * @example
  * ```ts
  * const client = new VeiloRelayerClient({
- *   relayerUrl: "https://relayer.veilo.io",
  *   apiKey: "your-api-key",
  *   relayerPublicKey: "<base64 NaCl public key>",
  * });
@@ -74,7 +75,7 @@ function encryptForRelayer(data, relayerPublicKey) {
  */
 export class VeiloRelayerClient {
     constructor(config, retry) {
-        this.baseUrl = config.relayerUrl.replace(/\/+$/, "");
+        this.baseUrl = (config.relayerUrl?.trim() || DEFAULT_RELAYER_URL).replace(/\/+$/, "");
         this.apiKey = config.apiKey;
         this.relayerPubKey = fromBase64(config.relayerPublicKey);
         this.authToken = config.authToken;
@@ -90,8 +91,9 @@ export class VeiloRelayerClient {
     headers(authenticated) {
         const h = {
             "Content-Type": "application/json",
-            "x-api-key": this.apiKey,
         };
+        if (this.apiKey)
+            h["x-api-key"] = this.apiKey;
         if (authenticated && this.authToken) {
             h["Authorization"] = `Bearer ${this.authToken}`;
         }
@@ -124,7 +126,7 @@ export class VeiloRelayerClient {
             if (res.ok && data.success !== false) {
                 return data;
             }
-            lastError = new VeiloApiError(data.error || "UNKNOWN", data.message || data.error || `Request failed: ${res.status}`, res.status);
+            lastError = new VeiloApiError(data.error || "UNKNOWN", data.message || data.error || `Request failed: ${res.status}`, res.status, data);
             // Only retry on transient statuses
             if (!this.retry.retryableStatuses.includes(res.status)) {
                 throw lastError;
@@ -167,6 +169,15 @@ export class VeiloRelayerClient {
             : `publicKey=${encodeURIComponent(params.publicKey)}`;
         return this.request("GET", `/auth/veiloPublicKey?${query}`);
     }
+    /**
+     * Provision (or retrieve) the Veilo spend key paired with a Solana address.
+     * Public and idempotent; the response contains public key material only.
+     */
+    async preRegisterKey(solanaAddress) {
+        return this.request("POST", "/auth/pre-register-key", {
+            body: { solanaAddress },
+        });
+    }
     // ---------------------------------------------------------------------------
     // Notes
     // ---------------------------------------------------------------------------

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 "../client.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 };
+}