@orbinum/sdk 1.1.1 → 1.2.0

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

@@ -342,14 +342,75 @@ var EncryptedMemo = {
   }
 };
 
-// src/foundation/crypto/stealth.ts
-import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
+// src/protocol/memo/OutgoingBlob.ts
+import { chacha20poly1305 as chacha20poly13052 } from "@noble/ciphers/chacha.js";
+import { randomBytes as randomBytes2 } from "@noble/ciphers/utils.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
+var OCK_DOMAIN = new TextEncoder().encode("orbinum-outgoing-cipher-v1");
+var NONCE_PREFIX = new TextEncoder().encode("OVK1");
+var NONCE_SUFFIX_SIZE = 8;
+var SHARED_SECRET_SIZE = 32;
+var MAC_SIZE = 16;
+var OVK_BLOB_SIZE = NONCE_SUFFIX_SIZE + SHARED_SECRET_SIZE + MAC_SIZE;
+function deriveOutgoingCipherKey(ovk, commitmentBytes, ephPkBytes) {
+  if (commitmentBytes.length !== 32) {
+    throw new Error(
+      `OutgoingBlob: commitmentBytes must be 32 bytes, got ${commitmentBytes.length}`
+    );
+  }
+  if (ephPkBytes.length !== 32) {
+    throw new Error(`OutgoingBlob: ephPkBytes must be 32 bytes, got ${ephPkBytes.length}`);
+  }
+  const salt = new Uint8Array(64);
+  salt.set(commitmentBytes, 0);
+  salt.set(ephPkBytes, 32);
+  return hkdf(sha2562, ovk, salt, OCK_DOMAIN, 32);
+}
+function buildNonce(suffix) {
+  const nonce = new Uint8Array(12);
+  nonce.set(NONCE_PREFIX, 0);
+  nonce.set(suffix, 4);
+  return nonce;
+}
+function sealOutgoingBlob(ovk, sharedSecret, commitmentBytes, ephPkBytes) {
+  if (sharedSecret.length !== SHARED_SECRET_SIZE) {
+    throw new Error(`OutgoingBlob: sharedSecret must be 32 bytes, got ${sharedSecret.length}`);
+  }
+  const ock = deriveOutgoingCipherKey(ovk, commitmentBytes, ephPkBytes);
+  const suffix = randomBytes2(NONCE_SUFFIX_SIZE);
+  const cipher = chacha20poly13052(ock, buildNonce(suffix));
+  const sealed = cipher.encrypt(sharedSecret);
+  const blob = new Uint8Array(OVK_BLOB_SIZE);
+  blob.set(suffix, 0);
+  blob.set(sealed, NONCE_SUFFIX_SIZE);
+  return blob;
+}
+function openOutgoingBlob(ovk, blob, commitmentBytes, ephPkBytes) {
+  if (blob.length !== OVK_BLOB_SIZE) return null;
+  if (commitmentBytes.length !== 32 || ephPkBytes.length !== 32) return null;
+  try {
+    const ock = deriveOutgoingCipherKey(ovk, commitmentBytes, ephPkBytes);
+    const suffix = blob.subarray(0, NONCE_SUFFIX_SIZE);
+    const sealed = blob.subarray(NONCE_SUFFIX_SIZE);
+    const cipher = chacha20poly13052(ock, buildNonce(suffix));
+    return cipher.decrypt(sealed);
+  } catch {
+    return null;
+  }
+}
+function randomOutgoingBlob() {
+  return randomBytes2(OVK_BLOB_SIZE);
+}
+
+// src/foundation/crypto/stealth.ts
+import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
+import { hkdf as hkdf2 } from "@noble/hashes/hkdf.js";
 import { mulPointEscalar, Base8, addPoint } from "@zk-kit/baby-jubjub";
 var STEALTH_INFO = new TextEncoder().encode("orbinum-stealth-v1");
 function deriveStealthScalar(sharedSecret, ownerPkBigint) {
   const salt = bigintTo32Le(ownerPkBigint);
-  const stealthBytes = hkdf(sha2562, sharedSecret, salt, STEALTH_INFO, 32);
+  const stealthBytes = hkdf2(sha2563, sharedSecret, salt, STEALTH_INFO, 32);
   return bytesToBigintLE(stealthBytes) % BABYJUB_SUBORDER || 1n;
 }
 function deriveStealthOwnerPk(sharedSecret, ownerPkBigint, ownerPkPoint) {
@@ -427,7 +488,7 @@ function recoverOwnerPkPoint(ax) {
 
 // src/protocol/note/NoteBuilder.ts
 import { mulPointEscalar as mulPointEscalar3, unpackPoint as unpackPoint2 } from "@zk-kit/baby-jubjub";
-import { randomBytes as randomBytes2 } from "@noble/ciphers/utils.js";
+import { randomBytes as randomBytes3 } from "@noble/ciphers/utils.js";
 import { poseidon2, poseidon4 } from "poseidon-lite";
 var NoteBuilder = class {
   /**
@@ -456,7 +517,7 @@ var NoteBuilder = class {
     if (useStealth) {
       const recipientOwnerPk = input.recipientOwnerPk;
       const recipientIvkPacked = input.viewingPublicKey;
-      const ephSk = randomBytes2(32);
+      const ephSk = randomBytes3(32);
       const ivkPackedBigint = bytesToBigintLE(recipientIvkPacked);
       const ivkPoint = unpackPoint2(ivkPackedBigint);
       if (!ivkPoint)
@@ -497,6 +558,21 @@ var NoteBuilder = class {
         throw new Error(
           `NoteBuilder.build: invariant violated \u2014 memo must be ${ENCRYPTED_MEMO_SIZE} bytes, got ${memo.length}`
         );
+      let ovkBlob;
+      if (input.outgoingViewingKey !== void 0) {
+        const ephPkBytes = Uint8Array.from(memo.slice(148, 180));
+        const sealed = sealOutgoingBlob(
+          input.outgoingViewingKey,
+          sharedSecret,
+          stealthCommitmentBytes,
+          ephPkBytes
+        );
+        if (sealed.length !== OVK_BLOB_SIZE)
+          throw new Error(
+            `NoteBuilder.build: invariant violated \u2014 ovkBlob must be ${OVK_BLOB_SIZE} bytes, got ${sealed.length}`
+          );
+        ovkBlob = Array.from(sealed);
+      }
       return {
         value,
         assetId,
@@ -511,7 +587,8 @@ var NoteBuilder = class {
         commitmentHex: toHex(commitmentBytes2),
         nullifierHex: toHex(nullifierBytes2),
         memo,
-        counterpartyPk
+        counterpartyPk,
+        ...ovkBlob ? { ovkBlob } : {}
       };
     }
     const commitment = poseidon4([value, assetId, ownerPk, blinding]);
@@ -641,6 +718,18 @@ function buildDummyTransferInput(assetId) {
 }
 
 // src/protocol/note/NoteDecryptor.ts
+function decryptAndVerifyPlaintext(memoBytes, commitmentBytes, sharedSecret, effectiveOwnerPk) {
+  const plaintext = EncryptedMemo.decryptWithSharedSecret(
+    memoBytes,
+    commitmentBytes,
+    sharedSecret
+  );
+  if (!plaintext) return null;
+  const ownerPk = effectiveOwnerPk ?? plaintext.ownerPk;
+  const recomputed = poseidon42([plaintext.value, plaintext.assetId, ownerPk, plaintext.blinding]);
+  if (recomputed !== bytesToBigintLE(commitmentBytes)) return null;
+  return plaintext;
+}
 function computeNullifier(commitment, spendingKey) {
   return poseidon22([commitment, spendingKey]);
 }
@@ -723,6 +812,40 @@ function tryDecryptNoteVerbose(commitment, viewingSecretKey, spendingKey, ownOwn
     }
   };
 }
+function tryRecoverOutgoing(hint, ovk, opts) {
+  if (!hint.ovkBlob || !hint.encryptedMemo) return null;
+  let commitmentBytes;
+  let memoBytes;
+  let blobBytes;
+  try {
+    commitmentBytes = fromHex(hint.commitmentHex);
+    memoBytes = fromHex(hint.encryptedMemo);
+    blobBytes = fromHex(hint.ovkBlob);
+  } catch {
+    return null;
+  }
+  if (memoBytes.length !== ENCRYPTED_MEMO_SIZE) return null;
+  if (blobBytes.length !== OVK_BLOB_SIZE) return null;
+  const ephPkBytes = memoBytes.subarray(148, 180);
+  const sharedSecret = openOutgoingBlob(ovk, blobBytes, commitmentBytes, ephPkBytes);
+  if (!sharedSecret) return null;
+  const activation = opts?.viewTagActivationLeaf;
+  if (activation !== void 0 && isValidLeafIndex(hint.leafIndex) && hint.leafIndex >= activation && !EncryptedMemo.checkViewTag(memoBytes, sharedSecret)) {
+    return null;
+  }
+  const plaintext = decryptAndVerifyPlaintext(memoBytes, commitmentBytes, sharedSecret, null);
+  if (!plaintext) return null;
+  return {
+    commitmentHex: hint.commitmentHex,
+    ...isValidLeafIndex(hint.leafIndex) ? { leafIndex: hint.leafIndex } : {},
+    value: plaintext.value,
+    assetId: plaintext.assetId,
+    recipientStealthPk: plaintext.ownerPk,
+    blinding: plaintext.blinding,
+    counterpartyPk: plaintext.counterpartyPk,
+    circuitVersion: plaintext.circuitVersion
+  };
+}
 
 // src/protocol/note/NoteDisclosure.ts
 import { poseidon4 as poseidon43 } from "poseidon-lite";
@@ -809,11 +932,11 @@ function decodeNoteDisclosureKey(key) {
 }
 
 // src/protocol/eph/selfEph.ts
-import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
+import { sha256 as sha2564 } from "@noble/hashes/sha2.js";
 import { packPoint as packPoint2, unpackPoint as unpackPoint3 } from "@zk-kit/baby-jubjub";
 var SELF_EPH_DOMAIN = new TextEncoder().encode("orbinum-self-eph-v1");
 function deriveSelfEphSk(spendingKey, index) {
-  const h = sha2563.create();
+  const h = sha2564.create();
   h.update(SELF_EPH_DOMAIN);
   h.update(bigintTo32Le(spendingKey));
   const idx = new Uint8Array(4);
@@ -839,7 +962,7 @@ function selfEphWindow(spendingKey, ivkPacked, from, count) {
 }
 
 // src/protocol/eph/pairwiseEph.ts
-import { sha256 as sha2564 } from "@noble/hashes/sha2.js";
+import { sha256 as sha2565 } from "@noble/hashes/sha2.js";
 import { packPoint as packPoint3, unpackPoint as unpackPoint4 } from "@zk-kit/baby-jubjub";
 var PAIRWISE_EPH_DOMAIN = new TextEncoder().encode("orbinum-pairwise-eph-v1");
 function derivePairwiseSharedSecret(myViewingSk, theirIvkPacked) {
@@ -849,7 +972,7 @@ function derivePairwiseSharedSecret(myViewingSk, theirIvkPacked) {
   return bigintTo32Le(shared[0]);
 }
 function derivePairwiseEphSk(pairSecret, index) {
-  const h = sha2564.create();
+  const h = sha2565.create();
   h.update(PAIRWISE_EPH_DOMAIN);
   h.update(pairSecret);
   const idx = new Uint8Array(4);
@@ -875,10 +998,11 @@ function pairwiseEphWindow(pairSecret, receiverIvkPacked, from, count) {
 }
 
 // src/protocol/keys/PrivacyKeys.ts
-import { hkdf as hkdf2 } from "@noble/hashes/hkdf.js";
-import { sha256 as sha2565 } from "@noble/hashes/sha2.js";
+import { hkdf as hkdf3 } from "@noble/hashes/hkdf.js";
+import { sha256 as sha2566 } from "@noble/hashes/sha2.js";
 import { packPoint as packPoint4 } from "@zk-kit/baby-jubjub";
 var IVK_DOMAIN = new TextEncoder().encode("orbinum-ivk-v1");
+var OVK_DOMAIN = new TextEncoder().encode("orbinum-ovk-v1");
 var KEY_VERSION = "v2";
 function deriveSpendingKeyFromMaster(masterBytes) {
   const skBigint = BigInt(toHex(masterBytes)) % BABYJUB_SUBORDER;
@@ -886,7 +1010,7 @@ function deriveSpendingKeyFromMaster(masterBytes) {
 }
 function deriveViewingSecretKey(spendingKey) {
   const ikm = bigintTo32Le(spendingKey);
-  return hkdf2(sha2565, ikm, void 0, IVK_DOMAIN, 32);
+  return hkdf3(sha2566, ikm, void 0, IVK_DOMAIN, 32);
 }
 function deriveViewingPublicKey(ivsk) {
   const ivskScalar = BigInt(toHex(ivsk)) % BABYJUB_SUBORDER || 1n;
@@ -902,6 +1026,9 @@ function deriveOwnerPk(spendingKey) {
     return 0n;
   }
 }
+function deriveOutgoingViewingKey(masterBytes) {
+  return hkdf3(sha2566, masterBytes, void 0, OVK_DOMAIN, 32);
+}
 
 // src/wallet/worker/kernel/types.ts
 var SELF_EPH_WINDOW = 1024;
@@ -1201,6 +1328,11 @@ export {
   ENCRYPTED_MEMO_SIZE,
   bytesToBjjScalar,
   EncryptedMemo,
+  OVK_BLOB_SIZE,
+  deriveOutgoingCipherKey,
+  sealOutgoingBlob,
+  openOutgoingBlob,
+  randomOutgoingBlob,
   deriveSelfEphSk,
   selfEphWindow,
   derivePairwiseSharedSecret,
@@ -1220,6 +1352,7 @@ export {
   computeNoteCommitment,
   tryDecryptNote,
   tryDecryptNoteVerbose,
+  tryRecoverOutgoing,
   createNoteDisclosureKey,
   decodeNoteDisclosureKey,
   KEY_VERSION,
@@ -1227,6 +1360,7 @@ export {
   deriveViewingSecretKey,
   deriveViewingPublicKey,
   deriveOwnerPk,
+  deriveOutgoingViewingKey,
   SELF_EPH_WINDOW,
   PAIRWISE_EPH_WINDOW,
   EMPTY_BATCH_RESULT,

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

@@ -76,6 +76,13 @@ type NoteInput = {
      * generates its own coordinated ephSk). Default: random.
      */
     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
@@ -129,6 +136,39 @@ type ZkNote = {
     memo: number[];
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
     counterpartyPk: 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. */
+    counterpartyPk: bigint;
+    /** Circuit version the sent note was created under. */
+    circuitVersion: number;
 };
 
 /**
@@ -350,4 +390,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, 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 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 };

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

@@ -76,6 +76,13 @@ type NoteInput = {
      * generates its own coordinated ephSk). Default: random.
      */
     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
@@ -129,6 +136,39 @@ type ZkNote = {
     memo: number[];
     /** Counterparty BabyJubJub Ax coordinate. Zero for shield/unshield notes. */
     counterpartyPk: 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. */
+    counterpartyPk: bigint;
+    /** Circuit version the sent note was created under. */
+    circuitVersion: number;
 };
 
 /**
@@ -350,4 +390,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, 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 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 };