@orbinum/sdk 1.1.0 → 1.2.0

package/dist/index.mjs

@@ -15,6 +15,7 @@ import {
   LEAVES_PER_TREE,
   MAX_WORKERS,
   NoteBuilder,
+  OVK_BLOB_SIZE,
   PAIRWISE_EPH_WINDOW,
   SELF_EPH_WINDOW,
   WORKER_CRASHED,
@@ -38,6 +39,8 @@ import {
   createWorkerPool,
   decodeNoteDisclosureKey,
   decryptHintBatch,
+  deriveOutgoingCipherKey,
+  deriveOutgoingViewingKey,
   deriveOwnerPk,
   derivePairwiseEphSk,
   derivePairwiseSharedSecret,
@@ -59,18 +62,22 @@ import {
   isSpendable,
   isValidLeafIndex,
   leHexToBigint,
+  openOutgoingBlob,
   pairwiseEphWindow,
+  randomOutgoingBlob,
   recoverOwnerPkPoint,
   scalarToHex,
   scanAbortError,
+  sealOutgoingBlob,
   selectNotes,
   selfEphWindow,
   serializeMemo,
   toHex,
   treeIdOf,
   tryDecryptNote,
-  tryDecryptNoteVerbose
-} from "./chunk-Y6LNYJAJ.mjs";
+  tryDecryptNoteVerbose,
+  tryRecoverOutgoing
+} from "./chunk-A2ZRMEYW.mjs";
 
 // src/foundation/encoding/base64.ts
 var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -365,6 +372,101 @@ function addressToFieldElement(address) {
   return bytesToBigintLE(bytes) % BN254_R;
 }
 
+// src/protocol/memo/PaymentSlip.ts
+import { chacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { randomBytes } from "@noble/ciphers/utils.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { packPoint, unpackPoint } from "@zk-kit/baby-jubjub";
+var SLIP_DOMAIN = new TextEncoder().encode("orbinum-payment-slip-v1");
+var NONCE_PREFIX = new TextEncoder().encode("SLP1");
+var EPH_PK_SIZE = 32;
+var NONCE_SUFFIX_SIZE = 8;
+function deriveSlipKey(sharedSecret) {
+  return hkdf(sha256, sharedSecret, void 0, SLIP_DOMAIN, 32);
+}
+function buildNonce(suffix) {
+  const nonce = new Uint8Array(12);
+  nonce.set(NONCE_PREFIX, 0);
+  nonce.set(suffix, 4);
+  return nonce;
+}
+function sealPaymentSlip(recipientIvkPacked, fields) {
+  if (recipientIvkPacked.length !== 32) {
+    throw new Error(
+      `PaymentSlip: recipientIvk must be 32 bytes, got ${recipientIvkPacked.length}`
+    );
+  }
+  const ivkPoint = unpackPoint(bytesToBigintLE(recipientIvkPacked));
+  if (!ivkPoint) throw new Error("PaymentSlip: invalid recipient viewing public key");
+  const ephSkScalar = bytesToBjjScalar(randomBytes(32));
+  const ephPkPacked = bigintTo32Le(packPoint(fastMulBase(ephSkScalar)));
+  const sharedPoint = fastMulPoint(ivkPoint, ephSkScalar);
+  const sharedSecret = bigintTo32Le(sharedPoint[0]);
+  const slipKey = deriveSlipKey(sharedSecret);
+  const suffix = randomBytes(NONCE_SUFFIX_SIZE);
+  const cipher = chacha20poly1305(slipKey, buildNonce(suffix));
+  const plaintext = new TextEncoder().encode(JSON.stringify(fields));
+  const sealed = cipher.encrypt(plaintext);
+  const envelope = new Uint8Array(EPH_PK_SIZE + NONCE_SUFFIX_SIZE + sealed.length);
+  envelope.set(ephPkPacked, 0);
+  envelope.set(suffix, EPH_PK_SIZE);
+  envelope.set(sealed, EPH_PK_SIZE + NONCE_SUFFIX_SIZE);
+  return envelope;
+}
+function openPaymentSlip(recipientIvsk, envelope) {
+  if (envelope.length < EPH_PK_SIZE + NONCE_SUFFIX_SIZE + 16) return null;
+  try {
+    const ephPkPacked = envelope.subarray(0, EPH_PK_SIZE);
+    const ephPkPoint = unpackPoint(bytesToBigintLE(ephPkPacked));
+    if (!ephPkPoint) return null;
+    const ivskScalar = bytesToBjjScalar(recipientIvsk);
+    const sharedSecret = bigintTo32Le(fastMulPoint(ephPkPoint, ivskScalar)[0]);
+    const slipKey = deriveSlipKey(sharedSecret);
+    const suffix = envelope.subarray(EPH_PK_SIZE, EPH_PK_SIZE + NONCE_SUFFIX_SIZE);
+    const sealed = envelope.subarray(EPH_PK_SIZE + NONCE_SUFFIX_SIZE);
+    const cipher = chacha20poly1305(slipKey, buildNonce(suffix));
+    const plaintext = cipher.decrypt(sealed);
+    const fields = JSON.parse(new TextDecoder().decode(plaintext));
+    if (typeof fields.commitmentHex !== "string" || typeof fields.encryptedMemo !== "string") {
+      return null;
+    }
+    return fields;
+  } catch {
+    return null;
+  }
+}
+var PAYMENT_SLIP_SCHEME = "orbslip1:";
+function slipChecksum(payload) {
+  const digest = sha256(new TextEncoder().encode(PAYMENT_SLIP_SCHEME + payload));
+  return toHex(digest.slice(0, 4)).slice(2);
+}
+function encodePaymentSlip(envelope) {
+  const payload = base64UrlEncode(toHex(envelope));
+  return `${PAYMENT_SLIP_SCHEME}${payload}:${slipChecksum(payload)}`;
+}
+function decodePaymentSlip(text) {
+  if (!text.startsWith(PAYMENT_SLIP_SCHEME)) return null;
+  const rest = text.slice(PAYMENT_SLIP_SCHEME.length);
+  const sep = rest.lastIndexOf(":");
+  if (sep < 0) return null;
+  const payload = rest.slice(0, sep);
+  const checksum = rest.slice(sep + 1);
+  if (slipChecksum(payload) !== checksum) return null;
+  try {
+    const hex = base64UrlDecode(payload);
+    const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0) return null;
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+  } catch {
+    return null;
+  }
+}
+
 // src/chain/evm/precompiles/addresses.ts
 var PRECOMPILE_ADDR = {
   // ── Ethereum standard (EIP) ─────────────────────────────────────────────
@@ -463,10 +565,10 @@ ${canonicalAccountId(address)}`;
 }
 
 // src/protocol/keys/PrivacyKeyManager.ts
-import { sha256 } from "@noble/hashes/sha2.js";
+import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
 function privacyAddressChecksum(ownerPkHex, ivkHex) {
   const body = `orbpriv2:${ownerPkHex}:${ivkHex}`;
-  const digest = sha256(new TextEncoder().encode(body));
+  const digest = sha2562(new TextEncoder().encode(body));
   return toHex(digest.slice(0, 4)).slice(2);
 }
 var PrivacyKeyManager = class {
@@ -475,7 +577,8 @@ var PrivacyKeyManager = class {
     masterBytes: null,
     viewingSecretKey: null,
     viewingPublicKeyPacked: null,
-    ownerPk: null
+    ownerPk: null,
+    outgoingViewingKey: null
   };
   /**
    * Load a spending key and its corresponding master bytes into the in-memory session.
@@ -490,12 +593,14 @@ var PrivacyKeyManager = class {
     const viewingSecretKey = deriveViewingSecretKey(spendingKey);
     const viewingPublicKeyPacked = deriveViewingPublicKey(viewingSecretKey);
     const ownerPk = deriveOwnerPk(spendingKey);
+    const outgoingViewingKey = deriveOutgoingViewingKey(masterBytes);
     this._state = {
       spendingKey,
       masterBytes,
       viewingSecretKey,
       viewingPublicKeyPacked,
-      ownerPk
+      ownerPk,
+      outgoingViewingKey
     };
   }
   /** Clear all key material from memory. Call on vault lock / sign-out. */
@@ -505,7 +610,8 @@ var PrivacyKeyManager = class {
       masterBytes: null,
       viewingSecretKey: null,
       viewingPublicKeyPacked: null,
-      ownerPk: null
+      ownerPk: null,
+      outgoingViewingKey: null
     };
   }
   /** Returns true if a spending key has been loaded. */
@@ -550,6 +656,16 @@ var PrivacyKeyManager = class {
     }
     return this._state.ownerPk;
   }
+  /**
+   * Returns the 32-byte outgoing viewing key (ovk). Throws if not loaded.
+   * Used to seal/open the outgoing blob that lets the sender recover a transfer.
+   */
+  getOutgoingViewingKey() {
+    if (this._state.outgoingViewingKey === null) {
+      throw new Error("PrivacyKeyManager: no key loaded. Call load() first.");
+    }
+    return this._state.outgoingViewingKey;
+  }
   /** Returns the spending key as a 32-byte little-endian Uint8Array. Throws if not loaded. */
   getSpendingKeyBytes() {
     return bigintTo32Le(this.getSpendingKey());
@@ -651,8 +767,8 @@ var PrivacyKeyManager = class {
 };
 
 // src/protocol/keys/spendingKeyDerivation.ts
-import { hkdf } from "@noble/hashes/hkdf.js";
-import { sha256 as sha2562 } from "@noble/hashes/sha2.js";
+import { hkdf as hkdf2 } from "@noble/hashes/hkdf.js";
+import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
 var MIN_SIGNATURE_BYTES = 32;
 var MIN_DISTINCT_BYTES = 8;
 function assertUsableSignature(sigBytes) {
@@ -674,7 +790,7 @@ async function deriveMasterKeyBytes(signatureHex, chainId, address) {
   const info = new TextEncoder().encode(
     `orbinum-sk-${KEY_VERSION}:${chainId}:${canonicalAccountId(address)}`
   );
-  return hkdf(sha2562, sigBytes, new Uint8Array(0), info, 32);
+  return hkdf2(sha2563, sigBytes, new Uint8Array(0), info, 32);
 }
 async function deriveSpendingKeyFromSignature(signatureHex, chainId, address) {
   return deriveSpendingKeyFromMaster(await deriveMasterKeyBytes(signatureHex, chainId, address));
@@ -686,7 +802,7 @@ import {
   generateProof,
   WebArtifactProvider
 } from "@orbinum/proof-generator";
-import { randomBytes } from "@noble/ciphers/utils.js";
+import { randomBytes as randomBytes2 } from "@noble/ciphers/utils.js";
 import { mulPointEscalar, Base8 } from "@zk-kit/baby-jubjub";
 import { poseidon4 } from "poseidon-lite";
 
@@ -720,7 +836,7 @@ async function generateUnshieldProof(inputs, options = {}) {
     throw new Error("changeValue must be >= 0.");
   }
   const changeOwnerPubkey = inputs.changeOwnerPubkey ?? mulPointEscalar(Base8, inputs.spendingKey)[0];
-  const changeBlinding = inputs.changeBlinding ?? (changeValue > 0n ? bytesToBigintLE(randomBytes(32)) : 0n);
+  const changeBlinding = inputs.changeBlinding ?? (changeValue > 0n ? bytesToBigintLE(randomBytes2(32)) : 0n);
   const changeCommitment = changeValue > 0n ? poseidon4([changeValue, inputs.assetId, changeOwnerPubkey, changeBlinding]) : 0n;
   const circuitInputs = {
     merkle_root: leHexToBigint(inputs.merkleRoot).toString(),
@@ -5232,7 +5348,9 @@ function noteToBackupEntry(note) {
   return {
     commitmentHex: note.commitmentHex,
     encryptedMemo: toHex(Uint8Array.from(note.memo)),
-    ...note.leafIndex !== void 0 ? { leafIndex: note.leafIndex } : {}
+    ...note.leafIndex !== void 0 ? { leafIndex: note.leafIndex } : {},
+    spent: note.spent,
+    spentAt: note.spentAt
   };
 }
 function encodeNoteBackup(notes, options = {}) {
@@ -5277,7 +5395,13 @@ function importNotesFromBackup(entries, keys) {
       keys.spendingKey,
       keys.ownerPk
     );
-    if (note) out.push(note);
+    if (note) {
+      out.push({
+        ...note,
+        spent: entry.spent ?? false,
+        spentAt: entry.spentAt ?? null
+      });
+    }
   }
   return out;
 }
@@ -5292,6 +5416,22 @@ function isEntry2(value) {
   return true;
 }
 
+// src/wallet/ops/notes/paymentSlipImport.ts
+function importPaymentSlip(slip, keys) {
+  const envelope = typeof slip === "string" ? decodePaymentSlip(slip) : slip;
+  if (!envelope) return null;
+  const fields = openPaymentSlip(keys.viewingSecretKey, envelope);
+  if (!fields) return null;
+  const commitment = {
+    commitmentHex: fields.commitmentHex,
+    leafIndex: fields.leafIndex ?? -1,
+    encryptedMemo: fields.encryptedMemo
+  };
+  const note = tryDecryptNote(commitment, keys.viewingSecretKey, keys.spendingKey, keys.ownerPk);
+  if (!note) return null;
+  return fields.txHash ? stampCreatedTxHash(note, fields.txHash) : note;
+}
+
 // src/wallet/ops/spend/transfer.ts
 import { CircuitType as CircuitType5 } from "@orbinum/proof-generator";
 
@@ -5501,6 +5641,18 @@ async function transferNotes(deps, params, onProgress) {
         await deps.vault.save(stampCreatedTxHash(selfNote, txResult.txHash, txKind));
       }
     }
+    const isSelf = deps.selfOwnerPk !== null && recipientPk === deps.selfOwnerPk;
+    if (recipientViewingPublicKey !== void 0 && !isSelf) {
+      try {
+        const envelope = sealPaymentSlip(recipientViewingPublicKey, {
+          commitmentHex: recipientNote.commitmentHex,
+          encryptedMemo: toHex(Uint8Array.from(recipientNote.memo)),
+          ...txResult.txHash ? { txHash: txResult.txHash } : {}
+        });
+        return { ...txResult, paymentSlip: encodePaymentSlip(envelope) };
+      } catch {
+      }
+    }
   }
   return txResult;
 }
@@ -6106,11 +6258,13 @@ export {
   NOTE_BIGINT_FIELDS,
   NOTE_TRANSFER_URI_SCHEME,
   NoteBuilder,
+  OVK_BLOB_SIZE,
   OrbinumClient,
   OrbinumClientProvider,
   OrbinumWallet,
   PAGE_SIZE,
   PAIRWISE_EPH_WINDOW,
+  PAYMENT_SLIP_SCHEME,
   PRECOMPILE_ADDR,
   PrivacyKeyManager,
   PrivacyModule,
@@ -6181,11 +6335,14 @@ export {
   decodeNoteBackup,
   decodeNoteDisclosureKey,
   decodeNoteTransferPage,
+  decodePaymentSlip,
   decodePrecompileCalldata,
   decryptHintBatch,
   decryptJson,
   decryptNoteRecord,
   deriveMasterKeyBytes,
+  deriveOutgoingCipherKey,
+  deriveOutgoingViewingKey,
   deriveOwnerPk,
   derivePairwiseEphSk,
   derivePairwiseSharedSecret,
@@ -6204,6 +6361,7 @@ export {
   detectCommitmentMismatch,
   encodeNoteBackup,
   encodeNoteTransferPages,
+  encodePaymentSlip,
   encryptJson,
   encryptNote,
   ensureCreatedAt,
@@ -6240,6 +6398,7 @@ export {
   implicitSubstrateToEvm,
   importDeviceKey,
   importNotesFromBackup,
+  importPaymentSlip,
   isAbortError,
   isAlreadySpentError,
   isConnectionLossError,
@@ -6269,6 +6428,8 @@ export {
   noteSpentTxHash,
   noteToTransferEntry,
   noteTxKind,
+  openOutgoingBlob,
+  openPaymentSlip,
   pairwiseEphWindow,
   palletErrorKind,
   parseAmount,
@@ -6278,6 +6439,7 @@ export {
   planTransfer,
   planUnshield,
   randomBlinding,
+  randomOutgoingBlob,
   reconstructOutgoingTxRecords,
   recoverOwnerPkPoint,
   recoverSelfStealthNote,
@@ -6293,6 +6455,8 @@ export {
   runScan,
   scalarToHex,
   scanAbortError,
+  sealOutgoingBlob,
+  sealPaymentSlip,
   selectGhosts,
   selectNotes,
   selfEphWindow,
@@ -6316,6 +6480,7 @@ export {
   truncateMiddle,
   tryDecryptNote,
   tryDecryptNoteVerbose,
+  tryRecoverOutgoing,
   txLandedAfterError,
   u128,
   u64,

package/dist/wallet/worker/index.d.mts

@@ -1 +1 @@
-export { c as DECRYPT_YIELD_EVERY, d as DecryptBatchResult, a as DecryptPool, e as DecryptRequest, E as EMPTY_BATCH_RESULT, K as KnownEphEntry, f as KnownEphWindow, M as MAX_WORKERS, g as MatchSource, P as PAIRWISE_EPH_WINDOW, i as SELF_EPH_WINDOW, b as ScanKeys, W as WORKER_CRASHED, j as WorkerFactory, k as WorkerLike, l as WorkerMessage, m as clearKnownEphWindow, n as createDecryptPool, o as createMainThreadPool, p as createWorkerPool, q as decryptHintBatch, r as getKnownEphWindow } from '../../index-JYVjYJtf.mjs';
+export { c as DECRYPT_YIELD_EVERY, d as DecryptBatchResult, a as DecryptPool, e as DecryptRequest, E as EMPTY_BATCH_RESULT, K as KnownEphEntry, f as KnownEphWindow, M as MAX_WORKERS, g as MatchSource, P as PAIRWISE_EPH_WINDOW, i as SELF_EPH_WINDOW, b as ScanKeys, W as WORKER_CRASHED, j as WorkerFactory, k as WorkerLike, l as WorkerMessage, m as clearKnownEphWindow, n as createDecryptPool, o as createMainThreadPool, p as createWorkerPool, q as decryptHintBatch, r as getKnownEphWindow } from '../../index-V5Z9igEN.mjs';

package/dist/wallet/worker/index.d.ts

@@ -1 +1 @@
-export { c as DECRYPT_YIELD_EVERY, d as DecryptBatchResult, a as DecryptPool, e as DecryptRequest, E as EMPTY_BATCH_RESULT, K as KnownEphEntry, f as KnownEphWindow, M as MAX_WORKERS, g as MatchSource, P as PAIRWISE_EPH_WINDOW, i as SELF_EPH_WINDOW, b as ScanKeys, W as WORKER_CRASHED, j as WorkerFactory, k as WorkerLike, l as WorkerMessage, m as clearKnownEphWindow, n as createDecryptPool, o as createMainThreadPool, p as createWorkerPool, q as decryptHintBatch, r as getKnownEphWindow } from '../../index-JYVjYJtf.js';
+export { c as DECRYPT_YIELD_EVERY, d as DecryptBatchResult, a as DecryptPool, e as DecryptRequest, E as EMPTY_BATCH_RESULT, K as KnownEphEntry, f as KnownEphWindow, M as MAX_WORKERS, g as MatchSource, P as PAIRWISE_EPH_WINDOW, i as SELF_EPH_WINDOW, b as ScanKeys, W as WORKER_CRASHED, j as WorkerFactory, k as WorkerLike, l as WorkerMessage, m as clearKnownEphWindow, n as createDecryptPool, o as createMainThreadPool, p as createWorkerPool, q as decryptHintBatch, r as getKnownEphWindow } from '../../index-V5Z9igEN.js';

package/dist/wallet/worker/index.js

@@ -570,6 +570,7 @@ var import_hkdf2 = require("@noble/hashes/hkdf.js");
 var import_sha25 = require("@noble/hashes/sha2.js");
 var import_baby_jubjub6 = require("@zk-kit/baby-jubjub");
 var IVK_DOMAIN = new TextEncoder().encode("orbinum-ivk-v1");
+var OVK_DOMAIN = new TextEncoder().encode("orbinum-ovk-v1");
 function deriveViewingPublicKey(ivsk) {
   const ivskScalar = BigInt(toHex(ivsk)) % BABYJUB_SUBORDER || 1n;
   const ivkPoint = fastMulBase(ivskScalar);

package/dist/wallet/worker/index.mjs

@@ -11,7 +11,7 @@ import {
   createWorkerPool,
   decryptHintBatch,
   getKnownEphWindow
-} from "../../chunk-Y6LNYJAJ.mjs";
+} from "../../chunk-A2ZRMEYW.mjs";
 export {
   DECRYPT_YIELD_EVERY,
   EMPTY_BATCH_RESULT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbinum/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Official TypeScript SDK for Orbinum.",
   "author": "Orbinum",
   "license": "MIT",