@orbinum/sdk 1.4.0 → 2.0.0

package/dist/{chunk-A2ZRMEYW.mjs → chunk-VYKKBXOE.mjs}

@@ -33,6 +33,9 @@ function fastMulPoint(point, scalar) {
 }
 
 // src/foundation/encoding/hex.ts
+function isHexOfLength(value, byteLen) {
+  return typeof value === "string" && new RegExp(`^0x[0-9a-fA-F]{${byteLen * 2}}$`).test(value);
+}
 function toHex(bytes) {
   return "0x" + Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -41,11 +44,12 @@ function fromHex(hex) {
   if (clean.length % 2 !== 0) {
     throw new Error(`Invalid hex string \u2014 odd length: "${hex}"`);
   }
+  if (!/^[0-9a-fA-F]*$/.test(clean)) {
+    throw new Error("Invalid hex string \u2014 non-hex characters");
+  }
   const bytes = new Uint8Array(clean.length / 2);
   for (let i = 0; i < bytes.length; i++) {
-    const byte = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
-    if (isNaN(byte)) throw new Error(`Invalid hex character at position ${i * 2}`);
-    bytes[i] = byte;
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
   }
   return bytes;
 }
@@ -63,7 +67,13 @@ function scalarToHex(value) {
 }
 
 // src/foundation/encoding/bytes.ts
+function assert32ByteRange(n, fn) {
+  if (n < 0n || n >= 1n << 256n) {
+    throw new Error(`${fn}: value does not fit in 32 bytes: ${n}`);
+  }
+}
 function bigintTo32Le(n) {
+  assert32ByteRange(n, "bigintTo32Le");
   const buf = new Uint8Array(32);
   let v = n;
   for (let i = 0; i < 32; i++) {
@@ -80,6 +90,7 @@ function bytesToBigintLE(bytes) {
   return result;
 }
 function bigintTo32Be(n) {
+  assert32ByteRange(n, "bigintTo32Be");
   const buf = new Uint8Array(32);
   let v = n;
   for (let i = 31; i >= 0 && v > 0n; i--) {
@@ -89,6 +100,7 @@ function bigintTo32Be(n) {
   return buf;
 }
 function bigintTo32LeArr(n) {
+  assert32ByteRange(n, "bigintTo32LeArr");
   const out = new Array(32).fill(0);
   let v = n;
   for (let i = 0; i < 32; i++) {
@@ -119,7 +131,7 @@ import { sha256 } from "@noble/hashes/sha2.js";
 var KEY_DOMAIN = new TextEncoder().encode("orbinum-note-encryption-v1");
 var VIEW_TAG_DOMAIN = new TextEncoder().encode("orbinum-view-tag-v1");
 var MEMO_PLAINTEXT_SIZE = 120;
-function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk, circuitVersion) {
+function serializeMemo(value, ownerPk, blinding, assetId, sourcePk, circuitVersion) {
   const buf = new Uint8Array(MEMO_PLAINTEXT_SIZE);
   const view = new DataView(buf.buffer);
   view.setBigUint64(0, value & 0xffffffffffffffffn, true);
@@ -127,7 +139,7 @@ function serializeMemo(value, ownerPk, blinding, assetId, counterpartyPk, circui
   buf.set(ownerPk.slice(0, 32), 16);
   buf.set(blinding.slice(0, 32), 48);
   view.setUint32(80, assetId >>> 0, true);
-  buf.set(counterpartyPk.slice(0, 32), 84);
+  buf.set(sourcePk.slice(0, 32), 84);
   view.setUint32(116, circuitVersion >>> 0, true);
   return buf;
 }
@@ -165,9 +177,9 @@ function parsePlaintext(nonce, ciphertextWithMac, encKey) {
     const ownerPk = bytesToBigintLE(plaintext.slice(16, 48));
     const blinding = bytesToBigintLE(plaintext.slice(48, 80));
     const assetId = BigInt(view.getUint32(80, true));
-    const counterpartyPk = bytesToBigintLE(plaintext.slice(84, 116));
+    const sourcePk = bytesToBigintLE(plaintext.slice(84, 116));
     const circuitVersion = view.getUint32(116, true);
-    return { value, ownerPk, blinding, assetId, counterpartyPk, circuitVersion };
+    return { value, ownerPk, blinding, assetId, sourcePk, circuitVersion };
   } catch {
     return null;
   }
@@ -185,19 +197,19 @@ var EncryptedMemo = {
    *                           (from PrivacyKeyManager.getViewingPublicKeyPacked() or
    *                           decoded from a privacy address).
    *                           Pass `new Uint8Array(32)` (all zeros) for a publicly-readable memo.
-   * @param counterpartyPk     32-byte counterparty BJJ Ax. Default: all zeros.
+   * @param sourcePk     32-byte counterparty BJJ Ax. Default: all zeros.
    * @param circuitVersion     ZK circuit version the note is spent under. Default: 0.
    * @param ephSkOverride      32-byte ephemeral secret key (stealth coordination). Optional.
    * @returns 180-byte encrypted memo: nonce(12) || ciphertext+MAC(136) || ephPk(32).
    */
-  encrypt(value, ownerPk, blinding, assetId, commitment, recipientIvkPacked, counterpartyPk = new Uint8Array(32), circuitVersion = 0, ephSkOverride) {
+  encrypt(value, ownerPk, blinding, assetId, commitment, recipientIvkPacked, sourcePk = new Uint8Array(32), circuitVersion = 0, ephSkOverride) {
     const nonce = randomBytes(NONCE_SIZE);
     const plaintext = serializeMemo(
       value,
       ownerPk,
       blinding,
       assetId,
-      counterpartyPk,
+      sourcePk,
       circuitVersion
     );
     const isZeroKey = recipientIvkPacked.every((b) => b === 0);
@@ -510,14 +522,14 @@ var NoteBuilder = class {
     const ownerPk = input.ownerPk ?? 0n;
     const blinding = input.blinding ?? BigInt(Date.now());
     const spendingKey = input.spendingKey ?? 0n;
-    const counterpartyPk = input.counterpartyPk ?? 0n;
+    const sourcePk = input.sourcePk ?? 0n;
     const circuitVersion = input.circuitVersion ?? CURRENT_CIRCUIT_VERSION;
     const useStealth = input.viewingPublicKey !== void 0 && input.recipientOwnerPk !== void 0;
     let memo;
     if (useStealth) {
       const recipientOwnerPk = input.recipientOwnerPk;
       const recipientIvkPacked = input.viewingPublicKey;
-      const ephSk = randomBytes3(32);
+      const ephSk = input.ephSkOverride ?? randomBytes3(32);
       const ivkPackedBigint = bytesToBigintLE(recipientIvkPacked);
       const ivkPoint = unpackPoint2(ivkPackedBigint);
       if (!ivkPoint)
@@ -545,7 +557,7 @@ var NoteBuilder = class {
           Number(assetId),
           stealthCommitmentBytes,
           recipientIvkPacked,
-          bigintTo32Le(counterpartyPk),
+          bigintTo32Le(sourcePk),
           circuitVersion,
           ephSk
         )
@@ -587,7 +599,7 @@ var NoteBuilder = class {
         commitmentHex: toHex(commitmentBytes2),
         nullifierHex: toHex(nullifierBytes2),
         memo,
-        counterpartyPk,
+        sourcePk,
         ...ovkBlob ? { ovkBlob } : {}
       };
     }
@@ -603,7 +615,7 @@ var NoteBuilder = class {
         Number(assetId),
         commitmentBytes,
         input.viewingPublicKey,
-        bigintTo32Le(counterpartyPk),
+        bigintTo32Le(sourcePk),
         circuitVersion,
         input.ephSkOverride
       )
@@ -626,7 +638,7 @@ var NoteBuilder = class {
       commitmentHex: toHex(commitmentBytes),
       nullifierHex: toHex(nullifierBytes),
       memo,
-      counterpartyPk
+      sourcePk
     };
   }
   /**
@@ -638,10 +650,10 @@ var NoteBuilder = class {
    * @param note                    The ZkNote whose fields populate the plaintext.
    * @param recipientIvkPacked      32-byte LE packed BJJ viewing public key of the recipient.
    *                                Pass `new Uint8Array(32)` (default) for a public/dummy memo.
-   * @param counterpartyPk          32-byte counterparty BabyJubJub Ax.
+   * @param sourcePk          32-byte counterparty BabyJubJub Ax.
    *                                Pass `new Uint8Array(32)` (default) for no counterparty.
    */
-  static buildMemo(note, recipientIvkPacked, counterpartyPk) {
+  static buildMemo(note, recipientIvkPacked, sourcePk) {
     return EncryptedMemo.encrypt(
       note.value,
       bigintTo32Le(note.ownerPk),
@@ -649,7 +661,7 @@ var NoteBuilder = class {
       Number(note.assetId),
       bigintTo32Le(note.commitment),
       recipientIvkPacked ?? new Uint8Array(32),
-      counterpartyPk ?? bigintTo32Le(note.counterpartyPk ?? 0n),
+      sourcePk ?? bigintTo32Le(note.sourcePk ?? 0n),
       note.circuitVersion
     );
   }
@@ -808,7 +820,7 @@ function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwn
       commitmentHex: toHex(bigintTo32Le(recomputed)),
       nullifierHex: toHex(bigintTo32Le(nullifier)),
       memo: Array.from(memoBytes),
-      counterpartyPk: plaintext.counterpartyPk
+      sourcePk: plaintext.sourcePk
     }
   };
 }
@@ -842,10 +854,19 @@ function tryRecoverOutgoing(hint, ovk, opts) {
     assetId: plaintext.assetId,
     recipientStealthPk: plaintext.ownerPk,
     blinding: plaintext.blinding,
-    counterpartyPk: plaintext.counterpartyPk,
+    sourcePk: plaintext.sourcePk,
     circuitVersion: plaintext.circuitVersion
   };
 }
+function collectOutgoingFacts(hint) {
+  if (!isHexOfLength(hint.commitmentHex, 32)) return null;
+  if (!isHexOfLength(hint.encryptedMemo, ENCRYPTED_MEMO_SIZE)) return null;
+  return {
+    commitmentHex: hint.commitmentHex,
+    ...isValidLeafIndex(hint.leafIndex) ? { leafIndex: hint.leafIndex } : {},
+    encryptedMemo: hint.encryptedMemo
+  };
+}
 
 // src/protocol/note/NoteDisclosure.ts
 import { poseidon4 as poseidon43 } from "poseidon-lite";
@@ -1300,6 +1321,7 @@ function createDecryptPool(options) {
 }
 
 export {
+  isHexOfLength,
   toHex,
   fromHex,
   ensureHexPrefix,
@@ -1333,13 +1355,6 @@ export {
   sealOutgoingBlob,
   openOutgoingBlob,
   randomOutgoingBlob,
-  deriveSelfEphSk,
-  selfEphWindow,
-  derivePairwiseSharedSecret,
-  derivePairwiseEphSk,
-  pairwiseEphWindow,
-  CURRENT_CIRCUIT_VERSION,
-  NoteBuilder,
   LEAVES_PER_TREE,
   isValidLeafIndex,
   treeIdOf,
@@ -1347,12 +1362,20 @@ export {
   canPairWith,
   selectNotes,
   buildDummyTransferInput,
+  deriveSelfEphSk,
+  selfEphWindow,
+  derivePairwiseSharedSecret,
+  derivePairwiseEphSk,
+  pairwiseEphWindow,
+  CURRENT_CIRCUIT_VERSION,
+  NoteBuilder,
   computeNullifier,
   commitmentHexOf,
   computeNoteCommitment,
   tryDecryptNote,
   tryDecryptNoteVerbose,
   tryRecoverOutgoing,
+  collectOutgoingFacts,
   createNoteDisclosureKey,
   decodeNoteDisclosureKey,
   KEY_VERSION,

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

@@ -36,7 +36,7 @@ type DecryptedMemo = {
     /** Asset ID of the note. */
     assetId: bigint;
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
-    counterpartyPk: bigint;
+    sourcePk: bigint;
     /** ZK circuit version the note is spent under, recovered from the memo plaintext. */
     circuitVersion: number;
 };
@@ -66,14 +66,21 @@ type NoteInput = {
      */
     recipientOwnerPk?: bigint;
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. Default 0n. */
-    counterpartyPk?: bigint;
+    sourcePk?: 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.
+     * 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`.
+     *
+     * 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
+     * that the value is unique — reusing it republishes an ephPk and links the
+     * two notes in public.
      */
     ephSkOverride?: Uint8Array;
     /**
@@ -135,7 +142,7 @@ type ZkNote = {
      */
     memo: number[];
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
-    counterpartyPk: bigint;
+    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
@@ -166,10 +173,36 @@ type OutgoingNoteRecord = {
      *  recomputes the commitment — needed to rebuild a payment slip for the note. */
     blinding: bigint;
     /** Counterparty BabyJubJub Ax coordinate stamped in the memo. */
-    counterpartyPk: bigint;
+    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.
+ *
+ * No decryption and no key: the memo travels verbatim, exactly as published.
+ * The point is to FORWARD it to the recipient inside a fresh payment slip, not
+ * to read it — the recipient opens it with their own viewing key as always.
+ *
+ * That is what makes a slip recoverable after a lost device. What is NOT
+ * recoverable this way is the amount and the recipient, which live inside the
+ * sealed memo: a sender restoring from a seed alone gets working slips, not
+ * their outgoing history.
+ */
+type NoteFacts = {
+    /** 0x-prefixed 32-byte LE commitment hex of the recipient output. */
+    commitmentHex: string;
+    /** Global Merkle leaf index, when known. */
+    leafIndex?: number;
+    /**
+     * The note's 180-byte encrypted memo, 0x-prefixed, exactly as published.
+     *
+     * Carried verbatim, never decrypted here — the sender has no key for it.
+     * Handing it back to the recipient inside a fresh slip is what re-issuing a
+     * slip means.
+     */
+    encryptedMemo: string;
+};
 
 /**
  * What crosses the worker boundary.
@@ -390,4 +423,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 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 };
+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 };

package/dist/{index-V5Z9igEN.d.ts → index-CLpM1984.d.ts}

@@ -36,7 +36,7 @@ type DecryptedMemo = {
     /** Asset ID of the note. */
     assetId: bigint;
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
-    counterpartyPk: bigint;
+    sourcePk: bigint;
     /** ZK circuit version the note is spent under, recovered from the memo plaintext. */
     circuitVersion: number;
 };
@@ -66,14 +66,21 @@ type NoteInput = {
      */
     recipientOwnerPk?: bigint;
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. Default 0n. */
-    counterpartyPk?: bigint;
+    sourcePk?: 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.
+     * 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`.
+     *
+     * 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
+     * that the value is unique — reusing it republishes an ephPk and links the
+     * two notes in public.
      */
     ephSkOverride?: Uint8Array;
     /**
@@ -135,7 +142,7 @@ type ZkNote = {
      */
     memo: number[];
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
-    counterpartyPk: bigint;
+    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
@@ -166,10 +173,36 @@ type OutgoingNoteRecord = {
      *  recomputes the commitment — needed to rebuild a payment slip for the note. */
     blinding: bigint;
     /** Counterparty BabyJubJub Ax coordinate stamped in the memo. */
-    counterpartyPk: bigint;
+    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.
+ *
+ * No decryption and no key: the memo travels verbatim, exactly as published.
+ * The point is to FORWARD it to the recipient inside a fresh payment slip, not
+ * to read it — the recipient opens it with their own viewing key as always.
+ *
+ * That is what makes a slip recoverable after a lost device. What is NOT
+ * recoverable this way is the amount and the recipient, which live inside the
+ * sealed memo: a sender restoring from a seed alone gets working slips, not
+ * their outgoing history.
+ */
+type NoteFacts = {
+    /** 0x-prefixed 32-byte LE commitment hex of the recipient output. */
+    commitmentHex: string;
+    /** Global Merkle leaf index, when known. */
+    leafIndex?: number;
+    /**
+     * The note's 180-byte encrypted memo, 0x-prefixed, exactly as published.
+     *
+     * Carried verbatim, never decrypted here — the sender has no key for it.
+     * Handing it back to the recipient inside a fresh slip is what re-issuing a
+     * slip means.
+     */
+    encryptedMemo: string;
+};
 
 /**
  * What crosses the worker boundary.
@@ -390,4 +423,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 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 };
+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 };