@veilo/sdk-core 0.4.0 → 0.5.0

package/dist/cjs/proofs/swap.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareSwapInputs = prepareSwapInputs;
+exports.formatSwapInputsForSnarkjs = formatSwapInputsForSnarkjs;
+exports.computeSwapParamsHash = computeSwapParamsHash;
+exports.computeSwapDataHash = computeSwapDataHash;
+const sha256_1 = require("@noble/hashes/sha256");
+const poseidon_js_1 = require("../poseidon.js");
+const nullifier_js_1 = require("../notes/nullifier.js");
+const transaction_js_1 = require("./transaction.js");
+/**
+ * Prepare the exact witness/public inputs used by the relayer's swap circuit.
+ * Output 0 must be source-mint change and output 1 the destination-mint note.
+ */
+function prepareSwapInputs(params) {
+    const { inputUTXOs, changeUTXO, destUTXO, sourceRoot, sourceMint, destMint, swapAmount, minAmountOut, deadline, extData, } = params;
+    const totalInput = inputUTXOs[0].amount + inputUTXOs[1].amount;
+    if (swapAmount <= 0n)
+        throw new Error("swapAmount must be positive");
+    if (deadline <= 0n) {
+        throw new Error("deadline must be a positive Unix timestamp");
+    }
+    if (totalInput !== swapAmount + changeUTXO.amount) {
+        throw new Error(`Swap balance mismatch: inputs=${totalInput}, swap=${swapAmount}, change=${changeUTXO.amount}`);
+    }
+    if (destUTXO.amount < minAmountOut) {
+        throw new Error("Destination note amount is below minAmountOut");
+    }
+    if (changeUTXO.mintAddress !== (0, poseidon_js_1.pubkeyToField)(sourceMint)) {
+        throw new Error("Change UTXO must use the source mint");
+    }
+    if (destUTXO.mintAddress !== (0, poseidon_js_1.pubkeyToField)(destMint)) {
+        throw new Error("Destination UTXO must use the destination mint");
+    }
+    return {
+        sourceRoot,
+        swapParamsHash: computeSwapParamsHash(sourceMint, destMint, minAmountOut, deadline, destUTXO.amount),
+        extDataHash: (0, transaction_js_1.computeExtDataHash)(extData),
+        sourceMint,
+        destMint,
+        inputNullifiers: [
+            (0, nullifier_js_1.deriveNullifier)(inputUTXOs[0], inputUTXOs[0].pathIndex, inputUTXOs[0].privateKey),
+            (0, nullifier_js_1.deriveNullifier)(inputUTXOs[1], inputUTXOs[1].pathIndex, inputUTXOs[1].privateKey),
+        ],
+        changeCommitment: changeUTXO.commitment,
+        destCommitment: destUTXO.commitment,
+        swapAmount,
+        inAmount: [inputUTXOs[0].amount, inputUTXOs[1].amount],
+        inPubkey: [inputUTXOs[0].pubkey, inputUTXOs[1].pubkey],
+        inBlinding: [inputUTXOs[0].blinding, inputUTXOs[1].blinding],
+        inPathIndex: [inputUTXOs[0].pathIndex, inputUTXOs[1].pathIndex],
+        inPathElements: [
+            inputUTXOs[0].pathElements.map((element) => (0, poseidon_js_1.bytesToBigIntBE)(element) % poseidon_js_1.BN254_FR_MODULUS),
+            inputUTXOs[1].pathElements.map((element) => (0, poseidon_js_1.bytesToBigIntBE)(element) % poseidon_js_1.BN254_FR_MODULUS),
+        ],
+        inPrivateKey: [inputUTXOs[0].privateKey, inputUTXOs[1].privateKey],
+        changeAmount: changeUTXO.amount,
+        changePubkey: changeUTXO.pubkey,
+        changeBlinding: changeUTXO.blinding,
+        destAmount: destUTXO.amount,
+        destPubkey: destUTXO.pubkey,
+        destBlinding: destUTXO.blinding,
+        minAmountOut,
+        deadline,
+    };
+}
+/**
+ * Convert SwapCircuitInputs into the shape expected by
+ * snarkjs.groth16.fullProve() for swap.circom. Every value is emitted as a
+ * decimal string (or string array) because snarkjs only accepts field
+ * elements as strings.
+ *
+ * Mirrors `generateSwapProof` in
+ * relayer-server/src/controllers/swap.helpers.ts so SDK-side swap proofs
+ * verify against the same circuit the relayer uses.
+ */
+function formatSwapInputsForSnarkjs(inputs) {
+    return {
+        // Public inputs
+        sourceRoot: (0, poseidon_js_1.bytesToBigIntBE)(inputs.sourceRoot).toString(),
+        swapParamsHash: (0, poseidon_js_1.bytesToBigIntBE)(inputs.swapParamsHash).toString(),
+        extDataHash: (0, poseidon_js_1.bytesToBigIntBE)(inputs.extDataHash).toString(),
+        sourceMint: (0, poseidon_js_1.pubkeyToField)(inputs.sourceMint).toString(),
+        destMint: (0, poseidon_js_1.pubkeyToField)(inputs.destMint).toString(),
+        inputNullifier: inputs.inputNullifiers.map((n) => (0, poseidon_js_1.bytesToBigIntBE)(n).toString()),
+        changeCommitment: (0, poseidon_js_1.bytesToBigIntBE)(inputs.changeCommitment).toString(),
+        destCommitment: (0, poseidon_js_1.bytesToBigIntBE)(inputs.destCommitment).toString(),
+        swapAmount: inputs.swapAmount.toString(),
+        // Private inputs - Input UTXOs
+        inAmount: inputs.inAmount.map((a) => a.toString()),
+        inPubkey: inputs.inPubkey.map((p) => p.toString()),
+        inBlinding: inputs.inBlinding.map((b) => b.toString()),
+        inPathIndex: inputs.inPathIndex.map((i) => i.toString()),
+        inPathElements: inputs.inPathElements.map((path) => path.map((e) => e.toString())),
+        inPrivateKey: inputs.inPrivateKey.map((k) => k.toString()),
+        // Private inputs - Change UTXO
+        changeAmount: inputs.changeAmount.toString(),
+        changePubkey: inputs.changePubkey.toString(),
+        changeBlinding: inputs.changeBlinding.toString(),
+        // Private inputs - Destination UTXO
+        destAmount: inputs.destAmount.toString(),
+        destPubkey: inputs.destPubkey.toString(),
+        destBlinding: inputs.destBlinding.toString(),
+        // Swap params
+        minAmountOut: inputs.minAmountOut.toString(),
+        deadline: inputs.deadline.toString(),
+    };
+}
+// -----------------------------------------------------------------------------
+// Swap Parameter Hashing
+// -----------------------------------------------------------------------------
+/**
+ * Compute the swap params hash that the swap circuit and on-chain program verify.
+ * Mirrors relayer-server/src/controllers/swap.helpers.ts `computeSwapParamsHash`.
+ *
+ * Circuit formula (swap.circom lines 293-307):
+ *   mintPairHash   = Poseidon(sourceMint, destMint)
+ *   swapTermsHash  = Poseidon(minAmountOut, deadline, destAmount)
+ *   swapParamsHash = Poseidon(mintPairHash, swapTermsHash)
+ *
+ * @param sourceMint   Source pool mint
+ * @param destMint     Destination pool mint
+ * @param minAmountOut Minimum accepted output amount (slippage protected)
+ * @param deadline     Positive Unix timestamp deadline (the program rejects 0)
+ * @param destAmount   Actual amount committed to destination UTXO (≥ minAmountOut -
+ *                     relayerFee). If omitted, defaults to minAmountOut.
+ */
+function computeSwapParamsHash(sourceMint, destMint, minAmountOut, deadline, destAmount) {
+    const srcField = (0, poseidon_js_1.pubkeyToField)(sourceMint);
+    const dstField = (0, poseidon_js_1.pubkeyToField)(destMint);
+    const mintPairHash = (0, poseidon_js_1.poseidon2)(srcField, dstField);
+    const dest = destAmount ?? minAmountOut;
+    const swapTermsHash = (0, poseidon_js_1.poseidon3)(minAmountOut, deadline, dest);
+    const paramsHash = (0, poseidon_js_1.poseidon2)(mintPairHash, swapTermsHash);
+    return (0, poseidon_js_1.bigIntToBytesBE)(paramsHash);
+}
+/**
+ * Compute the swap data hash committed on-chain for Jupiter instruction integrity.
+ * SHA-256 of the raw Jupiter swap instruction data bytes.
+ * Mirrors relayer-server/src/controllers/swap.helpers.ts `computeSwapDataHash`.
+ */
+function computeSwapDataHash(swapData) {
+    return (0, sha256_1.sha256)(swapData instanceof Buffer ? new Uint8Array(swapData) : swapData);
+}

