@ninsei-labs/sdk 0.53.0 → 0.55.0

package/engine/evm/funding.js

@@ -99,6 +99,43 @@ export function toWei(human, decimals = 18) {
   return BigInt(intPart || "0") * 10n ** BigInt(decimals) + BigInt(frac || "0");
 }
 
+// THE ONE NATIVE AMOUNT OF A TOKEN-FUNDED ORDER.
+//
+// The escrow holds the network's NATIVE coin; a quote paid in USDC/USDT carries a different number in the token.
+// The native figure is the quote's own `payNative`, in the network's native decimals. A quote without that figure
+// is a NAMED refusal, never a fallback to the payment amount: rescaling the payment amount is a known wrong answer
+// (10^12 on a 6-decimal token), not a smaller error. This is the rule both the intent target and the escrow order
+// read, so the two cannot diverge.
+export function escrowNativeWei({ quote = null, nativeDecimals = 18 } = {}) {
+  const raw = quote ? quote.payNative : null;
+  if (raw === null || raw === undefined || raw === "") {
+    return { ok: false, code: "native-amount-unread", reason: "the quote carries no native amount" };
+  }
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) {
+    return { ok: false, code: "native-amount-unread", reason: "the quote's native amount is not a positive number" };
+  }
+  const dec = Number(nativeDecimals);
+  if (!Number.isInteger(dec) || dec < 0) {
+    return { ok: false, code: "native-amount-unread", reason: "the native decimals are not a whole number" };
+  }
+  // THE QUOTE'S OWN DIGITS, NOT A RE-ROUNDED COPY. An exponent form falls back to toFixed(18), as the rest of the
+  // page does; everything else keeps exactly the digits it was typed with.
+  const text = /e/i.test(String(raw)) ? n.toFixed(18) : String(raw);
+  // DECIMAL DIGITS ONLY. BigInt accepts "0x10", and a native amount read as a hex literal would silently become
+  // sixteen times the token amount; a quote carries decimal text.
+  if (!/^(?:0|[1-9]\d*)(?:\.\d+)?$/.test(text)) {
+    return { ok: false, code: "native-amount-unread", reason: "the native amount is not a decimal number" };
+  }
+  let wei;
+  try { wei = toWei(text, dec); }
+  catch { return { ok: false, code: "native-amount-unread", reason: "the native amount is not a decimal number" }; }
+  if (wei <= 0n) {
+    return { ok: false, code: "native-amount-unread", reason: "the native amount rounds to zero wei" };
+  }
+  return { ok: true, wei: wei.toString(), source: "native" };
+}
+
 // WE SET THE GAS OURSELVES, WITH A MARGIN - A CURE FOR A REAL BUG, NOT CAUTION.
 // createOrderAndFund goes as ONE transaction, but the wallet estimates it at an address where the escrow does NOT
 // exist yet: instead of cloning and recording the deposit it counts a plain transfer (21000 plus data). The wallet

package/index.d.ts

