@veilo/sdk-core 0.4.0 → 0.5.0

package/dist/cjs/notes/model.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateKeypair = generateKeypair;
+exports.derivePublicKey = derivePublicKey;
+exports.keypairFromPrivateKey = keypairFromPrivateKey;
+exports.commitUTXO = commitUTXO;
+exports.createUTXO = createUTXO;
+exports.createOwnedUTXO = createOwnedUTXO;
+exports.createZeroUTXO = createZeroUTXO;
+exports.createOwnedZeroUTXO = createOwnedZeroUTXO;
+const random_js_1 = require("../random.js");
+const poseidon_js_1 = require("../poseidon.js");
+// -----------------------------------------------------------------------------
+// Keypair Functions
+// -----------------------------------------------------------------------------
+/**
+ * Generate a random keypair.
+ * Private key is a random 32-byte scalar.
+ * Public key is derived via Poseidon: pubkey = Poseidon(privateKey)
+ */
+function generateKeypair() {
+    const privateKeyBytes = new Uint8Array((0, random_js_1.randomBytes)(32));
+    const privateKey = (0, poseidon_js_1.bytesToBigIntBE)(privateKeyBytes) % poseidon_js_1.BN254_FR_MODULUS;
+    const publicKey = derivePublicKey(privateKey);
+    return { privateKey, publicKey };
+}
+/**
+ * Derive public key from private key.
+ * Matches circuit's Keypair template: publicKey = Poseidon(privateKey)
+ */
+function derivePublicKey(privateKey) {
+    return (0, poseidon_js_1.poseidon1)(privateKey);
+}
+/**
+ * Create keypair from a known private key.
+ */
+function keypairFromPrivateKey(privateKey) {
+    return {
+        privateKey: privateKey % poseidon_js_1.BN254_FR_MODULUS,
+        publicKey: derivePublicKey(privateKey % poseidon_js_1.BN254_FR_MODULUS),
+    };
+}
+// -----------------------------------------------------------------------------
+// UTXO Commitment Functions
+// -----------------------------------------------------------------------------
+/**
+ * Compute UTXO commitment.
+ * Matches circuit's UTXOCommitment template:
+ *   commitment = Poseidon(amount, pubkey, blinding, mintAddress)
+ */
+function commitUTXO(utxo) {
+    const commitment = (0, poseidon_js_1.poseidon4)(utxo.amount, utxo.pubkey, utxo.blinding, utxo.mintAddress);
+    return (0, poseidon_js_1.bigIntToBytesBE)(commitment);
+}
+/**
+ * Create a random UTXO with the given parameters.
+ */
+function createUTXO(params) {
+    const blindingBytes = new Uint8Array((0, random_js_1.randomBytes)(32));
+    const blinding = (0, poseidon_js_1.bytesToBigIntBE)(blindingBytes) % poseidon_js_1.BN254_FR_MODULUS;
+    const utxo = {
+        amount: params.amount,
+        pubkey: params.pubkey,
+        blinding,
+        mintAddress: (0, poseidon_js_1.pubkeyToField)(params.mintAddress),
+    };
+    const commitment = commitUTXO(utxo);
+    return {
+        ...utxo,
+        commitment,
+    };
+}
+/**
+ * Create a UTXO with a specified private key (for owned UTXOs).
+ */
+function createOwnedUTXO(params) {
+    const keypair = keypairFromPrivateKey(params.privateKey);
+    const utxo = createUTXO({
+        amount: params.amount,
+        pubkey: keypair.publicKey,
+        mintAddress: params.mintAddress,
+    });
+    return {
+        ...utxo,
+        privateKey: keypair.privateKey,
+    };
+}
+/**
+ * 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.
+ */
+function createZeroUTXO(pubkey, mintAddress) {
+    return createUTXO({
+        amount: 0n,
+        pubkey,
+        mintAddress,
+    });
+}
+/**
+ * Create a zero UTXO with private key (for owned zero UTXOs).
+ */
+function createOwnedZeroUTXO(privateKey, mintAddress) {
+    const keypair = keypairFromPrivateKey(privateKey);
+    const utxo = createZeroUTXO(keypair.publicKey, mintAddress);
+    return {
+        ...utxo,
+        privateKey: keypair.privateKey,
+    };
+}

package/dist/cjs/notes/nullifier.d.ts

@@ -0,0 +1,27 @@
+import type { InputUTXO, SerializedUTXO } from "./model.js";
+/**
+ * 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;
+};

package/dist/cjs/notes/nullifier.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeSignature = computeSignature;
+exports.deriveNullifier = deriveNullifier;
+exports.inputUTXOToCircuitFormat = inputUTXOToCircuitFormat;
+const poseidon_js_1 = require("../poseidon.js");
+// -----------------------------------------------------------------------------
+// Nullifier Functions
+// -----------------------------------------------------------------------------
+/**
+ * Compute signature for nullifier derivation.
+ * Matches circuit's Signature template:
+ *   signature = Poseidon(privateKey, commitment, pathIndex)
+ */
+function computeSignature(privateKey, commitment, pathIndex) {
+    return (0, poseidon_js_1.poseidon3)(privateKey, commitment, pathIndex);
+}
+/**
+ * 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.
+ */
+function deriveNullifier(utxo, pathIndex, privateKey) {
+    const commitment = (0, poseidon_js_1.bytesToBigIntBE)(utxo.commitment) % poseidon_js_1.BN254_FR_MODULUS;
+    const pathIndexField = BigInt(pathIndex) % poseidon_js_1.BN254_FR_MODULUS;
+    const signature = computeSignature(privateKey, commitment, pathIndexField);
+    const nullifier = (0, poseidon_js_1.poseidon3)(commitment, pathIndexField, signature);
+    return (0, poseidon_js_1.bigIntToBytesBE)(nullifier);
+}
+/**
+ * Convert InputUTXO to the format expected by the circuit.
+ */
+function inputUTXOToCircuitFormat(input) {
+    return {
+        amount: input.amount,
+        pubkey: input.pubkey,
+        blinding: input.blinding,
+        pathElements: input.pathElements.map((e) => (0, poseidon_js_1.bytesToBigIntBE)(e) % poseidon_js_1.BN254_FR_MODULUS),
+        pathIndex: input.pathIndex,
+        privateKey: input.privateKey,
+    };
+}