package/dist/cjs/proofs/transaction.d.ts

@@ -0,0 +1,28 @@
+import { PublicKey } from "@solana/web3.js";
+import type { InputUTXO, SerializedUTXO } from "../notes/model.js";
+import type { ExtData, TransactionCircuitInputs } from "./types.js";
+/**
+ * Compute the external data hash.
+ * Matches on-chain computation:
+ *   hash1 = Poseidon(recipient, relayer)
+ *   hash2 = Poseidon(fee, refund)
+ *   extDataHash = Poseidon(hash1, hash2, claimant)
+ */
+export declare function computeExtDataHash(extData: ExtData): Uint8Array;
+/**
+ * Convert i64 to field element (handles negative via modular arithmetic).
+ * For negative values, we add the field modulus to get the equivalent positive representation.
+ */
+export declare function i64ToField(value: bigint): bigint;
+/**
+ * Prepare transaction circuit inputs from high-level parameters.
+ * This converts the SDK types into the format expected by the circuit.
+ */
+export declare function prepareTransactionInputs(params: {
+    inputUTXOs: [InputUTXO, InputUTXO];
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    root: Uint8Array;
+    publicAmount: bigint;
+    extData: ExtData;
+    mintAddress: PublicKey;
+}): TransactionCircuitInputs;

