@veilo/sdk-core 0.1.17 → 0.4.0

package/dist/src/shield/types.d.ts

@@ -0,0 +1,202 @@
+import { AddressLookupTableAccount, Connection, PublicKey, VersionedTransaction } from "@solana/web3.js";
+import type { TransactionProofBuilder, TransactionProofStruct } from "../proof.js";
+import type { CompactNoteCipher } from "../compactNote.js";
+/**
+ * Who owns the resulting note. Both halves are required and neither is derived
+ * from the other:
+ *
+ *  - `veiloPublicKey` is the Poseidon field element bound into the output
+ *    commitment. It is the **spending** authority.
+ *  - `noteViewingKey` is the Ed25519 wallet key the compact cipher is encrypted
+ *    to. It is the **detection** authority.
+ *
+ * If these two belong to different people, the note is *spendable but
+ * invisible*: the owner can never find it, so the funds are effectively gone.
+ * Nothing on-chain and nothing in this type can detect that — which is why
+ * `resolveShieldOwner()` exists and why hand-constructing this requires an
+ * explicit acknowledgement.
+ *
+ * See veilo-browser-extension/.../privateStealthWallet.ts:403-415 for the
+ * production comment describing this failure mode.
+ */
+export type ShieldOwner = {
+    veiloPublicKey: bigint;
+    noteViewingKey: PublicKey;
+    /**
+     * Set automatically by {@link resolveShieldOwner}, which fetches both halves
+     * from a single relayer response and can therefore guarantee they match.
+     *
+     * Hand-built owners must set this explicitly — it is the only mechanism
+     * standing between an integration mistake and silent fund loss.
+     */
+    acknowledgeOwnerInvariant?: true;
+};
+/**
+ * Who signs and pays. Public key only — the SDK never receives a secret key.
+ *
+ * The signer is unavoidably the fee payer, the funding source, and the payer of
+ * ~0.00192 SOL of nullifier-marker rent (the program hardcodes
+ * `payer = relayer` on both marker accounts). A wallet with no SOL cannot
+ * shield through this path regardless of who submits the transaction.
+ */
+export type ShieldSigner = {
+    publicKey: PublicKey;
+    /**
+     * Source token account for SPL shields. Defaults to the signer's canonical
+     * ATA. Must be owned by `publicKey` with no delegate set.
+     */
+    tokenAccount?: PublicKey;
+};
+/** Where the target tree and its root come from. */
+export interface TreeSource {
+    getDepositTarget(mint: PublicKey): Promise<DepositTarget>;
+}
+export type DepositTarget = {
+    /** Always 0 — the tree whose root the dummy inputs nominally prove against. */
+    inputTreeId: number;
+    /** 32-byte root, read from that tree's on-chain root history. */
+    inputRoot: Uint8Array;
+    /** Tree the new commitments are appended to. */
+    outputTreeId: number;
+    /** `nextIndex` at build time. A prediction — see `predictedLeafIndex`. */
+    outputNextIndex: number;
+};
+/** Where the address lookup table comes from. */
+export interface AltSource {
+    resolve(ctx: {
+        connection: Connection;
+        mint: PublicKey;
+        outputTreeId: number;
+        programId: PublicKey;
+    }): Promise<AddressLookupTableAccount>;
+}
+/**
+ * Caching for values that are stable across builds (the ALT account, rent
+ * exemption minimums, pool config).
+ *
+ * Deliberately an interface: the three production deposit implementations
+ * differ on exactly this axis — `localStorage`, `chrome.storage`, and
+ * `AsyncStorage` — and none of them belongs in a published SDK.
+ */
+export interface ShieldCachePort {
+    get<T>(key: string): Promise<T | undefined>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+}
+export type PreflightOptions = {
+    /** Skip the SPL token-account inspection (owner, delegate, balance). */
+    skipTokenAccount?: boolean;
+    /** Skip the signer balance check. */
+    skipBalance?: boolean;
+    /** Skip pool state checks (paused, min/max, tree capacity). */
+    skipPoolState?: boolean;
+};
+export type ShieldParams = {
+    connection: Connection;
+    /** Net amount to shield, in base units. No fee is taken on deposits. */
+    amount: bigint;
+    /** Defaults to native SOL. */
+    mint?: PublicKey;
+    owner: ShieldOwner;
+    signer: ShieldSigner;
+    /** Proof generation. `createTransactionProver(artifacts)` satisfies this. */
+    prover: TransactionProofBuilder;
+    treeSource?: TreeSource;
+    alt?: AltSource;
+    cache?: ShieldCachePort;
+    programId?: PublicKey;
+    computeUnitLimit?: number;
+    /** Set to 0 to omit the priority-fee instruction entirely. */
+    computeUnitPriceMicroLamports?: number;
+    deadlineSeconds?: number;
+    /** Supply to avoid an RPC round-trip; otherwise fetched just before compiling. */
+    blockhash?: {
+        blockhash: string;
+        lastValidBlockHeight: number;
+    };
+    preflight?: boolean | PreflightOptions;
+};
+/**
+ * The recoverable secret material for the note this shield creates.
+ *
+ * SECRET. Anyone holding this can locate the note. It must never be persisted
+ * server-side in the clear or transmitted alongside {@link ShieldProofCache},
+ * which is deliberately public.
+ */
+export type ShieldNote = {
+    commitment: Uint8Array;
+    blinding: bigint;
+    amount: bigint;
+    ownerVeiloPublicKey: bigint;
+    mint: PublicKey;
+    treeId: number;
+    compact: CompactNoteCipher;
+};
+/**
+ * Everything needed to re-assemble the transaction with a fresh blockhash.
+ *
+ * PUBLIC and JSON-serializable by construction: it carries no blinding, no
+ * private key, and no note plaintext. A platform can build server-side, ship
+ * this to a client for signature, and rebuild in a different process without
+ * ever moving a secret.
+ */
+export type ShieldProofCache = {
+    version: 1;
+    programId: string;
+    mint: string;
+    signer: string;
+    altAddress: string;
+    inputTreeId: number;
+    outputTreeId: number;
+    root: string;
+    publicAmount: string;
+    extData: {
+        recipient: string;
+        relayer: string;
+        fee: string;
+        refund: string;
+        claimant: string;
+    };
+    extDataHash: string;
+    inputNullifiers: [string, string];
+    outputCommitments: [string, string];
+    proof: TransactionProofStruct;
+    noteCiphers: {
+        note0EphemeralKey: string;
+        note0Encrypted: string;
+        note0ViewTag: number;
+        note1EphemeralKey: string;
+        note1Encrypted: string;
+        note1ViewTag: number;
+    };
+    /** Resolved instruction accounts, keyed by IDL account name. */
+    accounts: Record<string, string>;
+    computeUnitLimit: number;
+};
+export type ShieldQuote = {
+    /** Serialized size including the signature. Must be <= 1232. */
+    serializedSize: number;
+    computeUnitLimit: number;
+    computeUnitPriceMicroLamports: number;
+    estimatedFeeLamports: bigint;
+    /** Nullifier-marker rent, permanently burned by the signer. */
+    estimatedRentLamports: bigint;
+};
+export type ShieldResult = {
+    /** UNSIGNED. The caller signs and submits — this SDK never broadcasts. */
+    transaction: VersionedTransaction;
+    blockhash: string;
+    lastValidBlockHeight: number;
+    deadline: bigint;
+    note: ShieldNote;
+    /**
+     * Leaf index the output commitment is *expected* to land at.
+     *
+     * A prediction, read before submission. Under concurrent deposits into the
+     * same tree it will be wrong. Use `finalizeShield()` to read the authoritative
+     * index from the confirmed transaction's `CommitmentEvent` before persisting
+     * anything that depends on it.
+     */
+    predictedLeafIndex: number;
+    quote: ShieldQuote;
+    proofCache: ShieldProofCache;
+};

package/dist/src/shield/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/utxo.d.ts

@@ -0,0 +1,235 @@
+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[]>;