@ninsei-labs/sdk 0.49.0 → 0.51.0

package/engine/atomic/order-worker.js

@@ -0,0 +1,129 @@
+// Воркер: считает сторону ордера ВНЕ главного потока.
+//
+// Зачем он нужен, если он ничего не ускоряет. Доказательство DLEQ в JS занимает около 11 секунд
+// (измерено; разбор половин ключа). Если считать его в главном потоке, страница
+// замирает целиком - вместе с любым индикатором прогресса, который на ней нарисован. Воркер не делает
+// счёт быстрее ни на миллисекунду: он делает его невидимым для интерфейса. Пока воркер считает, страница
+// жива и может честно показывать, что происходит.
+//
+// Протокол: { id, type, ...аргументы } -> { id, kind: "progress"|"done"|"error", ... }
+import {
+  createOrderBuilder, ed25519, secp256k1, keccak256, sha3_512, randomBytes,
+} from "../../assets/vendors/atomic/atomic-browser.js";
+
+const builder = createOrderBuilder({ ed25519, secp256k1, keccak256, sha3_512, randomBytes });
+
+// Ключи шифрования построенных сторон: приватный ключ по своему публичному. Наружу приватные не уходят -
+// вскрытие посылки происходит здесь.
+//
+// ПОЧЕМУ КАРТА, А НЕ ОДНА ПЕРЕМЕННАЯ. Сторон в ордере две, и посылка шифруется на ключ КОНКРЕТНОЙ стороны.
+// Одна переменная хранила ключ последней построенной стороны, поэтому посылка вскрывалась не тем ключом, и
+// проверка честно отвечала "в шифртексте не та половина". Теперь ключ находится по публичному.
+const encPrivByPub = new Map();
+
+// Кому зашифрована посылка в данном контексте ордера. Контекст - идентификатор стороны.
+const sealedToPub = new Map();
+
+const canon = (h) => "0x" + String(h || "").replace(/^0x/i, "").toLowerCase();
+
+self.onmessage = async (event) => {
+  const { id, type, orderContext, ownHalf, counterparty, sealedBytes, joint } = event.data || {};
+  const say = (stage, detail) => self.postMessage({ id, kind: "progress", stage, detail });
+  try {
+    if (type === "newSide") {
+      // Половина генерируется мгновенно, а доказательство считается долго: сообщаем оба этапа
+      // раздельно, чтобы интерфейс успел показать первый до начала второго.
+      say("half", "генерирую половину ключа");
+      // Текст идёт НА КНОПКУ: она неактивна во время доказательства, и это единственное место, куда
+      // смотрит пользователь. Поэтому коротко и на языке интерфейса.
+      say("proof", "proving DLEQ proof: about 10 seconds");
+      const side = builder.newSide(orderContext, false, (bit, total) => {
+        say("proof", "proving DLEQ proof: " + bit + " of " + total + " bits (" +
+          Math.round((bit / total) * 100) + "%)");
+      });
+      // Hex-поля отдаём в каноническом виде (с префиксом 0x, нижний регистр), как это делает seal():
+      // иначе одни и те же байты гуляют по коду в двух записях, и однажды это даёт ошибку в другом месте.
+      const canon = (h) => "0x" + String(h).replace(/^0x/i, "").toLowerCase();
+      // Ключ кладём в карту по публичному: он понадобится, если посылка шифруется на эту сторону.
+      encPrivByPub.set(canon(side.enc.pub), side.enc.priv);
+      self.postMessage({
+        id, kind: "done",
+        result: {
+          pub: { ed: canon(side.pub.ed), secp: canon(side.pub.secp) },
+          encPub: canon(side.enc.pub),
+          proof: side.proof,
+          half: side.half,   // BigInt: структурное клонирование переносит его без потерь
+      // ПОЛОВИНА ПРОСМОТРА ТОЖЕ УХОДИТ НАРУЖУ. Без неё сборка общего адреса падала на «не задано:
+      // ownViewHalf»: воркер возвращал только половину КЛЮЧА ТРАТЫ, а вызывающий код брал из ответа обе.
+      // Сторона их создаёт (order.js: newSide), терялся именно ответ воркера.
+      viewHalf: side.viewHalf,
+      viewPub: canon(side.viewPub),
+        },
+      });
+    } else if (type === "seal") {
+      say("seal", "шифрую половину для контрагента");
+      // Запоминаем, на чей ключ зашифровали: именно им и надо будет вскрывать.
+      sealedToPub.set(String(orderContext), canon(counterparty && counterparty.encPub));
+      const sealed = builder.sealFor({ enc: { pub: counterparty.encPub } }, ownHalf, orderContext);
+      self.postMessage({ id, kind: "done", result: { commitment: sealed.commitment, bytes: sealed.bytes } });
+    } else if (type === "commit") {
+      // Обязательство на половину: наружу уходит только хеш, сама половина остаётся здесь.
+      const hex = "0x" + builder.halfCommitment(ownHalf).replace(/^0x/, "");
+      self.postMessage({ id, kind: "done", result: { commitment: hex } });
+    } else if (type === "pointOf") {
+      self.postMessage({ id, kind: "done", result: { ed: builder.pointOf(ownHalf) } });
+    } else if (type === "jointAddress") {
+      // АДРЕС СЧИТАЕТСЯ ЗДЕСЬ, А НЕ В ГЛАВНОМ ПОТОКЕ: криптография живёт в одном месте, и главный поток
+      // не должен обрастать половинами и кривыми. Наружу уходит строка адреса и обе публичные точки.
+      self.postMessage({ id, kind: "done", result: builder.jointAddress(joint || {}) });
+    } else if (type === "newMakerMaterial") {
+      // МАТЕРИАЛ МЕЙКЕРА ОБРАТНОЙ СДЕЛКИ: ДВЕ ПОЛОВИНЫ И ИХ ПУБЛИЧНАЯ ЧАСТЬ, БЕЗ ДОКАЗАТЕЛЬСТВА.
+      //
+      // ПОЧЕМУ БЕЗ ДОКАЗАТЕЛЬСТВА, хотя в прямом направлении сторона его несёт. Доказательство DLEQ
+      // связывает половину с ПРИВЯЗКОЙ ордера (соль, сроки, адрес забора), а привязку в обратном режиме
+      // назначает НОДА и присылает её в билете. Пока билета нет, контекста нет, и доказывать нечего -
+      // ровно поэтому фаза 1 мейкера у ноды (tools/maker-reverse-order.mjs) считает те же величины и
+      // ничего не доказывает. Считать здесь одиннадцатисекундное доказательство значило бы заморозить
+      // кнопку заявки на то, что ноде пока не нужно.
+      //
+      // ЧТО УХОДИТ НАРУЖУ: те же четыре имени, которыми нода принимает заявку мейкера
+      // (rfq/reverseOrder.mjs, makerRequestRefusal), - и две половины, которыми мейкер потом забирает
+      // выплату и видит приход XMR. Имена половин взяты у вывода (order.js: newSide) и у файла
+      // восстановления (recovery/recoveryFile.js: spendHalf, viewHalf), чтобы у одного и того же
+      // значения не появилось второго имени.
+      const spendHalf = builder.halves.newHalf();
+      const viewHalf = builder.halves.newHalf();
+      self.postMessage({
+        id, kind: "done",
+        result: {
+          // ОБЯЗАТЕЛЬСТВО И ТОЧКА - ОБ ОДНОЙ И ТОЙ ЖЕ ПОЛОВИНЕ ТРАТЫ, и считает их один модуль половин:
+          // цепь сверяет половину с обязательством (NinseiEscrow.sol:235), поэтому разойтись им нельзя.
+          commitHalfClaimer: canon(builder.halfCommitment(spendHalf)),
+          edPointClaimer: canon(builder.halves.publicHalves(spendHalf).ed),
+          // ТОЧКА ПРОСМОТРА: по ней нода собирает общий адрес (адрес - сумма точек).
+          edViewPointClaimer: canon(builder.halves.publicHalves(viewHalf).ed),
+          // ПОЛОВИНА ПРОСМОТРА - ПРИВАТНАЯ и уходит ноде единственной из двух приватных: без неё она не
+          // увидит приход XMR. Форма записи та же, что у ноды: 32 байта hex (maker-reverse-order.mjs:83).
+          viewHalfClaimer: canon("0x" + viewHalf.toString(16).padStart(64, "0")),
+          spendHalf,
+          viewHalf,
+        },
+      });
+    } else if (type === "verify") {
+      say("verify", "проверяю доказательство контрагента");
+      const side = { proof: counterparty.proof, pub: { ed: counterparty.edPub } };
+      // Вскрываем тем ключом, на который посылка была зашифрована в этом контексте.
+      const recipient = sealedToPub.get(String(orderContext));
+      const openWith = recipient ? encPrivByPub.get(recipient) : null;
+      if (sealedBytes && !openWith) {
+        throw new Error("нет ключа, которым вскрывать посылку: не было шифрования в этом контексте ордера");
+      }
+      const verdict = builder.verifySide(side, orderContext, sealedBytes || null, openWith);
+      self.postMessage({ id, kind: "done", result: verdict });
+    } else {
+      self.postMessage({ id, kind: "error", message: "неизвестный запрос воркеру: " + String(type) });
+    }
+  } catch (err) {
+    self.postMessage({ id, kind: "error", message: (err && err.message) || String(err) });
+  }
+};