package/dist/cjs/proofs/transaction.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeExtDataHash = computeExtDataHash;
+exports.i64ToField = i64ToField;
+exports.prepareTransactionInputs = prepareTransactionInputs;
+const poseidon_js_1 = require("../poseidon.js");
+const nullifier_js_1 = require("../notes/nullifier.js");
+// -----------------------------------------------------------------------------
+// ExtData Hash Computation
+// -----------------------------------------------------------------------------
+/**
+ * Compute the external data hash.
+ * Matches on-chain computation:
+ *   hash1 = Poseidon(recipient, relayer)
+ *   hash2 = Poseidon(fee, refund)
+ *   extDataHash = Poseidon(hash1, hash2, claimant)
+ */
+function computeExtDataHash(extData) {
+    const recipientField = (0, poseidon_js_1.pubkeyToField)(extData.recipient);
+    const relayerField = (0, poseidon_js_1.pubkeyToField)(extData.relayer);
+    const feeField = extData.fee % poseidon_js_1.BN254_FR_MODULUS;
+    const refundField = extData.refund % poseidon_js_1.BN254_FR_MODULUS;
+    const claimantField = (0, poseidon_js_1.pubkeyToField)(extData.claimant);
+    const hash1 = (0, poseidon_js_1.poseidon2)(recipientField, relayerField);
+    const hash2 = (0, poseidon_js_1.poseidon2)(feeField, refundField);
+    const finalHash = (0, poseidon_js_1.poseidon3)(hash1, hash2, claimantField);
+    return (0, poseidon_js_1.bigIntToBytesBE)(finalHash);
+}
+// -----------------------------------------------------------------------------
+// Circuit Input Preparation
+// -----------------------------------------------------------------------------
+/**
+ * Convert i64 to field element (handles negative via modular arithmetic).
+ * For negative values, we add the field modulus to get the equivalent positive representation.
+ */
+function i64ToField(value) {
+    if (value >= 0n) {
+        return value % poseidon_js_1.BN254_FR_MODULUS;
+    }
+    return (poseidon_js_1.BN254_FR_MODULUS + value) % poseidon_js_1.BN254_FR_MODULUS;
+}
+/**
+ * Prepare transaction circuit inputs from high-level parameters.
+ * This converts the SDK types into the format expected by the circuit.
+ */
+function prepareTransactionInputs(params) {
+    const { inputUTXOs, outputUTXOs, root, publicAmount, extData, mintAddress } = params;
+    const extDataHash = computeExtDataHash(extData);
+    const mintField = (0, poseidon_js_1.pubkeyToField)(mintAddress);
+    // Prepare input UTXO data
+    const inAmount = [
+        inputUTXOs[0].amount,
+        inputUTXOs[1].amount,
+    ];
+    const inPubkey = [
+        inputUTXOs[0].pubkey,
+        inputUTXOs[1].pubkey,
+    ];
+    const inBlinding = [
+        inputUTXOs[0].blinding,
+        inputUTXOs[1].blinding,
+    ];
+    const inPathIndex = [
+        inputUTXOs[0].pathIndex,
+        inputUTXOs[1].pathIndex,
+    ];
+    const inPathElements = [
+        inputUTXOs[0].pathElements.map((e) => (0, poseidon_js_1.bytesToBigIntBE)(e) % poseidon_js_1.BN254_FR_MODULUS),
+        inputUTXOs[1].pathElements.map((e) => (0, poseidon_js_1.bytesToBigIntBE)(e) % poseidon_js_1.BN254_FR_MODULUS),
+    ];
+    const inPrivateKey = [
+        inputUTXOs[0].privateKey,
+        inputUTXOs[1].privateKey,
+    ];
+    // Prepare output UTXO data
+    const outAmount = [
+        outputUTXOs[0].amount,
+        outputUTXOs[1].amount,
+    ];
+    const outPubkey = [
+        outputUTXOs[0].pubkey,
+        outputUTXOs[1].pubkey,
+    ];
+    const outBlinding = [
+        outputUTXOs[0].blinding,
+        outputUTXOs[1].blinding,
+    ];
+    // Derive nullifiers for input UTXOs
+    const inputNullifiers = [
+        (0, nullifier_js_1.deriveNullifier)(inputUTXOs[0], inputUTXOs[0].pathIndex, inputUTXOs[0].privateKey),
+        (0, nullifier_js_1.deriveNullifier)(inputUTXOs[1], inputUTXOs[1].pathIndex, inputUTXOs[1].privateKey),
+    ];
+    return {
+        root,
+        publicAmount,
+        extDataHash,
+        mintAddress,
+        inputNullifiers,
+        outputCommitments: [outputUTXOs[0].commitment, outputUTXOs[1].commitment],
+        inAmount,
+        inPubkey,
+        inBlinding,
+        inPathIndex,
+        inPathElements,
+        inPrivateKey,
+        outAmount,
+        outPubkey,
+        outBlinding,
+    };
+}

