@veilo/sdk-core 0.3.3 → 0.4.0

package/dist/cjs/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/cjs/shield/types.js

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

package/dist/cjs/utxo.d.ts

@@ -182,6 +182,26 @@ export type DecryptedNote = {
     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.

package/dist/cjs/utxo.js

@@ -17,13 +17,16 @@ exports.inputUTXOToCircuitFormat = inputUTXOToCircuitFormat;
 exports.deriveEncryptionKeypair = deriveEncryptionKeypair;
 exports.encryptUTXONote = encryptUTXONote;
 exports.decryptUTXONote = decryptUTXONote;
+exports.kdfSHA512_256 = kdfSHA512_256;
+exports.ed25519SeedToX25519Private = ed25519SeedToX25519Private;
+exports.ed25519PublicKeyToX25519 = ed25519PublicKeyToX25519;
 exports.encryptBlindMailboxNote = encryptBlindMailboxNote;
 exports.decryptBlindMailboxNote = decryptBlindMailboxNote;
 exports.fetchAndDecryptNotes = fetchAndDecryptNotes;
-const crypto_1 = require("crypto");
+const random_js_1 = require("./random.js");
 const tweetnacl_1 = __importDefault(require("tweetnacl"));
 const sha256_1 = require("@noble/hashes/sha256");
-const poseidon_1 = require("./poseidon");
+const poseidon_js_1 = require("./poseidon.js");
 // -----------------------------------------------------------------------------
 // Keypair Functions
 // -----------------------------------------------------------------------------
@@ -33,8 +36,8 @@ const poseidon_1 = require("./poseidon");
  * Public key is derived via Poseidon: pubkey = Poseidon(privateKey)
  */
 function generateKeypair() {
-    const privateKeyBytes = new Uint8Array((0, crypto_1.randomBytes)(32));
-    const privateKey = (0, poseidon_1.bytesToBigIntBE)(privateKeyBytes) % poseidon_1.BN254_FR_MODULUS;
+    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 };
 }
