@orbinum/sdk 0.25.0 → 1.0.0

package/dist/index-JYVjYJtf.d.mts

@@ -0,0 +1,353 @@
+/**
+ * What a note IS.
+ *
+ * The protocol's own vocabulary: a note, the inputs that build one, and the
+ * plaintext recovered from its memo. Nothing here describes an extrinsic — the
+ * argument shapes the pallet accepts live in `pallet/extrinsicParams.ts`,
+ * because a wallet can build, decrypt and select notes without ever submitting
+ * anything.
+ */
+/** On-chain Merkle tree state for the shielded pool. */
+type MerkleTreeInfo = {
+    /** 0x-prefixed current Merkle root hex. */
+    root: string;
+    /** Number of leaves (commitments) inserted so far. */
+    treeSize: number;
+    /** Tree depth (levels from leaf to root). */
+    depth: number;
+};
+/** A commitment surfaced by the indexer scan feed, for trial-decryption. */
+type ScanCommitment = {
+    /** 0x-prefixed 32-byte commitment hex. */
+    commitmentHex: string;
+    /** Leaf position of the commitment in the Merkle tree. */
+    leafIndex: number;
+    /** 0x-prefixed encrypted memo hex, or null if none was published. */
+    encryptedMemo: string | null;
+};
+/** Plaintext fields recovered from a note's encrypted memo. */
+type DecryptedMemo = {
+    /** Note amount in planck. */
+    value: bigint;
+    /** Owner's BabyJubJub Ax coordinate. */
+    ownerPk: bigint;
+    /** Blinding scalar used in the commitment. */
+    blinding: bigint;
+    /** Asset ID of the note. */
+    assetId: bigint;
+    /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
+    counterpartyPk: bigint;
+    /** ZK circuit version the note is spent under, recovered from the memo plaintext. */
+    circuitVersion: number;
+};
+/** Input params for NoteBuilder.build(). All fields except value have defaults. */
+type NoteInput = {
+    /** Amount in planck (required). */
+    value: bigint;
+    /** Asset ID — default 0 (native ORB-Privacy). */
+    assetId?: bigint;
+    /** BabyJubJub Ax coordinate (owner public key x). Default 0n. */
+    ownerPk?: bigint;
+    /** Random blinding scalar. Defaults to BigInt(Date.now()). */
+    blinding?: bigint;
+    /** Secret spending key used to derive the nullifier. Default 0n. */
+    spendingKey?: bigint;
+    /**
+     * 32-byte LE-encoded packed BJJ viewing public key of the recipient (from their privacy address).
+     * When provided, NoteBuilder.build() will auto-generate the 180-byte ECDH-encrypted memo.
+     * Omit to skip memo generation (use buildMemo() separately if needed).
+     */
+    viewingPublicKey?: Uint8Array;
+    /**
+     * BabyJubJub Ax coordinate of the recipient (from their privacy address).
+     * Required together with viewingPublicKey to enable stealth address derivation:
+     * the commitment will use stealthOwnerPk instead of ownerPk, making each
+     * transaction unlinkable even when the same privacy address is reused.
+     */
+    recipientOwnerPk?: bigint;
+    /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. Default 0n. */
+    counterpartyPk?: bigint;
+    /** Circuit version to stamp on the note. Defaults to `CURRENT_CIRCUIT_VERSION`. */
+    circuitVersion?: number;
+    /**
+     * 32-byte ephemeral secret for the memo ECDH. Self-notes pass a
+     * deterministic one (deriveSelfEphSk) so a cold restore recognizes them by
+     * ephPk equality with no trial ECDH. Ignored on the stealth path (it
+     * generates its own coordinated ephSk). Default: random.
+     */
+    ephSkOverride?: Uint8Array;
+};
+/**
+ * Circuit version notes are created under today. A note carries its version
+ * (`ZkNote.circuitVersion`) so that, after a VK rotation, it is always proven
+ * and verified against the circuit that created it. Only one version exists
+ * today; callers may pass the chain's active version explicitly.
+ */
+declare const CURRENT_CIRCUIT_VERSION = 1;
+/**
+ * Computed ZK note (commitment + nullifier). Built entirely off-chain.
+ *
+ * commitment = Poseidon(value, assetId, ownerPk, blinding)
+ * nullifier  = Poseidon(commitment, spendingKey)
+ */
+type ZkNote = {
+    /** Note amount in planck. */
+    value: bigint;
+    /** Asset ID of the note. */
+    assetId: bigint;
+    /** Owner's BabyJubJub Ax coordinate (or stealth owner Pk for stealth notes). */
+    ownerPk: bigint;
+    /** Blinding scalar mixed into the commitment. */
+    blinding: bigint;
+    /** Secret spending key used to derive the nullifier. */
+    spendingKey: bigint;
+    /** Circuit version this note was created under (see `CURRENT_CIRCUIT_VERSION`). Required. */
+    circuitVersion: number;
+    /**
+     * Global Merkle leaf index, when known. Optional so pre-forest vaults
+     * need no migration: notes without it predate the first tree seal and
+     * belong to tree 0. Populated on shield and on scan; used only to derive
+     * the forest tree for same-tree coin selection (`treeIdOf`).
+     */
+    leafIndex?: number;
+    /** Whether the note has been spent/nullified on-chain. */
+    spent: boolean;
+    /** Local timestamp when this note was marked spent, or null if still active/unknown. */
+    spentAt: number | null;
+    /** Poseidon commitment scalar. */
+    commitment: bigint;
+    /** Poseidon nullifier scalar. */
+    nullifier: bigint;
+    /** 0x-prefixed 32-byte little-endian hex commitment. */
+    commitmentHex: string;
+    /** 0x-prefixed 32-byte little-endian hex nullifier. */
+    nullifierHex: string;
+    /**
+     * 180-byte encrypted memo (ChaCha20-Poly1305 ECDH) as number[] for SCALE encoding.
+     * Always populated: uses a dummy memo when no viewingPublicKey is provided.
+     */
+    memo: number[];
+    /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
+    counterpartyPk: bigint;
+};
+
+/**
+ * What crosses the worker boundary.
+ *
+ * Every value here must survive structured clone: it travels through
+ * `postMessage` to a worker and back. That rules out classes, functions and
+ * bigint-keyed maps — `bigint` itself is fine, `Uint8Array` is fine, anything
+ * with a prototype is not.
+ */
+
+/**
+ * Self-note discovery window: how many deterministic ephemeral indexes to
+ * precompute. BIP-44-style gap limit — a wallet with more self-created notes
+ * than this still finds the excess through the trial-decrypt path (correct,
+ * just slower) until the counter syncs. Fixed size, no extension loop; add
+ * one when a real wallet approaches this many self notes.
+ */
+declare const SELF_EPH_WINDOW = 1024;
+/**
+ * Per-counterparty discovery window. Much smaller than the self window: this
+ * counts payments from ONE sender, and a sender who outruns it just falls back
+ * to the trial-decrypt path — correct, only slower — until the counter syncs.
+ * The window costs two EC muls per index per sender, so it is the one number
+ * that scales with how many people the wallet knows.
+ */
+declare const PAIRWISE_EPH_WINDOW = 64;
+/** Wallet keys needed for trial-decryption. Structured-clone transferable. */
+interface ScanKeys {
+    viewingKey: Uint8Array;
+    spendingKey: bigint;
+    ownerPk: bigint;
+    /**
+     * First leafIndex from which every memo carries a view tag — hints at/after
+     * it go through the 1-byte fast-scan filter (skip the AEAD decrypt on
+     * mismatch). null/undefined = filter off (network not activated yet).
+     */
+    viewTagActivationLeaf?: number | null;
+    /**
+     * Enable self-note discovery: precompute the deterministic ephPk window and
+     * recognize the wallet's own notes (shields, change) by hash lookup — zero
+     * trial ECDH for them. Only worth its one-time window cost (two EC muls
+     * per index) on full scans/restores; leave off for incremental ticks.
+     */
+    selfEph?: boolean;
+    /** Window size override (tests/tuning). Default SELF_EPH_WINDOW. */
+    selfEphWindowSize?: number;
+    /**
+     * Counterparties whose future payments can be recognized without an ECDH.
+     *
+     * A sender's key travels in the plaintext of the first payment they make us,
+     * so once that one is decrypted the normal way, every later note from them
+     * carries an ephemeral both sides derive — found by the same hash lookup as a
+     * self note. A stranger's first payment is unaffected.
+     *
+     * Each entry is one packed viewing public key. Matching happens entirely on
+     * this device: asking a server for a specific ephPk would tell it which notes
+     * are ours, which is exactly what the download-everything feed prevents.
+     */
+    pairwiseCounterparties?: Uint8Array[];
+    /** Per-counterparty window size. Default PAIRWISE_EPH_WINDOW. */
+    pairwiseWindowSize?: number;
+}
+interface DecryptBatchResult {
+    /** One entry per hint, aligned with the input order (null = not ours). */
+    notes: Array<ZkNote | null>;
+    /** Hints discarded by the view-tag check alone — no AEAD work attempted. */
+    tagFiltered: number;
+    /** Hints recognized as own self-notes via the deterministic ephPk window. */
+    selfMatched: number;
+    /**
+     * Hints recognized as coming from a known counterparty, via that sender's
+     * precomputed window. Counted apart from `selfMatched` because it answers a
+     * different question: whether the pairwise mechanism actually fired, or
+     * whether those notes quietly fell through to the expensive path.
+     */
+    pairwiseMatched: number;
+    /** Highest self-eph index seen (feeds the counter bump), or null. */
+    maxSelfEphIndex: number | null;
+}
+/** An empty result — the shape both pool strategies return for zero hints. */
+declare const EMPTY_BATCH_RESULT: DecryptBatchResult;
+
+/**
+ * Trial-decrypts every hint against the wallet's keys. Returns one entry per
+ * hint, aligned with the input order: the recovered note, or null when the
+ * hint isn't ours (MAC failure, view-tag mismatch) or is malformed — a single
+ * bad hint must not kill the batch, the scan just counts it as failed.
+ *
+ * Order per hint: self-note window match (hash lookup, no EC) → view-tag
+ * fast path (one ECDH, one byte) → full trial-decrypt.
+ */
+declare function decryptHintBatch(hints: Array<ScanCommitment & {
+    ephPkHex?: string | null;
+}>, keys: ScanKeys): DecryptBatchResult;
+
+/** Which precomputed window recognized a hint — the two differ in what they prove. */
+type MatchSource = 'self' | 'pairwise';
+interface KnownEphEntry {
+    sharedSecret: Uint8Array;
+    index: number;
+    source: MatchSource;
+}
+interface KnownEphWindow {
+    /** ephPkHex (lowercase) → entry. */
+    byEphPk: Map<string, KnownEphEntry>;
+}
+/**
+ * Drops the precomputed discovery window and the shared secrets in it.
+ *
+ * Call when the wallet locks. The cache is keyed by spending key, so it can
+ * never serve a different identity — but "cannot be misused" is not "is gone":
+ * after `lock()` the session keys are dropped while ~100 KB of ECDH secrets
+ * derived from the viewing key stay reachable in module memory, and on a
+ * main-thread pool that is the page's own heap.
+ *
+ * Terminating a worker achieves the same thing by discarding the whole realm.
+ * This exists for the main-thread pool, which has no realm to discard, and for
+ * hosts that keep their workers warm across a lock.
+ */
+declare function clearKnownEphWindow(): void;
+/**
+ * The window for these keys, built on first use and cached after.
+ *
+ * Returns null when discovery is off entirely (no self-eph, no counterparties)
+ * or when the primitives are unavailable — the scan then takes the trial-decrypt
+ * path for everything, which is slower but correct.
+ */
+declare function getKnownEphWindow(keys: ScanKeys): KnownEphWindow | null;
+
+/**
+ * The pool contract, and the minimal Worker surface it drives.
+ *
+ * `WorkerLike` is deliberately narrower than the DOM `Worker`: the pool only
+ * ever posts a message, reads one back, and terminates. Keeping it to those
+ * four members is what lets a test pass a fake that runs the kernel inline, and
+ * what keeps this file free of `lib.dom`.
+ */
+
+/** Cap on pool size — EC math parallelizes linearly but tabs share the CPU. */
+/**
+ * Ceiling on workers per batch. Past four the ECDH loop is bound by memory
+ * bandwidth rather than cores, and every extra worker still costs its own copy
+ * of the precomputed discovery window.
+ */
+declare const MAX_WORKERS = 4;
+/**
+ * Main-thread strategy only: trial-decrypts to run before yielding so the
+ * browser can paint between bursts of synchronous EC math.
+ */
+declare const DECRYPT_YIELD_EVERY = 25;
+/**
+ * The message a worker hands back, structurally.
+ *
+ * Not `MessageEvent`: that name lives in `lib.dom`, and naming it here would put
+ * it in the published `.d.ts` of the ROOT entry — so a React Native consumer
+ * compiling with `lib: esnext` and no `@types/node` would fail to typecheck an
+ * import it never asked for. `data` is the only member the pool reads, and a
+ * real `MessageEvent` satisfies this shape.
+ *
+ * Same reasoning as `CryptoKey` in `utils/crypto/webcrypto-types.d.ts`.
+ */
+interface WorkerMessage {
+    data: unknown;
+}
+/**
+ * The minimal Worker surface the pool needs — a real Worker or a test fake.
+ *
+ * The handler parameters are typed `any` rather than `unknown`, which is the
+ * one place this file trades strictness for reach. A DOM `Worker` declares
+ * `onerror` as `(event: ErrorEvent) => void`, and function parameters are
+ * contravariant: a handler accepting `unknown` is NOT assignable where one
+ * accepting `ErrorEvent` is expected. Typing these as `unknown` therefore makes
+ * a real browser `Worker` fail to satisfy the interface — the exact consumer
+ * this contract exists to serve.
+ *
+ * `any` keeps both a real Worker and an inline fake assignable while still
+ * keeping `MessageEvent`/`ErrorEvent` — both `lib.dom` — out of the published
+ * types. The pool reads only `event.data` and ignores the error payload
+ * entirely, so nothing downstream depends on the precision given up here.
+ */
+interface WorkerLike {
+    postMessage(message: unknown): void;
+    onmessage: ((event: any) => void) | null;
+    /** Error payload is unused: the pool treats any error as "worker died". */
+    onerror: ((event: any) => void) | null;
+    terminate(): void;
+}
+type WorkerFactory = () => WorkerLike;
+interface DecryptPool {
+    /** Decrypts `hints` in input order. Rejects with AbortError when cancelled. */
+    decryptBatch(hints: ScanCommitment[], keys: ScanKeys, signal?: AbortSignal): Promise<DecryptBatchResult>;
+    /** Tears down every worker. The pool is per-scan; always call when done. */
+    terminate(): void;
+}
+/** The message a worker receives. Structured-clone friendly by construction. */
+interface DecryptRequest {
+    hints: ScanCommitment[];
+    keys: ScanKeys;
+}
+/** Thrown when a worker dies mid-batch; the factory catches it to fall back. */
+declare const WORKER_CRASHED = "Decrypt worker crashed";
+
+/**
+ * Builds the decrypt pool for one scan run.
+ *
+ * `factory` is required rather than defaulted: constructing a worker means
+ * naming a module URL, which only the host's bundler can resolve. Pass `null`
+ * to decrypt on the calling thread — correct everywhere, and the only option
+ * outside a browser.
+ */
+declare function createDecryptPool(options: {
+    factory: WorkerFactory | null;
+    /** Workers to spread a batch across. Defaults to `MAX_WORKERS`. */
+    size?: number;
+}): DecryptPool;
+
+declare function createMainThreadPool(): DecryptPool;
+
+declare function createWorkerPool(factory: WorkerFactory, size: number): DecryptPool;
+
+export { CURRENT_CIRCUIT_VERSION as C, type DecryptedMemo as D, EMPTY_BATCH_RESULT as E, type KnownEphEntry as K, MAX_WORKERS as M, type NoteInput as N, PAIRWISE_EPH_WINDOW as P, type ScanCommitment as S, WORKER_CRASHED as W, type ZkNote as Z, type DecryptPool as a, type ScanKeys as b, DECRYPT_YIELD_EVERY as c, type DecryptBatchResult as d, type DecryptRequest as e, type KnownEphWindow as f, type MatchSource as g, type MerkleTreeInfo as h, SELF_EPH_WINDOW as i, type WorkerFactory as j, type WorkerLike as k, type WorkerMessage as l, clearKnownEphWindow as m, createDecryptPool as n, createMainThreadPool as o, createWorkerPool as p, decryptHintBatch as q, getKnownEphWindow as r };