@@ -454,6 +454,11 @@ export interface QuotesApi {
   snapshot(): QuoteSnapshot | null;
   /** A binding quote with a TTL. A refusal comes as a code, not text. */
   firm(offer: FirmOffer): Promise<Quote>;
+  /**
+   * A firm quote through a relay, built from one recovery key. The relay answer is verified against the
+   * requested terms and the on-chain registry/factory binding before it is returned.
+   */
+  firmRelay(request: FirmRelayOffer): Promise<FirmRelayAnswer>;
   /**
    * A reverse-mode ticket: the maker sells XMR. The request is the node's `request` object; the answer carries the
    * signed order quote and its claim tip, which is checked against the gas price before it is returned.
@@ -660,11 +665,60 @@ export interface QuoteReference {
 }
 
 export interface FirmOffer {
-  readonly direction: "buy" | "sell";
-  readonly token: string;
-  readonly amount: number;
-  readonly receiveTo: string;
-  readonly providerId?: string;
+  /** Who gives the quote. Without it there is no one to ask. */
+  readonly providerId: string;
+  /** The order terms the signature is bound to. */
+  readonly order: Readonly<Record<string, unknown>>;
+  /** The taker's maker view half when the order was built from a recovery key. */
+  readonly viewHalfClaimer?: string;
+}
+
+export interface FirmRelayOffer {
+  /** Relay origin, without the `/v1/quote` path. */
+  readonly relayUrl: string;
+  /** The signed public features the relay forwarded; they are verified before anything is sent. */
+  readonly features: Readonly<Record<string, unknown>>;
+  readonly order: Readonly<Record<string, unknown>>;
+  readonly side: "ask" | "bid";
+  /** The twelve-word recovery key or an object carrying it. */
+  readonly recoveryKey: string | { readonly mnemonic: string };
+  /** A fresh salt the client owns; it must equal `order.salt`. Defaults to `order.salt`. */
+  readonly recoverySalt?: string;
+  /** The v1 index; it is mutually exclusive with `recoverySalt`. */
+  readonly recoveryIndex?: number;
+  /** The market's chain and asset, for example `421614:ETH`. Derived when exactly one window matches. */
+  readonly market?: string;
+  readonly xmrNetwork?: string;
+  readonly xmrAmount: string | number;
+  readonly claimTip?: string | number;
+  readonly partner?: string;
+  readonly fetchImpl?: typeof fetch;
+  readonly timeoutMs?: number;
+}
+
+export interface FirmRelayAnswer {
+  readonly quote: Readonly<Record<string, unknown>>;
+  readonly orderQuote: Readonly<Record<string, unknown>>;
+  /** The exact order terms the quote is bound to. */
+  readonly order: Readonly<Record<string, unknown>>;
+  readonly nodeHalf: Readonly<Record<string, unknown>>;
+  /** Ready to pass as `swaps.start({ counterparty })`: proof, claimer commitment and maker view half. */
+  readonly counterparty: Readonly<Record<string, unknown>>;
+  readonly edViewPointLocker: string;
+  readonly edViewPointClaimer: string;
+  readonly context: string;
+  readonly viewHalfClaimer: string;
+  readonly viewHalfPoint: string;
+  /** The one-time Monero address assembled from the recovery key and the answer's points. */
+  readonly jointAddress: string;
+  /** The escrow address predicted from the signed quote and the depositor's half. */
+  readonly escrow: string;
+  readonly recovery: { readonly kind: "salt-v2"; readonly salt: string }
+    | { readonly kind: "index-v1"; readonly index: number };
+  readonly relay: string | null;
+  readonly offered: number | null;
+  readonly forwarded: Readonly<Record<string, unknown>> | null;
+  readonly answer: Readonly<Record<string, unknown>>;
 }
 
 /**
@@ -758,6 +812,13 @@ export interface SwapsApi {
    * the swap with if the browser is lost.
    */
   start(request: StartRequest): Promise<SwapStart>;
+  /**
+   * START A SELL from a verified relay offer. It records the one-time address, the escrow, our half and the
+   * order expectations; it sends nothing. The same offer retried yields the same record (`resumed: true`).
+   */
+  startSell(request: SellStartRequest): Promise<SellStart>;
+  /** CLAIM THE ETH on a sell from the record: the half and the expectations are the ones stored by `startSell`. */
+  sellClaim(request: SellClaimRequest, wallet: WalletAdapter): Promise<unknown>;
   /**
    * WAIT FOR THE XMR TO ARRIVE at the order's joint address. The polling uses the same request as the page's
    * (GET /swaps/{id}), the rate and the timeout - from `config.limits` and overridable here.
@@ -774,6 +835,12 @@ export interface SwapsApi {
    * signed, and the decline is written into the record, so every later read of the swap reports the same state.
    */
   watch(request: SwapWatchRequest): Promise<SwapWatch | SwapDeclinedWatch>;
