@ninsei-labs/sdk 0.52.0 → 0.54.0

package/src/lock.mjs

@@ -99,12 +99,10 @@ export async function send(request, wallet, deps = {}) {
       send: (tx) => wallet.send(tx),
       // NORMALISING THE RECEIPT ARGUMENT'S SHAPE - HERE, AT THE CORE'S BOUNDARY, NOT AT EVERY CALLER.
       //
-      // www/js/evm/funding.js calls the receipt with an OBJECT { hash } (waitReceipt), while the adapter contract
-      // declares receipt(txHash: string). A strict adapter (sdk/src/adapters/evm-wallet.mjs) answers bad-input to
-      // an object, the refusal is SWALLOWED by the receipt wait, and the escrow address is silently replaced with
-      // the PREDICTED one - that is, the "address from the receipt" check stops working without saying so. We
-      // normalise the argument to a string here: funding.js is foreign code and must not be edited, and every
-      // adapter should not repeat the normalisation.
+      // funding.js calls the receipt with an OBJECT { hash } (waitReceipt), while the adapter contract declares
+      // receipt(txHash: string). A strict adapter (sdk/src/adapters/evm-wallet.mjs) answers bad-input to an object,
+      // the refusal is SWALLOWED by the receipt wait, and the address would silently fall back. We normalise the
+      // argument to a string at this boundary so every adapter sees one shape.
       receipt: (arg) => wallet.receipt(typeof arg === "string" ? arg : (arg && typeof arg.hash === "string" ? arg.hash : arg)),
     });
   } catch (error) {

package/src/order.mjs

@@ -1,15 +1,18 @@
 // THE COUNTERPARTY'S SIDE AND THE JOINT ADDRESS.
 //
-// TWO CHECKS, BOTH MANDATORY BEFORE SIGNING - after it there is nothing to fix:
+// THREE CHECKS, ALL MANDATORY BEFORE SIGNING - after it there is nothing to fix:
 //
 //   1) the DLEQ proof stands in the CONTEXT OF THIS order: the counterparty proved for our terms, not for others.
 //      The context is the same one the quote signature is bound to (see quotes.firm);
 //   2) the proven ed25519 point is THE VERY ONE that will go into the contract and from which the address is
 //      assembled. Without this check the counterparty could prove one thing and substitute another: on our side
 //      everything would look sound, and the discrepancy would surface when claiming the XMR, with nothing left to
-//      fix.
+//      fix;
+//   3) the proven secp256k1 point matches `commitHalfClaimer`, the commitment the contract compares on claim and
+//      refund. A proof without this comparison binds the wrong half and the escrow rejects it after the other side
+//      has paid.
 //
-// Both are done by the engine (order.js: the verifying code is the same for us and for the counterparty). The
+// All three are done by the engine (order.js: the verifying code is the same for us and for the counterparty). The
 // core has no cryptography of its own and should not: a copy would silently drift from the original.
 import { SdkError } from "./errors.mjs";
 import { primitives } from "./primitives.mjs";
@@ -86,6 +89,43 @@ const sameFormAsPoint = (proof) => (proof && typeof proof === "object" && proof.
 // "no point", not "point in another form".
 const pointForm = (v) => (typeof v === "string" && v ? norm(v) : v);
 
+// THE COUNTERPARTY'S VIEW MATERIAL HAS TWO SPELLINGS, AND THEY MUST AGREE. A quote carries `viewHalfClaimer`
+// (and sometimes `viewHalf`), a point as `viewPoint` or `viewPub`. The guard and the builder used to prefer
+// different names: the guard took the half first and ignored the point, the builder took the point first. A
+// counterparty could then supply a half and a different point, the address was built from one and the recovery
+// words from the other. Normalise once, refuse conflicting aliases, and derive the point from the half when only
+// the half is present.
+export function normalizeCounterpartyView(counterparty) {
+  const cp = counterparty && typeof counterparty === "object" ? counterparty : {};
+  const halves = [cp.viewHalf, cp.viewHalfClaimer].filter((v) => v !== undefined && v !== null && v !== "");
+  let half = null;
+  if (halves.length) {
+    try { half = BigInt(String(halves[0])); } catch { throw new SdkError("bad-input", { field: "counterparty", why: "view-half" }); }
+    for (const other of halves.slice(1)) {
+      let n = null;
+      try { n = BigInt(String(other)); } catch { n = null; }
+      if (n === null || n !== half) throw new SdkError("bad-input", { field: "counterparty", why: "conflicting-view-half" });
+    }
+  }
+  const points = [cp.viewPoint, cp.viewPub].filter((v) => v !== undefined && v !== null && v !== "");
+  let point = null;
+  if (points.length) {
+    point = pointForm(points[0]);
+    if (!isPoint(point)) throw new SdkError("bad-input", { field: "counterparty", why: "view-point" });
+    for (const other of points.slice(1)) {
+      if (pointForm(other) !== point) throw new SdkError("bad-input", { field: "counterparty", why: "conflicting-view-point" });
+    }
+  }
+  if (half !== null) {
+    let derived = null;
+    try { derived = pointForm(builder().pointOf(half)); } catch { derived = null; }
+    if (!derived) throw new SdkError("bad-input", { field: "counterparty", why: "view-half" });
+    if (point !== null && point !== derived) throw new SdkError("bad-input", { field: "counterparty", why: "view-half-point-mismatch" });
+    point = derived;
+  }
+  return { half: half === null ? null : halves[0], point };
+}
+
 /**
  * Our side of the order. It is built by the engine's builder: two halves, their points, the DLEQ PROOF (it is
  * bound to the order terms and so is not computed without the context) and the side's encryption key.
@@ -136,11 +176,12 @@ export function acceptCounterparty({ context, side = null, counterparty = null,
     // (rfq/orderQuote.mjs). While only `edPub`/`viewPub` were accepted, the facade's own side was NOT accepted:
     // start answered bad-input { field: "counterparty", missing: ["edPub"] } to its own answer. The engine knew
     // this mapping (sdk/src/swap-flow.mjs: edPub: quote.edPointClaimer). We accept BOTH names.
+    const view = normalizeCounterpartyView(counterparty);
     accepted = {
       proof: sameFormAsPoint(counterparty.proof),
       edPub: pointForm(counterparty.edPub || counterparty.edPoint || counterparty.edPointClaimer || pub.ed || null),
-      viewPoint: pointForm(counterparty.viewPoint || counterparty.viewPub || null),
-      viewHalf: counterparty.viewHalf || counterparty.viewHalfClaimer || null,
+      viewPoint: view.point,
+      viewHalf: view.half,
       // THE COUNTERPARTY'S SPEND HALF: HIS commitment (commitHalfClaimer) is computed from it where it did not
       // arrive ready-made. Without the half the commitment cannot be obtained - and that is named null, not invented.
       half: counterparty.half !== undefined ? counterparty.half : null,
@@ -155,13 +196,18 @@ export function acceptCounterparty({ context, side = null, counterparty = null,
     // not what the page runs on.
     const mock = builder().newSide(context, true);
     accepted = { proof: sameFormAsPoint(mock.proof), edPub: norm(mock.pub.ed), viewPoint: norm(mock.viewPub),
-      viewHalf: mock.viewHalf, half: mock.half, commitHalfClaimer: null, sealed: null, providerId: null, standIn: true, mock };
+      viewHalf: mock.viewHalf, half: mock.half,
+      // THE STAND-IN DOES CARRY A COMMITMENT: it is derived from the half it just built, by the same formula
+      // the contract uses. The proof check below is therefore the real one, not a path that skips it.
+      commitHalfClaimer: norm(builder().halfCommitment(mock.half)), sealed: null, providerId: null, standIn: true, mock };
   } else {
     throw new SdkError("bad-input", { field: "counterparty" });
   }
   const missing = [];
   if (!accepted.proof) missing.push("proof");
   if (!accepted.edPub) missing.push("edPub");
+  // THE COMMITMENT IS NOT OPTIONAL. Without it the proof says nothing about the half the contract will compare.
+  if (!accepted.commitHalfClaimer) missing.push("commitHalfClaimer");
   if (missing.length) throw new SdkError("bad-input", { field: "counterparty", missing });
   // OPENING THE SEALED PACKAGE - BY THE SAME ENGINE CALL, and the key is OURS (the package is addressed to us).
   // The envelope's composition is locked separately (www/js/atomic/halfenc.js, HALFENC_LOCK_REASON): in the live
@@ -169,7 +215,7 @@ export function acceptCounterparty({ context, side = null, counterparty = null,
   // with a refusal rather than passing itself off as a working key handover.
   const ownEncPriv = accepted.sealed && side && side.enc ? side.enc.priv : null;
   let verdict = null;
-  try { verdict = builder().verifySide({ proof: accepted.proof, pub: { ed: accepted.edPub } }, context, accepted.sealed, ownEncPriv); }
+  try { verdict = builder().verifySide({ proof: accepted.proof, pub: { ed: accepted.edPub }, commitHalfClaimer: accepted.commitHalfClaimer }, context, accepted.sealed, ownEncPriv); }
   catch { throw new SdkError("bad-input", { field: "counterparty" }); }
   if (!verdict || verdict.ok !== true) {
     throw new SdkError("quote-refused", { step: "proof", why: verdict && verdict.reason ? "rejected" : "unknown" });

package/src/public/networks.d.ts

@@ -21,10 +21,23 @@ export interface ChainUniswap {
   [field: string]: unknown;
 }
 
+/** What a settlement side looks like: address format, account/UTXO settlement and reference shape. Metadata, not a
+ * claim that a driver exists. */
+export interface SettlementProfile {
+  vm: string;
+  addressFormat: string;
+  settlementKind: "contract" | "program" | "utxo-script" | string;
+  refKind: "address" | "pda" | "script" | string;
+  txRef: "hash" | "signature" | "txid" | string;
+}
+
 export interface Chain {
   id: string;
   name: string;
-  vm: string;
+  /** A registry chain names its VM; the type allows null so an unknown network is never read as EVM. */
+  vm: string | null;
+  /** Present when the VM has a profile; unknown VMs are null, never silently EVM. */
+  settlementProfile?: SettlementProfile | null;
   chainId: number;
   caip2?: string;
   testnet?: boolean;

package/src/public/recovery.d.ts

@@ -269,12 +269,16 @@ export declare function recoveryFileName(swapId?: string | null): string;
 export declare const RECOVERY_KEY_VERSION: number;
 /** Twelve words, by the BIP39 rules. */
 export declare const RECOVERY_KEY_WORDS: number;
+/** The default number of v1 indices one `findSwaps` call scans. */
+export declare const RECOVERY_SCAN_DEFAULT: number;
 /** The store key a browser adapter keeps the key under. */
 export declare const RECOVERY_KEY_STORE: string;
 /** The first line of a plain backup file. */
 export declare const RECOVERY_KEY_FILE_MAGIC: string;
 /** The domain half derivation binds to; the chain id and swap number join it. */
 export declare const RECOVERY_KEY_DOMAIN: string;
+/** The salt-based derivation domain; the chain, factory, role and order salt join it. */
+export declare const RECOVERY_KEY_DOMAIN_V2: string;
 /** The domain of the counterparty's view half, derived from the same one key. */
 export declare const MAKER_VIEW_HALF_DOMAIN: string;
 /** The encrypted backup envelope version. */
@@ -290,6 +294,8 @@ export interface RecoveryKey {
   readonly mnemonic: string;
   readonly fingerprint: string;
   readonly createdAt: string;
+  /** True only after the person confirmed that the key is saved; a key in storage is not proof of that. */
+  readonly backupConfirmed?: boolean;
 }
 
 /** A derived swap number: the halves cross JSON as hex scalars. */
@@ -305,6 +311,15 @@ export interface TakerHalves {
   readonly spendCommitment: string;
 }
 
+/** A salt-based derivation: no number is reserved, and the public order salt is the input. */
+export interface TakerHalvesV2 extends Omit<TakerHalves, "index"> {
+  readonly index: null;
+  readonly derivation: "salt-v2";
+  readonly factory: string;
+  readonly role: string;
+  readonly salt: string;
+}
+
 /** One order found by the key's commitments. */
 export interface FoundSwap {
   readonly escrow: string;
@@ -338,12 +353,17 @@ export interface FoundSwap {
    * the expected clone. */
   readonly xmrAmount: string | null;
   readonly xmrAmountReason: "event" | "no-code-reader" | "code" | "not-clone" | null;
-  readonly index: number;
+  /** The v1 swap number; null for a salt-based v2 order. */
+  readonly index: number | null;
+  /** Which derivation found this order. v1 orders keep recovering through the index path. */
+  readonly derivation: "index-v1" | "salt-v2";
+  /** The factory the order was read from; the v2 binding needs it. */
+  readonly factory: string;
   readonly side: "locker" | "claimer";
   /** The Monero height a withdrawal may start from, derived from the order's block time. Null when the caller did
    * not pass the readers; `startHeightReason` then names why. */
   readonly startHeight: number | null;
-  readonly startHeightReason: "no-block-number" | "no-height-readers" | "monero-nodes-unreachable" | "monero-network-mismatch" | "no-block-time" | "monero-header" | null;
+  readonly startHeightReason: "no-block-number" | "no-height-readers" | "monero-nodes-unreachable" | "monero-network-mismatch" | "no-block-time" | "block-time-read" | "monero-header" | null;
 }
 
 /** A storage adapter: the same shape the SDK store takes. */
@@ -361,8 +381,16 @@ export declare function importRecoveryKey(mnemonic: string, options?: { createdA
 export declare function fingerprintOf(mnemonic: string): string;
 /** The binding for a chain and swap number: `ninsei-taker-v1|<chainId>|<index>`. */
 export declare function recoveryBinding(chainId: number, index: number): string;
+/** The salt-based binding: `ninsei-taker-v2|<chainId>|<factory>|<role>|<salt>`. */
+export declare function recoveryBindingV2(request: { chainId: number; factory: string; role?: string; salt: string }): string;
+/** Normalises a 32-byte salt from an event word, a hex string, a bigint or a safe integer. */
+export declare function recoverySaltOf(value: string | number | bigint): string;
+/** A fresh 32-byte public salt for one salt-based order. */
+export declare function newRecoverySalt(): string;
 /** Derives the taker spend and view halves for one swap number. */
 export declare function takerHalves(request: { mnemonic: string; chainId: number; index: number }): TakerHalves;
+/** Derives the taker halves from a public per-order salt; no index is reserved. */
+export declare function takerHalvesV2(request: { mnemonic: string; chainId: number; factory: string; role?: string; salt: string }): TakerHalvesV2;
 /** The stable backup name, with `DO-NOT-DELETE` in it on purpose. */
 export declare function recoveryKeyFileName(request: { mnemonic?: string; fingerprint?: string; createdAt?: string | Date }): string;
 /** A plain backup file: readable header above the words. */
@@ -372,9 +400,9 @@ export declare function createRecoveryKeyFile(request: { mnemonic: string; creat
 /** Reads a plain or encrypted backup file and validates the words. */
 export declare function openRecoveryKeyFile(contents: string, passphrase?: string): Promise<RecoveryKey>;
 /** Saves the key through a storage adapter. */
-export declare function saveRecoveryKey(storage: RecoveryKeyStorage, key: RecoveryKey & { nextIndex?: number; reserved?: Record<string, unknown>; retired?: Record<string, unknown> }): RecoveryKey;
+export declare function saveRecoveryKey(storage: RecoveryKeyStorage, key: RecoveryKey & { nextIndex?: number; reserved?: Record<string, unknown>; retired?: Record<string, unknown>; backupConfirmed?: boolean }): RecoveryKey;
 /** Reads the key from a storage adapter, or null. */
-export declare function loadRecoveryKey(storage: RecoveryKeyStorage): (RecoveryKey & { nextIndex: number; reserved: Record<string, unknown>; retired: Record<string, unknown> }) | null;
+export declare function loadRecoveryKey(storage: RecoveryKeyStorage): (RecoveryKey & { nextIndex: number; reserved: Record<string, unknown>; retired: Record<string, unknown>; backupConfirmed?: boolean }) | null;
 /** Reserves a swap number; the caller releases it if the request is abandoned. */
 export declare function reserveRecoveryIndex(storage: RecoveryKeyStorage, request: { chainId: number; swapId?: string | null }): number;
 /** True when an order already holds this number's commitment on chain. A page that starts swaps without the SDK's
@@ -403,8 +431,17 @@ export declare function findSwaps(request: {
   /** The factory's deployment block from the chain registry; used when `fromBlock` is omitted. */
   deploymentBlock?: number | null;
   toBlock?: number | string;
+  /** Deprecated and ignored: discovery no longer stops after a run of empty numbers. */
   gap?: number;
+  /** The first index to try. Defaults to 0; a continuation passes the previous `nextIndex`. */
+  fromIndex?: number;
+  /** How many indices this call may try. Defaults to `RECOVERY_SCAN_DEFAULT` (1000), not the allocator ceiling. */
   maxIndex?: number;
+  /** Stop the scan between chunks. An aborted scan returns `complete: false`, `incompleteReason: "aborted"` and
+   * the `nextIndex` to resume from. */
+  signal?: { readonly aborted: boolean } | null;
+  /** Called after every chunk and after the last index, with the count and the index just scanned. */
+  onProgress?: ((value: { readonly scanned: number; readonly index: number }) => void) | null;
   /** Reads the settlement block timestamp, in seconds: (blockNumber) -> seconds. */
   evmBlockTime?: (blockNumber: number) => Promise<number>;
   /** Reads contract code: (address) -> 0x-hex. Used to read the XMR amount from an order clone. */
@@ -420,4 +457,15 @@ export declare function findSwaps(request: {
   moneroNetwork?: string | null;
   /** The fetch used for those node requests; absent - the global fetch. */
   fetchImpl?: typeof fetch;
-}): Promise<{ swaps: FoundSwap[]; scanned: number }>;
+}): Promise<{
+  swaps: FoundSwap[];
+  scanned: number;
+  /** The last index tried, or null when no index was scanned. */
+  searchedUpTo: number | null;
+  /** True when every order in the logs was matched, or when the allocator range was searched to its end. */
+  complete: boolean;
+  /** `max-index` or `aborted` when a bound or the caller stopped the search before every order was matched. */
+  incompleteReason?: string;
+  /** The next index to pass as `fromIndex`; absent when the search is complete. */
+  nextIndex?: number;
+}>;

package/src/public/recovery.mjs

@@ -25,6 +25,7 @@ export {
 export {
   RECOVERY_KEY_ALG,
   RECOVERY_KEY_DOMAIN,
+  RECOVERY_KEY_DOMAIN_V2,
   RECOVERY_KEY_ENVELOPE_VERSION,
   RECOVERY_KEY_FILE_MAGIC,
   RECOVERY_KEY_ITER,
@@ -32,6 +33,7 @@ export {
   RECOVERY_KEY_VERSION,
   MAKER_VIEW_HALF_DOMAIN,
   RECOVERY_KEY_WORDS,
+  RECOVERY_SCAN_DEFAULT,
   commitRecoveryIndex,
   createRecoveryKey,
   createRecoveryKeyFile,
@@ -39,13 +41,17 @@ export {
   fingerprintOf,
   importRecoveryKey,
   loadRecoveryKey,
+  newRecoverySalt,
   openRecoveryKeyFile,
   recoveryBinding,
+  recoveryBindingV2,
   recoveryIndexTaken,
+  recoverySaltOf,
   recoveryKeyFileName,
   recoveryKeyText,
   releaseRecoveryIndex,
   reserveRecoveryIndex,
   saveRecoveryKey,
   takerHalves,
+  takerHalvesV2,
 } from "../recovery-key.mjs";

package/src/public/xmr.d.ts

@@ -407,17 +407,18 @@ export declare function judgeDaemonAddress(
   options?: { network?: string; allowPlainLoopback?: boolean },
 ): DaemonAddressJudgement;
 
-/** A per-KB price -> the fee for a transaction of `bytes`, rounded UP. Throws on a non-integer or a negative input. */
-export declare function feeForBytes(feePerKB: bigint | number | string, bytes: bigint | number | string): string;
+/** A per-byte price -> the fee for a transaction of `bytes`/weight. Exact integer multiplication. */
+export declare function feeForBytes(feePerByte: bigint | number | string, bytes: bigint | number | string): string;
 
 export interface FeeEstimateOk {
   readonly ok: true;
   readonly url: string;
-  /** The price per kilobyte for the next block, in atomic units, or null when the daemon did not send it. */
-  readonly feePerKB: string | null;
-  readonly medianFeePerKB: string | null;
-  /** The daemon's own priority list, in its order, or null. */
+  /** The price per byte for the next block, in atomic units, or null when the daemon did not send it. */
+  readonly feePerByte: string | null;
+  /** The daemon's own priority list, per byte and in its order, or null. */
   readonly perPriority: readonly string[] | null;
+  /** The unit the final fee is rounded to, or null when the daemon did not send it. */
+  readonly quantizationMask: string | null;
 }
 
 export interface FeeEstimateRefusal {
@@ -430,7 +431,7 @@ export interface FeeEstimateRefusal {
 
 /**
  * ASK A NODE WHAT A TRANSACTION WILL COST (`get_fee_estimate`). The exact sum needs the assembled transaction, so
- * this is a price per kilobyte; `feeForBytes` is the only arithmetic that turns it into a fee. Never throws.
+ * this is a price per byte; `feeForBytes` is the only arithmetic that turns it into a fee. Never throws.
  */
 export declare function moneroFeeEstimate(options: {
   url: string;
@@ -483,6 +484,19 @@ export interface ScannedMatch {
   [field: string]: unknown;
 }
 
+/** A range scan's answer: the per-address totals and whether every block was read. */
+export interface ScanRangeResult {
+  readonly fromHeight: number;
+  readonly toHeight: number;
+  readonly results: ScannedMatch[];
+  /** False when at least one block or its transactions could not be read. */
+  readonly complete: boolean;
+  /** The heights that failed; empty when `complete` is true. */
+  readonly missingHeights: number[];
+  /** `blocks-unreadable` when `complete` is false. */
+  readonly incompleteReason?: "blocks-unreadable";
+}
+
 /** Walk a block range and return the transactions that pay a watched address. */
 export declare function scanRange(options: {
   daemonUrl: string;
@@ -492,4 +506,8 @@ export declare function scanRange(options: {
   log?: (event: unknown) => void;
   concurrency?: number;
   nowSec?: number | null;
-}): Promise<ScannedMatch[]>;
+  /** The chain tip used to judge a height lock; defaults to `toHeight`. Inclusion height still drives confirmations. */
+  tipHeight?: number | null;
+  /** The fetch used for the daemon requests; absent - the global fetch. */
+  fetchImpl?: typeof fetch;
+}): Promise<ScanRangeResult>;