package/dist/cjs/notes/recovery.d.ts

@@ -0,0 +1,10 @@
+import type { DecryptedNote } from "./mailbox.js";
+/**
+ * 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[]>;

package/dist/cjs/notes/recovery.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchAndDecryptNotes = fetchAndDecryptNotes;
+const mailbox_js_1 = require("./mailbox.js");
+/**
+ * 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")
+ */
+async function fetchAndDecryptNotes(walletPublicKey, walletSecretKey, relayerUrl) {
+    const resp = await fetch(`${relayerUrl}/api/notes?recipientPublicKey=${walletPublicKey}`);
+    if (!resp.ok) {
+        throw new Error(`fetchAndDecryptNotes: ${resp.status} ${resp.statusText}`);
+    }
+    const { notes } = (await resp.json());
+    const results = [];
+    for (const note of notes) {
+        try {
+            const epk = Buffer.from(note.ephemeralPublicKey, "base64");
+            const decrypted = (0, mailbox_js_1.decryptBlindMailboxNote)(walletSecretKey, new Uint8Array(epk), note.encryptedBlob);
+            results.push(decrypted);
+        }
+        catch {
+            // Note not for this key or corrupted — skip silently
+        }
+    }
+    return results;
+}

package/dist/cjs/proof.d.ts

@@ -1,183 +1 @@
-import { PublicKey } from "@solana/web3.js";
-import { SerializedUTXO, InputUTXO } from "./utxo.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>;
-/**
- * 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;
-/**
- * Turn a snarkjs Groth16 proof into 256 bytes:
- *   A(G1) | B(G2) | C(G1)
- * where:
- *   A = (ax, ay)               -> 64 bytes
- *   B = (bx1, bx0, by1, by0)  -> 128 bytes  (swapped pairs for alt_bn128)
- *   C = (cx, cy)               -> 64 bytes
- *
- * Each field element is encoded as 32-byte BE to match the on-chain verifier.
- * We ignore the extra projective/z components snarkjs keeps.
- */
-export declare function packProofToBytes(proof: RawProof): Uint8Array;
-/**
- * Encode a snarkjs proof into the TransactionProofStruct format expected by the on-chain program.
- */
-export declare function encodeSnarkjsProofToTransactionProof(proof: RawProof): TransactionProofStruct;
-/**
- * Convert TransactionCircuitInputs to the format expected by snarkjs.groth16.fullProve().
- * All values are converted to strings (snarkjs expects string inputs for field elements).
- */
-export declare function formatInputsForSnarkjs(inputs: TransactionCircuitInputs): Record<string, any>;
-/**
- * Swap circuit inputs. Matches the signal shape declared by swap.circom's
- * main component (see zk-circuits/swap.circom lines 208-238). Unlike the
- * transaction circuit, the swap circuit distinguishes a "change" output
- * (same mint as source) from a "dest" output (dest mint) and takes a
- * swap-specific params hash and swapAmount alongside the usual inputs.
- */
-export type SwapCircuitInputs = {
-    sourceRoot: Uint8Array;
-    swapParamsHash: Uint8Array;
-    extDataHash: Uint8Array;
-    sourceMint: PublicKey;
-    destMint: PublicKey;
-    inputNullifiers: [Uint8Array, Uint8Array];
-    changeCommitment: Uint8Array;
-    destCommitment: Uint8Array;
-    swapAmount: bigint;
-    inAmount: [bigint, bigint];
-    inPubkey: [bigint, bigint];
-    inBlinding: [bigint, bigint];
-    inPathIndex: [number, number];
-    inPathElements: [bigint[], bigint[]];
-    inPrivateKey: [bigint, bigint];
-    changeAmount: bigint;
-    changePubkey: bigint;
-    changeBlinding: bigint;
-    destAmount: bigint;
-    destPubkey: bigint;
-    destBlinding: bigint;
-    minAmountOut: bigint;
-    deadline: bigint;
-};
-/**
- * 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.
- */
-export declare function formatSwapInputsForSnarkjs(inputs: SwapCircuitInputs): Record<string, any>;
-/**
- * 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     Unix timestamp deadline (i64, 0 = no deadline)
- * @param destAmount   Actual amount committed to destination UTXO (≥ minAmountOut -
- *                     relayerFee). If omitted, defaults to minAmountOut.
- */
-export declare function computeSwapParamsHash(sourceMint: PublicKey, destMint: PublicKey, minAmountOut: bigint, deadline: bigint, destAmount?: bigint): Uint8Array;
-/**
- * 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`.
- */
-export declare function computeSwapDataHash(swapData: Uint8Array | Buffer): Uint8Array;
+export * from "./proofs/index.js";