@@ -43,15 +46,15 @@ function generateKeypair() {
  * Matches circuit's Keypair template: publicKey = Poseidon(privateKey)
  */
 function derivePublicKey(privateKey) {
-    return (0, poseidon_1.poseidon1)(privateKey);
+    return (0, poseidon_js_1.poseidon1)(privateKey);
 }
 /**
  * Create keypair from a known private key.
  */
 function keypairFromPrivateKey(privateKey) {
     return {
-        privateKey: privateKey % poseidon_1.BN254_FR_MODULUS,
-        publicKey: derivePublicKey(privateKey % poseidon_1.BN254_FR_MODULUS),
+        privateKey: privateKey % poseidon_js_1.BN254_FR_MODULUS,
+        publicKey: derivePublicKey(privateKey % poseidon_js_1.BN254_FR_MODULUS),
     };
 }
 // -----------------------------------------------------------------------------
@@ -63,20 +66,20 @@ function keypairFromPrivateKey(privateKey) {
  *   commitment = Poseidon(amount, pubkey, blinding, mintAddress)
  */
 function commitUTXO(utxo) {
-    const commitment = (0, poseidon_1.poseidon4)(utxo.amount, utxo.pubkey, utxo.blinding, utxo.mintAddress);
-    return (0, poseidon_1.bigIntToBytesBE)(commitment);
+    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, crypto_1.randomBytes)(32));
-    const blinding = (0, poseidon_1.bytesToBigIntBE)(blindingBytes) % poseidon_1.BN254_FR_MODULUS;
+    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_1.pubkeyToField)(params.mintAddress),
+        mintAddress: (0, poseidon_js_1.pubkeyToField)(params.mintAddress),
     };
     const commitment = commitUTXO(utxo);
     return {
@@ -130,7 +133,7 @@ function createOwnedZeroUTXO(privateKey, mintAddress) {
  *   signature = Poseidon(privateKey, commitment, pathIndex)
  */
 function computeSignature(privateKey, commitment, pathIndex) {
-    return (0, poseidon_1.poseidon3)(privateKey, commitment, pathIndex);
+    return (0, poseidon_js_1.poseidon3)(privateKey, commitment, pathIndex);
 }
 /**
  * Derive nullifier for a UTXO.
@@ -141,11 +144,11 @@ function computeSignature(privateKey, commitment, pathIndex) {
  * The signature-based nullifier ensures only the private key holder can spend.
  */
 function deriveNullifier(utxo, pathIndex, privateKey) {
-    const commitment = (0, poseidon_1.bytesToBigIntBE)(utxo.commitment) % poseidon_1.BN254_FR_MODULUS;
-    const pathIndexField = BigInt(pathIndex) % poseidon_1.BN254_FR_MODULUS;
+    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_1.poseidon3)(commitment, pathIndexField, signature);
-    return (0, poseidon_1.bigIntToBytesBE)(nullifier);
+    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.
@@ -155,7 +158,7 @@ function inputUTXOToCircuitFormat(input) {
         amount: input.amount,
         pubkey: input.pubkey,
         blinding: input.blinding,
-        pathElements: input.pathElements.map((e) => (0, poseidon_1.bytesToBigIntBE)(e) % poseidon_1.BN254_FR_MODULUS),
+        pathElements: input.pathElements.map((e) => (0, poseidon_js_1.bytesToBigIntBE)(e) % poseidon_js_1.BN254_FR_MODULUS),
         pathIndex: input.pathIndex,
         privateKey: input.privateKey,
     };
@@ -165,7 +168,7 @@ function inputUTXOToCircuitFormat(input) {
  * The keypair is deterministic: same privateKey always yields the same pair.
  */
 function deriveEncryptionKeypair(privateKey) {
-    const seed = (0, sha256_1.sha256)((0, poseidon_1.bigIntToBytesBE)(privateKey));
+    const seed = (0, sha256_1.sha256)((0, poseidon_js_1.bigIntToBytesBE)(privateKey));
     return tweetnacl_1.default.box.keyPair.fromSecretKey(seed);
 }
 /**
@@ -189,8 +192,8 @@ function encryptUTXONote(utxo, recipientEncPubkey) {
     }
     const plaintext = new Uint8Array(72);
     plaintext.set(amountBuf, 0);
-    plaintext.set((0, poseidon_1.bigIntToBytesBE)(utxo.blinding), 8);
-    plaintext.set((0, poseidon_1.bigIntToBytesBE)(utxo.privateKey), 40);
+    plaintext.set((0, poseidon_js_1.bigIntToBytesBE)(utxo.blinding), 8);
+    plaintext.set((0, poseidon_js_1.bigIntToBytesBE)(utxo.privateKey), 40);
     const sharedKey = tweetnacl_1.default.box.before(recipientEncPubkey, ephemeral.secretKey);
     const ciphertext = tweetnacl_1.default.box.after(plaintext, nonce, sharedKey);
     return { nonce, ciphertext, senderEphemeralPubkey: ephemeral.publicKey };
@@ -209,14 +212,14 @@ function decryptUTXONote(note, recipientPrivateKey, commitment, mintAddress) {
     let amount = 0n;
     for (let i = 7; i >= 0; i--)
         amount = (amount << 8n) | BigInt(plaintext[i]);
-    const blinding = (0, poseidon_1.bytesToBigIntBE)(plaintext.slice(8, 40)) % poseidon_1.BN254_FR_MODULUS;
-    const privateKey = (0, poseidon_1.bytesToBigIntBE)(plaintext.slice(40, 72)) % poseidon_1.BN254_FR_MODULUS;
+    const blinding = (0, poseidon_js_1.bytesToBigIntBE)(plaintext.slice(8, 40)) % poseidon_js_1.BN254_FR_MODULUS;
+    const privateKey = (0, poseidon_js_1.bytesToBigIntBE)(plaintext.slice(40, 72)) % poseidon_js_1.BN254_FR_MODULUS;
     const pubkey = derivePublicKey(privateKey);
     const utxo = {
         amount,
         pubkey,
         blinding,
-        mintAddress: (0, poseidon_1.pubkeyToField)(mintAddress),
+        mintAddress: (0, poseidon_js_1.pubkeyToField)(mintAddress),
     };
     const expectedCommitment = commitUTXO(utxo);
     if (!expectedCommitment.every((b, i) => b === commitment[i]))
@@ -225,12 +228,20 @@ function decryptUTXONote(note, recipientPrivateKey, commitment, mintAddress) {
 }
 // -- Internal crypto helpers (no extra dependencies) --------------------------
 /** 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]. */
+ *  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. */
 function kdfSHA512_256(secret) {
     return tweetnacl_1.default.hash(secret).slice(0, 32);
 }
 /** Convert an Ed25519 private seed (32 bytes) to an X25519 scalar.
- *  Equivalent to ed2curve.convertSecretKey(seed). */
+ *  Equivalent to ed2curve.convertSecretKey(seed).
+ *
+ *  @internal Exported for `compactNote.ts`. Not part of the stable public API. */
 function ed25519SeedToX25519Private(seed) {
     const h = tweetnacl_1.default.hash(seed); // SHA-512
     const scalar = h.slice(0, 32);
@@ -253,7 +264,9 @@ function modpow25519(b, e) {
 }
 /** 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). */
+ *  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. */
 function ed25519PublicKeyToX25519(pubkey) {
     const pk = new Uint8Array(pubkey);
     pk[31] &= 0x7f; // clear sign bit to get y as LE integer
@@ -284,7 +297,7 @@ function ed25519PublicKeyToX25519(pubkey) {
  */
 function encryptBlindMailboxNote(recipientWalletPubkey, noteData) {
     // 1. Generate ephemeral Ed25519 keypair seed
-    const ephemeralSeed = (0, crypto_1.randomBytes)(32);
+    const ephemeralSeed = (0, random_js_1.randomBytes)(32);
     // Ed25519 public key stored by relayer; dapp recovers X25519 via ed2curve.convertPublicKey()
     const ephemeralEdPublicKey = tweetnacl_1.default.sign.keyPair.fromSeed(new Uint8Array(ephemeralSeed)).publicKey;
     // X25519 scalar (ed2curve.convertSecretKey equivalent)