@veilo/sdk-core 0.4.0 → 0.5.0

package/dist/esm/transactions/transfer.d.ts

@@ -0,0 +1,51 @@
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { Keypair, PublicKey } from "@solana/web3.js";
+import type { TransactionProofBuilder } from "../proofs/types.js";
+import type { InputUTXO, SerializedUTXO } from "../notes/model.js";
+import { MerkleTree } from "../merkle.js";
+import { type NoteCiphers } from "../compactNote.js";
+export type TransferResult = {
+    /** Output UTXOs created by the transfer */
+    outputUTXOs: [SerializedUTXO, SerializedUTXO];
+    /** Leaf indices where the UTXOs were inserted */
+    leafIndices: [number, number];
+    /** New Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * Execute a private transfer within the pool.
+ *
+ * For transfers, the publicAmount is 0 (no funds enter or leave the pool).
+ * Input amounts must equal output amounts.
+ *
+ * @param inputUTXOs - The UTXOs being spent
+ * @param outputPubkeys - UTXO public keys for the recipients
+ * @param outputAmounts - Amounts for each output (must sum to input total)
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where output commitments will be inserted
+ */
+export declare function privateTransfer<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    mintAddress: PublicKey;
+    inputUTXOs: [InputUTXO, InputUTXO];
+    outputPubkeys: [bigint, bigint];
+    outputAmounts: [bigint, bigint];
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    /** Must be zero: the program rejects fees on publicAmount=0 transfers. */
+    fee?: bigint;
+    deadline?: bigint;
+    /** Public recipient account committed in ExtData (no funds are sent to it). */
+    externalRecipient?: PublicKey;
+    /** Wallet keys used to encrypt output notes for on-chain recovery. */
+    noteRecipientWallets?: [
+        PublicKey | Uint8Array | null,
+        PublicKey | Uint8Array | null
+    ];
+    /** Prebuilt note ciphers. Takes precedence over noteRecipientWallets. */
+    noteCiphers?: NoteCiphers | null;
+}): Promise<TransferResult>;

package/dist/esm/transactions/transfer.js

