@zbase-protocol/core 0.1.0

package/dist/notes.d.ts

@@ -0,0 +1,305 @@
+/**
+ * @zbase-protocol/core — UTXO note primitives (Shipment A.1 scaffold)
+ *
+ * v0: in-memory note model + viewing-key encryption for storing notes off-chain
+ * and posting their ciphertext alongside the spend's `NoteCommitted` event.
+ *
+ * Mirrors Railgun's note model (https://docs.railgun.org/wiki/learn/privacy-system).
+ * The on-chain commitment encoding is intentionally identical to the current
+ * single-value commitment in `account.ts` so the same Poseidon helpers stay in
+ * use and the Anchor program's `crypto.rs` continues to apply without change:
+ *
+ *   precommitment = Poseidon2(nullifier, secret)
+ *   commitment    = Poseidon3(amount, label, precommitment)
+ *
+ * Cryptographic envelope chosen for cold-start performance over libsodium.js
+ * (no WASM init, no async load) — see /docs/utxo-notes-design.md §4.1.
+ *
+ *   * X25519 key agreement   (`@noble/curves/ed25519` → `x25519`)
+ *   * XChaCha20-Poly1305     (`@noble/ciphers/chacha`)
+ *   * 2-byte view-tag        (Railgun-style fast scan filter)
+ *
+ * Status: scaffold. Do NOT use the encryption helpers in production until
+ * (a) the bytes layout has been pinned by a wallet review and
+ * (b) the trusted-setup ceremony for `note_spend.circom` has completed.
+ */
+/**
+ * Plaintext note. Lives off-chain (in the wallet, in the facilitator's
+ * per-user cache, or as the decrypted payload of a `NoteCommitted` log).
+ *
+ * v1 RECIPE (audit C3): the on-chain commitment recipe was migrated to match
+ * the frozen `note_spend.circom`:
+ *
+ *   NPK        = Poseidon2(spendingPK, viewingPKBlind)
+ *   commitment = Poseidon3(amount, NPK, secret)
+ *
+ * The previous v0 recipe `Poseidon3(amount, label, Poseidon2(nullifier,secret))`
+ * did NOT match the circuit, so any UTXO proof the SDK built would have failed
+ * verification. `label` is no longer part of the commitment (it now binds
+ * privately through the NPK + the ASP-membership witness), but is retained on
+ * the note because the circuit still proves ASP membership of `label`.
+ *
+ * ⚠️ AUDITOR-SCOPED GAP: this aligns the commitment HASH STRUCTURE with the
+ * circuit. How `spendingPK` / `viewingPKBlind` are DERIVED from the recipient's
+ * viewing key (the Railgun NPK key-derivation, and exactly how the ASP label is
+ * folded into that derivation off-chain) is NOT yet implemented in the SDK and
+ * must be designed + reviewed in the external circuit audit before the UTXO pool
+ * goes live. Until then these are caller-supplied fields.
+ */
+export interface Note {
+    /** USDC atomic units (6 decimal places). 0 marks a dummy / zero-note. */
+    amount: bigint;
+    /** ASP label inherited from the originating deposit. Proven for ASP
+     *  membership; NOT part of the commitment in v1. */
+    label: bigint;
+    /** Recipient spending public key (field element) — NPK input. */
+    spendingPK: bigint;
+    /** Per-note blinded recipient viewing public key (field element) — NPK input. */
+    viewingPKBlind: bigint;
+    /** Per-note nullifier (random field element). */
+    nullifier: bigint;
+    /** Per-note secret (random field element). */
+    secret: bigint;
+}
+/**
+ * Viewing keypair. The private key gives read access to all notes addressed to
+ * this owner; it cannot move funds (which require the per-note nullifier+secret).
+ */
+export interface ViewingKeyPair {
+    privateKey: Uint8Array;
+    publicKey: Uint8Array;
+}
+/**
+ * Encrypted note as it would appear on-chain inside a `NoteCommitted` log:
+ *
+ *   bytes layout:
+ *     [0..32)   ephemeral X25519 public key
+ *     [32..34)  2-byte view-tag (firstTwoBytes(keccak(shared)))
+ *     [34..58)  XChaCha20 nonce (24 bytes)
+ *     [58..)    AEAD ciphertext (plaintext_len + 16-byte Poly1305 tag)
+ *
+ * Total per-note overhead ≈ 58 + ciphertext_len. The plaintext is ~120-150
+ * bytes after JSON serialization, putting per-note calldata cost at ~3K gas
+ * (well under the ~250K Groth16 verification cost).
+ */
+export type EncryptedNote = Uint8Array;
+/**
+ * Create a fresh note with random nullifier + secret.
+ *
+ * `amount` + `label` come from a deposit or a parent note being split. The NPK
+ * inputs (`spendingPK`, `viewingPKBlind`) identify the RECIPIENT and bind the
+ * label privately — they default to 0 here for the self-spend / scaffold case,
+ * but a real transfer MUST pass the recipient's derived NPK inputs.
+ *
+ * ⚠️ Deriving spendingPK/viewingPKBlind from a recipient's viewing key is the
+ * auditor-scoped gap (see the Note doc). Until that lands, callers either pass
+ * 0 (change-back-to-self placeholder) or supply explicit values.
+ */
+export declare function createNote(amount: bigint, label: bigint, npk?: {
+    spendingPK: bigint;
+    viewingPKBlind: bigint;
+}): Note;
+/**
+ * Create a zero-value dummy note. Used as a placeholder input/output to fill
+ * the fixed N=2/M=2 slots of the v0 spend circuit when the spender does not
+ * actually need 2 inputs or 2 outputs.
+ *
+ * A dummy carries amount=0 and label=0; the circuit's `inIsDummy[i]` flag
+ * must be set to 1 for input dummies. (Output dummies are valid as-is because
+ * a 0-amount output commitment hashes deterministically and inserts harmlessly
+ * into the state tree — though wallets should treat amount=0 commitments as
+ * unspendable noise.)
+ */
+export declare function createDummyNote(): Note;
+/**
+ * `NPK = Poseidon2(spendingPK, viewingPKBlind)`. The note-public-key the
+ * circuit's `NpkBuilder` template computes (note_spend.circom NpkBuilder).
+ */
+export declare function npkOf(note: Pick<Note, "spendingPK" | "viewingPKBlind">): bigint;
+/**
+ * v1 UTXO commitment (audit C3): `commitment = Poseidon3(amount, NPK, secret)`,
+ * `NPK = Poseidon2(spendingPK, viewingPKBlind)`.
+ *
+ * This now matches `CommitmentHasher` in `note_spend.circom` EXACTLY (Poseidon3
+ * over `[amount, npk, secret]`). The prior v0 recipe
+ * `Poseidon3(amount, label, Poseidon2(nullifier, secret))` did NOT match the
+ * circuit and would have made every UTXO proof unverifiable.
+ *
+ * NOTE: this is the UTXO-pool recipe. The legacy single-value pool keeps its own
+ * (correct, deployed) recipe in `account.ts::computeCommitment` — do not unify
+ * them; they back two different pools.
+ */
+export declare function commitmentOf(note: Note): bigint;
+/**
+ * `nullifierHash = Poseidon1(nullifier)`. Imported from account.ts. Repeated
+ * here only for convenient note-centric API.
+ */
+export declare function nullifierHashOf(note: Note): bigint;
+export declare class NoteValueError extends Error {
+}
+/**
+ * Circuit range bound (audit F11): `note_spend.circom` range-checks every output
+ * amount and the withdrawn amount to 64 bits (`Num2Bits(64)`). Amounts at or
+ * above 2^64 would fail proof generation with an opaque error, or — if a caller
+ * skipped the SDK — risk field-wraparound creating value. We validate here so
+ * bad amounts are rejected up front with a clear message.
+ */
+export declare const MAX_NOTE_AMOUNT: bigint;
+/**
+ * Split a single note into two new notes that conserve the parent value and
+ * inherit its label. The two outputs are returned in the order
+ * `[primary, change]`; pass them straight into a 2-output spend.
+ */
+export declare function splitNote(parent: Note, primaryAmount: bigint): [Note, Note];
+/**
+ * Merge two notes (with matching label) into one. Returns the merged note.
+ * The caller must spend the two inputs and mint this one output via a spend.
+ */
+export declare function mergeNotes(a: Note, b: Note): Note;
+/**
+ * Plan the inputs/outputs for paying `payAmount` out of an array of available
+ * notes. Returns the (≤2) input notes and (≤2) output notes for a v0 spend.
+ *
+ * Strategy:
+ *  - Pick the smallest single note ≥ payAmount if possible (minimises change).
+ *  - Otherwise merge the two largest notes — error if their sum is still
+ *    insufficient (caller must perform multiple spends; defer to a future
+ *    "PaymentPlanner" helper).
+ *
+ * This is a v0 heuristic; production wallets should use a coin-selection
+ * algorithm tuned for anonymity-set size (e.g., randomised LIFO).
+ */
+export declare function planSpend(available: readonly Note[], payAmount: bigint): {
+    inputs: [Note, Note];
+    outputAmounts: [bigint, bigint];
+};
+/**
+ * Plan one dust-consolidation step (Phase 1C operational fix).
+ *
+ * Fragmented wallets leak: every spend that has to merge two inputs reveals
+ * (via the conservation law) that the spender held exactly those two note
+ * values, and a wallet forced into many small spends produces a recognisable
+ * on-chain cadence. Keeping the note count low ahead of time means real
+ * payments can take the single-input path, which is the quietest shape.
+ *
+ * Given the available notes and a target count, returns the inputs/outputs
+ * for ONE 2-in/1-out merge spend (the v0 circuit is fixed at 2×2, so a merge
+ * consumes two notes and mints one; the second output slot carries 0):
+ *
+ *  - Only notes with amount > 0 count toward the threshold (zero-amount
+ *    commitments are unspendable noise by convention — see createDummyNote).
+ *  - Returns null when the spendable count is already ≤ threshold, or when
+ *    no two spendable notes share a label (merging across labels would mix
+ *    ASP attestations — same rule as mergeNotes).
+ *  - Within the most-fragmented label group, the two SMALLEST notes merge
+ *    first: dust is the priority, and small notes are the ones whose values
+ *    are most identifiable in conservation-law analysis.
+ *
+ * Repeat-callable: apply the plan (spend the two inputs, keep the merged
+ * output), then call again with the updated set. Each round reduces the
+ * spendable count by exactly one, so looping until null terminates.
+ */
+export declare function consolidateNotes(available: readonly Note[], threshold?: number): {
+    inputs: [Note, Note];
+    outputAmounts: [bigint, bigint];
+} | null;
+/**
+ * Serialize a note to a compact JSON-friendly form. BigInts are encoded as
+ * decimal strings; the round-trip is exact. Used for localStorage today; will
+ * back the facilitator's encrypted note cache later.
+ */
+export declare function serializeNote(n: Note): string;
+export declare function deserializeNote(s: string): Note;
+/**
+ * Generate a fresh X25519 viewing keypair. Private key is sampled from
+ * `randomBytes` (= crypto.getRandomValues underneath). Curve constraints
+ * (clamping) are handled by `x25519`'s scalar multiplication.
+ */
+export declare function generateViewingKey(): ViewingKeyPair;
+/**
+ * Encrypt a note to a recipient's viewing public key.
+ *
+ * Returns the on-chain blob (see `EncryptedNote` layout above).
+ *
+ * Caveats:
+ *  - The output is non-deterministic (ephemeral key + random nonce).
+ *  - Includes a 2-byte view-tag to make recipient scanning O(N) trial-decrypt
+ *    instead of O(N) full AEAD-decrypt.
+ *  - Does NOT bind the ciphertext to any on-chain commitment. If you want
+ *    AAD binding (preventing a malicious relayer from swapping ciphertexts
+ *    between commitments) pass the commitment hash as `aad`.
+ */
+export declare function encryptNote(note: Note, recipientPublicKey: Uint8Array, aad?: Uint8Array): EncryptedNote;
+/**
+ * Attempt to decrypt a note using a viewing private key. Returns `null` on
+ * view-tag mismatch (fast path: 99.998% of foreign notes reject here) or on
+ * AEAD failure (cryptographically authenticated decryption).
+ *
+ * `aad` must match what the sender supplied at encryption time (commonly the
+ * commitment hash as bytes).
+ */
+export declare function decryptNote(encrypted: EncryptedNote, viewingPrivateKey: Uint8Array, aad?: Uint8Array): Note | null;
+/**
+ * Scan an array of (commitment, encryptedNote) pairs and decrypt all notes
+ * addressed to the viewing key. Convenience helper for the wallet/facilitator.
+ *
+ * `aadFor` allows AAD binding to the commitment (default: no AAD).
+ */
+export declare function scanNotes(entries: ReadonlyArray<{
+    commitment: bigint;
+    encrypted: EncryptedNote;
+}>, viewingPrivateKey: Uint8Array, aadFor?: (commitment: bigint) => Uint8Array | undefined): Array<{
+    commitment: bigint;
+    note: Note;
+}>;
+/**
+ * Build the AAD that binds a ciphertext to its on-chain commitment.
+ *
+ * Must match the value the UTXOPool contract verifies in `transfer()`:
+ *
+ *   aad = keccak256(abi.encode(outputCommitment))   (Solidity)
+ *       = keccak256(uint256ToBE32(commitment))      (TypeScript, here)
+ *
+ * Returns the 32-byte keccak256 digest. Passing the bare commitment bytes
+ * instead would still bind to the commitment but would NOT match the contract
+ * — the on-chain hash is mandatory for the Phase 1B Fix 3 ciphertext-shuffle
+ * defense to engage.
+ */
+export declare function commitmentAAD(commitment: bigint): Uint8Array;
+/**
+ * Convenience wrapper around `encryptNote` for the transfer use case.
+ * Auto-derives the AAD from the commitment so callers can't accidentally
+ * forget to bind. Equivalent to:
+ *
+ *   encryptNote(note, recipientPub, commitmentAAD(commitment))
+ *
+ * Use this everywhere the SDK builds `CommitmentCiphertext` for `transfer()`.
+ */
+export declare function encryptNoteForTransfer(note: Note, recipientViewingPubKey: Uint8Array, commitment: bigint): EncryptedNote;
+/**
+ * Decrypt a transfer-bound ciphertext, requiring the AAD to match the given
+ * commitment. Returns `null` on:
+ *
+ *  - view-tag mismatch (fast path — not this key's note),
+ *  - AEAD authentication failure (wrong key, corrupted blob),
+ *  - AAD mismatch (relayer attempted to shuffle ciphertexts between
+ *    commitments — Phase 1B Fix 3).
+ *
+ * Callers should ALWAYS use this in the scanner, never the bare `decryptNote`,
+ * for `Transferred`-event ciphertexts. The bare form is reserved for legacy
+ * `NoteCommitted` payloads (Shipment A.1 v0) which predate AAD binding.
+ */
+export declare function decryptNoteWithAAD(encrypted: EncryptedNote, viewingPrivateKey: Uint8Array, expectedCommitment: bigint): Note | null;
+/** Wire-format version for packed transfer ciphertexts. */
+export declare const CIPHERTEXT_WIRE_VERSION: 1;
+/**
+ * Frame an EncryptedNote for the on-chain `CommitmentCiphertext.ciphertext`
+ * field. Returns a 0x-hex string ready to pass as Solidity `bytes`.
+ */
+export declare function packCiphertext(encrypted: EncryptedNote): `0x${string}`;
+/**
+ * Inverse of packCiphertext: recover the EncryptedNote blob from the on-chain
+ * `bytes`. Returns null on malformed / wrong-version / length-mismatch input
+ * (a scanner should skip, not throw, on a payload it can't parse).
+ */
+export declare function unpackCiphertext(packedHex: string): EncryptedNote | null;