@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/cjs/relayer/errors.d.ts

@@ -0,0 +1,7 @@
+/** Structured error thrown by managed Veilo API helpers. */
+export declare class VeiloApiError extends Error {
+    code: string;
+    status: number;
+    details?: unknown;
+    constructor(code: string, message: string, status: number, details?: unknown);
+}

package/dist/cjs/relayer/errors.js

@@ -0,0 +1,17 @@
+"use strict";
+// =============================================================================
+// Structured Error
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VeiloApiError = void 0;
+/** Structured error thrown by managed Veilo API helpers. */
+class VeiloApiError extends Error {
+    constructor(code, message, status, details) {
+        super(message);
+        this.name = "VeiloApiError";
+        this.code = code;
+        this.status = status;
+        this.details = details;
+    }
+}
+exports.VeiloApiError = VeiloApiError;

package/dist/cjs/relayer/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./api.js";
+export type * from "../positions/types.js";
+export type * from "../perps/types.js";
+export type * from "../predictions/types.js";

package/dist/cjs/relayer/index.js

@@ -0,0 +1,19 @@
+"use strict";
+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 });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./errors.js"), exports);
+__exportStar(require("./api.js"), exports);

package/dist/cjs/relayer/internal-config.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Veilo network coordinates are protocol configuration, not integrator input.
+ * Keep them behind the public package entry points.
+ */
+export declare const VEILO_RELAYER_URL = "https://relayer-server.onrender.com";
+export declare const VEILO_RELAYER_PUBLIC_KEY = "utVxnA7zax09qJCZ7UJsa8PAOoWLRcCwOkdxg/ZGmD4=";
+/**
+ * Internal construction options. Overrides exist only for isolated tests.
+ *
+ * ⚠ `baseUrl` MUST NOT be promoted to the public API. Two invariants depend on
+ * it staying internal:
+ *
+ *   1. The privacy pool gates every spend on an on-chain relayer allowlist
+ *      (`RelayerNotAllowed`). Only deposits are permissionless. A request sent
+ *      to any other host cannot land on chain, so the option would be a
+ *      footgun that fails late rather than a feature.
+ *   2. These request bodies carry note spending keys (`TransactNote.privateKey`,
+ *      and `claimantSecretKey` on position close/merge). A caller-settable
+ *      destination is a caller-settable exfiltration target for user funds.
+ *
+ * Only `internal.ts` may construct these options, and it builds the object
+ * literal itself — no caller-supplied object is ever forwarded here. To verify
+ * that still holds:
+ *
+ *   grep -rn "createInternalRelayerClient(\|new VeiloRelayerClient(" src
+ *
+ * Whitelisted partners who run their own relayer are handled out of band, not
+ * by a config flag. See README → "Submission always targets Veilo's relayer".
+ */
+export interface InternalRelayerClientOptions {
+    authToken?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    encryptionPublicKey?: string;
+    fetch?: typeof fetch;
+}

package/dist/cjs/relayer/internal-config.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VEILO_RELAYER_PUBLIC_KEY = exports.VEILO_RELAYER_URL = void 0;
+/**
+ * Veilo network coordinates are protocol configuration, not integrator input.
+ * Keep them behind the public package entry points.
+ */
+exports.VEILO_RELAYER_URL = "https://relayer-server.onrender.com";
+exports.VEILO_RELAYER_PUBLIC_KEY = "utVxnA7zax09qJCZ7UJsa8PAOoWLRcCwOkdxg/ZGmD4=";

package/dist/cjs/relayer/internal.d.ts

@@ -0,0 +1,6 @@
+import { VeiloRelayerClient } from "./client.js";
+import type { InternalRelayerClientOptions } from "./internal-config.js";
+/** @internal Shared stateless production client for public SDK helpers. */
+export declare function getInternalRelayerClient(): VeiloRelayerClient;
+/** @internal Auth state is isolated per call to avoid cross-user token leaks. */
+export declare function createInternalRelayerClient(options?: InternalRelayerClientOptions): VeiloRelayerClient;

