@veilo/sdk-core 0.4.0 → 0.6.0

package/dist/cjs/transactions/withdraw.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withdraw = withdraw;
+const web3_js_1 = require("@solana/web3.js");
+const transaction_js_1 = require("../proofs/transaction.js");
+const encoding_js_1 = require("../proofs/encoding.js");
+const model_js_1 = require("../notes/model.js");
+const transact_js_1 = require("./transact.js");
+const poseidon_js_1 = require("../poseidon.js");
+const compactNote_js_1 = require("../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
+ */
+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 = (0, model_js_1.createUTXO)({
+        amount: changeAmount,
+        pubkey: changePubkey,
+        mintAddress,
+    });
+    const zeroUTXO = (0, model_js_1.createUTXO)({
+        amount: 0n,
+        pubkey: (0, model_js_1.generateKeypair)().publicKey,
+        mintAddress,
+    });
+    const outputUTXOs = [changeUTXO, zeroUTXO];
+    const extData = {
+        recipient,
+        relayer: relayer.publicKey,
+        fee,
+        refund,
+        claimant: web3_js_1.SystemProgram.programId,
+    };
+    // publicAmount is negative for withdrawals
+    const publicAmount = -outflowAmount;
+    const circuitInputs = (0, transaction_js_1.prepareTransactionInputs)({
+        inputUTXOs,
+        outputUTXOs,
+        root,
+        publicAmount,
+        extData,
+        mintAddress,
+    });
+    const rawProof = await proofBuilder(circuitInputs);
+    const proof = (0, encoding_js_1.encodeSnarkjsProofToTransactionProof)(rawProof);
+    const withdrawNoteCiphers = noteCiphers !== undefined
+        ? noteCiphers
+        : changeNoteRecipientWallet && changeAmount > 0n
+            ? (0, compactNote_js_1.createNoteCiphers)({
+                recipientWalletPubkey: changeNoteRecipientWallet instanceof web3_js_1.PublicKey
+                    ? changeNoteRecipientWallet.toBytes()
+                    : changeNoteRecipientWallet,
+                blinding: (0, poseidon_js_1.bigIntToBytesBE)(changeUTXO.blinding),
+                amount: changeAmount,
+            }, null)
+            : null;
+    await (0, transact_js_1.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/cjs/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";