package/engine/core/config.js

@@ -389,7 +389,9 @@ export const CHAINS = [
     // half is not sent but revealed by presentation. Switching back to "simulated" is one edit, to show a demo with
     // no money movement. cashier: the INTERFACE's fee cashier, named in quotes and now deployed (the second CREATE of
     // the same pass). implementationCodeHash: the escrow implementation the factory carries, checked against the chain.
-    escrow: { address: "0x3eE25f12758ec28e5b3045d16132D89Cd0bf341F", mode: "live", cashier: "0x1123A3875775Da25FA181Af0d91EB278E94a5dfb", implementationCodeHash: "0xf97af2b4eed8c646d82bce001e52ff03c065d43127073f8ee52271b65c35d659" },
+    // deploymentBlock: the height the factory was created at; a log search for its orders starts here, not at zero,
+    // because public RPCs cap a log query at about 10M blocks and would refuse a scan from genesis.
+    escrow: { address: "0x3eE25f12758ec28e5b3045d16132D89Cd0bf341F", mode: "live", deploymentBlock: 321430239, cashier: "0x1123A3875775Da25FA181Af0d91EB278E94a5dfb", implementationCodeHash: "0xf97af2b4eed8c646d82bce001e52ff03c065d43127073f8ee52271b65c35d659" },
     tokens: [
       // Test USDC (Circle): decimals 6 and symbol "USDC" verified on chain by the same node.
       { symbol: "USDC", address: "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d", decimals: 6, usd: 1, cls: "ar-token-usdc" },

package/engine/sdk/bridge.js

@@ -66,9 +66,9 @@ import { cachedFeeRate } from "../evm/fees.js";
 import { networkFromShape } from "../monero/address.js";
 import { height as nodeHeightValue } from "../monero/node.js";
 
-// THE CORE ADDRESS AS A STRING - THE BUILT BUNDLE UNDER www/: the page gets the core as ONE module, not a pile
-// of sdk/ sources; ?v=<hash> keeps the cache fresh.
-const SDK_BUNDLE = "/assets/vendors/sdk/sdk-browser.js?v=69d79c13";
+// THE CORE ADDRESS AS A STRING - THE BUILT BUNDLE SHIPPED WITH THE PACKAGE. A relative URL resolves both in the
+// published `engine/` tree and in the page that serves this shim from `www/js/sdk/`; ?v=<hash> keeps the cache fresh.
+const SDK_BUNDLE = new URL("../../assets/vendors/sdk/sdk-browser.js?v=69d79c13", import.meta.url).href;
 
 // A NAMED SEAM FOR CHECKS - THE SAME TECHNIQUE AS sdkBookUse BELOW. The asynchronous path is driven against a
 // stand-in order book (the demo network has no provider), and the ordinary escrow funding that follows a settled

package/index.d.ts

@@ -80,7 +80,7 @@ export interface NinseiOptions {
     readonly rpc?: { readonly evm?: string; readonly monero?: string };
   };
   /**
-   * Renaming API paths by name: { swaps, swap, evmSwaps, orderQuote, revealedHalf, swept }.
+   * Renaming API paths by name: { swaps, swap, evmSwaps, orderQuote, orderSell, revealedHalf, swept }.
    * An unknown name is bad-input (a typo must not silently fall back to the default).
    */
   routes?: Readonly<Record<string, string>>;
@@ -294,6 +294,12 @@ export interface ChainConfig {
   readonly nativeSymbol: string;
   readonly tokens: readonly TokenConfig[];
   readonly dex: { readonly routes: readonly unknown[] } | null;
+  /** The escrow deployment on this network, when there is one. `deploymentBlock` is the block that holds the factory's creation. */
+  readonly escrow: {
+    readonly address: string | null;
+    readonly mode: string | null;
+    readonly deploymentBlock: number | null;
+  } | null;
 }
 
 export interface TokenConfig {
@@ -423,6 +429,11 @@ export interface FirmQuoteRequest {
   readonly providerId: string;
   /** The order terms: how much, to whom, the deadlines, the salt. The context the signature is bound to is assembled from them. */
   readonly order: Readonly<Record<string, unknown>>;
+  /**
+   * THE TAKER'S MAKER VIEW HALF, when the order was built from a recovery key. Sent top-level to the node; the quote
+   * must echo it, so the joint view key can be rebuilt from the twelve words.
+   */
+  readonly viewHalfClaimer?: string;
 }
 
 export interface QuotesApi {
@@ -435,6 +446,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 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.
+   */
+  sale(request: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>>>;
 }
 
 export interface QuoteRequest {
@@ -507,6 +523,8 @@ export interface QuoteOffer {
   readonly currency: string | null;
   readonly rate: number;
   readonly rateQuote: number;
+  /** The claim tip in native-token wei; a sale is ranked by the payout AFTER it. */
+  readonly claimTip: string;
   readonly min: number | null;
   readonly max: number | null;
   readonly step: number | null;
@@ -1258,6 +1276,11 @@ export interface SweepApi {
   destination(request: SweepDestinationRequest): Promise<SweepDestination>;
   /** What is known about the withdrawal from the recovery file: the address, the restore height, what we can dispose of. */
   plan(request: SweepPlanRequest): Promise<SweepPlan>;
+  /**
+   * Build the same withdrawal material from the 12 words and an order found by `findSwaps`, without a recovery file.
+   * The checks are the same: the side, the person's points against the key, the joint address.
+   */
+  fromOrder(request: SweepFromOrderRequest): Promise<SweepFromOrderResult>;
   /**
    * RESTORE THE WALLET FROM A HEIGHT AND REPORT WHAT IT HOLDS. Sets the restore height a little below the one given,
    * rescans, syncs and reads the total and the spendable balance. Coins that exist but are locked get ONE more pass
@@ -1334,6 +1357,8 @@ export interface SweepRestoreResult {
   /** Present when a window was requested: whether it was used, and why it was skipped. */
   readonly window?: {
     readonly used: boolean;
+    /** Whether the full scan ran because the window found nothing (or could not scan). */
+    readonly fallback: boolean;
     readonly skipped: string | null;
     readonly fromHeight: number;
     readonly toHeight: number;
@@ -1373,6 +1398,11 @@ export interface SweepWallet {
   chainId(): string;
   unlockedBalance(): Promise<bigint | number | string>;
   sync(): Promise<void>;
+  /** The withdrawal role: no-op when this wallet is already open on the plan's address. */
+  open(plan: SweepPlan): Promise<void>;
+  sweepUnlocked(request: { readonly address: string; readonly relay: boolean }): Promise<unknown>;
+  relay(signed: unknown): Promise<readonly string[]>;
+  fee?(signed: unknown): Promise<string | null>;
   close(): Promise<void>;
   driver(): unknown;
 }
@@ -1387,6 +1417,43 @@ export interface SweepReportResult {
   readonly reported: boolean;
 }
 
+export interface SweepFromOrderRequest {
+  /** The 12 words of the recovery key. */
+  readonly mnemonic: string;
+  readonly chainId: number;
+  /** The settlement network slug, e.g. `arbitrum-sepolia`. */
+  readonly network: string;
+  /** The Monero network the joint address belongs to, e.g. `stagenet`. */
+  readonly moneroNetwork: string;
+  /** One entry from `findSwaps`. */
+  readonly order: {
+    readonly escrow: string;
+    readonly locker: string;
+    readonly claimer: string;
+    readonly edPointLocker: string;
+    readonly edPointClaimer: string;
+    readonly edViewPointLocker: string;
+    readonly index: number;
+    readonly side: "locker" | "claimer";
+    readonly startHeight?: number | null;
+    readonly blockTime?: number | null;
+    readonly readyBy?: number;
+    readonly t1?: number;
+    readonly [field: string]: unknown;
+  };
+  /** Optional encryption boundary for the generated file; empty means an unencrypted file. */
+  readonly passphrase?: string;
+}
+
+export interface SweepFromOrderResult {
+  /** The payload `buildPayload` produced; the same fields a recovery file carries. */
+  readonly payload: unknown;
+  /** The same file `plan`/`keys` accept, so a caller can keep using the file-based API. */
+  readonly contents: string;
+  /** The joint Monero address built from the key and the order. */
+  readonly address: string;
+}
+
 export interface SweepPlanRequest {
   readonly file: { readonly contents: string } | string;
   readonly passphrase: string;
@@ -1427,8 +1494,10 @@ export type SweepMissing = "restore-height" | "spendable" | "revealed-half";
 export interface SweepRunRequest extends SweepPlanRequest {
   /** Where to withdraw the XMR to. */
   readonly to: string;
+  /** An already opened and synced adapter, the same one `restore` used. */
+  readonly wallet?: MoneroWalletAdapter;
   /** Returns a Monero wallet: the core does not drag in WASM. */
-  readonly connectWallet: (plan: SweepPlan) => Promise<MoneroWalletAdapter>;
+  readonly connectWallet?: (plan: SweepPlan) => Promise<MoneroWalletAdapter>;
 }
 
 /**
@@ -1597,6 +1666,9 @@ export interface ActionsApi {
 export interface ActionsRequest {
   readonly escrow: string;
   readonly expect: Readonly<Record<string, unknown>>;
+  /** The claimer whose half is revealed by `claim`; absent - `expect.claimer` is used. A claim without one is
+   * refused: the package sends it only from the claimer's own wallet, never from a third-party sender. */
+  readonly claimer?: string;
   readonly onStep?: (stage: string, detail?: string) => void;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -28,6 +28,7 @@
     "check:terminal": "node tools/check.mjs --only=terminal",
     "check:terminal-teeth": "node tools/check-terminal-teeth.mjs",
     "check:sweep": "node tools/sweep-refusal.test.mjs",
+    "check:sweep-half": "node tools/check-sweep-half.mjs",
     "sync:version": "node tools/sync-version.mjs",
     "check:restore": "node tools/check-restore.mjs",
     "check:restore-height": "node tools/check-restore-height.mjs",
@@ -87,13 +88,14 @@
   "files": [
     "src",
     "engine",
+    "assets",
     "index.d.ts",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=24.22.1"
   },
   "keywords": [
     "xmr",

package/src/actions.mjs

@@ -25,6 +25,18 @@ const walletOrFail = (wallet) => {
   return wallet;
 };
 
+// THE CLAIM'S HALF IS REVEALED BY WHOEVER SENDS IT. The package sends a claim only from the claimer's own wallet:
+// a third-party sender would see the half before the claim is mined, and the only reason to use one is the tip -
+// not a reason to hand the half to another party. A caller with no claimer is refused, not sent blind.
+export function claimSenderVerdict({ sender = null, claimer = null } = {}) {
+  const from = typeof sender === "string" ? sender.trim().toLowerCase() : "";
+  const to = typeof claimer === "string" ? claimer.trim().toLowerCase() : "";
+  if (!to) return { ok: false, code: "bad-input", field: "claimer" };
+  if (!from) return { ok: false, code: "bad-input", field: "wallet.address" };
+  if (from !== to) return { ok: false, code: "bad-input", field: "wallet", why: "not-the-claimer" };
+  return { ok: true };
+}
+
 const requestOrFail = (request, extra) => {
   if (!request || typeof request !== "object") throw new SdkError("bad-input", { field: "request" });
   const missing = missingFields(request, ["escrow", "expect", ...extra]);
@@ -59,6 +71,9 @@ export function createActions({ call = null } = {}) {
       requestOrFail(request, ["halfClaimer"]);
       walletOrFail(wallet);
       const { escrow, halfClaimer, expect, onStep } = request;
+      const sender = typeof wallet.address === "function" ? await wallet.address() : null;
+      const verdict = claimSenderVerdict({ sender, claimer: request.claimer || (expect && expect.claimer) });
+      if (!verdict.ok) throw new SdkError(verdict.code, { field: verdict.field, why: verdict.why, surface: "actions.claim" });
       return await withCodes("claim", () => flow.claimOrder({ escrow, halfClaimer, expect, onStep, deps: deps(wallet) }));
     },
     /** Refunding: it also reveals a half. The core passes the expectations ALWAYS, though the engine does not require them. */

package/src/adapters/monero-wallet.mjs

@@ -164,6 +164,32 @@ export function moneroWalletAdapter({
       return undefined;
     },
 
+    // THE SAME ADAPTER ALSO PLAYS THE WITHDRAWAL ROLE. `sweep.restore` already takes this wallet; `sweep.sign`
+    // opened a second adapter over a second monero-ts wallet. `open` is a no-op when the address already matches
+    // (the page has opened and synced this wallet), and the withdrawal calls go to the same underlying wallet.
+    async open(plan) {
+      if (wallet === null) throw new SdkError("wallet-not-connected", { vm: XMR_VM, surface: "open" });
+      const wanted = plan && plan.address ? String(plan.address) : null;
+      if (wanted && address !== wanted) throw new SdkError("recovery-failed", { step: "address" });
+      return undefined;
+    },
+
+    async sweepUnlocked(request) {
+      return await need("sweepUnlocked").sweepUnlocked({ address: request.address, relay: request.relay });
+    },
+
+    async relay(signed) {
+      return await need("relay").relayTxs(signed);
+    },
+
+    // Optional, like every withdrawal adapter: a library that reports no fee answers null rather than a zero.
+    async fee(signed) {
+      const tx = Array.isArray(signed) ? signed[0] : signed;
+      if (!tx || typeof tx.getFee !== "function") return null;
+      const value = tx.getFee();
+      return value === null || value === undefined ? null : String(value);
+    },
+
     // THE MONERO WALLET HAS NO EVENTS (monero-ts has no on/removeListener): a subscriber receives a notification
     // after connect and after sync, and the subscription promises nothing more. Unsubscribing is the same as the EVM
     // adapter's.

package/src/config.mjs

@@ -51,6 +51,13 @@ const chainConfig = (chain) => ({
     decimals: Number(t.decimals),
   })),
   dex: chain.dex ? { routes: chain.dex.routes || [] } : null,
+  // THE ESCROW'S BIRTH HEIGHT, when the network has an escrow. A caller can hand it to findSwaps instead of
+  // inventing a start block or asking from genesis, which public RPCs refuse.
+  escrow: chain.escrow ? {
+    address: chain.escrow.address || null,
+    mode: chain.escrow.mode || null,
+    deploymentBlock: Number.isSafeInteger(chain.escrow.deploymentBlock) ? chain.escrow.deploymentBlock : null,
+  } : null,
 });
 
 // --- ADDRESSES AND PATHS THAT ARE SUPPLIED FROM OUTSIDE ------------------------------------
@@ -79,6 +86,8 @@ export const DEFAULT_ROUTES = Object.freeze({
   evmSwaps: "/evm-swaps",
   // A quote for an order: the provider's commitment under keys, not a market snapshot.
   orderQuote: "/order-quote",
+  // A reverse-mode ticket: the maker supplies the XMR fields, the node answers with a signed quote and its claim tip.
+  orderSell: "/order-sell",
   revealedHalf: "/escrow/revealed-half",
   swept: "/swaps/{id}/swept",
 });

package/src/index.mjs

@@ -269,6 +269,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),
+      // A REVERSE TICKET: the node signs it; its claim tip is checked here before the caller sees it.
+      sale: (request) => quotes.sale(request),
     },
     // READING STATE WORKS, STARTING IS NAMED HONESTLY: list/get raise swaps from storage after a page reload;
     // start holds the step order and runs into the step that creates the record (stage 2).

package/src/public/networks.d.ts

@@ -32,6 +32,8 @@ export interface Chain {
   rpcUrl?: string;
   tokens?: ChainToken[];
   uniswap?: ChainUniswap;
+  /** The escrow deployment, including the factory's birth height. */
+  escrow?: { address?: string; mode?: string; deploymentBlock?: number; [field: string]: unknown };
   [field: string]: unknown;
 }
 

package/src/public/recovery.d.ts

@@ -325,6 +325,18 @@ export interface FoundSwap {
   readonly transactionHash: string | null;
   readonly blockNumber: number | null;
   readonly logIndex: number | null;
+  /** The settlement block timestamp in seconds, when the caller passed `evmBlockTime`; null otherwise. */
+  readonly blockTime: number | null;
+  /** The settlement asset of the escrow. Current contracts are native-only. */
+  readonly settlementToken: "native";
+  /** The asset the person actually paid before the DEX leg. Not on the settlement chain, so `null` for a found order. */
+  readonly payToken: string | null;
+  /** Why `payToken` is absent. `not-on-chain` means the order event and clone carry no token; do not infer one. */
+  readonly payTokenReason: "not-on-chain";
+  /** The XMR side of the order in atomic units, read from the clone's condition word 18; null when no code reader
+   * was passed or the contract is not the expected clone. */
+  readonly xmrAmount: string | null;
+  readonly xmrAmountReason: "no-code-reader" | "code" | "not-clone" | null;
   readonly index: number;
   readonly side: "locker" | "claimer";
   /** The Monero height a withdrawal may start from, derived from the order's block time. Null when the caller did
@@ -376,11 +388,15 @@ export declare function findSwaps(request: {
   address?: string | null;
   evmLogs: (request: { address: string; topics: (string | null)[]; fromBlock: number | string; toBlock: number | string }) => Promise<unknown[]>;
   fromBlock?: number | string;
+  /** The factory's deployment block from the chain registry; used when `fromBlock` is omitted. */
+  deploymentBlock?: number | null;
   toBlock?: number | string;
   gap?: number;
   maxIndex?: number;
   /** 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. */
+  evmCode?: (address: string) => Promise<string>;
   /** The Monero tip at the time of the search: () -> height. */
   moneroTip?: () => Promise<number>;
   /** A Monero block header timestamp, in seconds: (height) -> seconds. */

package/src/quotes.mjs

@@ -83,6 +83,13 @@ export function readQuote(pair, raw, owner = {}, data = {}) {
     currencyNetwork: q.currencyNetwork ? String(q.currencyNetwork) : null,
     rateQuote,
     rate,
+    // THE CLAIM TIP IS IN THE MAKER'S NATIVE TOKEN (wei). A sale is ranked by what the seller receives AFTER it;
+    // the value is kept as a string, because a wei amount does not fit a float reliably.
+    claimTip: (() => {
+      if (q.claimTip === undefined || q.claimTip === null || q.claimTip === "") return "0";
+      try { const n = BigInt(q.claimTip); return n < 0n ? "0" : n.toString(); }
+      catch { return "0"; }
+    })(),
     min: num(q.min),
     max: num(q.max),
     step: num(q.step),
@@ -104,6 +111,27 @@ export function readQuote(pair, raw, owner = {}, data = {}) {
   };
 }
 
+/**
+ * THE BEST OFFER IS THE ONE THAT PAYS THE MOST, NOT THE ONE WITH THE HIGHEST RATE. On a sale the maker may move
+ * its margin into `claimTip`: the escrow pays that tip out of the seller's payout, so a higher rate with a larger
+ * tip can leave the seller with less. With no amount there is nothing to compare beyond the rate, and a buy has
+ * no tip. Native-token wei are converted at 18 decimals: a sale settles in the chain's native coin.
+ */
+export function rankOffers(offers = [], { direction = "buy", amount = null } = {}) {
+  const list = Array.isArray(offers) ? offers.filter((offer) => offer && Number(offer.rate) > 0) : [];
+  const amountXmr = Number(amount);
+  const score = (offer) => {
+    const rate = Number(offer.rate);
+    if (direction !== "sell" || !(amountXmr > 0)) return rate;
+    let tip = 0;
+    try { tip = Number(BigInt(offer.claimTip || "0")) / 1e18; } catch { tip = 0; }
+    return amountXmr * rate - tip;
+  };
+  const ranked = list.map((offer) => ({ offer, net: score(offer) }))
+    .sort((a, b) => (b.net - a.net) || (Number(b.offer.rate) - Number(a.offer.rate)));
+  return { best: ranked.length ? ranked[0].offer : null, net: ranked.length ? ranked[0].net : null, ranked };
+}
+
 /**
  * Parsing the book in one place. The envelope is accepted in three forms (a map by pairs, a list of rows, a list
  * of providers) and is brought to a single list: the screen must not know which form the answer came in.
@@ -201,7 +229,7 @@ const compactOffer = (o) => ({
   assetNetwork: o.assetNetwork, currencyNetwork: o.currencyNetwork, networkStated: o.networkStated,
   networksDerived: o.networksDerived === true, networksUnnamed: o.networksUnnamed === true,
   // THE REASON (in the provider's words), THE PACKAGE'S SIGNATURE AND KEY, THE AGE BY ITS OWN MARK.
-  why: o.why, signature: o.signature, keyId: o.keyId, ageMs: o.ageMs,
+  claimTip: o.claimTip, why: o.why, signature: o.signature, keyId: o.keyId, ageMs: o.ageMs,
   networks: { asset: o.assetNetwork, currency: o.currencyNetwork, stated: o.networkStated },
 });
 
@@ -267,8 +295,11 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       const asked = explicit ? Number(request.size) : size;
       const data = await http.json("/rate?amount=" + encodeURIComponent(asked) + "&side=" + encodeURIComponent(request.direction));
       const book = readBook(data, now());
-      const offer = book.best;
       const amount = Number.isFinite(Number(request.amount)) ? Number(request.amount) : null;
+      // A SALE IS RANKED BY THE PAYOUT AFTER THE TIP; a buy has no tip. Without an amount the rate is the only
+      // comparable number, and the service's own best remains the fallback.
+      const ranked = rankOffers(book.offers, { direction: request.direction, amount });
+      const offer = ranked.best || book.best;
       // The size derived from the person's amount becomes the size of the NEXT request: the price does not depend
       // on volume, and the volume is needed by the provider to say whether it takes such a size. With a named size
       // there is nothing to derive - it stays what it was asked as.
@@ -362,6 +393,58 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
     //
     // The path and the body are the same as the engine's (`requestOrderQuote` in www/js/core/rfqSource.js): POST to
     // the named path, body { providerId, order }. The path is named by name, so it is overridable by options.
+    // A REVERSE-MODE TICKET. The maker sells XMR; the node answers with a signed order quote that carries the claim
+    // tip. The tip is checked HERE, on the ticket's own signed figure, with the same formula the node used: base fee
+    // plus the priority part of the gas price. A buy quote has no tip; a sale is the only route where one exists.
+    async sale(request) {
+      if (!request || typeof request !== "object") fail("bad-input", { field: "request" });
+      const payload = request.request && typeof request.request === "object" ? request : { request };
+      let res = null;
+      try {
+        res = await http.tryJson(config.route("orderSell"), {
+          method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(payload),
+        });
+      } catch (error) {
+        if (error && error.code === "bad-input") throw error;
+        fail("server-unavailable", { step: "order-sell" });
+      }
+      if (!res || res.ok !== true || !res.body || res.body.ok !== true) fail("quote-refused", { step: "order-sell" });
+      const ticket = res.body;
+      const quote = (ticket.handoff && ticket.handoff.quote) || ticket.quote || null;
+      if (!quote || typeof quote !== "object") fail("quote-field-unbound", { step: "order-sell", field: "quote" });
+      // THE TICKET'S TIP MUST BE THE SIGNED ONE. The node returns both the ticket's `claimTip` object and the quote it
+      // signed; a difference means the figure shown to the person is not the figure the escrow will pay.
+      const shown = ticket.claimTip && ticket.claimTip.wei !== undefined && ticket.claimTip.wei !== null
+        ? String(ticket.claimTip.wei) : null;
+      if (shown === null) fail("quote-field-unbound", { step: "claimTip", field: "claimTip" });
+      if (ticket.claimTip.signed !== true) fail("quote-field-unbound", { step: "claimTip", field: "signed" });
+      let signedTip = null;
+      try { signedTip = quote.claimTip === undefined || quote.claimTip === null || quote.claimTip === "" ? "0" : BigInt(quote.claimTip).toString(); }
+      catch { fail("quote-field-unbound", { step: "claimTip", field: "claimTip" }); }
+      let shownBig = null;
+      try { shownBig = BigInt(shown); } catch { fail("quote-tip-unreadable", { step: "claimTip" }); }
+      if (signedTip === null || shownBig < 0n || BigInt(signedTip) !== shownBig) {
+        fail("quote-refused", { step: "claimTip", why: "not-the-signed-tip" });
+      }
+      if (shownBig > 0n) {
+        if (typeof evmBlock !== "function") fail("quote-tip-unchecked", { step: "claimTip", why: "no-block-read" });
+        let block = null;
+        try { block = await evmBlock("latest"); } catch { fail("quote-tip-unchecked", { step: "claimTip", why: "block-read-failed" }); }
+        const baseFeeWei = block && (block.baseFeePerGas !== undefined ? block.baseFeePerGas : block.baseFeeWei);
+        // THE NODE SIZES THE TIP FROM THE GAS PRICE, PRIORITY INCLUDED. The SDK used to pass only the base fee, so an
+        // honest L1 tip (or a base fee that dropped between sizing and checking) was refused.
+        let priorityFeeWei = block && block.priorityFeePerGas !== undefined ? block.priorityFeePerGas : null;
+        if (priorityFeeWei === null && block && block.gasPrice !== undefined && baseFeeWei !== undefined && baseFeeWei !== null) {
+          try {
+            const gas = BigInt(block.gasPrice); const base = BigInt(baseFeeWei);
+            priorityFeeWei = gas > base ? gas - base : 0n;
+          } catch { priorityFeeWei = 0n; }
+        }
+        const verdict = claimTipVerdict({ claimTipWei: shownBig, baseFeeWei, priorityFeeWei: priorityFeeWei === null ? 0n : priorityFeeWei });
+        if (!verdict.ok) fail(verdict.code, { step: "claimTip", ...verdict });
+      }
+      return ticket;
+    },
     async firm(request) {
       if (!request || typeof request !== "object") fail("bad-input", { field: "request" });
       if (typeof request.providerId !== "string" || !request.providerId) fail("bad-input", { field: "providerId" });
@@ -374,6 +457,8 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
         fail("address-denied", { step: "order-quote" });
       }
       let res = null;
+      const viewHalfClaimer = request.viewHalfClaimer === undefined || request.viewHalfClaimer === null || request.viewHalfClaimer === ""
+        ? null : String(request.viewHalfClaimer);
       try {
         // THE ANSWER IS READ AS A VALUE (tryJson), NOT AS AN EXCEPTION: "did not answer" and "answered and
         // refused" must stay different, and a refusal's own body carries the reason. `json` throws
@@ -381,7 +466,8 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
         res = await http.tryJson(config.route("orderQuote"), {
           method: "POST",
           headers: { "content-type": "application/json" },
-          body: JSON.stringify({ providerId: request.providerId, order: request.order }),
+          body: JSON.stringify({ providerId: request.providerId, order: request.order,
+            ...(viewHalfClaimer === null ? {} : { viewHalfClaimer }) }),
         });
       } catch (error) {
         if (error && error.code === "bad-input") throw error;
@@ -397,6 +483,17 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       }
       const body = res.body;
       const quote = body.quote;
+      // THE MAKER'S VIEW HALF IS OURS, NOT THE NODE'S CHOICE. When the caller supplies it, the quote must carry the
+      // same scalar back; otherwise the maker used another half and the joint view key cannot be rebuilt from the key.
+      if (viewHalfClaimer !== null) {
+        const echoed = quote.viewHalfClaimer;
+        if (echoed === undefined || echoed === null || echoed === "") {
+          fail("quote-field-unbound", { step: "viewHalfClaimer", field: "viewHalfClaimer" });
+        }
+        if (String(echoed).toLowerCase() !== viewHalfClaimer.toLowerCase()) {
+          fail("quote-refused", { step: "viewHalfClaimer", why: "not-echoed" });
+        }
+      }
       // A MISSING FIELD OF THE SIGNED SET IS NOT "PROBABLY ZERO": the digest cannot be built, so the quote is
       // not verifiable and is refused (its own code, so the interface can say which field is unbound).
       const missingFields = orderQuoteMissingFields(quote);