package/dist/cjs/relayer/internal.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInternalRelayerClient = getInternalRelayerClient;
+exports.createInternalRelayerClient = createInternalRelayerClient;
+const client_js_1 = require("./client.js");
+const RELAYER = new client_js_1.VeiloRelayerClient();
+/** @internal Shared stateless production client for public SDK helpers. */
+function getInternalRelayerClient() {
+    return RELAYER;
+}
+/** @internal Auth state is isolated per call to avoid cross-user token leaks. */
+function createInternalRelayerClient(options = {}) {
+    return new client_js_1.VeiloRelayerClient(options);
+}

package/dist/cjs/relayer/transport.d.ts

@@ -0,0 +1,19 @@
+import { type InternalRelayerClientOptions } from "./internal-config.js";
+import type { RetryPolicy } from "./types.js";
+export interface RelayerRequestOptions {
+    body?: unknown;
+    authenticated?: boolean;
+    retryable?: boolean;
+}
+/** Owns HTTP authentication, retry, and response normalization. */
+export declare class RelayerHttpTransport {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private authToken;
+    private readonly retry;
+    private readonly fetcher?;
+    constructor(config?: InternalRelayerClientOptions, retry?: Partial<RetryPolicy>);
+    setAuthToken(token: string): void;
+    request<T>(method: string, route: string, options?: RelayerRequestOptions): Promise<T>;
+    private headers;
+}

package/dist/cjs/relayer/transport.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayerHttpTransport = void 0;
+const errors_js_1 = require("./errors.js");
+const internal_config_js_1 = require("./internal-config.js");
+const DEFAULT_RETRY = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    retryableStatuses: [429, 502, 503, 504],
+};
+/** Owns HTTP authentication, retry, and response normalization. */
+class RelayerHttpTransport {
+    constructor(config = {}, retry) {
+        this.baseUrl = (config.baseUrl?.trim() || internal_config_js_1.VEILO_RELAYER_URL).replace(/\/+$/, "");
+        this.apiKey = config.apiKey ?? "";
+        this.authToken = config.authToken;
+        this.retry = { ...DEFAULT_RETRY, ...retry };
+        this.fetcher = config.fetch;
+    }
+    setAuthToken(token) {
+        this.authToken = token;
+    }
+    async request(method, route, options = {}) {
+        const url = `${this.baseUrl}/api${route}`;
+        const { body, authenticated = false, retryable = true } = options;
+        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((resolve) => setTimeout(resolve, delay));
+            }
+            let response;
+            try {
+                const fetcher = this.fetcher ?? globalThis.fetch;
+                if (typeof fetcher !== "function") {
+                    throw new Error("This environment does not provide fetch");
+                }
+                response = await fetcher(url, {
+                    method,
+                    headers: this.headers(authenticated),
+                    body: body == null ? undefined : JSON.stringify(body),
+                });
+            }
+            catch (error) {
+                lastError = new errors_js_1.VeiloApiError("NETWORK_ERROR", error instanceof Error ? error.message : "Network request failed", 0);
+                continue;
+            }
+            const data = await response.json().catch(() => ({}));
+            if (response.ok && data.success !== false)
+                return data;
+            lastError = new errors_js_1.VeiloApiError(data.error || "UNKNOWN", data.message || data.error || `Request failed: ${response.status}`, response.status, data);
+            if (!this.retry.retryableStatuses.includes(response.status))
+                throw lastError;
+        }
+        throw lastError;
+    }
+    headers(authenticated) {
+        const headers = { "Content-Type": "application/json" };
+        if (this.apiKey)
+            headers["x-api-key"] = this.apiKey;
+        if (authenticated && this.authToken) {
+            headers.Authorization = `Bearer ${this.authToken}`;
+        }
+        return headers;
+    }
+}
+exports.RelayerHttpTransport = RelayerHttpTransport;

package/dist/{src/relayer.d.ts → cjs/relayer/types.d.ts}