package/dist/cjs/proofs/types.d.ts

@@ -0,0 +1,70 @@
+import { PublicKey } from "@solana/web3.js";
+/**
+ * External data that gets hashed into ext_data_hash.
+ * These are public parameters that affect financial flows.
+ */
+export type ExtData = {
+    /** Who receives withdrawal (for withdrawals) */
+    recipient: PublicKey;
+    /** Who submits tx and gets fee */
+    relayer: PublicKey;
+    /** Fee to relayer in lamports/token units */
+    fee: bigint;
+    /** Refund to user in lamports/token units (for gas compensation) */
+    refund: bigint;
+    /** Claimant key committed into the proof */
+    claimant: PublicKey;
+};
+/**
+ * Transaction circuit inputs (8 public inputs, many private inputs).
+ * This structure is used to prepare inputs for the snarkjs prover.
+ */
+export type TransactionCircuitInputs = {
+    /** Merkle root of UTXO tree */
+    root: Uint8Array;
+    /** Net deposit/withdrawal amount (positive = deposit, negative = withdrawal) */
+    publicAmount: bigint;
+    /** Hash of external data (recipient, relayer, fee, refund) */
+    extDataHash: Uint8Array;
+    /** Token mint address */
+    mintAddress: PublicKey;
+    /** Nullifiers for the two input UTXOs */
+    inputNullifiers: [Uint8Array, Uint8Array];
+    /** Commitments for the two output UTXOs */
+    outputCommitments: [Uint8Array, Uint8Array];
+    inAmount: [bigint, bigint];
+    inPubkey: [bigint, bigint];
+    inBlinding: [bigint, bigint];
+    inPathIndex: [number, number];
+    inPathElements: [bigint[], bigint[]];
+    inPrivateKey: [bigint, bigint];
+    outAmount: [bigint, bigint];
+    outPubkey: [bigint, bigint];
+    outBlinding: [bigint, bigint];
+};
+/**
+ * Proof structure matching the on-chain TransactionProof struct.
+ * Total size: 256 bytes (64 + 128 + 64)
+ */
+export type TransactionProofStruct = {
+    /** G1 point A (64 bytes) */
+    proofA: number[];
+    /** G2 point B (128 bytes) */
+    proofB: number[];
+    /** G1 point C (64 bytes) */
+    proofC: number[];
+};
+/**
+ * Shape of a Groth16 proof produced by snarkjs.
+ */
+export type RawProof = {
+    pi_a: [string, string, string];
+    pi_b: [[string, string], [string, string], [string, string]];
+    pi_c: [string, string, string];
+    protocol: string;
+    curve: string;
+};
+/**
+ * Proof builder function type - takes circuit inputs and returns a raw snarkjs proof.
+ */
+export type TransactionProofBuilder = (inputs: TransactionCircuitInputs) => Promise<RawProof>;

package/dist/cjs/prover.d.ts