@@ -0,0 +1,103 @@
+import { Keypair, PublicKey, SystemProgram } from "@solana/web3.js";
+import { prepareTransactionInputs } from "../proofs/transaction.js";
+import { encodeSnarkjsProofToTransactionProof } from "../proofs/encoding.js";
+import { createUTXO } from "../notes/model.js";
+import { transact } from "./transact.js";
+import { bigIntToBytesBE } from "../poseidon.js";
+import { createNoteCiphers, } from "../compactNote.js";
+/**
+ * Execute a private transfer within the pool.
+ *
+ * For transfers, the publicAmount is 0 (no funds enter or leave the pool).
+ * Input amounts must equal output amounts.
+ *
+ * @param inputUTXOs - The UTXOs being spent
+ * @param outputPubkeys - UTXO public keys for the recipients
+ * @param outputAmounts - Amounts for each output (must sum to input total)
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where output commitments will be inserted
+ */
+export async function privateTransfer(params) {
+    const { program, relayer, mintAddress, inputUTXOs, outputPubkeys, outputAmounts, root, inputTreeId, outputTreeId, tree, proofBuilder, fee = 0n, deadline = BigInt(Math.floor(Date.now() / 1000) + 600), externalRecipient = Keypair.generate().publicKey, noteRecipientWallets, noteCiphers, } = params;
+    if (fee !== 0n) {
+        throw new Error("Private transact transfers require fee=0; represent any relayer fee in the output amounts");
+    }
+    const totalInput = inputUTXOs[0].amount + inputUTXOs[1].amount;
+    const totalOutput = outputAmounts[0] + outputAmounts[1];
+    if (totalInput !== totalOutput) {
+        throw new Error(`Balance mismatch: inputs=${totalInput}, outputs=${totalOutput}`);
+    }
+    const outputUTXO0 = createUTXO({
+        amount: outputAmounts[0],
+        pubkey: outputPubkeys[0],
+        mintAddress,
+    });
+    const outputUTXO1 = createUTXO({
+        amount: outputAmounts[1],
+        pubkey: outputPubkeys[1],
+        mintAddress,
+    });
+    const outputUTXOs = [
+        outputUTXO0,
+        outputUTXO1,
+    ];
+    const extData = {
+        recipient: externalRecipient,
+        relayer: relayer.publicKey,
+        fee: 0n,
+        refund: 0n,
+        claimant: SystemProgram.programId,
+    };
+    // publicAmount is 0 for transfers
+    const publicAmount = 0n;
+    const circuitInputs = prepareTransactionInputs({
+        inputUTXOs,
+        outputUTXOs,
+        root,
+        publicAmount,
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = encodeSnarkjsProofToTransactionProof(rawProof);
+    const walletBytes = (wallet) => wallet instanceof PublicKey ? wallet.toBytes() : wallet;
+    const transferNoteCiphers = noteCiphers ??
+        (noteRecipientWallets
+            ? createNoteCiphers(noteRecipientWallets[0]
+                ? {
+                    recipientWalletPubkey: walletBytes(noteRecipientWallets[0]),
+                    blinding: bigIntToBytesBE(outputUTXOs[0].blinding),
+                    amount: outputUTXOs[0].amount,
+                }
+                : null, noteRecipientWallets[1]
+                ? {
+                    recipientWalletPubkey: walletBytes(noteRecipientWallets[1]),
+                    blinding: bigIntToBytesBE(outputUTXOs[1].blinding),
+                    amount: outputUTXOs[1].amount,
+                }
+                : null)
+            : null);
+    await transact({
+        program,
+        relayer,
+        recipient: externalRecipient,
+        mintAddress,
+        root,
+        inputTreeId,
+        outputTreeId,
+        publicAmount,
+        inputNullifiers: circuitInputs.inputNullifiers,
+        outputCommitments: circuitInputs.outputCommitments,
+        extData,
+        proof,
+        deadline,
+        noteCiphers: transferNoteCiphers,
+    });
+    const { index: outIdx0 } = tree.insert(outputUTXOs[0].commitment);
+    const { index: outIdx1, root: newRoot } = tree.insert(outputUTXOs[1].commitment);
+    return {
+        outputUTXOs,
+        leafIndices: [outIdx0, outIdx1],
+        root: newRoot,
+    };
+}

package/dist/esm/transactions/withdraw.d.ts

@@ -0,0 +1,52 @@
+import type { Program, Idl } from "@coral-xyz/anchor";
+import { Keypair, PublicKey } from "@solana/web3.js";
+import type { TransactionProofBuilder } from "../proofs/types.js";
+import type { InputUTXO, SerializedUTXO } from "../notes/model.js";
+import { MerkleTree } from "../merkle.js";
+import { type NoteCiphers } from "../compactNote.js";
+export type WithdrawResult = {
+    /** Change UTXO (remaining balance) */
+    changeUTXO: SerializedUTXO;
+    /** Leaf index of the change UTXO */
+    leafIndex: number;
+    /** New Merkle root after insertion */
+    root: Uint8Array;
+};
+/**
+ * Withdraw funds from the privacy pool.
+ *
+ * For withdrawals, we spend input UTXOs and create change output UTXOs.
+ * The publicAmount is negative (funds flowing out).
+ *
+ * @param withdrawAmount - Amount to withdraw in lamports/token units
+ * @param inputUTXOs - The UTXOs being spent
+ * @param changePubkey - UTXO public key for the change output
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where change outputs will be inserted
+ */
+export declare function withdraw<T extends Idl>(params: {
+    program: Program<T>;
+    relayer: Keypair;
+    recipient: PublicKey;
+    mintAddress: PublicKey;
+    inputUTXOs: [InputUTXO, InputUTXO];
+    changePubkey: bigint;
+    withdrawAmount: bigint;
+    fee: bigint;
+    refund: bigint;
+    root: Uint8Array;
+    inputTreeId: number;
+    outputTreeId: number;
+    tree: MerkleTree;
+    proofBuilder: TransactionProofBuilder;
+    /** When true, the fee is debited in addition to withdrawAmount. */
+    feeOnTop?: boolean;
+    deadline?: bigint;
+    /** Solana wallet key used to encrypt the change note for chain recovery. */
+    changeNoteRecipientWallet?: PublicKey | Uint8Array;
+    /** Prebuilt recovery payload. Takes precedence over changeNoteRecipientWallet. */
+    noteCiphers?: NoteCiphers | null;
+}): Promise<WithdrawResult>;
+/**
+ * Result of a private transfer operation.
+ */

package/dist/esm/transactions/withdraw.js

@@ -0,0 +1,101 @@
+import { PublicKey, SystemProgram } from "@solana/web3.js";
+import { prepareTransactionInputs } from "../proofs/transaction.js";
+import { encodeSnarkjsProofToTransactionProof } from "../proofs/encoding.js";
+import { createUTXO, generateKeypair } from "../notes/model.js";
+import { transact } from "./transact.js";
+import { bigIntToBytesBE } from "../poseidon.js";
+import { createNoteCiphers, } from "../compactNote.js";
+/**
+ * Withdraw funds from the privacy pool.
+ *
+ * For withdrawals, we spend input UTXOs and create change output UTXOs.
+ * The publicAmount is negative (funds flowing out).
+ *
+ * @param withdrawAmount - Amount to withdraw in lamports/token units
+ * @param inputUTXOs - The UTXOs being spent
+ * @param changePubkey - UTXO public key for the change output
+ * @param inputTreeId - The tree ID where input UTXOs are located
+ * @param outputTreeId - The tree ID where change outputs will be inserted
+ */
+export async function withdraw(params) {
+    const { program, relayer, recipient, mintAddress, inputUTXOs, changePubkey, withdrawAmount, fee, refund, root, inputTreeId, outputTreeId, tree, proofBuilder, feeOnTop = false, deadline = BigInt(Math.floor(Date.now() / 1000) + 600), changeNoteRecipientWallet, noteCiphers, } = params;
+    const totalInput = inputUTXOs[0].amount + inputUTXOs[1].amount;
+    const outflowAmount = feeOnTop ? withdrawAmount + fee : withdrawAmount;
+    const changeAmount = totalInput - outflowAmount;
+    if (withdrawAmount <= 0n) {
+        throw new Error("Withdrawal amount must be positive");
+    }
+    if (fee < 0n || refund < 0n || fee + refund > outflowAmount) {
+        throw new Error("Withdrawal fee and refund must fit within the public outflow");
+    }
+    if (changeAmount < 0n) {
+        throw new Error("Insufficient input balance for withdrawal");
+    }
+    const changeUTXO = createUTXO({
+        amount: changeAmount,
+        pubkey: changePubkey,
+        mintAddress,
+    });
+    const zeroUTXO = createUTXO({
+        amount: 0n,
+        pubkey: generateKeypair().publicKey,
+        mintAddress,
+    });
+    const outputUTXOs = [changeUTXO, zeroUTXO];
+    const extData = {
+        recipient,
+        relayer: relayer.publicKey,
+        fee,
+        refund,
+        claimant: SystemProgram.programId,
+    };
+    // publicAmount is negative for withdrawals
+    const publicAmount = -outflowAmount;
+    const circuitInputs = prepareTransactionInputs({
+        inputUTXOs,
+        outputUTXOs,
+        root,
+        publicAmount,
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = encodeSnarkjsProofToTransactionProof(rawProof);
+    const withdrawNoteCiphers = noteCiphers !== undefined
+        ? noteCiphers
+        : changeNoteRecipientWallet && changeAmount > 0n
+            ? createNoteCiphers({
+                recipientWalletPubkey: changeNoteRecipientWallet instanceof PublicKey
+                    ? changeNoteRecipientWallet.toBytes()
+                    : changeNoteRecipientWallet,
+                blinding: bigIntToBytesBE(changeUTXO.blinding),
+                amount: changeAmount,
+            }, null)
+            : null;
+    await transact({
+        program,
+        relayer,
+        recipient,
+        mintAddress,
+        root,
+        inputTreeId,
+        outputTreeId,
+        publicAmount,
+        inputNullifiers: circuitInputs.inputNullifiers,
+        outputCommitments: circuitInputs.outputCommitments,
+        extData,
+        proof,
+        deadline,
+        noteCiphers: withdrawNoteCiphers,
+    });
+    const { index: changeIdx } = tree.insert(changeUTXO.commitment);
+    const { root: newRoot } = tree.insert(zeroUTXO.commitment);
+    return {
+        changeUTXO,
+        leafIndex: changeIdx,
+        root: newRoot,
+    };
+}
+/**
+ * Result of a private transfer operation.
+ */

package/dist/esm/utxo.d.ts

@@ -1,235 +1 @@
-import { PublicKey } from "@solana/web3.js";
-/**
- * Keypair for UTXO ownership.
- * Public key is derived via Poseidon: pubkey = Poseidon(privateKey)
- */
-export type Keypair = {
-    privateKey: bigint;
-    publicKey: bigint;
-};
-/**
- * UTXO structure matching the circuit's UTXOCommitment template.
- * commitment = Poseidon(amount, pubkey, blinding, mintAddress)
- */
-export type UTXO = {
-    /** Amount in lamports/token units */
-    amount: bigint;
-    /** Owner's public key (derived from private key via Poseidon) */
-    pubkey: bigint;
-    /** Random blinding factor for commitment privacy */
-    blinding: bigint;
-    /** Token mint address as field element */
-    mintAddress: bigint;
-};
-/**
- * Serialized UTXO with precomputed commitment and optional ownership data.
- */
-export type SerializedUTXO = UTXO & {
-    /** 32-byte commitment: Poseidon(amount, pubkey, blinding, mintAddress) */
-    commitment: Uint8Array;
-    /** Private key for spending (only present for owned UTXOs) */
-    privateKey?: bigint;
-    /** Leaf index in the Merkle tree (set after insertion) */
-    pathIndex?: number;
-};
-/**
- * Input UTXO with Merkle proof data for spending.
- */
-export type InputUTXO = SerializedUTXO & {
-    /** Leaf index in the Merkle tree */
-    pathIndex: number;
-    /** Merkle path elements (sibling hashes from leaf to root) */
-    pathElements: Uint8Array[];
-    /** Private key for nullifier derivation */
-    privateKey: bigint;
-};
-/**
- * Generate a random keypair.
- * Private key is a random 32-byte scalar.
- * Public key is derived via Poseidon: pubkey = Poseidon(privateKey)
- */
-export declare function generateKeypair(): Keypair;
-/**
- * Derive public key from private key.
- * Matches circuit's Keypair template: publicKey = Poseidon(privateKey)
- */
-export declare function derivePublicKey(privateKey: bigint): bigint;
-/**
- * Create keypair from a known private key.
- */
-export declare function keypairFromPrivateKey(privateKey: bigint): Keypair;
-/**
- * Compute UTXO commitment.
- * Matches circuit's UTXOCommitment template:
- *   commitment = Poseidon(amount, pubkey, blinding, mintAddress)
- */
-export declare function commitUTXO(utxo: UTXO): Uint8Array;
-/**
- * Create a random UTXO with the given parameters.
- */
-export declare function createUTXO(params: {
-    amount: bigint;
-    pubkey: bigint;
-    mintAddress: PublicKey;
-}): SerializedUTXO;
-/**
- * Create a UTXO with a specified private key (for owned UTXOs).
- */
-export declare function createOwnedUTXO(params: {
-    amount: bigint;
-    privateKey: bigint;
-    mintAddress: PublicKey;
-}): SerializedUTXO;
-/**
- * Create a zero UTXO (for deposits where no input exists).
- * Zero UTXOs have amount=0 and are used as placeholders in 2-in-2-out transactions.
- */
-export declare function createZeroUTXO(pubkey: bigint, mintAddress: PublicKey): SerializedUTXO;
-/**
- * Create a zero UTXO with private key (for owned zero UTXOs).
- */
-export declare function createOwnedZeroUTXO(privateKey: bigint, mintAddress: PublicKey): SerializedUTXO;
-/**
- * Compute signature for nullifier derivation.
- * Matches circuit's Signature template:
- *   signature = Poseidon(privateKey, commitment, pathIndex)
- */
-export declare function computeSignature(privateKey: bigint, commitment: bigint, pathIndex: bigint): bigint;
-/**
- * Derive nullifier for a UTXO.
- * Matches circuit's UTXONullifier template:
- *   signature = Poseidon(privateKey, commitment, pathIndex)
- *   nullifier = Poseidon(commitment, pathIndex, signature)
- *
- * The signature-based nullifier ensures only the private key holder can spend.
- */
-export declare function deriveNullifier(utxo: SerializedUTXO, pathIndex: number, privateKey: bigint): Uint8Array;
-/**
- * Convert InputUTXO to the format expected by the circuit.
- */
-export declare function inputUTXOToCircuitFormat(input: InputUTXO): {
-    amount: bigint;
-    pubkey: bigint;
-    blinding: bigint;
-    pathElements: bigint[];
-    pathIndex: number;
-    privateKey: bigint;
-};
-/**
- * Encrypted UTXO note — can be broadcast alongside a transaction so the
- * recipient can recover their note without a server.
- */
-export type EncryptedNote = {
-    /** 24-byte NaCl box nonce */
-    nonce: Uint8Array;
-    /** Ciphertext containing amount + blinding + privateKey */
-    ciphertext: Uint8Array;
-    /** Sender's ephemeral 32-byte X25519 public key */
-    senderEphemeralPubkey: Uint8Array;
-};
-/**
- * Derive a NaCl X25519 encryption keypair from a UTXO private key.
- * The keypair is deterministic: same privateKey always yields the same pair.
- */
-export declare function deriveEncryptionKeypair(privateKey: bigint): {
-    publicKey: Uint8Array;
-    secretKey: Uint8Array;
-};
-/**
- * Encrypt a UTXO so the recipient can recover it from on-chain events.
- *
- * Plaintext layout (72 bytes):
- *   [0..8]   amount  — 8-byte little-endian u64
- *   [8..40]  blinding — 32-byte big-endian field element
- *   [40..72] privateKey — 32-byte big-endian field element
- *
- * Uses ephemeral-key NaCl box so the sender key is single-use.
- */
-export declare function encryptUTXONote(utxo: SerializedUTXO & {
-    privateKey: bigint;
-}, recipientEncPubkey: Uint8Array): EncryptedNote;
-/**
- * Try to decrypt an encrypted UTXO note using the recipient's private key.
- * Returns the SerializedUTXO if decryption succeeds and the commitment
- * matches, or `null` if the note was not intended for this key.
- */
-export declare function decryptUTXONote(note: EncryptedNote, recipientPrivateKey: bigint, commitment: Uint8Array, mintAddress: PublicKey): SerializedUTXO | null;
-/** Note data stored inside a Blind Mailbox encrypted blob */
-export type BlindMailboxNoteData = {
-    blinding: Uint8Array;
-    leafIndex: number;
-    commitment: Uint8Array;
-    amount: bigint;
-    mintAddress: string;
-    treeId: number;
-};
-/** Encrypted note as returned by the relayer's /api/notes endpoint */
-export type BlindMailboxNote = {
-    commitment: string;
-    ephemeralPublicKey: string;
-    encryptedBlob: string;
-    timestamp?: number;
-    blockHeight?: number;
-    txSignature?: string;
-};
-/** Decrypted note data after calling decryptBlindMailboxNote */
-export type DecryptedNote = {
-    blinding: Uint8Array;
-    leafIndex: number;
-    commitment: Uint8Array;
-    amount: bigint;
-    timestamp: number;
-    mintAddress?: string;
-    treeId: number;
-};
-/** Derive 32-byte encryption key from a shared secret using SHA-512 truncated.
- *  Must match the production "sha256" helper which uses nacl.hash (SHA-512) [0:32].
- *
- *  DO NOT "fix" this to real SHA-256. The name in the sibling implementations
- *  (`sha256ForNotes`) is a misnomer, but the bytes are load-bearing: changing the
- *  KDF makes every historical note undecryptable.
- *
- *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
-export declare function kdfSHA512_256(secret: Uint8Array): Uint8Array;
-/** Convert an Ed25519 private seed (32 bytes) to an X25519 scalar.
- *  Equivalent to ed2curve.convertSecretKey(seed).
- *
- *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
-export declare function ed25519SeedToX25519Private(seed: Uint8Array): Uint8Array;
-/** Convert an Ed25519 compressed public key (32 bytes) to X25519.
- *  Equivalent to ed2curve.convertPublicKey(pubkey).
- *  Edwards y-coord → Montgomery u via: u = (1 + y) / (1 - y) (mod p).
- *
- *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
-export declare function ed25519PublicKeyToX25519(pubkey: Uint8Array): Uint8Array;
-/**
- * Encrypt a UTXO note for a recipient identified by their Solana wallet public key.
- * Produces a blob the relayer will store and serve via POST /notes/save.
- *
- * @param recipientWalletPubkey  32-byte Ed25519 public key (wallet.publicKey.toBytes())
- * @param noteData               UTXO details to encrypt
- */
-export declare function encryptBlindMailboxNote(recipientWalletPubkey: Uint8Array, noteData: BlindMailboxNoteData): {
-    ephemeralPublicKey: Uint8Array;
-    encryptedBlob: string;
-};
-/**
- * Decrypt a Blind Mailbox note using the recipient's Solana wallet private seed.
- *
- * @param walletSecretKey  Full 64-byte wallet.secretKey — the first 32 bytes are the seed
- * @param ephemeralPublicKey  32-byte raw public key stored alongside the encrypted blob.
- *                            This may be either an Ed25519 pubkey (from Keypair.generate())
- *                            or a raw X25519 pubkey — the decryption path handles both:
- *                            if it is an Ed25519 key it is converted; otherwise used directly.
- * @param encryptedBlob      Base64 string as stored by the relayer
- */
-export declare function decryptBlindMailboxNote(walletSecretKey: Uint8Array, ephemeralPublicKey: Uint8Array, encryptedBlob: string): DecryptedNote;
-/**
- * Fetch all encrypted notes for a wallet from the relayer's Blind Mailbox endpoint
- * and decrypt them using the wallet's secret key.
- *
- * @param walletPublicKey  Base58 wallet address used to query the relayer
- * @param walletSecretKey  Full 64-byte keypair.secretKey for decryption
- * @param relayerUrl       Relayer base URL (e.g. "https://relay.veilo.app")
- */
-export declare function fetchAndDecryptNotes(walletPublicKey: string, walletSecretKey: Uint8Array, relayerUrl: string): Promise<DecryptedNote[]>;
+export * from "./notes/index.js";