@ninsei-labs/sdk 0.52.0 → 0.54.0

package/index.d.ts

@@ -9,7 +9,7 @@
 //   2) not a single DOM access: `document`, `window`, `localStorage` do not occur in the SDK. Storage and the wallet
 //      come from outside: as an adapter and an EIP-1193 provider;
 //   3) the SDK opens no windows: the interface shows the wallet modal, the SDK accepts a ready provider;
-//   4) funds are not locked until the interface has confirmed the recovery file is saved (onRecoveryFile);
+//   4) funds are not locked until the interface has confirmed the one recovery key is saved (onRecoveryKey);
 //   5) the guards cannot be bypassed: preflight is part of the same path, not a separate button.
 //
 // Naming language: the values are data. `step` and `code` are stable strings from the tables below; they are
@@ -288,7 +288,15 @@ export interface SdkConfig {
 export interface ChainConfig {
   readonly id: string;
   /** The network's virtual machine: "evm" today; "tron" and "solana" - when their leg drivers appear. */
-  readonly vm: string;
+  readonly vm: string | null;
+  /** What this settlement side looks like. Metadata only: it does not claim that a driver exists. */
+  readonly settlementProfile?: {
+    readonly vm: string;
+    readonly addressFormat: string;
+    readonly settlementKind: "contract" | "program" | "utxo-script" | string;
+    readonly refKind: "address" | "pda" | "script" | string;
+    readonly txRef: "hash" | "signature" | "txid" | string;
+  } | null;
   readonly chainId: number;
   readonly name: string;
   readonly nativeSymbol: string;
@@ -446,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.
@@ -652,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>>;
 }
 
 /**
@@ -742,16 +804,21 @@ export interface SwapsApi {
   /**
    * Start a swap. The SDK holds the step order, not the screen:
    *   1) guards (preflight); 2) the swap record (createSwap); 3) the order - it GENERATES the key halves;
-   *   4) the recovery file / one key and the interface's confirmation that it is saved; 5) locking the funds (signature);
+   *   4) the one recovery key and the interface's confirmation that it is saved; 5) locking the funds (signature);
    *   6) saving on the server; 7) opening the watch on the Monero address.
-   * HALVES DO NOT EXIST BEFORE THE ORDER: the recovery file carries MY half of the spend key and the counterparty's
-   * open points, and they are taken from the signed order (www/js/atomic/order-worker.js, createOrderBuilder; in the
-   * engine they are fetched by halvesWalletOf). So the file is assembled AFTER the order, but BEFORE locking the
-   * funds.
-   * FUNDS ARE NOT LOCKED UNTIL onRecoveryFile ALLOWS IT: the order is like this not for convenience, but because a
-   * lock without a recovery file is a lock with nothing to open it with if the browser is lost.
+   * HALVES DO NOT EXIST BEFORE THE ORDER: the key's halves and the counterparty's open points are taken from the
+   * signed order. The key is shown BEFORE locking the funds.
+   * FUNDS ARE NOT LOCKED UNTIL onRecoveryKey ALLOWS IT: a lock without a saved key is a lock with nothing to open
+   * 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.
@@ -768,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
@@ -1015,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;
@@ -1123,23 +1243,20 @@ export interface StartRequest {
   /**
    * The EVM wallet for LOCKING THE FUNDS: an adapter with `send` and `receipt` (the same role as WalletAdapter).
    * It comes from outside and is NOT substituted by default: without it the lock step answers with a code
-   * (`bad-input`), rather than going in blind. The recovery file has by now been confirmed by the person.
+   * (`bad-input`), rather than going in blind. The recovery key has by now been confirmed by the person.
    */
   readonly wallet?: WalletAdapter;
-  /**
-   * Hand the OLD per-swap recovery file to the interface and wait for the person's decision.
-   * `true` - the person confirmed the file is saved; `false` - the swap is not started.
-   * Not used when `recoveryKey` is present: that path has one key, saved once.
-   */
-  onRecoveryFile?(file: RecoveryFile): Promise<boolean>;
   /**
    * THE ONE RECOVERY KEY (sdk#76). A BIP39 mnemonic, or a key object from `@ninsei-labs/sdk/recovery`.
-   * When present, the swap's spend and view halves are derived from it instead of being generated, and no
-   * per-swap recovery file is written. The key is kept through the SDK's storage adapter.
+   * The swap's spend and view halves are derived from it; the per-swap recovery file path is gone, and the key is
+   * kept through the SDK's storage adapter.
    */
   recoveryKey?: string | { readonly mnemonic: string };
   /** The swap number, when the caller already reserved one. Absent - the SDK reserves the next free number. */
   recoveryIndex?: number;
+  /** The per-order salt the caller put into the signed quote. When present, the key uses the v2 salt binding and
+   * no index is reserved; it must equal `order.salt`. */
+  recoverySalt?: string | number | bigint;
   /** The first block for the on-chain number check. Absent - the chain registry's escrow deployment block, and
    * zero only when the registry has no height. */
   fromBlock?: string | number;
@@ -1272,6 +1389,7 @@ export interface SweepApi {
    */
   wallet(request: SweepWalletRequest): SweepWallet;
 
+  /**
    * COMPARE A DESTINATION WITH THE FILE'S PROMISE. `ok` is "usable address on the file's network", `matches` is
    * "the promised one" and is null when the file named nobody. Sending XMR elsewhere is a different payment, so the
    * comparison is not presentation.
@@ -1344,6 +1462,10 @@ export interface SweepRestoreRequest {
 export interface SweepRestoreResult {
   readonly total: string;
   readonly unlocked: string;
+  /** False when the wallet did not reach the node's height after its sync; a zero balance is then not evidence. */
+  readonly scanComplete: boolean;
+  /** `sync-failed`, `behind-node` or `no-heights` when `scanComplete` is false. */
+  readonly scanIncompleteReason?: string;
   /** The height the scan actually started from. */
   readonly scanHeight: number;
   readonly walletHeight: number | null;
@@ -1431,7 +1553,10 @@ export interface SweepFromOrderRequest {
     readonly edPointLocker: string;
     readonly edPointClaimer: string;
     readonly edViewPointLocker: string;
-    readonly index: number;
+    readonly index?: number | null;
+    readonly derivation?: "index-v1" | "salt-v2";
+    readonly factory?: string;
+    readonly salt?: string;
     readonly side: "locker" | "claimer";
     readonly startHeight?: number | null;
     readonly blockTime?: number | null;
@@ -1549,8 +1674,9 @@ export interface SweepSignResult {
   /** The free remainder at the moment of signing, in atomic units (string). */
   readonly amount: string;
   /**
-   * THE FEE OF THE SIGNED TRANSFER, in atomic units, or null when the wallet could not report one. A withdrawal
-   * moves the whole remainder, so the fee comes out of it - `receive` is what the recipient gets.
+   * THE FEE OF THE SIGNED TRANSFER, in atomic units, summed over every signed transaction, or null when any of
+   * them could not report one. A withdrawal moves the whole remainder, so the fee comes out of it - `receive` is
+   * what the recipient gets.
    */
   readonly fee: string | null;
   /** The remainder minus the fee. Null when the fee is unknown, or when a reported fee claims more than the remainder. */
@@ -1763,6 +1889,8 @@ export type ErrorCode =
   | "server-unavailable"
   /** The service answered and did not accept: the connection got through, the request did not (status and reason in params). */
   | "server-refused"
+  /** The funding transaction was sent, but no status-1 receipt with the expected OrderCreated proves the escrow. */
+  | "funding-pending"
   /** The wait for the XMR to arrive expired: a separate code, because this is a state of the money, not a breakdown. */
   | "xmr-timeout"
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.52.0",
+  "version": "0.54.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -38,13 +38,39 @@
     "check:destination": "node tools/check-destination.mjs",
     "check:codes-meta": "node tools/check-codes-meta.mjs",
     "check:arrival-read": "node tools/check-arrival-read.mjs",
+    "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: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",
     "check:node-probe": "node tools/check-node-probe.mjs",
-    "check:recovery-key": "node tools/check.mjs --only=recovery-key"
+    "check:recovery-key": "node tools/check.mjs --only=recovery-key",
+    "check:recovery-open": "node tools/check-recovery-open.mjs",
+    "check:contract-vectors": "node tools/check-contract-vectors.mjs",
+    "check:live-contract": "node tools/check-live-contract.mjs",
+    "check:anvil-fork": "node tools/check-anvil-fork.mjs",
+    "check:dex": "node tools/check.mjs --only=cow,cow-refusal,kyber,kyber-refusal,uniswapx,uniswapx-refusal,uniswap-relay,uniswap-relay-refusal",
+    "check:anvil-uniswap": "node tools/check-anvil-uniswap.mjs",
+    "check:atomic-flow": "node tools/check-atomic-flow.mjs",
+    "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"
   },
   "types": "./index.d.ts",
   "exports": {
@@ -121,10 +147,16 @@
     "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",
     "keccak256": "^1.0.6"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "devDependencies": {
+    "typescript": "7.0.2"
+  }
 }

package/src/adapters/monero-wallet.mjs

@@ -25,16 +25,25 @@
 // with a code and params. Neither `null` nor a zero in place of the answer: an empty address and a zero balance
 // look like real data, and that is exactly why they are not returned.
 import { SdkError } from "../errors.mjs";
+import { signedFeeTotal } from "../sweep-fees.mjs";
 import { config as engineConfig, xmrAddress } from "../engine.mjs";
 
 const XMR_VM = "monero";
 // The wallet session label - the same as the withdrawal page's. This is not a secret and not an address, but a session name.
 const DEFAULT_PASSWORD = "ninsei-wallet-session";
 
-/** Monero network names declared by the core's registry. The adapter keeps no table of its own. */
+// THE STANDARD NAMES ARE PART OF THE PROTOCOL, NOT OF A DEPLOYMENT. XMR_NETWORKS names what the demo is configured
+// for (stagenet in CI, fakechain in regtest); a mainnet or testnet wallet is still a valid Monero wallet and the
+// withdrawal page takes the network from its own node. Refuse only a name that is not a Monero network at all.
+const STANDARD_XMR_NETWORKS = ["mainnet", "stagenet", "testnet", "fakechain"];
+
+/** Monero network names declared by the core's registry plus the standard names. */
 const knownNetworks = () => {
   const declared = engineConfig.XMR_NETWORKS || {};
-  return [...new Set(Object.values(declared).filter((v) => typeof v === "string" && v))].sort();
+  return [...new Set([
+    ...Object.values(declared).filter((v) => typeof v === "string" && v),
+    ...STANDARD_XMR_NETWORKS,
+  ])].sort();
 };
 
 /**
@@ -183,11 +192,9 @@ export function moneroWalletAdapter({
     },
 
     // Optional, like every withdrawal adapter: a library that reports no fee answers null rather than a zero.
+    // A split sweep pays a fee on EVERY signed transaction; the total is what leaves the remainder.
     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);
+      return signedFeeTotal(signed);
     },
 
     // THE MONERO WALLET HAS NO EVENTS (monero-ts has no on/removeListener): a subscriber receives a notification

package/src/adapters/monero.mjs

@@ -8,6 +8,7 @@
 // sending is a separate call. That way the interface has a point where it can show the person what exactly will
 // leave, BEFORE sending rather than after.
 import { SdkError } from "../errors.mjs";
+import { signedFeeTotal } from "../sweep-fees.mjs";
 
 export function moneroWallet({ createWallet, networkType, serverUri, password = "ninsei-sweep-session", fields = {} }) {
   const build = typeof createWallet === "function" ? createWallet : null;
@@ -41,15 +42,12 @@ export function moneroWallet({ createWallet, networkType, serverUri, password =
       return await wallet.sweepUnlocked({ address, relay });
     },
     // THE FEE OF WHAT WAS SIGNED, when the library reports one. `sweepUnlocked` answers with the signed
-    // transactions; monero-ts puts the fee on each transaction. Optional by contract - the core treats a missing
-    // method as "unknown", so this adapter says what it can and nothing more.
+    // transactions; monero-ts puts the fee on each transaction and a split sweep pays every one of them. Optional
+    // by contract - the core treats a missing method as "unknown", so this adapter says what it can and nothing
+    // more; one unreadable fee makes the total unknown, not partial.
     async fee(signed) {
       need();
-      const list = Array.isArray(signed) ? signed : [signed];
-      const tx = list[0];
-      if (!tx || typeof tx.getFee !== "function") return null;
-      const value = tx.getFee();
-      return value === null || value === undefined ? null : String(value);
+      return signedFeeTotal(signed);
     },
 
     async relay(signed) {

package/src/codes.mjs

@@ -92,6 +92,9 @@ export const ERROR_CODES = [
   // through - server-unavailable, while the service answered and did not accept - server-refused (with the
   // status and its own reason). The advice to the interface differs: "retry" versus "investigate".
   "server-refused",
+  // THE TRANSACTION WAS SENT BUT THE RECEIPT DOES NOT PROVE AN ESCROW: no receipt yet, no expected OrderCreated,
+  // or a receipt from another factory. The tx hash is the handle for a retry read; nothing was saved as funded.
+  "funding-pending",
   // A TIMEOUT WAITING FOR XMR TO ARRIVE - a separate code. "We did not wait long enough" is a state of the
   // money, not a breakdown and not an empty response: mixing it with other refusals, the interface could not
   // tell "not arrived yet" from "broken".
@@ -167,6 +170,7 @@ export const ERROR_META = Object.freeze({
   "storage-unavailable": { retryable: true, side: "service" },
   "server-unavailable": { retryable: true, side: "service" },
   "server-refused": { retryable: false, side: "service" },
+  "funding-pending": { retryable: true, side: "chain" },
   "xmr-timeout": { retryable: true, side: "chain" },
   "xmr-locked": { retryable: true, side: "chain" },
   "xmr-nodes-disagree": { retryable: true, side: "chain" },

package/src/config.mjs

@@ -8,7 +8,7 @@
 import * as engine from "./engine.mjs";
 import { CHECK_CODES, ERROR_CODES, STEP_CODES } from "./codes.mjs";
 import { fail } from "./errors.mjs";
-import { implementedVms, legFor } from "./legs/index.mjs";
+import { implementedVms, legFor, profileOfChain } from "./legs/index.mjs";
 import { routeProviders } from "./legs/evm.mjs";
 
 // TOKENS ARE TAKEN BY AN ENGINE FUNCTION, NOT FROM A NETWORK FIELD: `tokensOf` returns the native coin first,
@@ -41,7 +41,10 @@ const tokensOfNetwork = (chainId) => {
 const chainConfig = (chain) => ({
   id: chain.id,
   name: chain.name,
-  vm: chain.vm || "evm",
+  vm: chain.vm || null,
+  // WHAT THIS SETTLEMENT SIDE LOOKS LIKE: address format, contract/program/UTXO and ref kind. It is metadata and
+  // does not claim a driver exists; `implementedVms` and `legFor` decide that. Finality belongs to a chain.
+  settlementProfile: profileOfChain(chain.id),
   chainId: chain.chainId,
   nativeSymbol: chain.native && chain.native.symbol ? chain.native.symbol : null,
   tokens: tokensOfNetwork(chain.chainId).map((t) => ({
@@ -108,7 +111,7 @@ export const DEFAULT_XMR_NODES = Object.freeze({
     { url: "https://mainnet.xmr.kernal.eu:18089", operator: "kernal.eu" },
   ],
   stagenet: [
-    { url: "https://xmr.arrakisswap.trade", operator: "ninseiswap" },
+    { url: "https://xmr-stagenet.ninsei.finance", operator: "Ninsei" },
     { url: "https://stagenet.xmr.kernal.eu:38089", operator: "kernal.eu" },
   ],
 });

package/src/decline.mjs

@@ -41,7 +41,12 @@ const hexOf = (bytes) => {
   return out;
 };
 
-/** keccak256("Declined(address)") - the first (and only) topic of a decline's log. */
+/**
+ * keccak256("Declined(address)") - topic0 of a decline's log. The escrow indexes `claimer`, so a log emitted by the
+ * current contracts also carries it in topic1; the event signature (and therefore topic0) does not change. Logs from
+ * escrows deployed before the indexing carry the claimer in data instead, which is why this module matches only
+ * topic0 and does not assume a claimer position.
+ */
 export const DECLINED_TOPIC0 = hexOf(keccak256(DECLINE_EVENT_SIGNATURE()));
 
 // THE NODE'S OWN TWO FIELDS for a declined swap: `{ status: "declined", code: "compliance" }`. The code is the

package/src/feeEstimate.mjs

@@ -13,13 +13,16 @@ const DEFAULT_TIMEOUT_MS = 8000;
 
 const text = (value) => (typeof value === "string" ? value.trim() : "");
 
-/** A per-KB price -> the fee for a transaction of `bytes`, rounded UP: one unit short is still short. */
-export function feeForBytes(feePerKB, bytes) {
-  let perKB;
+/**
+ * A PER-BYTE price -> the fee for a transaction of `bytes`/weight. Monero's `get_fee_estimate` returns `fee` and
+ * `fees` in atomic units per byte; dividing by 1024 made every estimate 1024 times too low.
+ */
+export function feeForBytes(feePerByte, bytes) {
+  let perByte;
   let size;
-  try { perKB = BigInt(feePerKB); size = BigInt(bytes); } catch { throw new RangeError("feeForBytes: whole numbers only"); }
-  if (perKB < 0n || size < 0n) throw new RangeError("feeForBytes: negative input");
-  return ((perKB * size + 1023n) / 1024n).toString();
+  try { perByte = BigInt(feePerByte); size = BigInt(bytes); } catch { throw new RangeError("feeForBytes: whole numbers only"); }
+  if (perByte < 0n || size < 0n) throw new RangeError("feeForBytes: negative input");
+  return (perByte * size).toString();
 }
 
 const atomicField = (source, ...names) => {
@@ -34,8 +37,9 @@ const atomicField = (source, ...names) => {
 /**
  * ASK A NODE WHAT A TRANSACTION WILL COST.
  *
- * The answer is a price per kilobyte (and the median, and the daemon's own priority list). The exact sum needs the
- * assembled transaction; `feeForBytes` is the arithmetic that gets there. Never throws - a refusal names the problem.
+ * The answer is a price per byte (and the daemon's own priority list, and its quantization mask). The exact sum
+ * needs the assembled transaction; `feeForBytes` is the arithmetic that gets there. Never throws - a refusal names
+ * the problem.
  */
 export async function moneroFeeEstimate({ url, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
   // TRAILING SLASHES WITHOUT A REGEX: a pattern anchored on a run of slashes is flagged as a slow expression on
@@ -65,9 +69,12 @@ export async function moneroFeeEstimate({ url, fetchImpl = globalThis.fetch, tim
   try { body = await response.json(); } catch { return { ok: false, why: "not-json" }; }
   if (!body || body.error) return { ok: false, why: "rpc", rpc: body && body.error ? body.error.code ?? null : null };
   const result = body.result || {};
-  const feePerKB = atomicField(result, "fee_per_kb", "feePerKB");
-  const medianFeePerKB = atomicField(result, "median_fee_per_kb", "medianFeePerKB");
-  const list = result.fees ?? result.feesPerKB ?? null;
+  // THE DAEMON'S OWN UNITS. `fee` and each entry of `fees` are atomic units PER BYTE; `quantization_mask` is the
+  // unit the final fee is rounded to. `fee_per_kb` was never sent, so the old read found nothing on a real node and
+  // the old fallback then divided per-byte values by 1024.
+  const feePerByte = atomicField(result, "fee", "feePerByte");
+  const quantizationMask = atomicField(result, "quantization_mask", "quantizationMask");
+  const list = result.fees ?? result.feesPerByte ?? null;
   let perPriority = null;
   if (Array.isArray(list)) {
     perPriority = [];
@@ -75,6 +82,6 @@ export async function moneroFeeEstimate({ url, fetchImpl = globalThis.fetch, tim
       try { perPriority.push(BigInt(value).toString()); } catch { perPriority = null; break; }
     }
   }
-  if (feePerKB === null && medianFeePerKB === null && !perPriority) return { ok: false, why: "no-estimate" };
-  return { ok: true, url: base, feePerKB, medianFeePerKB, perPriority };
+  if (feePerByte === null && !perPriority) return { ok: false, why: "no-estimate" };
+  return { ok: true, url: base, feePerByte, perPriority, quantizationMask };
 }

package/src/index.mjs

@@ -198,10 +198,11 @@ export function createNinsei(options) {
   // THE STORAGE THE INTERFACE BROUGHT BECOMES THE CORE'S STORAGE: unfinished swaps and the agent session live
   // where the interface decided (browser storage, memory, a server). Without the option the core takes its
   // default: web storage if it is present in the environment, otherwise memory.
-  if (o.storage) {
-    engine.store.setStorage(o.storage);
-    engine.auth.setSessionStore(o.storage);
-  }
+  // ONE CLIENT, ONE STORE. A second client with another adapter used to replace the module-wide store, so the
+  // first client listed the second's swaps and could delete them. Even a client that brought no adapter binds the
+  // current one, so a later explicit store cannot take it over.
+  engine.store.bindStorage(o.storage || engine.store.storage());
+  if (o.storage) engine.auth.setSessionStore(o.storage);
   const http = createHttp({ apiBase: config.apiBase, fetchImpl: o.fetch, timeoutMs: config.limits.httpTimeoutMs });
   // THE CHAIN READ AND THE ALLOW-LIST GO INTO THE QUOTE CHECK: without the read the signature certifies itself,
   // so the same evmCall seam the lock and the actions use is handed to the quotes too.
@@ -269,6 +270,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/legs/index.mjs

@@ -10,6 +10,8 @@
 // What must not be in a driver: no user strings, no DOM. A driver is chain reads and writes plus knowing what the
 // network is measured in for this VM.
 import * as evm from "./evm.mjs";
+export { profileOf, VM_PROFILES } from "./profiles.mjs";
+import { profileOf } from "./profiles.mjs";
 
 export const LEGS = { evm };
 
@@ -37,6 +39,12 @@ export const vmOfChain = (chainId) => {
   return chain && chain.vm ? chain.vm : null;
 };
 
+/** The VM profile for a network, or null when the network or the profile is unknown. */
+export const profileOfChain = (chainId) => {
+  const vm = vmOfChain(chainId);
+  return vm ? profileOf(vm) : null;
+};
+
 /**
  * The leg driver for a network. A network without a driver is a NAMED refusal: you can see which vm is not
  * supported and which are. This is exactly the rule "no network is silently assumed to be EVM".

package/src/legs/profiles.mjs

@@ -0,0 +1,51 @@
+// WHAT A SETTLEMENT SIDE LOOKS LIKE, WITHOUT ASSERTING THAT A DRIVER EXISTS.
+//
+// The profile is metadata, not an implementation. It tells the SDK and the interface which address and transaction
+// shapes a VM uses, and whether settlement is a contract, a program or a UTXO script. The driver registry
+// (./index.mjs) stays the source of truth for what is RUNNABLE today.
+//
+// Bitcoin is listed because the planned order is Tron, Solana, then Bitcoin; a UTXO settlement side is a
+// script/HTLC, not an account with an escrow contract. A profile is not a promise that the chain is selectable:
+// `escrow: null` and the driver registry decide that. Finality is not here: it is a chain policy, not a VM shape,
+// and a generic "12 confirmations" is wrong for an L2. Add it to the chain that first needs it.
+export const VM_PROFILES = Object.freeze({
+  // EVM: 20-byte hex addresses, a contract escrow, a transaction hash.
+  evm: Object.freeze({
+    vm: "evm",
+    addressFormat: "hex-20",
+    settlementKind: "contract",
+    refKind: "address",
+    txRef: "hash",
+  }),
+  // TVM: base58check addresses on the wire (with a 0x41 hex form internally), a contract escrow and energy/bandwidth
+  // instead of gas.
+  tron: Object.freeze({
+    vm: "tron",
+    addressFormat: "base58check",
+    settlementKind: "contract",
+    refKind: "address",
+    txRef: "hash",
+  }),
+  // SVM: base58 addresses, a program with PDA accounts, a transaction signature.
+  solana: Object.freeze({
+    vm: "solana",
+    addressFormat: "base58",
+    settlementKind: "program",
+    refKind: "pda",
+    txRef: "signature",
+  }),
+  // UTXO: no account and no escrow contract. Settlement is an HTLC/adaptor-script output, addressed by a script
+  // or an address, and identified by a txid. A future Bitcoin-family chain uses the same shape with its own
+  // network parameters. Taproot outputs (the likely shape of an adaptor-signature leg) are bech32m (BIP350), so
+  // that format is named here next to the legacy bech32 (v0) and base58check forms.
+  bitcoin: Object.freeze({
+    vm: "bitcoin",
+    addressFormat: "base58check-or-bech32-or-bech32m",
+    settlementKind: "utxo-script",
+    refKind: "script",
+    txRef: "txid",
+  }),
+});
+
+/** The profile for a VM, or null. An unknown VM is never silently treated as EVM. */
+export const profileOf = (vm) => VM_PROFILES[vm] || null;