@@ -1,4 +1,5 @@
-import { TransactionProofBuilder, RawProof } from "./proof.js";
+import type { TransactionProofBuilder, RawProof } from "./proofs/types.js";
+import { type SwapProofBuilder } from "./proofs/swap.js";
 /**
  * Circuit artifact paths required by snarkjs.
  *
@@ -41,6 +42,8 @@ export interface CircuitArtifacts {
  * ```
  */
 export declare function createTransactionProver(artifacts: CircuitArtifacts): TransactionProofBuilder;
+/** Create a proof builder for the current `swap.circom` witness shape. */
+export declare function createSwapProver(artifacts: CircuitArtifacts): SwapProofBuilder;
 /**
  * Verify a Groth16 proof against public signals and a verification key.
  *

package/dist/cjs/prover.js

@@ -34,8 +34,10 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTransactionProver = createTransactionProver;
+exports.createSwapProver = createSwapProver;
 exports.verifyProof = verifyProof;
-const proof_js_1 = require("./proof.js");
+const formatting_js_1 = require("./proofs/formatting.js");
+const swap_js_1 = require("./proofs/swap.js");
 /** Lazy-load snarkjs — works in both CJS and ESM contexts. */
 async function loadSnarkjs() {
     try {
@@ -75,11 +77,19 @@ async function loadSnarkjs() {
 function createTransactionProver(artifacts) {
     return async (inputs) => {
         const snarkjs = await loadSnarkjs();
-        const formattedInputs = (0, proof_js_1.formatInputsForSnarkjs)(inputs);
+        const formattedInputs = (0, formatting_js_1.formatInputsForSnarkjs)(inputs);
         const { proof } = await snarkjs.groth16.fullProve(formattedInputs, artifacts.wasmPath, artifacts.zkeyPath);
         return proof;
     };
 }
+/** Create a proof builder for the current `swap.circom` witness shape. */
+function createSwapProver(artifacts) {
+    return async (inputs) => {
+        const snarkjs = await loadSnarkjs();
+        const { proof } = await snarkjs.groth16.fullProve((0, swap_js_1.formatSwapInputsForSnarkjs)(inputs), artifacts.wasmPath, artifacts.zkeyPath);
+        return proof;
+    };
+}
 /**
  * Verify a Groth16 proof against public signals and a verification key.
  *

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

@@ -0,0 +1,61 @@
+import type { ChallengeResponse, CheckUsernameResponse, DeleteUserDataResponse, MerkleRootResponse, MerkleTreeResponse, PreRegisterKeyResponse, PrivateSwapRequest, PrivateSwapResponse, PrivateTransferRequest, PrivateTransferResponse, QueryNotesRequest, QueryNotesResponse, RegisterRequest, RegisterResponse, RestoreRequest, RestoreResponse, RetryPolicy, SaveEncryptedNoteRequest, SaveEncryptedNoteResponse, VeiloPublicKeyResponse, VeiloRelayerConfig, WithdrawRequest, WithdrawResponse } from "./types.js";
+/**
+ * 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 transport;
+    private readonly relayerPubKey;
+    constructor(config: VeiloRelayerConfig, retry?: Partial<RetryPolicy>);
+    /** Update the auth token (e.g. after register/restore). */
+    setAuthToken(token: string): void;
+    private encryptPayload;
+    /** 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/client.js

@@ -0,0 +1,151 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VeiloRelayerClient = void 0;
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const crypto_js_1 = require("./crypto.js");
+const encoding_js_1 = require("./encoding.js");
+const transport_js_1 = require("./transport.js");
+// =============================================================================
+// 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...");
+ * ```
+ */
+class VeiloRelayerClient {
+    constructor(config, retry) {
+        this.transport = new transport_js_1.RelayerHttpTransport(config, retry);
+        this.relayerPubKey = (0, encoding_js_1.fromBase64)(config.relayerPublicKey);
+    }
+    /** Update the auth token (e.g. after register/restore). */
+    setAuthToken(token) {
+        this.transport.setAuthToken(token);
+    }
+    encryptPayload(data) {
+        return (0, crypto_js_1.encryptForRelayer)({
+            ...data,
+            timestamp: Date.now(),
+            nonce: (0, encoding_js_1.toBase64)(tweetnacl_1.default.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. */
+    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,
+        });
+    }
+}
+exports.VeiloRelayerClient = VeiloRelayerClient;

package/dist/cjs/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/cjs/relayer/crypto.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encryptForRelayer = encryptForRelayer;
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const encoding_js_1 = require("./encoding.js");
+// =============================================================================
+// 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 (0, encoding_js_1.toBase64)(payload);
+}

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

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