@@ -1,20 +1,3 @@
-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) */
@@ -56,6 +39,15 @@ export interface QueryNotesResponse {
     limit: number;
     offset: number;
 }
+/** Nullifiers to test for spend status. Max 200 per request, 64-char hex. */
+export interface CheckNullifiersRequest {
+    nullifiers: string[];
+}
+export interface CheckNullifiersResponse {
+    success: boolean;
+    /** The SPENT subset, lowercase hex. Absent entries are unspent. */
+    spent: string[];
+}
 export interface SaveEncryptedNoteRequest {
     commitment: string;
     ephemeralPublicKey: string;
@@ -114,14 +106,29 @@ export interface MerkleTreeResponse {
     };
 }
 export interface TransactNote {
+    /** Relayer database identifier when the note came from relayer sync. */
+    id?: string;
+    /** Client-side alias used by the dapp, wallet, and extension. */
+    noteId?: string;
+    amount: string;
     commitment: string;
+    root?: string;
+    nullifier: string;
+    blinding: string;
     privateKey: string;
     publicKey: string;
-    blinding: string;
-    amount: string;
-    nullifier: string;
+    /** Optional because the relayer corrects it against commitment events. */
     leafIndex?: number;
-    noteId?: string;
+    timestamp?: number;
+    spent?: boolean;
+    spentAt?: number;
+    txSignature?: string;
+    treeId?: number;
+    mintAddress?: string;
+    merklePath?: {
+        pathElements: string[];
+        pathIndices: number[];
+    };
 }
 export interface WithdrawRequest {
     notes: TransactNote[];
@@ -129,6 +136,7 @@ export interface WithdrawRequest {
     amount: string;
     userPublicKey: string;
     mintAddress: string;
+    feeOnTop?: boolean;
 }
 export interface WithdrawResponse {
     success: boolean;
@@ -136,17 +144,17 @@ export interface WithdrawResponse {
     data?: {
         withdrawRecipient: string;
         withdrawAmount: number;
+        fee: number;
+        feeBps: number;
+        feeOnTop: boolean;
+        totalDebited: number;
         changeAmount: number;
         changeNote: {
             commitment: string;
-            privateKey: string;
-            publicKey: string;
-            blinding: string;
             amount: string;
-            nullifier: string;
+            leafIndex: number;
         };
-        spentNoteIds?: string[];
-        txSignature?: string;
+        savedNoteId?: string;
     };
 }
 export interface PrivateTransferRequest {
@@ -155,11 +163,17 @@ export interface PrivateTransferRequest {
     recipientUsername: string;
     userPublicKey?: string;
     mintAddress?: string;
+    mode?: "merge";
+    recipientSolanaAddress?: string;
+    /** Legacy extension field; current relayer resolves the key itself. */
+    recipientShieldedKey?: string;
 }
 export interface PrivateTransferResponse {
     success: boolean;
     message: string;
     data?: {
+        merged: false;
+    } | {
         recipient: string;
         transferAmount: number;
         senderChangeAmount: number;
@@ -172,12 +186,8 @@ export interface PrivateTransferResponse {
         };
         senderChangeNote: {
             commitment: string;
-            privateKey: string;
-            publicKey: string;
-            blinding: string;
             amount: string;
             leafIndex: number;
-            savedNoteId: string;
         } | null;
     };
 }
@@ -192,6 +202,18 @@ export interface PrivateSwapRequest {
     slippageBps: number;
     userPublicKey: string;
     veiloPublicKey: string;
+    /** Optional veilo-connect intent forwarded by the browser extension. */
+    intentCommit?: {
+        origin: string;
+        fromMint: string;
+        toMint: string;
+        amountIn: string;
+        minAmountOut: string;
+        deadline: number;
+        nonce: string;
+    };
+    intentHash?: string;
+    intentDeadlineMs?: number;
 }
 export interface PrivateSwapResponse {
     success: boolean;
@@ -251,68 +273,3 @@ export interface DeleteUserDataResponse {
     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/cjs/relayer/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// =============================================================================
+// Retry Policy
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });