@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/esm/relayer/client.js

@@ -0,0 +1,199 @@
+import nacl from "tweetnacl";
+import { encryptForRelayer } from "./crypto.js";
+import { fromBase64, toBase64 } from "./encoding.js";
+import { VEILO_RELAYER_PUBLIC_KEY, } from "./internal-config.js";
+import { RelayerHttpTransport } from "./transport.js";
+// =============================================================================
+// Relayer Client
+// =============================================================================
+/** @internal Relayer transport behind the SDK's functional helpers. */
+export class VeiloRelayerClient {
+    constructor(config = {}, retry) {
+        this.transport = new RelayerHttpTransport(config, retry);
+        this.relayerPubKey = fromBase64(config.encryptionPublicKey ?? VEILO_RELAYER_PUBLIC_KEY);
+    }
+    /** Update the auth token (e.g. after register/restore). */
+    setAuthToken(token) {
+        this.transport.setAuthToken(token);
+    }
+    encryptPayload(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.transport.request("POST", "/auth/challenge", {
+            body: { walletPublicKey },
+        });
+    }
+    /** Register a new account with a signed challenge. Returns a JWT auth token. */
+    async register(data) {
+        return this.transport.request("POST", "/auth/register", { body: data });
+    }
+    /** Restore an existing account using a signed challenge. Returns a JWT auth token. */
+    async restore(data) {
+        return this.transport.request("POST", "/auth/restore", { body: data });
+    }
+    /** Check whether a username is available for registration. */
+    async checkUsername(username) {
+        return this.transport.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.transport.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.transport.request("POST", "/auth/pre-register-key", {
+            body: { solanaAddress },
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Notes
+    // ---------------------------------------------------------------------------
+    /** Save an encrypted note to the relayer's database. */
+    async saveEncryptedNote(data) {
+        return this.transport.request("POST", "/notes/save", { body: data });
+    }
+    /** Query encrypted notes for the authenticated user. Requires auth token. */
+    async queryEncryptedNotes(params = {}) {
+        return this.transport.request("POST", "/notes/query", {
+            body: params,
+            authenticated: true,
+        });
+    }
+    /** Delete all stored data for the authenticated user. Requires auth token. */
+    /**
+     * Ask which of these nullifiers the relayer has seen spent.
+     *
+     * Caller must respect MAX_NULLIFIERS_PER_CHECK; `checkNullifiersSpent` in
+     * notes/spent.ts does the chunking. Unauthenticated: a nullifier reveals
+     * nothing about ownership on its own.
+     */
+    async checkNullifiers(nullifiers) {
+        return this.transport.request("POST", "/notes/nullifiers/check-batch", {
+            body: { nullifiers },
+        });
+    }
+    async deleteUserData() {
+        return this.transport.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.transport.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.transport.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.encryptPayload(data);
+        return this.transport.request("POST", "/transact/withdraw", {
+            body: { encryptedPayload },
+            retryable: false,
+        });
+    }
+    /** Submit an encrypted private transfer request. Not retried on failure. */
+    async submitPrivateTransfer(data) {
+        const encryptedPayload = this.encryptPayload(data);
+        return this.transport.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.encryptPayload(data);
+        return this.transport.request("POST", "/transact/private-swap", {
+            body: { encryptedPayload },
+            retryable: false,
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Private positions (encrypted payloads)
+    // ---------------------------------------------------------------------------
+    async submitOpenPosition(data) {
+        return this.submitEncrypted("/positions/open", data);
+    }
+    async submitClosePosition(data) {
+        return this.submitEncrypted("/positions/close", data);
+    }
+    async submitMergePositions(data) {
+        return this.submitEncrypted("/positions/merge", data);
+    }
+    // ---------------------------------------------------------------------------
+    // Private Jupiter Perps (encrypted payloads)
+    // ---------------------------------------------------------------------------
+    async submitJperpOpen(data) {
+        return this.submitEncrypted("/jperp/open", data);
+    }
+    async submitJperpClose(data) {
+        return this.submitEncrypted("/jperp/close", data);
+    }
+    async submitJperpSetTpsl(data) {
+        return this.submitEncrypted("/jperp/set-tpsl", data);
+    }
+    async submitJperpUpdateTpsl(data) {
+        return this.submitEncrypted("/jperp/update-tpsl", data);
+    }
+    async submitJperpCancelTrigger(data) {
+        return this.submitEncrypted("/jperp/cancel-trigger", data);
+    }
+    async submitJperpReissue(data) {
+        return this.submitEncrypted("/jperp/reissue", data);
+    }
+    async submitJperpRecoverSeed(data) {
+        return this.submitEncrypted("/jperp/recover-seed", data);
+    }
+    async submitJperpRecoverNative(data) {
+        return this.submitEncrypted("/jperp/recover-native", data);
+    }
+    // ---------------------------------------------------------------------------
+    // Private Jupiter Predictions (encrypted payloads)
+    // ---------------------------------------------------------------------------
+    async submitPredictionOpen(data) {
+        return this.submitEncrypted("/predictions/open", data);
+    }
+    async submitPredictionReissue(data) {
+        return this.submitEncrypted("/predictions/reissue", data);
+    }
+    submitEncrypted(route, data) {
+        const encryptedPayload = this.encryptPayload(data);
+        return this.transport.request("POST", route, {
+            body: { encryptedPayload },
+            // These endpoints can land transactions; automatic replay is unsafe.
+            retryable: false,
+        });
+    }
+}

package/dist/esm/relayer/crypto.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Encrypt a JSON-serializable payload for the relayer using NaCl box.
+ * Layout: [ephemeralPubKey (32)] [nonce (24)] [ciphertext (...)]
+ */
+export declare function encryptForRelayer(data: unknown, relayerPublicKey: Uint8Array): string;

package/dist/esm/relayer/crypto.js

@@ -0,0 +1,20 @@
+import nacl from "tweetnacl";
+import { toBase64 } from "./encoding.js";
+// =============================================================================
+// Encryption
+// =============================================================================
+/**
+ * Encrypt a JSON-serializable payload for the relayer using NaCl box.
+ * Layout: [ephemeralPubKey (32)] [nonce (24)] [ciphertext (...)]
+ */
+export 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);
+}

package/dist/esm/relayer/encoding.d.ts

@@ -0,0 +1,2 @@
+export declare function toBase64(bytes: Uint8Array): string;
+export declare function fromBase64(str: string): Uint8Array;

package/dist/esm/relayer/encoding.js

@@ -0,0 +1,19 @@
+// =============================================================================
+// Base64 helpers (no dependency on tweetnacl-util)
+// =============================================================================
+export function toBase64(bytes) {
+    if (typeof Buffer !== "undefined") {
+        return Buffer.from(bytes).toString("base64");
+    }
+    return btoa(String.fromCharCode(...bytes));
+}
+export 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;
+}

package/dist/esm/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/esm/relayer/errors.js

@@ -0,0 +1,13 @@
+// =============================================================================
+// Structured Error
+// =============================================================================
+/** Structured error thrown by managed Veilo API helpers. */
+export class VeiloApiError extends Error {
+    constructor(code, message, status, details) {
+        super(message);
+        this.name = "VeiloApiError";
+        this.code = code;
+        this.status = status;
+        this.details = details;
+    }
+}

package/dist/esm/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/esm/relayer/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./api.js";

package/dist/esm/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/esm/relayer/internal-config.js

@@ -0,0 +1,6 @@
+/**
+ * Veilo network coordinates are protocol configuration, not integrator input.
+ * Keep them behind the public package entry points.
+ */
+export const VEILO_RELAYER_URL = "https://relayer-server.onrender.com";
+export const VEILO_RELAYER_PUBLIC_KEY = "utVxnA7zax09qJCZ7UJsa8PAOoWLRcCwOkdxg/ZGmD4=";

package/dist/esm/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/esm/relayer/internal.js

@@ -0,0 +1,10 @@
+import { VeiloRelayerClient } from "./client.js";
+const RELAYER = new VeiloRelayerClient();
+/** @internal Shared stateless production client for public SDK helpers. */
+export function getInternalRelayerClient() {
+    return RELAYER;
+}
+/** @internal Auth state is isolated per call to avoid cross-user token leaks. */
+export function createInternalRelayerClient(options = {}) {
+    return new VeiloRelayerClient(options);
+}

package/dist/esm/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/esm/relayer/transport.js

@@ -0,0 +1,64 @@
+import { VeiloApiError } from "./errors.js";
+import { VEILO_RELAYER_URL, } from "./internal-config.js";
+const DEFAULT_RETRY = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    retryableStatuses: [429, 502, 503, 504],
+};
+/** Owns HTTP authentication, retry, and response normalization. */
+export class RelayerHttpTransport {
+    constructor(config = {}, retry) {
+        this.baseUrl = (config.baseUrl?.trim() || 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 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 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;
+    }
+}