@veilo/sdk-core 0.3.3 → 0.5.0

package/dist/cjs/relayer.d.ts

@@ -1,295 +1 @@
-export interface VeiloRelayerConfig {
-    /** Base URL of the relayer (e.g. "https://relayer.veilo.io") */
-    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;
-    constructor(code: string, message: string, status: number);
-}
-/** 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;
-}
-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;
-}
-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 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({
- *   relayerUrl: "https://relayer.veilo.io",
- *   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>;
-    /** 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>;
-}
+export * from "./relayer/index.js";

package/dist/cjs/relayer.js

@@ -1,246 +1,18 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VeiloRelayerClient = exports.VeiloApiError = void 0;
-const tweetnacl_1 = __importDefault(require("tweetnacl"));
-// =============================================================================
-// Structured Error
-// =============================================================================
-/** Structured error thrown by VeiloRelayerClient on API failures. */
-class VeiloApiError extends Error {
-    constructor(code, message, status) {
-        super(message);
-        this.name = "VeiloApiError";
-        this.code = code;
-        this.status = status;
-    }
-}
-exports.VeiloApiError = VeiloApiError;
-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 = tweetnacl_1.default.box.keyPair();
-    const message = new TextEncoder().encode(JSON.stringify(data));
-    const nonce = tweetnacl_1.default.randomBytes(tweetnacl_1.default.box.nonceLength);
-    const ciphertext = tweetnacl_1.default.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...");
- * ```
- */
-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(tweetnacl_1.default.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,
-        });
-    }
-}
-exports.VeiloRelayerClient = VeiloRelayerClient;
+// Backward-compatible entry point. Relayer responsibilities live in src/relayer.
+__exportStar(require("./relayer/index.js"), exports);

package/dist/cjs/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 {};