@orbinum/sdk 2.0.0 → 3.0.0

package/dist/{index-CLpM1984.d.mts → index-B-dbSIPN.d.mts}

@@ -35,7 +35,12 @@ type DecryptedMemo = {
     blinding: bigint;
     /** Asset ID of the note. */
     assetId: bigint;
-    /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
+    /**
+     * Who this note came from, or — on a CHANGE note — the recipient book entry
+     * for the payment beside it: the recipient's viewing key sealed under the
+     * sender's ovk, which is ciphertext and not a curve point. Zero for
+     * shield/unshield notes. See `protocol/note/recipientBook`.
+     */
     sourcePk: bigint;
     /** ZK circuit version the note is spent under, recovered from the memo plaintext. */
     circuitVersion: number;
@@ -48,7 +53,7 @@ type NoteInput = {
     assetId?: bigint;
     /** BabyJubJub Ax coordinate (owner public key x). Default 0n. */
     ownerPk?: bigint;
-    /** Random blinding scalar. Defaults to BigInt(Date.now()). */
+    /** Random blinding scalar. Defaults to a CSPRNG draw — never the clock. */
     blinding?: bigint;
     /** Secret spending key used to derive the nullifier. Default 0n. */
     spendingKey?: bigint;
@@ -65,17 +70,21 @@ type NoteInput = {
      * transaction unlinkable even when the same privacy address is reused.
      */
     recipientOwnerPk?: bigint;
-    /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. Default 0n. */
+    /**
+     * Counterparty BabyJubJub Ax, or a sealed recipient book entry on a change
+     * note. Zero for shield/unshield notes. Default 0n.
+     */
     sourcePk?: bigint;
     /** Circuit version to stamp on the note. Defaults to `CURRENT_CIRCUIT_VERSION`. */
     circuitVersion?: number;
     /**
      * 32-byte ephemeral secret for the memo ECDH. Default: random.
      *
-     * Two callers supply one, and both do it so the RECIPIENT can predict the
-     * published ephPk and match it by table lookup instead of one trial ECDH per
-     * pool hint: self-notes pass `deriveSelfEphSk`, and a payment to a known
-     * counterparty passes `derivePairwiseEphSk`.
+     * Callers supply one so that somebody can predict the published ephPk and
+     * match it by table lookup instead of one trial ECDH per pool hint:
+     * self-notes pass `deriveSelfEphSk`, and a payment passes
+     * `deriveOutgoingEphSk` — the latter predictable by the SENDER, which is
+     * what lets a restored wallet read back its own payment history.
      *
      * Honoured on the stealth path too, where the same ephSk drives both the
      * memo encryption and the stealth-owner derivation. Passing one is a promise
@@ -83,13 +92,6 @@ type NoteInput = {
      * two notes in public.
      */
     ephSkOverride?: Uint8Array;
-    /**
-     * Sender's 32-byte outgoing viewing key (ovk). When present on the stealth
-     * path, `build()` seals the memo's shared secret into a 56-byte `ovkBlob` so
-     * the sender can recover this transfer after a cold restore. Absent → no blob
-     * (the app applies the ⊥ default at submit time, never the SDK).
-     */
-    outgoingViewingKey?: Uint8Array;
 };
 /**
  * Circuit version notes are created under today. A note carries its version
@@ -143,39 +145,6 @@ type ZkNote = {
     memo: number[];
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
     sourcePk: bigint;
-    /**
-     * 56-byte outgoing-viewing-key blob (per-note in the domain object; becomes a
-     * per-transaction field at submit, see the OVK plan §4.1). Present only on a
-     * stealth recipient note built with an `outgoingViewingKey`. It wraps the
-     * memo's shared secret under the sender's ovk so the sender can recover the
-     * transfer; the recipient never needs it. Not persisted in the vault.
-     */
-    ovkBlob?: number[];
-};
-/**
- * A sender's record of a note they SENT, recovered via the OVK blob. Not a
- * spendable note: it deliberately carries no `spendingKey`, no `nullifier`, no
- * `spent` flag — the sender does not own the recipient's note, only the memory of
- * having sent it. Used to rebuild the outgoing history after a cold restore.
- */
-type OutgoingNoteRecord = {
-    /** 0x-prefixed 32-byte LE commitment hex of the recipient output. */
-    commitmentHex: string;
-    /** Global Merkle leaf index, when the hint carried one. */
-    leafIndex?: number;
-    /** Amount sent, in planck. */
-    value: bigint;
-    /** Asset ID of the sent note. */
-    assetId: bigint;
-    /** The recipient's one-time stealth owner public key (BJJ Ax). */
-    recipientStealthPk: bigint;
-    /** Blinding scalar of the recipient output. With value/assetId/stealthPk it
-     *  recomputes the commitment — needed to rebuild a payment slip for the note. */
-    blinding: bigint;
-    /** Counterparty BabyJubJub Ax coordinate stamped in the memo. */
-    sourcePk: bigint;
-    /** Circuit version the sent note was created under. */
-    circuitVersion: number;
 };
 /**
  * What a sender can still say about a note they sent, using only public data.
@@ -204,6 +173,75 @@ type NoteFacts = {
     encryptedMemo: string;
 };
 
+/**
+ * What a sender recovers about a note they sent.
+ *
+ * Deliberately without `spendingKey`, `nullifier` or a spent flag: this is a
+ * record of a payment, not a note this wallet can spend.
+ */
+type SentNoteFacts = {
+    /** 0x-prefixed 32-byte LE commitment hex of the recipient output. */
+    commitmentHex: string;
+    /** Global Merkle leaf index, when the hint carried a usable one. */
+    leafIndex?: number;
+    /** Amount sent, in planck. */
+    value: bigint;
+    assetId: bigint;
+    /** The recipient's ONE-TIME stealth owner pk — not their global identity. */
+    recipientStealthPk: bigint;
+    /** Blinding of the recipient output; with the rest it recomputes the commitment. */
+    blinding: bigint;
+    /** Counterparty pk stamped in the memo. */
+    sourcePk: bigint;
+    circuitVersion: number;
+    /** Which outgoing index this note used. Lets a caller repair a lost counter. */
+    ephIndex: number;
+};
+interface RecoverSentNoteParams {
+    /** The output as the indexer serves it: commitment, memo, leaf index. */
+    hint: ScanCommitment;
+    /** This wallet's OUTGOING viewing key — the root of the outgoing sequence. */
+    outgoingViewingKey: Uint8Array;
+    /**
+     * The outgoing index this hint's ephPk matched.
+     *
+     * Callers hold it already: they found the hint by looking its ephPk up in a
+     * precomputed window, and that lookup names the index.
+     */
+    ephIndex: number;
+    /**
+     * Candidate recipients, as packed viewing keys — normally the book rebuilt
+     * from change notes. Each is tried until one opens the memo; the memo's own
+     * MAC is what decides, so a wrong candidate cannot yield a wrong amount.
+     */
+    recipientCandidates: readonly Uint8Array[];
+}
+/**
+ * The facts of a sent note, from a shared secret the caller already derived.
+ *
+ * Split out because a caller sweeping candidates derives the secret itself and
+ * would otherwise pay for it twice.
+ *
+ * Never throws — this runs in loops over hints and candidates.
+ */
+declare function recoverSentFromSharedSecret(hint: ScanCommitment, outgoingSharedSecret: Uint8Array, ephIndex: number): SentNoteFacts | null;
+/**
+ * Recover a note this wallet sent, trying each candidate recipient.
+ *
+ * Returns the facts plus WHICH candidate opened it — the caller needs that to
+ * re-seal a payment slip, which is sealed toward the recipient's viewing key.
+ *
+ * Null covers every "not this one" case without distinguishing them: a
+ * malformed hint, a payment whose recipient is not among the candidates, or a
+ * note this wallet did not send all read the same, and no caller can act on the
+ * difference.
+ *
+ * Never throws — this runs in a loop over hints.
+ */
+declare function recoverSentNote(params: RecoverSentNoteParams): (SentNoteFacts & {
+    recipientIvk: Uint8Array;
+}) | null;
+
 /**
  * What crosses the worker boundary.
  *
@@ -229,11 +267,28 @@ declare const SELF_EPH_WINDOW = 1024;
  * that scales with how many people the wallet knows.
  */
 declare const PAIRWISE_EPH_WINDOW = 64;
+/**
+ * How many outgoing indexes a scan precomputes — how many payments back the
+ * sender's own history reaches in one pass.
+ *
+ * A wallet that has sent more than this gets its window widened from the stored
+ * counter, the same way `selfEphGap` widens the self window.
+ */
+declare const OUTGOING_EPH_WINDOW = 64;
 /** Wallet keys needed for trial-decryption. Structured-clone transferable. */
 interface ScanKeys {
     viewingKey: Uint8Array;
     spendingKey: bigint;
     ownerPk: bigint;
+    /**
+     * Outgoing viewing key (ovk), when this wallet can see what it sent.
+     *
+     * Its own capability: it seeds the outgoing ephemerals and opens the
+     * recipient book, so a scan without it still finds every note the wallet
+     * OWNS and simply reports no payment history. That is what a watch-only
+     * wallet holding only the incoming viewing key gets.
+     */
+    outgoingViewingKey?: Uint8Array;
     /**
      * 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
@@ -264,6 +319,30 @@ interface ScanKeys {
     pairwiseCounterparties?: Uint8Array[];
     /** Per-counterparty window size. Default PAIRWISE_EPH_WINDOW. */
     pairwiseWindowSize?: number;
+    /**
+     * Recognise the notes this wallet SENT, by precomputing the outgoing ephPk
+     * window from the OUTGOING viewing key.
+     *
+     * Not from the spending key: predicting these points IS the capability "see
+     * what I sent", so it hangs off the branch that names it. Requires
+     * `outgoingViewingKey` to be set.
+     *
+     * Enables the sender's own history: amount, recipient and a re-issuable
+     * payment slip, none of which the chain exposes. Costs one EC mul per index
+     * — worth it on a full scan or a restore, waste on an incremental tick.
+     */
+    outgoingEph?: boolean;
+    /** Window size override (tests/tuning). Default OUTGOING_EPH_WINDOW. */
+    outgoingEphWindowSize?: number;
+    /**
+     * Candidate recipients for opening a sent note, as packed viewing keys.
+     *
+     * The outgoing ephPk identifies the note without them, but the secret that
+     * OPENS it is an ECDH against the recipient's key, so recovery tries each
+     * candidate until the memo's MAC accepts one. Normally the recipient book
+     * rebuilt from change notes; a wrong candidate cannot yield a wrong amount.
+     */
+    recipientCandidates?: Uint8Array[];
 }
 interface DecryptBatchResult {
     /** One entry per hint, aligned with the input order (null = not ours). */
@@ -281,7 +360,78 @@ interface DecryptBatchResult {
     pairwiseMatched: number;
     /** Highest self-eph index seen (feeds the counter bump), or null. */
     maxSelfEphIndex: number | null;
+    /**
+     * Highest OUTGOING index seen, or null.
+     *
+     * Feeds the same counter repair as `maxSelfEphIndex`: a restored wallet has
+     * no stored counter, and starting again at 0 would republish the ephemeral
+     * of its own first payment. Every index the scan matched is one this wallet
+     * demonstrably published, so the maximum is a floor the counter must clear.
+     */
+    maxOutgoingEphIndex: number | null;
+    /**
+     * Notes this wallet SENT, recognised in the same sweep.
+     *
+     * A hint whose ephPk falls in the outgoing window is one of our own
+     * payments. Kept apart from `notes` on purpose: the sender does not own it,
+     * and putting it in the vault would show a payment they made as balance
+     * they hold.
+     */
+    sentNotes: SentNoteMatch[];
+    /**
+     * Recipient viewing keys learned from payments opened in this batch, as
+     * lowercase hex.
+     *
+     * Reported so the scan can feed them back as `recipientCandidates` — a
+     * wallet that pays the same person twice opens the second payment from the
+     * first one's key, even when its own change note is in another page.
+     */
+    learnedRecipients: string[];
+    /**
+     * Payments recognised as ours whose memo no candidate opened.
+     *
+     * Their book entry is in a change note this batch did not contain — a page
+     * boundary between a payment and its change is enough. Reported rather than
+     * dropped so the caller can retry them once more of the feed is read;
+     * silently losing one costs a history row and a re-issuable slip forever.
+     */
+    unmatchedSent: UnmatchedSentHint[];
+    /**
+     * Sealed book entries seen in this batch, as raw `sourcePk` values.
+     *
+     * Still ciphertext: the key that opens one is the commitment of the PAYMENT
+     * it names, which this batch may not contain. Reported so a caller holding
+     * a stranded payment can try them against it — the pairing is only knowable
+     * once both halves are in the same place.
+     *
+     * Serialised as decimal strings: `bigint` survives structured clone, but the
+     * worker reply is host-written JSON in some hosts, where it would not.
+     */
+    sealedBookEntries: string[];
 }
+/**
+ * A payment recognised by its outgoing ephPk but not yet opened.
+ *
+ * Carries only what a retry needs: the hint itself and the index its ephPk
+ * matched, so the retry costs no second window lookup.
+ */
+interface UnmatchedSentHint {
+    hint: ScanCommitment;
+    ephIndex: number;
+}
+/**
+ * A note this wallet sent, plus what re-issuing its payment slip needs.
+ *
+ * The memo travels verbatim — a slip forwards it, never reads it — and the
+ * counterparty key is who the fresh envelope is sealed toward. Both are already
+ * in hand at the point of recovery, so carrying them costs nothing and spares
+ * the caller a second lookup.
+ */
+type SentNoteMatch = SentNoteFacts & {
+    counterpartyIvkHex: string;
+    /** The 180-byte encrypted memo, 0x-prefixed, exactly as published. */
+    encryptedMemo: string;
+};
 /** An empty result — the shape both pool strategies return for zero hints. */
 declare const EMPTY_BATCH_RESULT: DecryptBatchResult;
 
@@ -294,9 +444,7 @@ declare const EMPTY_BATCH_RESULT: DecryptBatchResult;
  * 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;
+declare function decryptHintBatch(hints: ScanCommitment[], keys: ScanKeys): DecryptBatchResult;
 
 /** Which precomputed window recognized a hint — the two differ in what they prove. */
 type MatchSource = 'self' | 'pairwise';
@@ -308,6 +456,15 @@ interface KnownEphEntry {
 interface KnownEphWindow {
     /** ephPkHex (lowercase) → entry. */
     byEphPk: Map<string, KnownEphEntry>;
+    /**
+     * ephPkHex (lowercase) → outgoing index, for the notes this wallet SENT.
+     *
+     * Separate from `byEphPk` because it holds no shared secret: an outgoing
+     * memo is sealed toward the RECIPIENT, whose key is not known until a
+     * candidate opens it. The index is all the precompute can supply, and it is
+     * what recovery needs to derive the secret per candidate.
+     */
+    outgoingByEphPk: Map<string, number>;
 }
 /**
  * Drops the precomputed discovery window and the shared secrets in it.
@@ -362,7 +519,7 @@ declare const DECRYPT_YIELD_EVERY = 25;
  * 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`.
+ * Same reasoning as `CryptoKey` in `foundation/crypto/webcrypto-types.d.ts`.
  */
 interface WorkerMessage {
     data: unknown;
@@ -423,4 +580,4 @@ 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, type OutgoingNoteRecord as O, PAIRWISE_EPH_WINDOW as P, type ScanCommitment as S, WORKER_CRASHED as W, type ZkNote as Z, type NoteFacts as a, type DecryptPool as b, type ScanKeys as c, DECRYPT_YIELD_EVERY as d, type DecryptBatchResult as e, type DecryptRequest as f, type KnownEphWindow as g, type MatchSource as h, type MerkleTreeInfo as i, SELF_EPH_WINDOW as j, type WorkerFactory as k, type WorkerLike as l, type WorkerMessage as m, clearKnownEphWindow as n, createDecryptPool as o, createMainThreadPool as p, createWorkerPool as q, decryptHintBatch as r, getKnownEphWindow as s };
+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, OUTGOING_EPH_WINDOW as O, PAIRWISE_EPH_WINDOW as P, type ScanCommitment as S, type UnmatchedSentHint as U, WORKER_CRASHED as W, type ZkNote as Z, type NoteFacts as a, type SentNoteMatch as b, type DecryptPool as c, type ScanKeys as d, DECRYPT_YIELD_EVERY as e, type DecryptBatchResult as f, type DecryptRequest as g, type KnownEphWindow as h, type MerkleTreeInfo as i, SELF_EPH_WINDOW as j, type SentNoteFacts as k, type WorkerFactory as l, type WorkerLike as m, type WorkerMessage as n, clearKnownEphWindow as o, createDecryptPool as p, createMainThreadPool as q, createWorkerPool as r, decryptHintBatch as s, getKnownEphWindow as t, recoverSentFromSharedSecret as u, recoverSentNote as v };