@veilo/sdk-core 0.1.17 → 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

@@ -0,0 +1,249 @@
+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, details) {
+        super(message);
+        this.name = "VeiloApiError";
+        this.code = code;
+        this.status = status;
+        this.details = details;
+    }
+}
+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({
+ *   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?.trim() || DEFAULT_RELAYER_URL).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",
+        };
+        if (this.apiKey)
+            h["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, data);
+            // 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}`);
+    }
+    /**
+     * 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
+    // ---------------------------------------------------------------------------
+    /** 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,
+        });
+    }
+}

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/retry.js

@@ -0,0 +1,71 @@
+// -----------------------------------------------------------------------------
+// RPC Retry / Resilience
+// -----------------------------------------------------------------------------
+export const DEFAULT_RPC_RETRY = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 10000,
+};
+/** Error messages / patterns that indicate a transient RPC failure worth retrying. */
+const RETRYABLE_PATTERNS = [
+    "blockhash not found",
+    "block height exceeded",
+    "blockhash already expired",
+    "node is behind",
+    "service unavailable",
+    "too many requests",
+    "429",
+    "502",
+    "503",
+    "504",
+    "timeout",
+    "timed out",
+    "econnreset",
+    "econnrefused",
+    "socket hang up",
+    "fetch failed",
+];
+function isRetryableError(error) {
+    const msg = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return RETRYABLE_PATTERNS.some((p) => msg.includes(p));
+}
+/**
+ * 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 async function withRpcRetry(fn, policy) {
+    const { maxRetries, baseDelayMs, maxDelayMs } = {
+        ...DEFAULT_RPC_RETRY,
+        ...policy,
+    };
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= maxRetries || !isRetryableError(error)) {
+                throw error;
+            }
+            const delay = Math.min(baseDelayMs * Math.pow(2, attempt) + Math.random() * 200, maxDelayMs);
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    throw lastError;
+}