@veilo/sdk-core 0.4.0 → 0.6.0

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

@@ -1,202 +0,0 @@
-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/utxo.d.ts

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