+  /**
+   * WAIT FOR THE NODE'S SIDE ON A SELL. The escrow is the one predicted by `quotes.firmRelay`; the client sends
+   * XMR to the joint address, and this reads the escrow itself until the locker marks it ready, claims it or
+   * refunds it. No backend watcher is involved. A wait that expires is `sell-timeout`.
+   */
+  sellWatch(request: SellWatchRequest): Promise<SellWatchResult>;
   /**
    * THE XMR ARRIVAL CHECK WITHOUT THE WATCH LOOP (issue #85). The client reads the chain itself with its own view
    * key and `ready` opens only when at least two nodes of DIFFERENT operators see the transaction IN THE SAME BLOCK
@@ -1021,6 +1088,53 @@ export interface SwapStart {
   readonly next: "watch";
 }
 
+export interface SellStartRequest {
+  /** The verified `quotes.firmRelay` answer for the bid side. */
+  readonly offer: FirmRelayAnswer;
+  /** The twelve-word key; required only when no key is stored yet. */
+  readonly recoveryKey?: string | { readonly mnemonic: string };
+}
+
+export interface SellStart {
+  readonly id: string;
+  readonly side: "sell";
+  readonly escrow: string;
+  /** The one-time Monero address the client sends XMR to. */
+  readonly address: string;
+  readonly xmrAmount: string;
+  readonly claimTip: string | null;
+  readonly orderQuote: Readonly<Record<string, unknown>> | null;
+  readonly resumed: boolean;
+  readonly next: "send-xmr";
+}
+
+export interface SellClaimRequest {
+  readonly id: string;
+  readonly escrow?: string;
+  readonly halfClaimer?: string;
+  readonly expect?: Readonly<Record<string, unknown>>;
+  readonly onStep?: (step: unknown) => void;
+}
+
+export interface SellWatchRequest {
+  /** The escrow predicted by the relay adapter. */
+  readonly escrow: string;
+  readonly timeoutMs?: number;
+  readonly pollMs?: number;
+}
+
+export interface SellWatchResult {
+  readonly escrow: string;
+  readonly state: "ready" | "claimed" | "refunded";
+  readonly funded: boolean;
+  readonly claimed: boolean;
+  readonly refunded: boolean;
+  /** `null` for a terminal claim/refund: the ready mark is not part of that answer. */
+  readonly ready: boolean | null;
+  readonly balanceWei: string;
+  readonly waitedMs: number;
+}
+
 export interface SwapWatchRequest {
   /** The watch record's identifier at the service (from SwapStart.watch.id). */
   readonly id: string;
@@ -1585,7 +1699,11 @@ export interface SweepRunResult {
 
 // --- Recovery// --- Recovery ------------------------------------------------------------------------------
 
-/** Order checks. Both are BEFORE the signature: after it there is nothing to fix. */
+/** Order checks and pure order helpers. Checks are BEFORE the signature: after it there is nothing to fix. */
+export type EscrowNativeAmount =
+  | { readonly ok: true; readonly wei: string; readonly source: "native" }
+  | { readonly ok: false; readonly code: "native-amount-unread"; readonly reason: string };
+
 export interface OrderApi {
   /** The order context string the proof and the quote signature are bound to. */
   context(terms: Readonly<Record<string, unknown>>): string;
@@ -1593,6 +1711,13 @@ export interface OrderApi {
   verifyCounterparty(request: { readonly side: unknown; readonly order: Readonly<Record<string, unknown>>; readonly sealed?: unknown; readonly ownEncPriv?: unknown }): unknown;
   /** The joint Monero address from your own spend half and the other's point. */
   jointAddress(request: { readonly ownSpendHalf: string; readonly ownViewHalf: string; readonly otherSpendPoint: string; readonly otherViewPoint: string; readonly network?: string }): unknown;
+  /**
+   * The ONE native amount of a token-funded order: the quote's `payNative` in the network's native decimals.
+   * The escrow holds native coin, so the token amount is never used as the escrow amount (a 6-decimal token
+   * would be off by 10^12). A quote without a native figure answers `{ ok: false, code: "native-amount-unread" }`;
+   * it is never replaced by the payment amount.
+   */
+  escrowNativeWei(request?: { readonly quote?: Readonly<Record<string, unknown>> | null; readonly nativeDecimals?: number }): EscrowNativeAmount;
   /**
    * The order state, READ FROM THE CHAIN (escrow status()): which of the four states the order is in. The state is
    * read by a call, not guessed from logs. It is read by the same chain-read seam as the actions (`evmCall`), so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -41,11 +41,23 @@
     "check:sale-auth": "node tools/check-sale-auth.mjs",
     "check:backup-confirmation": "node tools/check-backup-confirmation.mjs",
     "check:key-view": "node tools/check-key-view.mjs",
+    "check:relay-view": "node tools/check-relay-view.mjs",
+    "check:relay-terms": "node tools/check-relay-terms.mjs",
+    "check:relay-features": "node tools/check-relay-features.mjs",
+    "check:relay-request": "node tools/check-relay-request.mjs",
+    "check:relay-answer": "node tools/check-relay-answer.mjs",
+    "check:relay-http": "node tools/check-relay-http.mjs",
+    "check:relay-adapter": "node tools/check-relay-adapter.mjs",
+    "check:sell-watch": "node tools/check-sell-watch.mjs",
+    "check:sell-start": "node tools/check-sell-start.mjs",
     "check:arrival-consensus": "node tools/check-arrival-consensus.mjs",
     "check:arrival-real": "node tools/check-arrival-real.mjs",
     "check:order-proof": "node tools/check-order-proof.mjs",
     "check:daemon-address": "node tools/check-daemon-address.mjs",
     "check:ci-scripts": "node tools/check-ci-scripts.mjs",
+    "check:licenses": "node tools/check-licenses.mjs",
+    "notices": "node tools/third-party-notices.mjs",
+    "check:notices": "node tools/third-party-notices.mjs --check",
     "check:factory-selectors": "node tools/check-factory-selectors.mjs",
     "check:fee-estimate": "node tools/check-fee-estimate.mjs",
     "check:deadline-scale": "node tools/check-deadline-scale.mjs",
@@ -61,7 +73,8 @@
     "check:packed-consumer": "node tools/check-packed-consumer.mjs",
     "check:quote-binding": "node tools/check-quote-binding.mjs",
     "check:types-consumer": "node node_modules/typescript/bin/tsc -p tools/ts-consumer/tsconfig.json",
-    "check:monero-live": "node tools/check-monero-live.mjs"
+    "check:monero-live": "node tools/check-monero-live.mjs",
+    "check:native-amount": "node tools/check-native-amount.mjs"
   },
   "types": "./index.d.ts",
   "exports": {
@@ -100,6 +113,10 @@
     "./provider": {
       "types": "./src/public/provider.d.ts",
       "default": "./src/public/provider.mjs"
+    },
+    "./relay": {
+      "types": "./src/public/relay.d.ts",
+      "default": "./src/public/relay.mjs"
     }
   },
   "files": [
@@ -109,7 +126,9 @@
     "index.d.ts",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "LICENSE-POLICY.md",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "engines": {
     "node": ">=24.22.1"
@@ -138,6 +157,9 @@
     "url": "https://github.com/Ninsei-Labs/sdk/issues"
   },
   "dependencies": {
+    "@hpke/chacha20poly1305": "1.8.0",
+    "@hpke/core": "1.9.0",
+    "@hpke/dhkem-x25519": "1.8.0",
     "@noble/curves": "^2.4.0",
     "@noble/hashes": "^2.4.0",
     "@scure/bip39": "2.4.0",

package/src/index.mjs

@@ -249,6 +249,10 @@ export function createNinsei(options) {
       context: (terms) => contextOf(terms),
       verifyCounterparty: (request) => verifyCounterparty(request),
       jointAddress: (request) => jointAddress(request),
+      // THE ONE NATIVE AMOUNT OF A TOKEN-FUNDED ORDER. The escrow holds native coin, while a stablecoin quote
+      // carries a different number in the token; this reads the quote's native figure. A quote without it is a
+      // named refusal (`native-amount-unread`), never a rescale of the payment amount.
+      escrowNativeWei: (request) => engine.evm.escrowNativeWei(request),
       // ORDER STATE FROM THE CHAIN (escrow slot 3): which of the four states the order is in. Read, not guessed
       // from logs - the very call the engine used to make from www/js/core/swap-flow.js.
       status: (escrow) => orderFlow.orderStatus(escrow, orderDeps),
@@ -270,6 +274,8 @@ export function createNinsei(options) {
       // A firm quote is stage 2: it is signed with a key and lives in the order protocol, not in a market snapshot.
       // A FIRM QUOTE: accepted only with a confirmed provider signature.
       firm: (request) => quotes.firm(request),
+      // THE RELAY PATH: one recovery key in, signed orderQuote and its maker view half out.
+      firmRelay: (request) => quotes.firmRelay(request),
       // A REVERSE TICKET: the node signs it; its claim tip is checked here before the caller sees it.
       sale: (request) => quotes.sale(request),
     },

package/src/public/recovery.d.ts

@@ -269,6 +269,8 @@ 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. */
@@ -431,8 +433,15 @@ export declare function findSwaps(request: {
   toBlock?: number | string;
   /** Deprecated and ignored: discovery no longer stops after a run of empty numbers. */
   gap?: number;
-  /** The last index to try. Defaults to the allocator's ceiling; a smaller value returns `complete: false`. */
+  /** 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. */
@@ -453,8 +462,10 @@ export declare function findSwaps(request: {
   scanned: number;
   /** The last index tried, or null when no index was scanned. */
   searchedUpTo: number | null;
-  /** True only when the whole allocator range was searched. */
+  /** True when every order in the logs was matched, or when the allocator range was searched to its end. */
   complete: boolean;
-  /** `max-index` when a smaller caller-supplied bound stopped the search. */
+  /** `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

@@ -33,6 +33,7 @@ export {
   RECOVERY_KEY_VERSION,
   MAKER_VIEW_HALF_DOMAIN,
   RECOVERY_KEY_WORDS,
+  RECOVERY_SCAN_DEFAULT,
   commitRecoveryIndex,
   createRecoveryKey,
   createRecoveryKeyFile,

package/src/public/relay.d.ts

@@ -0,0 +1,77 @@
+export declare const RELAY_FEATURES_TYPE_NAME: "NodeFeatures";
+export declare const RELAY_DOMAIN_NAME: "Ninsei Relay";
+export declare const RELAY_DOMAIN_VERSION: "1";
+export declare const FIRM_WINDOW_TYPE: string;
+export declare const NODE_FEATURES_TYPE: string;
+export declare const FIRM_WINDOW_FIELDS: ReadonlyArray<readonly [string, string]>;
+export declare const NODE_FEATURES_FIELDS: ReadonlyArray<readonly [string, string]>;
+
+export interface RelayFirmWindow {
+  market: string;
+  side: "ask" | "bid";
+  xmrNetwork: string;
+  readyMinSeconds: number;
+  readyMaxSeconds: number;
+  settlementMinSeconds: number;
+  settlementMaxSeconds: number;
+  quoteTtlSeconds: number;
+}
+
+export interface RelayNodeFeatures {
+  type: "node_features";
+  version: 1;
+  relayId: string;
+  provider: string;
+  quoteKey: string;
+  registry: string;
+  capabilities: string[];
+  hpkeKey: string;
+  firmWindows: RelayFirmWindow[];
+  time: number;
+  nonce: string;
+  signature: string;
+}
+
+export interface RelayVerifyTerms {
+  market: string;
+  side: "ask" | "bid";
+  maker: string;
+  registry: string;
+  xmrNetwork: string;
+}
+
+export declare function nodeFeaturesStructHash(features: RelayNodeFeatures): Uint8Array;
+export declare function nodeFeaturesDomainSeparator(): Uint8Array;
+export declare function nodeFeaturesDigest(features: RelayNodeFeatures): Uint8Array;
+export declare function verifyNodeFeatures(input: { features: RelayNodeFeatures; terms?: RelayVerifyTerms | null }): {
+  featuresHash: string;
+  hpkeKey: string;
+  window: RelayFirmWindow | null;
+};
+export declare function nodeFeaturesMissingFields(features: Partial<RelayNodeFeatures>): string[];
+
+export declare function firmTermsDigest(input: { crypto: { keccak256(bytes: Uint8Array): Uint8Array }; terms: Record<string, unknown> }): Uint8Array;
+export declare function firmTermsMissingFields(terms: Record<string, unknown>): string[];
+
+export declare const RELAY_VIEW_INFO_PREFIX: string;
+export declare function relayViewInfo(input: {
+  termsDigest: string;
+  commitHalf: string;
+  edPoint: string;
+  edViewPointClient: string;
+  edViewPointNode: string;
+}): Uint8Array;
+export declare function sealViewEnvelope(input: { hpkeKey: string; info: Uint8Array; plaintext: Uint8Array }): Promise<{ enc: string; ciphertext: string }>;
+export declare function openViewEnvelope(input: { privateKey: string; enc: string; ciphertext: string; info: Uint8Array }): Promise<Uint8Array>;
+
+export declare const RELAY_QUOTE_TYPE: string;
+export declare function relayQuoteStructHash(answer: Record<string, unknown>): Uint8Array;
+export declare function relayQuoteDomainSeparator(): Uint8Array;
+export declare function relayQuoteDigest(answer: Record<string, unknown>): Uint8Array;
+export declare function verifyRelayQuoteFrame(answer: Record<string, unknown>, quoteKey: string): Record<string, unknown>;
+export declare function verifyFirmAnswer(input: {
+  answer: Record<string, unknown>;
+  features: RelayNodeFeatures;
+  request: { terms: Record<string, unknown>; edViewPointClient: string; edViewPointNode: string };
+  now?: number | null;
+}): Record<string, unknown>;

package/src/public/relay.mjs

@@ -0,0 +1,37 @@
+// THE RELAY EXCHANGE FOR A NODE THAT EMBEDS THE SDK.
+//
+// A maker needs the other half of the same rules a client uses: the public features digest it signs, the terms
+// digest, the HPKE view envelope it opens, and the answer verifier. Names only; no second implementation.
+
+export {
+  RELAY_FEATURES_TYPE_NAME,
+  RELAY_DOMAIN_NAME,
+  RELAY_DOMAIN_VERSION,
+  FIRM_WINDOW_TYPE,
+  NODE_FEATURES_TYPE,
+  FIRM_WINDOW_FIELDS,
+  NODE_FEATURES_FIELDS,
+  nodeFeaturesStructHash,
+  nodeFeaturesDomainSeparator,
+  nodeFeaturesDigest,
+  verifyNodeFeatures,
+  nodeFeaturesMissingFields,
+} from "../relayFeatures.mjs";
+
+export { firmTermsDigest, firmTermsMissingFields } from "../relayTerms.mjs";
+
+export {
+  RELAY_VIEW_INFO_PREFIX,
+  relayViewInfo,
+  sealViewEnvelope,
+  openViewEnvelope,
+} from "../relayView.mjs";
+
+export {
+  RELAY_QUOTE_TYPE,
+  relayQuoteStructHash,
+  relayQuoteDomainSeparator,
+  relayQuoteDigest,
+  verifyRelayQuoteFrame,
+  verifyFirmAnswer,
+} from "../relayQuote.mjs";