@ninsei-labs/sdk 0.42.0 → 0.43.1

package/CHANGELOG.md

@@ -1,3 +1,70 @@
+## 0.43.1 — 2026-10-12
+
+THE DECLINE, THE REFUND AND THE MAKER'S RECLAIM EACH CARRY THEIR OWN STATE, AND THE TERMINAL CHECK READS THE
+DECLARATIONS RATHER THAN ONLY THE MAP. A maker's decline is a terminal state of its own, a refund reports
+`refunded_eth` instead of the `closed` fallback, the maker's reclaimed XMR is the phase code `xmr_reclaimed`, and
+`xmr_returned` - a terminal no code path could ever produce - is gone from the public union and from the table.
+Five comments that claimed this package keeps a second, byte-identical copy of the levels walk and of the EIP-712
+spec are corrected: it keeps no such copy.
+
+- A MAKER'S DECLINE IS A TERMINAL STATE OF ITS OWN (`declined`). The escrow's `Declined` event and the node's
+  `declined` + `compliance` status are two independent sources of the same state and either one is enough; the
+  wait for XMR stops at once, the state is written down, and it carries no reason, category or provider at any
+  depth. It is told apart from an ordinary refund, which keeps `refunded_eth`.
+- A REFUND REPORTS ITS OWN STATE, NOT THE FALLBACK. The terminal map in src/swaps.mjs was keyed by names no code
+  path writes (`refunded` for a refund the engine writes as `kind: "refund_eth"`), so every refund missed its key
+  and told the app `closed` about an order whose ETH was already back in the wallet. The map is now keyed by the
+  kinds the engine and this package really write - `success`, `refund_eth`, `declined` - exhaustively, and a kind
+  nobody knows still comes out as the declared fallback `closed` (`closed` is a fallback, not a key).
+- THE MAKER'S RECLAIMED XMR IS A PHASE CODE OF ITS OWN: `state.phase === "xmr_reclaimed"` (engine/core/swap.js
+  `derive`). It was visible only as a label - the shared `refund_available`, which the maker who never locked sets
+  too - so an interface had to compare `state.phaseLabel` to tell the two apart. The code is what it branches on
+  now; the maker who never locked keeps `refund_available`.
+- `xmr_returned` IS REMOVED from the public `TerminalCode` union (index.d.ts), from the engine's `TERMINAL` table
+  and from the code table in src/codes.mjs, with the reason named where each stood. No code path anywhere wrote
+  it, and a declared terminal nothing can produce reads as coverage.
+- BREAKING FOR A TYPESCRIPT CONSUMER, ON PURPOSE: a consumer that branched on `xmr_returned` no longer compiles,
+  because the member is gone from the union. That is the intent, not a regression - no settlement with that kind
+  exists, so no value could ever reach that branch.
+- WHAT A CONSUMER SEES INSTEAD: a swap whose XMR the maker has taken back carries the phase code
+  `xmr_reclaimed` with `terminal` still `null` (and not settled) - the depositor's ETH is still in the escrow, so
+  the swap has NOT ended; it ends later as `refunded_eth` when the ETH goes back to the wallet.
+- THE TERMINAL CHECK READS THE DECLARATIONS, NOT ONLY THE MAP: `node tools/check.mjs --only=terminal` compared the
+  map against the writers, which is exactly how a dead entry outside the map survived. It now reads the engine's
+  own `TERMINAL` table and the public `TerminalCode` union as well and asserts BOTH directions against the writers
+  - every kind a writer produces has an entry, and every declared terminal is one a writer can produce (or the
+  fallback an unknown kind comes out as). A declared-but-unwritable terminal is RED naming the declaration it came
+  from. The check also drives the reclaim to its own phase and holds `terminal: null` there.
+- `tools/check-terminal-teeth.mjs` exercises it with EIGHT breaking runs: the dead key put back, the refund's code
+  sent to another declared code, a key nothing writes, the decline's own key dropped, a rename in the engine's
+  mirror, a terminal with no writer in the engine's table, the same in the public union, and the reclaim's phase
+  renamed - each RED, naming its own reason, every file restored byte for byte with sha256 compared.
+- COMMENT-ONLY CORRECTIONS IN FIVE FILES (index.d.ts, src/index.mjs, src/levelsWalkSpec.mjs, src/quoteEip712.mjs,
+  src/quoteEip712Spec.mjs): their headers claimed this package exists as two byte-identical copies of the levels
+  walk and of the EIP-712 spec, pinned by sha256. Neither is true - only the package has the implementation, a
+  node runs it from the entry and is bound to it by the guard on its imports, and the behaviour is pinned by the
+  vectors. No assertion, no line of logic, no signature and no export name changed.
+
+Checks: `node tools/check.mjs` - all 21 green; `node tools/check-terminal-teeth.mjs` (8 breaking runs),
+`node tools/check-decline-teeth.mjs` (5), `node tools/check-types-teeth.mjs` (4), `node tools/check-refusals-teeth.mjs`
+(5), `node tools/npm-tag.test.mjs` (28 cases) and `node tools/sweep-refusal.test.mjs` (11 checks) are green too.
+
+## 0.42.1 — 2026-10-12
+
+THE BID SIDE OF THE QUOTE WALK ROUNDED THE WRONG WAY. The specification fixes a rounding DIRECTION per side, and
+the walk rounded both sides alike: a bid price came out up to 3 wei high and disagreed with the reference at a
+level boundary.
+
+- Per-level rounding follows the side now: a level's cost rounds up on the ask side, where the user pays, and down
+  on the bid side, where the user is paid; the XMR amount a budget yields at a level rounds up on the bid side.
+- The level-fits test is asymmetric: a level is taken whole when `remaining >= full` on the ask side and when
+  `remaining > full` on the bid side.
+- This removes a systematic 1-to-3-wei over-charge on bid prices and the disagreement with the reference at level
+  boundaries.
+
+Checks: `node tools/check.mjs` - all 19 green; `node tools/sync-version.mjs`, `node tools/npm-tag.test.mjs`, the two
+teeth runs and `tools/sweep-refusal.test.mjs` are green too.
+
 ## 0.42.0 — 2026-10-12
 
 EVERY ENTRY THIS PACKAGE PUBLISHES CARRIES ITS OWN DECLARATIONS, AND THE SWEEP PAGE'S TWO PRIMITIVES ARE ON

package/README.md

@@ -20,7 +20,7 @@ machine). The wallet arrives as an EIP-1193 provider, storage as an adapter, and
 | `quotes.firm` | answers `not-implemented` (stage 2: signing with a key and the order protocol) |
 | `swaps.list` / `swaps.get` | read state from storage (and after a page reload) |
 | `swaps.start` | holds the order: guards → recovery file and the person's confirmation → order → locking funds → **recording with us and watching the Monero address**; returns the named state `step: "xmr-incoming"` |
-| `swaps.watch` | waits for XMR to arrive at the joint address with the same request as the page (`GET /swaps/{id}`): arrived — returns the fact (amount, confirmations, txid); did not wait — a refusal with the code `xmr-timeout`; already on the address but barred by `unlock_time` — a refusal with the code `xmr-locked` (the boundary is in `params.until`), and NO ready mark; with expectations and a wallet, places the ready mark after the arrival |
+| `swaps.watch` | waits for XMR to arrive at the joint address with the same request as the page (`GET /swaps/{id}`): arrived — returns the fact (amount, confirmations, txid); did not wait — a refusal with the code `xmr-timeout`; already on the address but barred by `unlock_time` — a refusal with the code `xmr-locked` (the boundary is in `params.until`), and NO ready mark; the maker DECLINED the order — returns `SwapDeclinedWatch` (`declined: true`, `terminal: "declined"`, the node's own `code`), with every action off; with expectations and a wallet, places the ready mark after the arrival |
 | `wallet.balances` | works: the native coin and tokens, in minimal units |
 
 What is not ready names itself with the code `not-implemented` with the fields `surface` and `stage`: an empty
@@ -74,7 +74,23 @@ user-facing string.
 | `claimed` | the maker took the ETH |
 | `swept` | the XMR has been sent to the recipient's address |
 
-Terminal states (`state.terminal`): `success`, `refunded_eth`, `xmr_returned`, `closed`.
+Terminal states (`state.terminal`): `success`, `refunded_eth`, `closed`, `declined`.
+
+`xmr_returned` WAS HERE AND IS GONE, AND SO IS THE STATE IT NAMED AS A TERMINAL. When the depositor does not place
+the ready mark in time the maker takes the XMR back — and the swap does NOT end there: the depositor's ETH is still
+in the escrow, so it is a PHASE of a live swap, not a terminal. `state.phase` is then `xmr_reclaimed` (the code an
+interface branches on, while `state.terminal` stays `null`), and the swap ends later as `refunded_eth` when the ETH
+goes back. The code exists because that phase used to be the shared `refund_available`, which the "maker never
+locked the XMR" situation sets too: the two could only be told apart by comparing a label.
+
+`declined` — THE MAKER REFUSED A FUNDED ORDER (issue #40). The escrow sets `refunded` and emits
+`Declined(claimer)`, so `status()` alone reads it exactly like any other refund; the SDK tells the two apart by
+that EVENT (the chain, read through `evmLogs`) or by the node's status `declined` with the code `compliance` (the
+wire). Either source stops the wait for XMR at once and ends the swap as `declined` with EVERY action off: the
+whole balance, the fee included, is already back in the wallet and no half was revealed, so there is nothing to
+recover — no recovery file is needed and no manual refund is offered. NO reason, category or provider travels
+with it (the node returns only `compliance`, on purpose), and the neutral sentence a person reads is the
+interface's: this package holds no user-facing string.
 
 ### Checks (`preflight().checks[].code`)
 

package/engine/core/swap.js

@@ -41,10 +41,13 @@ export const STEP_LABELS = [
   ["swept", "Sent to your address"],
 ];
 
+// THE STATES A SWAP ENDS IN. `xmr_returned` STOOD HERE AND IS GONE ON PURPOSE: it was declared with a phase and a
+// label and NO code path anywhere wrote it. The maker taking the XMR back does not END a swap - the depositor's ETH
+// is still in the escrow - so that situation is a PHASE of a live swap (`xmr_reclaimed`, in derive below), and a
+// terminal nothing can produce is worse than no terminal at all: a reader takes the declaration for coverage.
 export const TERMINAL = {
   success: { phase: "success", label: "XMR delivered" },
   refunded_eth: { phase: "refunded_eth", label: "ETH refunded" },
-  xmr_returned: { phase: "xmr_returned", label: "Swap cancelled, funds returned" },
 };
 
 export function createSwap(input) {
@@ -592,7 +595,12 @@ export function derive(swap, now = nowReal()) {
     phase = "maker_locking";
     phaseLabel = "Maker is locking XMR";
   } else if (xmrReclaimed) {
-    phase = "refund_available";
+    // THE MAKER TOOK THE XMR BACK - A PHASE OF ITS OWN, NOT A TERMINAL AND NOT A STEP. The depositor's ETH is
+    // still in the escrow, so the swap is LIVE (`terminal` stays empty) and ends later as `refunded_eth`; and the
+    // ordered stepper has no passage for a deal that is taken back. It used to be the shared `refund_available`,
+    // which the "maker never locked" situation sets too, so the two could only be told apart by reading the label -
+    // `xmr_reclaimed` is the code an interface branches on.
+    phase = "xmr_reclaimed";
     phaseLabel = "XMR returned to the maker";
     refundAfterSim = makerReclaimAt;
     can.refund = true;

package/index.d.ts

@@ -15,6 +15,25 @@
 // Naming language: the values are data. `step` and `code` are stable strings from the tables below; they are
 // translated, shown and coloured as one sees fit. They change only with a package version bump (see CHANGELOG).
 
+/** One log as a node answers it: an emitter, its topics and its data. Only what the decline is read from is named. */
+export interface EvmLog {
+  readonly address?: string;
+  readonly topics?: readonly string[];
+  readonly data?: string;
+  readonly blockNumber?: string;
+  readonly transactionHash?: string;
+}
+
+/** The log read a caller may bring: the seam the decline is read through. */
+export type EvmLogReader = (
+  request: {
+    readonly address: string;
+    readonly topics?: readonly string[];
+    readonly fromBlock?: string | number;
+    readonly toBlock?: string | number;
+  },
+) => Promise<readonly EvmLog[]>;
+
 export interface NinseiOptions {
   /** The service's HTTP API base. Default is "/api" (the interface proxies it to our server). */
   apiBase?: string;
@@ -80,6 +99,15 @@ export interface NinseiOptions {
    * matched against the interface's known builds. Same rule as evmCall: a read, not a node substitution.
    */
   evmCode?: (request: { readonly address: string }) => Promise<string>;
+  /**
+   * READING THE ESCROW'S LOGS FROM OUTSIDE (issue #40): `({ address, topics, fromBlock, toBlock }) -> logs`, for
+   * the MAKER'S DECLINE. The escrow emits `Declined(claimer)` and keeps NO getter that names it, while `status()`
+   * reads a decline and an ordinary refund the same way - so the event is the only on-chain fact that tells them
+   * apart. By default the logs are read through the page's wallet, the same provider `evmCall` uses, so the wallet
+   * that reads is the wallet that signs. Same rule as `evmCall`: a READ, not a node substitution - the address is
+   * the order's escrow and the topic is the package's own.
+   */
+  evmLogs?: EvmLogReader;
   /**
    * THE INTERFACE'S OWN ADMISSION LIST - policy, not proof. The chain (maker registry, providerOf, taken from the
    * quote) proves whose key signed; this says whom THIS interface trades with at all. An array of provider
@@ -500,7 +528,8 @@ export interface QuoteOffer {
  * The providers already name them in their own tables (`COW_REFUSAL_CODES` and its three siblings), and the
  * battery proves each of those is reachable; what was missing was the TYPE, so an interface could enumerate
  * them instead of meeting a string it cannot switch on. `broken` is shared by all four: it is the code for a
- * case a provider could not classify.
+ * case a provider could not classify. `RouteRefusalTables` below declares what those tables ARE - each of them a
+ * `readonly RouteRefusalCode[]` - so the union is the tables' TYPE and not a comment standing beside them.
  *
  * These are OUR codes, and they are what a person's message should be phrased from. A provider's OWN reason
  * stays opaque on purpose (`QuoteRefusal.why`): that is data the provider sent, not a name of ours, so it is
@@ -546,6 +575,28 @@ export type RouteRefusalCode =
   // shared
   | "broken";
 
+/**
+ * WHAT THE FOUR REFUSAL TABLES *ARE*. Each route provider names its own refusals in one table - `COW_REFUSAL_CODES`
+ * (src/legs/cow.mjs), `KYBER_REFUSAL_CODES` (src/legs/kyber.mjs), `UNISWAPX_REFUSAL_CODES` (src/legs/uniswapx.mjs) and
+ * `UNISWAPRELAY_REFUSAL_CODES` (src/legs/uniswaprelay.mjs) - and every one of those tables is a
+ * `readonly RouteRefusalCode[]`. The dependency runs ONE WAY on purpose: a table answers to the union (a code that is
+ * not declared above cannot enter a table), while the union answers to no single table, so the same vocabulary is
+ * met in four modules.
+ *
+ * THEY ARE NOT ON THIS ENTRY'S SURFACE, and this is deliberately NOT a value: the package re-exports no provider and
+ * no table (src/index.mjs), the tables travel in the shipped source (`files` in package.json) and they are the
+ * VOCABULARY, not an API. A `declare const` here that the runtime does not export would be a lie, and the `surface`
+ * check refuses exactly that - so the tables are declared as their TYPE. That is what keeps the union from being a
+ * comment beside the tables: this declaration says what they are, and the `refusals` check says the same thing from
+ * the other side - a table declared here as a plain `readonly string[]` is a named problem there.
+ */
+export interface RouteRefusalTables {
+  readonly COW_REFUSAL_CODES: readonly RouteRefusalCode[];
+  readonly KYBER_REFUSAL_CODES: readonly RouteRefusalCode[];
+  readonly UNISWAPX_REFUSAL_CODES: readonly RouteRefusalCode[];
+  readonly UNISWAPRELAY_REFUSAL_CODES: readonly RouteRefusalCode[];
+}
+
 export interface QuoteRefusal {
   readonly providerId: string;
   readonly displayName: string | null;
@@ -686,8 +737,12 @@ export interface SwapsApi {
    * IF `expect` AND `wallet` ARE PASSED, then after the arrival the ready mark (actions.markReady) is called with
    * THESE expectations: the slot check against the chain stands in it before the signature. Without them the step
    * names the next one (`next: "mark-ready"`) and signs nothing.
+   * THE MAKER DECLINED - THE WAIT STOPS AT ONCE (issue #40): the escrow's `Declined` event and the service's
+   * `declined` + `compliance` status are BOTH asked on every tick, and either one ends the wait with
+   * `SwapDeclinedWatch` instead of running to `xmr-timeout` about an order whose ETH is already back. Nothing is
+   * 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>;
+  watch(request: SwapWatchRequest): Promise<SwapWatch | SwapDeclinedWatch>;
   /**
    * 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
@@ -962,6 +1017,33 @@ export interface SwapWatchRequest {
   readonly readyBySec?: number;
 }
 
+/**
+ * THE WATCH'S ANSWER WHEN THE MAKER DECLINED (issue #40). There is no arrival to wait for, so `seen` is false and
+ * there is no `marked`, no `next` and no `txids` - and NO field naming a reason, a category or a provider, because
+ * the node names none. `code` is the node's own single token, unchanged; `terminal` is the state the interface
+ * draws its own neutral sentence from; `source` says WHICH reader saw it (provenance, not a reason).
+ */
+export interface SwapDeclinedWatch {
+  readonly id: string;
+  /** The escrow the decline was read on, or null when the record did not know it. */
+  readonly escrow: string | null;
+  readonly address: string | null;
+  /** Never true here: a decline is not an arrival. */
+  readonly seen: false;
+  readonly declined: true;
+  readonly terminal: "declined";
+  readonly code: "compliance";
+  /** `event` - the escrow's `Declined` log; `status` - the service's status; `record` - already written down. */
+  readonly source: "event" | "status" | "record";
+  readonly at: number;
+  readonly waitedMs: number;
+  /**
+   * WHAT THE CHAIN READ DID. `checked: false` means the escrow's event could not be read at all (no reader, an
+   * unreachable node) - which is NOT "the escrow declined nothing" - and `error` carries the refusal's own code.
+   */
+  readonly chain: { readonly checked: boolean; readonly error: string | null };
+}
+
 /** THE OUTCOME OF THE WATCH: the arrival is seen as a FACT, not assumed. */
 export interface SwapWatch {
   readonly seen: true;
@@ -1082,7 +1164,12 @@ export interface SwapState {
   readonly simulated: { readonly evm: boolean; readonly xmr: boolean };
   /** The refusal reason, if any: a code and params, no text. */
   readonly error?: { readonly code: ErrorCode; readonly params?: Readonly<Record<string, unknown>> };
-  /** The terminal state, if the swap has ended. */
+  /**
+   * The terminal state, if the swap has ended. `declined` (issue #40) is the maker's refusal of a funded order:
+   * the ETH, the fee included, is already back in the wallet, every flag in `actions` is OFF, and there is nothing
+   * to recover. The interface owes the person a NEUTRAL sentence and no reason, category or provider - the node
+   * names none, and the package forwards none.
+   */
   readonly terminal: TerminalCode | null;
   /**
    * WHEN THE RECORD WAS CREATED (the record's own `createdAt`, an ISO string). null - an old record without
@@ -1091,7 +1178,12 @@ export interface SwapState {
   readonly createdAt: string | null;
   /** WHO GAVE THE PRICE. Either field may be absent: an old record or a swap without a provider. */
   readonly maker: { readonly id: string | null; readonly name: string | null };
-  /** The engine's phase code and its human name: the list shows the name. */
+  /**
+   * The engine's phase code and its human name: the list shows the name, the CODE is what an interface branches on.
+   * `xmr_reclaimed` is the maker taking the XMR back before the ready mark - a LIVE state, not a terminal: the
+   * depositor's ETH is still in the escrow, `terminal` stays null and the swap ends later as `refunded_eth`. It is
+   * told apart by that code from the other situation that opens a refund, the maker who never locked the XMR.
+   */
   readonly phase: string | null;
   readonly phaseLabel: string | null;
   /** The swap has a settlement record: the list splits live from settled by THIS flag, not by the phase's text. */
@@ -1118,7 +1210,17 @@ export type StepCode =
   | "claimed"
   | "swept";
 
-export type TerminalCode = "success" | "refunded_eth" | "xmr_returned" | "closed";
+/**
+ * THE ORDER'S TERMINAL STATE. `declined` is THE MAKER'S REFUSAL OF A FUNDED ORDER (issue #40): the whole balance,
+ * the fee included, is already back in the depositor's wallet and NO half was revealed, so there is nothing to
+ * recover and nothing left to do. It is deliberately NOT `refunded_eth`: that one is the depositor taking the ETH
+ * back, and it DOES reveal the depositor's half. The words a person reads are the interface's, not the package's.
+ *
+ * `xmr_returned` WAS A MEMBER AND IS GONE: it named the maker taking the XMR back, which does NOT end a swap - the
+ * depositor's ETH is still in the escrow - so it is a PHASE of a live swap (`SwapState.phase`, the code
+ * `xmr_reclaimed`), never a terminal. A member with no writer reads as coverage.
+ */
+export type TerminalCode = "success" | "refunded_eth" | "closed" | "declined";
 
 // --- The XMR withdrawal (the sweep page) --------------------------------------------------------
 
@@ -1277,6 +1379,41 @@ export interface OrderApi {
    * terms hash the recovery file is bound to. The screen uses them to say whether the person is in the dead zone.
    */
   deadlines(escrow: string): Promise<OrderDeadlines>;
+  /**
+   * THE MAKER'S DECLINE, READ FROM THE ESCROW (issue #40): the `Declined` event THE ESCROW EMITTED. It is a
+   * separate read because `status()` cannot answer it - the escrow has no `declined()` getter, and a decline sets
+   * the same `refunded` flag an ordinary refund does. Read through the same seam as the state (`evmLogs`, or the
+   * `logs` argument), so the wallet that reads is the wallet that signs.
+   *
+   * THE ANSWER CARRIES THE STATE AND NOTHING ELSE: no reason, no category, no provider. `checked: false` says the
+   * chain was NOT read, which is not the same as "the escrow did not decline".
+   */
+  decline(escrow: string, deps?: OrderDeclineDeps): Promise<OrderDecline>;
+}
+
+/**
+ * WHAT IS KNOWN ABOUT A DECLINE: exactly these fields, and the SHORTNESS IS THE POINT. Anything else would be a
+ * reason, a category or a provider, and the node names none of those on purpose.
+ */
+export interface OrderDecline {
+  readonly declined: boolean;
+  /** The state the interface draws from (`declined`), or null when this is not a decline. */
+  readonly terminal: "declined" | null;
+  /** The node's own single token, UNCHANGED (`compliance`), or null. It is a token, not a reason. */
+  readonly code: "compliance" | null;
+  /** `event` - the escrow's log was read; `status` - the node's status was read; null - neither. */
+  readonly source: "event" | "status" | null;
+  /** When it was seen (epoch ms), or null. */
+  readonly at: number | null;
+  /** Whether the reading happened at all: `false` is "not measured", NOT "no decline". */
+  readonly checked: boolean;
+}
+
+/** The seams of the decline read: the log reader and where the scan starts. */
+export interface OrderDeclineDeps {
+  readonly logs?: EvmLogReader;
+  /** The first block to scan (the escrow's birth height when it is known). Default: the whole chain. */
+  readonly fromBlock?: string | number;
 }
 
 /** THE ORDER STATE, READ FROM THE CHAIN (escrow status()): three flags and the remainder. */
@@ -1439,7 +1576,7 @@ export declare function createNinsei(options: NinseiOptions): Ninsei;
 /**
  * THE LEVEL WALK. A maker publishes a LEVEL SET - chunks of volume with their own prices - and both the node and
  * the client compute a firm price by WALKING it, before anything is signed. `levelsWalkSpec.mjs` is the ONE
- * implementation, a byte-identical twin of the node's copy (`rfq/lib/levelsWalkSpec.mjs`), and it is exported so a
+ * implementation, taken from the package entry by the node rather than copied, and it is exported so a
  * consumer reaches the same price: the maker's set in, the walk's answer out.
  *
  * NUMBERS ARE INTEGERS, BigInt ONLY. XMR is in atomic units (1 XMR = 1e12); a price is in the asset's atomic units

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.42.0",
+  "version": "0.43.1",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -20,6 +20,12 @@
     "check:secrets": "node tools/check.mjs --only=secrets",
     "check:types": "node tools/check.mjs --only=types",
     "check:types-teeth": "node tools/check-types-teeth.mjs",
+    "check:refusals": "node tools/check.mjs --only=refusals",
+    "check:refusals-teeth": "node tools/check-refusals-teeth.mjs",
+    "check:decline": "node tools/check.mjs --only=decline",
+    "check:decline-teeth": "node tools/check-decline-teeth.mjs",
+    "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", "sync:version": "node tools/sync-version.mjs"
   },
   "types": "./index.d.ts",

package/src/codes.mjs

@@ -13,7 +13,13 @@ export const STEP_CODES = [
   "swept",
 ];
 
-export const TERMINAL_CODES = ["success", "refunded_eth", "xmr_returned", "closed"];
+// `declined` IS A TERMINAL STATE OF ITS OWN (issue #40): the maker refused a funded order, so the whole balance -
+// the fee included - is already back in the depositor's wallet and NO half was revealed. It is told apart from
+// `refunded_eth`, which is the depositor taking the ETH back and DOES reveal a half (src/decline.mjs).
+// `xmr_returned` WAS DECLARED HERE AND IS GONE (it had no writer anywhere): the maker's reclaim of the XMR does
+// NOT end a swap - the depositor's ETH is still in the escrow - so it is a PHASE of a live swap (`xmr_reclaimed`,
+// engine/core/swap.js), never a terminal state. A declared terminal nothing can produce reads as coverage.
+export const TERMINAL_CODES = ["success", "refunded_eth", "closed", "declined"];
 
 export const CHECK_CODES = [
   "balance",

package/src/decline.mjs

@@ -0,0 +1,178 @@
+// THE MAKER'S DECLINE: A STATE OF ITS OWN, TOLD APART FROM AN ORDINARY REFUND.
+//
+// WHAT HAPPENS ON THE CHAIN. A maker who refuses a funded purchase - after screening the deposited ETH, say -
+// calls `decline()` on the escrow. The contract sets `refunded`, emits `Declined(claimer)` and sends the whole
+// balance, the fee included, back to the locker. NO half is revealed: there is nothing to recover, and nobody
+// assembles a Monero key from a declined order.
+//
+// WHY `status()` IS NOT ENOUGH TO SEE IT. `escrow.status()` answers four words - funded, claimed, refunded,
+// balance - and a decline reads exactly like an ordinary refund there: `refunded` is set and the money is back.
+// The two are not the same event, though. An ordinary refund is the depositor (or whoever holds their half)
+// taking the ETH back when the maker did not claim; it REVEALS THE DEPOSITOR'S HALF (`HalfRevealed(half, false)`)
+// so the maker can still take their XMR. A decline is the MAKER closing the order in the depositor's favour and
+// reveals nothing. On screen the two want different things said and different buttons hidden, so the SDK tells
+// them apart instead of reporting "refunded" for both.
+//
+// THE TWO SOURCES, AND EITHER ONE IS ENOUGH:
+//   1) THE ESCROW'S `Declined` EVENT (the chain) - `declinedFromLogs`. The escrow has no getter for a decline
+//      (there is no `declined()` view), so the event is the on-chain fact that names it; it is read through the
+//      same read seam as every other chain read - an `eth_getLogs` over the escrow's address.
+//   2) THE NODE'S SWAP STATUS `declined` WITH THE CODE `compliance` (the wire) - `declinedFromStatus`. Those ARE
+//      the two fields the node returns and nothing else, so BOTH are required: the bare word without its code is
+//      not the state the node names, and guessing at it would put a category on a refusal that carries none.
+//
+// WHAT IS DELIBERATELY NOT CARRIED: a reason, a category, a provider. The node returns only `compliance` on
+// purpose - it does not name who declined or why - so the SDK reports the state, the node's own single token and
+// which reader saw it, AND NOTHING ELSE (see DECLINE_FIELDS below). The sentence a person reads is the
+// interface's: this package holds no user-facing string, and a decline is no exception.
+import { SdkError } from "./errors.mjs";
+import { keccak256 } from "./primitives.mjs";
+import * as engine from "./engine.mjs";
+
+// THE EVENT, AND ONLY IT. The signature is assembled from its parts and hashed HERE, once, exactly as Solidity
+// does it: keccak256("Declined(address)"). The topic is exported so a caller filters logs with it rather than
+// deriving it a second time - a second copy of the same event would be a second truth about it.
+export const DECLINE_EVENT_NAME = "Declined";
+export const DECLINE_EVENT_SIGNATURE = () => `${DECLINE_EVENT_NAME}(${["address"].join(",")})`;
+
+const hexOf = (bytes) => {
+  let out = "0x";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+};
+
+/** keccak256("Declined(address)") - the first (and only) topic of a decline's log. */
+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
+// node's single token, deliberately opaque: it says "a screening decision was taken", not by whom or on what.
+export const DECLINED_STATUS = "declined";
+export const DECLINED_CODE = "compliance";
+
+// THE STATE'S OWN CODE - a `TerminalCode` (`index.d.ts`). The interface draws the decline screen from THIS, and
+// phrases the sentence itself; the package contributes the state and the code, not the words.
+export const DECLINED_TERMINAL = "declined";
+
+/**
+ * THE WHOLE SET OF FIELDS A DECLINE IS REPORTED WITH - and the list is short ON PURPOSE. Everything else would be
+ * a reason, a category or a provider, and the node names none of those:
+ *   `declined`  - what happened (true/false);
+ *   `terminal`  - the state the interface draws from (`declined`, or null);
+ *   `code`      - the node's own token, UNCHANGED, or null;
+ *   `source`    - which reader saw it: `event` (the escrow) or `status` (the node). PROVENANCE, NOT A REASON:
+ *                 it says where the SDK learned it, not why the maker refused;
+ *   `at`        - when it was seen (epoch ms), or null;
+ *   `checked`   - whether the chain was read at all. `false` means "not measured", which is NOT "no decline" - a
+ *                 caller that blurs the two would read a maker's refusal as an ordinary refund.
+ */
+export const DECLINE_FIELDS = ["declined", "terminal", "code", "source", "at", "checked"];
+
+// Every verdict is built through this, so no field can creep in beside the list above: the reporter is the shape.
+const verdictOf = (fields) => {
+  const out = {};
+  for (const key of DECLINE_FIELDS) out[key] = fields[key] === undefined ? null : fields[key];
+  return out;
+};
+
+/** A DECLINE, AS THE SDK REPORTS IT: the state, the node's token and where it was seen - and nothing more. */
+export const declineSeen = ({ source = null, at = null } = {}) =>
+  verdictOf({ declined: true, terminal: DECLINED_TERMINAL, code: DECLINED_CODE, source, at, checked: true });
+
+/**
+ * NO DECLINE. `checked: false` says the reading did not happen (no chain reader, no status body): the two are
+ * kept apart on purpose, because "we could not look" and "we looked and it was not a decline" are different
+ * states of knowledge, and only one of them lets a caller treat a closed escrow as an ordinary refund.
+ */
+export const declineNone = ({ source = null, at = null, checked = true } = {}) =>
+  verdictOf({ declined: false, terminal: null, code: null, source, at, checked });
+
+/**
+ * SOURCE 1 - THE ESCROW'S `Declined` EVENT. `logs` is what the log read answered: an ARRAY of log objects.
+ * Anything that is not an array is a refusal (`bad-input`), never "no decline": an unread chain must not be
+ * reported as an escrow that declined nothing.
+ *
+ * Only the FIRST TOPIC is compared (the event's own signature). A log from another address is skipped when the
+ * answer carries one and the caller named the escrow; a log without an address is still matched, because the
+ * request that produced it was filtered by address and dropping it would hide a real decline.
+ */
+export function declinedFromLogs(logs, { escrow = null, at = null } = {}) {
+  if (!Array.isArray(logs)) throw new SdkError("bad-input", { field: "logs", why: "not-array" });
+  const wanted = typeof escrow === "string" && escrow ? escrow.toLowerCase() : null;
+  for (const log of logs) {
+    if (!log || typeof log !== "object") continue;
+    if (wanted && typeof log.address === "string" && log.address && log.address.toLowerCase() !== wanted) continue;
+    const topics = Array.isArray(log.topics) ? log.topics : [];
+    if (String(topics[0] || "").toLowerCase() === DECLINED_TOPIC0) return declineSeen({ source: "event", at });
+  }
+  return declineNone({ source: "event", at });
+}
+
+/**
+ * SOURCE 2 - THE NODE'S SWAP STATUS. `{ status: "declined", code: "compliance" }`, in either of the two shapes
+ * the wire carries it in: at the top level of the answer (the swap state a backend relays) or NESTED UNDER
+ * `userStatus` (the field the maker API names it by). BOTH fields must be there and must be exactly these tokens;
+ * anything else is not the state the node names, and a partial match is NOT a decline.
+ *
+ * A body that is not an object at all answers `checked: false` - there was nothing to read, which is not the same
+ * as having read it and found no decline.
+ */
+export function declinedFromStatus(body, { at = null } = {}) {
+  if (!body || typeof body !== "object") return declineNone({ source: "status", at, checked: false });
+  for (const candidate of [body, body.userStatus]) {
+    if (!candidate || typeof candidate !== "object") continue;
+    if (String(candidate.status || "") === DECLINED_STATUS && String(candidate.code || "") === DECLINED_CODE) {
+      return declineSeen({ source: "status", at });
+    }
+  }
+  return declineNone({ source: "status", at });
+}
+
+/**
+ * BOTH SOURCES AT ONCE, AND EITHER ONE IS ENOUGH - the form the flow uses. The chain is asked first (the escrow's
+ * own event is the stronger fact) and the wire second; a source that was not read is named as such (its own
+ * verdict stays, with `source: null` when neither was read), and a body without the node's two fields does not
+ * cancel a chain answer.
+ */
+export function declineOf({ logs = undefined, status = undefined, escrow = null, at = null } = {}) {
+  const fromChain = Array.isArray(logs) ? declinedFromLogs(logs, { escrow, at }) : null;
+  if (fromChain && fromChain.declined) return fromChain;
+  const fromWire = status && typeof status === "object" ? declinedFromStatus(status, { at }) : null;
+  if (fromWire && fromWire.declined) return fromWire;
+  if (fromChain) return fromChain;                       // the chain was read: it answered "not declined"
+  if (fromWire) return fromWire;                         // only the wire was read, and it was not a decline
+  return declineNone({ checked: false, at });            // nothing was read, which is NOT "no decline"
+}
+
+/**
+ * THE DEFAULT CHAIN LOG READER: `eth_getLogs` THROUGH THE PAGE'S WALLET - the same provider the engine's
+ * `readContract` uses, so the wallet that reads is the wallet that will sign (the rule the whole chain-read seam
+ * follows). It is a READ, not a node substitution: the address is the caller's escrow and the filter is the
+ * decline's own topic.
+ *
+ * `fromBlock` is the caller's: a watch that knows the escrow's birth height scans from there instead of walking
+ * the chain's whole history. An answer that is not an array is a REFUSAL - a node that answered something else
+ * did not answer "no decline", and a caller must not read it as one.
+ */
+export async function readDeclinedLogs({ address, topics = [DECLINED_TOPIC0], fromBlock = "earliest", toBlock = "latest" } = {}) {
+  if (typeof address !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(address)) throw new SdkError("bad-input", { field: "logs.address" });
+  let provider = null;
+  try { provider = typeof engine.evm.currentProvider === "function" ? engine.evm.currentProvider() : null; } catch { provider = null; }
+  if (!provider || typeof provider.request !== "function") throw new SdkError("bad-input", { field: "evmLogs", why: "no-provider" });
+  const answer = await provider.request({ method: "eth_getLogs", params: [{ address, topics, fromBlock, toBlock }] });
+  if (!Array.isArray(answer)) throw new SdkError("server-unavailable", { step: "logs", why: "bad-response" });
+  return answer;
+}
+
+/** The log reader a call was given: the caller's seam, or the default above. */
+export const logReaderOf = (logs) => (typeof logs === "function" ? logs : readDeclinedLogs);
+
+/**
+ * A BLOCK BOUNDARY AS THE NODE WANTS IT (hex quantity), for a caller that knows where its escrow was born.
+ * A value that is not a whole, non-negative number is the fallback - the safe end of the chain, not an invented
+ * block: scanning too far is slow, scanning too little misses the event.
+ */
+export const blockBoundaryOf = (height, fallback = "earliest") => {
+  const value = Number(height);
+  if (!Number.isFinite(value) || value < 0) return fallback;
+  return "0x" + Math.trunc(value).toString(16);
+};

package/src/index.mjs

@@ -85,6 +85,12 @@ const normalizeOptions = (options) => {
   // THE CODE-READ SEAM (issue #103): ({address}) -> hex code, for the extcodehash check of the factory. Same
   // rule as evmCall - a read brought from outside, not a substitution of the chain.
   if (o.evmCode !== undefined && typeof o.evmCode !== "function") fail("bad-input", { field: "evmCode" });
+  // THE LOG-READ SEAM (issue #40): ({ address, topics, fromBlock, toBlock }) -> logs. Needed for the maker's
+  // decline, which is the escrow's `Declined` EVENT - the escrow has no getter that names it, and `status()` reads
+  // a decline and an ordinary refund the same way. By default the logs are read through the page's wallet, the
+  // same provider the chain read uses. Same rule as evmCall: a READ of the escrow's own event, not a node
+  // substitution.
+  if (o.evmLogs !== undefined && typeof o.evmLogs !== "function") fail("bad-input", { field: "evmLogs" });
   // THE INTERFACE'S ALLOW-LIST (POLICY, NOT PROOF): an array of provider addresses (or providerIds) OR a
   // predicate. It is NOT the check itself - that is `providerOf` on chain, taken from the quote - but the
   // interface's own decision about whom it trades with. A wrong shape is a typo, not a silent no-op.
@@ -149,6 +155,7 @@ const normalizeOptions = (options) => {
     addNodes: o.addNodes === undefined ? null : o.addNodes,
     evmCall: o.evmCall || null,
     evmCode: o.evmCode || null,
+    evmLogs: o.evmLogs || null,
     allowedProviders: o.allowedProviders === undefined ? null : o.allowedProviders,
     knownFactoryCodes: o.knownFactoryCodes === undefined ? null : o.knownFactoryCodes,
     knownImplementationCodes: o.knownImplementationCodes === undefined ? null : o.knownImplementationCodes,
@@ -216,6 +223,10 @@ export function createNinsei(options) {
   // THE SAME CHAIN-READ SEAM FOR THE ORDER READS: state and deadlines must be read by the wallet that will sign,
   // not by a second provider. Without a caller reader the module keeps its engine default.
   const orderDeps = typeof o.evmCall === "function" ? { call: o.evmCall } : {};
+  // THE LOG SEAM GOES WITH THE ORDER READS: the decline is read by the same caller-brought reader as the state,
+  // for the same reason (the wallet that reads must be the wallet that signs), and it is the READER that is
+  // substituted - the addresses and the topic stay the core's.
+  const logDeps = typeof o.evmLogs === "function" ? { logs: o.evmLogs } : {};
 
   return Object.freeze({
     config,
@@ -238,6 +249,11 @@ export function createNinsei(options) {
       // THE ORDER DEADLINES (t1, readyBy, termsHash) from the chain: the screen needs them to say whether the
       // person is in the dead zone.
       deadlines: (escrow) => orderFlow.orderDeadlines(escrow, orderDeps),
+      // THE MAKER'S DECLINE, READ FROM THE ESCROW (issue #40): the `Declined` event, which is the on-chain fact
+      // that tells a decline apart from an ordinary refund. The answer carries the state and the node's own token
+      // and NOTHING ELSE - no reason, no category, no provider. `checked: false` means the chain was not read,
+      // which is NOT the same as "the escrow did not decline".
+      decline: (escrow, deps = {}) => orderFlow.orderDecline(escrow, { ...logDeps, ...(deps || {}) }),
     },
     sim,
     quotes: {
@@ -260,6 +276,9 @@ export function createNinsei(options) {
     // would not know where to knock, and without the pass there is nothing to present to the service (and that
     // is a refusal with a CODE, not an invented path).
     swaps: createSwaps({ preflight, http, mode: o.mode, xmrNetwork: o.xmrNetwork, call: o.evmCall,
+      // THE LOG SEAM FOR THE DECLINE CHECK: the watch asks the escrow for its `Declined` event on every tick, so
+      // a declined order stops the wait at once instead of running to `xmr-timeout`.
+      logs: o.evmLogs || null,
       config, auth: o.serverAuth, denylist, watch: o.watch,
       // THE RECORD IS BUILT HERE ITSELF, and one brought from outside is only the caller's preference.
       createRecord: o.createRecord }),
@@ -274,7 +293,7 @@ export { SDK_VERSION } from "./version.mjs";
 
 // THE LEVEL WALK IS ON THE PACKAGE SURFACE. A maker publishes a level set (chunks of volume with their own prices)
 // and both the node and the client compute a firm price by WALKING it - the client must reach the SAME price before
-// signing. `levelsWalkSpec.mjs` is the ONE implementation, a byte-identical twin of the node's copy, and it is
-// exported so a consumer can run the same walk: the set in, the answer out. Answers are values with a `reason`
-// token on refusal, never exceptions.
+// signing. `levelsWalkSpec.mjs` is the ONE implementation, which the node takes from the package entry rather than
+// copying, and it is exported so a consumer can run the same walk: the set in, the answer out. Answers are values
+// with a `reason` token on refusal, never exceptions.
 export { checkLevels, xmrForAsset, assetForXmr, toBigInt, XMR_ATOMIC_PER_ONE } from "./levelsWalkSpec.mjs";

package/src/levelsWalkSpec.mjs

@@ -1,13 +1,13 @@
 // THE MAKER'S LEVEL SET: THE REFERENCE WALK OVER IT (issue #110, part B).
 //
 // WHY. The maker sends the node a LEVEL SET - chunks of volume with their own prices - and the node computes a
-// firm price by WALKING it. The client (SDK) needs the same walk to show the same price before signing. This is
-// the SINGLE implementation of the walk and of the level-set rules; the file exists as BYTE-IDENTICAL copies in
-// two places, and tools/check-levels-walk.mjs verifies that:
-//     node: rfq/lib/levelsWalkSpec.mjs        SDK: sdk/src/levelsWalkSpec.mjs
-// Two copies, not an import: the node runs on the provider's machine and sees neither www/ nor sdk/, and the SDK
-// package does not see rfq/ - each starts on its own (the same argument as rfq/lib/quoteEip712Spec.mjs). A
-// divergence would mean the node and the client name a DIFFERENT price for the same set.
+// firm price by WALKING it. The client (SDK) needs the same walk to show the same price before signing. This file
+// is the SINGLE implementation of the walk and of the level-set rules, and BOTH sides run it from here: the node
+// imports the package entry, so it keeps no copy of its own. A second copy would let the node and the client name
+// a DIFFERENT price for the same set.
+// WHAT HOLDS IT: the node is bound to the package by the guard on its imports (no copy may come back under
+// rfq/lib), and the behaviour of this one implementation is pinned by the vectors in tools/check-levels-walk.mjs,
+// computed independently of this code - not by comparing two files.
 //
 // NUMBERS ARE INTEGERS ONLY, BigInt ONLY (rule 10). XMR is in atomic units (1 XMR = 1e12). A price is in the
 // asset's atomic units PER 1 WHOLE XMR (for a wei asset that is wei per 1 XMR). No Number for money.
@@ -19,7 +19,9 @@
 //   3. the first level sets the minimum deal size (there is no separate min);
 //   4. an EMPTY set = the side is off, and that is NOT an error;
 //   5. the walk goes BOTH ways: "I give asset - how much XMR" and "I give XMR - how much asset";
-//   6. rounding to atomic units is in the maker's favour;
+//   6. rounding to atomic units is in the maker's favour, EACH LEVEL ON ITS OWN: up on ask, where the user pays,
+//      down on bid, where the user is paid; the answer in XMR is rounded the maker's way too, down for a buyer
+//      (ask) and up for a seller (bid);
 //   7. one orientation: volume in XMR, price in the asset per 1 XMR;
 //   8. a fixed swap fee (fee in wei, separate for each side): the buyer pays the walk PLUS the fee, the seller
 //      receives the walk MINUS the fee. It is NOT spread over the volume: otherwise the average price would fall
@@ -83,51 +85,65 @@ export function checkLevels(levels, orientation = "ask") {
   return { ok: true, enabled: true, count: levels.length, minAtomic: toBigInt(levels[0].amount), totalAtomic };
 }
 
-// THE COST OF A CHUNK OF VOLUME IN WEI, ROUNDED UP (rule 6, in the maker's favour).
-function levelCostWei(amountAtomic, priceWeiPerXmr) {
-  const num = amountAtomic * priceWeiPerXmr;
-  return (num + XMR_ATOMIC_PER_ONE - 1n) / XMR_ATOMIC_PER_ONE;
+// ROUND A NON-NEGATIVE FRACTION TO A WHOLE UNIT: up, or down. Money is BigInt only (rule 10); the fraction is
+// non-negative where this is reached (amounts and prices are positive, a budget is positive).
+function divRound(num, den, up) {
+  const q = num / den;
+  return up && q * den < num ? q + 1n : q;
 }
 
-// HOW MANY XMR ATOMS A BUDGET GIVES WITHIN ONE LEVEL, ROUNDED DOWN (rule 6).
-function levelXmrForBudget(budgetWei, priceWeiPerXmr) {
-  return (budgetWei * XMR_ATOMIC_PER_ONE) / priceWeiPerXmr;
+// THE COST OF A CHUNK OF VOLUME IN THE ASSET, ONE LEVEL AT A TIME (rule 6). Rounding is always in the maker's
+// favour: UP on ask, where the user pays, DOWN on bid, where the node pays the user. A walk rounds each level on
+// its own and adds the levels up, as the node does: rounding the sum once would differ by up to a unit per level,
+// and the node would sign the maker another amount than its journal books.
+function levelCostWei(amountAtomic, priceWeiPerXmr, orientation) {
+  return divRound(amountAtomic * priceWeiPerXmr, XMR_ATOMIC_PER_ONE, orientation === "ask");
 }
 
-// THE FULL COST OF A SIDE (the sum of its levels' costs) and its volume - computed once.
-function sideSummary(levels) {
+// HOW MANY XMR ATOMS A BUDGET GIVES WITHIN ONE LEVEL (rule 6). The answer in XMR is rounded the maker's way too:
+// DOWN for a buyer (ask), UP for a seller (bid). At a coarse asset several atomic units pay the same, and a
+// seller sends no more of them than the payout needs.
+function levelXmrForBudget(budgetWei, priceWeiPerXmr, orientation) {
+  return divRound(budgetWei * XMR_ATOMIC_PER_ONE, priceWeiPerXmr, orientation === "bid");
+}
+
+// THE FULL COST OF A SIDE (the sum of its levels' costs, each rounded on its own) and its volume - computed once.
+function sideSummary(levels, orientation) {
   let totalAtomic = 0n;
   let fullCostWei = 0n;
   for (const level of levels) {
     const amount = toBigInt(level.amount);
     const price = toBigInt(level.price);
     totalAtomic += amount;
-    fullCostWei += levelCostWei(amount, price);
+    fullCostWei += levelCostWei(amount, price, orientation);
   }
   return { totalAtomic, fullCostWei };
 }
 
-// THE WALK WITHOUT THE FEE: a budget is given - how much XMR it yields (rounding down within a level, rule 6).
-function walkXmrForBudget(levels, budgetWei) {
+// THE WALK WITHOUT THE FEE: a budget is given - how much XMR it yields (each level rounded on its own, rule 6).
+function walkXmrForBudget(levels, budgetWei, orientation) {
   let remaining = budgetWei;
   let xmrAtomic = 0n;
   for (const level of levels) {
     const amount = toBigInt(level.amount);
     const price = toBigInt(level.price);
-    const full = levelCostWei(amount, price);
-    if (remaining >= full) {
+    const full = levelCostWei(amount, price, orientation);
+    // The maker's way once more: a buyer (ask) takes a level whole even when the budget only just reaches it; a
+    // seller (bid) sends no more than the payout needs, so an exact match is left to the partial step, rounded up.
+    const fits = orientation === "ask" ? remaining >= full : remaining > full;
+    if (fits) {
       xmrAtomic += amount;
       remaining -= full;
       continue;
     }
-    xmrAtomic += levelXmrForBudget(remaining, price);
+    xmrAtomic += levelXmrForBudget(remaining, price, orientation);
     break;
   }
   return xmrAtomic;
 }
 
-// THE WALK WITHOUT THE FEE: an XMR volume is given - what it costs (each chunk's cost rounded up, rule 6).
-function walkCostForXmr(levels, xmrAtomic) {
+// THE WALK WITHOUT THE FEE: an XMR volume is given - what it costs (each chunk's cost rounded on its own, rule 6).
+function walkCostForXmr(levels, xmrAtomic, orientation) {
   let left = xmrAtomic;
   let costWei = 0n;
   for (const level of levels) {
@@ -135,7 +151,7 @@ function walkCostForXmr(levels, xmrAtomic) {
     const amount = toBigInt(level.amount);
     const price = toBigInt(level.price);
     const take = left < amount ? left : amount;
-    costWei += levelCostWei(take, price);
+    costWei += levelCostWei(take, price, orientation);
     left -= take;
   }
   return costWei;
@@ -166,16 +182,16 @@ export function xmrForAsset({ levels, role, feeWei = 0n, assetWei, orientation =
   if (asset === null || fee === null || fee < 0n) return { ok: false, reason: "levels-not-integer", role };
   const budget = role === "buy" ? asset - fee : asset + fee;
   if (budget <= 0n) return { ok: false, reason: "levels-fee-beyond-budget", role };
-  const { fullCostWei } = sideSummary(levels);
+  const { fullCostWei } = sideSummary(levels, orientation);
   if (budget > fullCostWei) return { ok: false, reason: "levels-exceed-side", role };
   // THE SMALLEST TRADE, from the set AS THE MAKER SENT IT (rule 3): callers pass it in minAtomic and the
   // node's deductions never change it. Absent, the set's own first level is used, as it always was.
   const min = minOf(levels, minAtomic);
   // Its cost ON THE EFFECTIVE SET: after deductions the smallest trade may reach into a later level, so the
   // cost is walked, not read off one price.
-  const minCost = walkCostForXmr(levels, min);
+  const minCost = walkCostForXmr(levels, min, orientation);
   if (budget < minCost) return { ok: false, reason: "levels-below-minimum", role };
-  const xmrAtomic = walkXmrForBudget(levels, budget);
+  const xmrAtomic = walkXmrForBudget(levels, budget, orientation);
   return { ok: true, role, xmrAtomic, assetWei: asset };
 }
 
@@ -193,7 +209,7 @@ export function assetForXmr({ levels, role, feeWei = 0n, xmrAtomic, orientation
   if (want > verdict.totalAtomic) return { ok: false, reason: "levels-exceed-side", role };
   // THE SMALLEST TRADE AS THE MAKER SENT IT, never the effective set's first level (rule 3): see minOf.
   if (want < minOf(levels, minAtomic)) return { ok: false, reason: "levels-below-minimum", role };
-  const walkWei = walkCostForXmr(levels, want);
+  const walkWei = walkCostForXmr(levels, want, orientation);
   const assetWei = role === "buy" ? walkWei + fee : walkWei - fee;
   if (assetWei <= 0n) return { ok: false, reason: "levels-fee-beyond-budget", role };
   return { ok: true, role, xmrAtomic: want, assetWei };

package/src/quoteEip712.mjs

@@ -1,8 +1,8 @@
 // EIP-712 ORDER-QUOTE SIGNATURE - THE SDK SIDE (VERIFICATION ONLY).
 //
 // The SDK verifies, it does not sign: the maker's wallet key never reaches the customer's machine. The spec
-// (types, domain, digest, recovery) lives in quoteEip712Spec.mjs, byte-identical to the node's copy and pinned
-// by tools/check-quote-eip712.mjs. Here it is only bound to the SDK's own crypto primitives.
+// (types, domain, digest, recovery) lives in quoteEip712Spec.mjs - the ONE embodiment: the node takes it from the
+// package entry, so there is no second copy (tools/check-quote-eip712.mjs). Here it is only bound to SDK primitives.
 //
 // The rule the old flag carried is kept: a quote that cannot be verified is REFUSED. A missing field, a
 // missing signature or an unusable domain is not "probably fine" - the caller names it with a code.

package/src/quoteEip712Spec.mjs

@@ -1,9 +1,9 @@
 // EIP-712 TYPED DATA FOR AN ORDER QUOTE - THE SPEC, SHARED BY THE NODE AND THE SDK.
 //
-// WHY THE SAME FILE EXISTS TWICE. The node (rfq/) runs on the provider's machine and never sees www/ or sdk/:
-// it has to start on its own. The SDK is a package and never sees rfq/. So the spec is embodied twice and the
-// two copies are pinned by sha256 (tools/check-quote-eip712.mjs), exactly like the order context. A divergence
-// here would mean one side signs what the other does not verify - the failure this format exists to prevent.
+// WHO HOLDS IT. The node (rfq/) runs on the provider's machine and does not read our files; it takes this spec
+// from the package entry (@ninsei-labs/sdk/order), so there is ONE embodiment here and no copy on the node's side
+// (that wiring is pinned by tools/check-quote-eip712.mjs). A divergence here would mean one side signs what the
+// other does not verify - the failure this format exists to prevent.
 //
 // WHAT IS BOUND, AND WHY EACH FIELD IS INSIDE THE DIGEST (changing any of them breaks recovery):
 //   provider, quoteKey   - whose quote it is and which key signed it. For a solo maker the two are equal; a

package/src/swap-flow.mjs

@@ -28,6 +28,10 @@
 // is the RULES, not the crypto.
 import { SdkError } from "./errors.mjs";
 import * as engine from "./engine.mjs";
+// THE MAKER'S DECLINE (issue #40) - the escrow's `Declined` event and the neutral vocabulary the state is
+// reported in. It is its own module because TWO surfaces ask the same question (this flow and the swaps watch)
+// and a second implementation of the same event would be a second truth about it.
+import { declinedFromLogs, logReaderOf, blockBoundaryOf, DECLINED_TOPIC0 } from "./decline.mjs";
 
 // THE ENGINE SURFACES, TAKEN THROUGH THE ONE SEAM (./engine.mjs) - exactly as the rest of the core does.
 const { chainById, DEFAULT_CHAIN, MONERO } = engine.config;
@@ -354,6 +358,30 @@ export async function orderStatus(escrow, deps = {}) {
   return decodeStatus(raw);
 }
 
+/**
+ * THE ESCROW'S `Declined` EVENT - THE MAKER'S OWN CLOSING OF A FUNDED ORDER (issue #40).
+ *
+ * WHY THE EVENT AND NOT `status()`. Read on its own, `status()` cannot tell a decline from an ordinary refund:
+ * both set `refunded` and send the whole balance back to the locker. The escrow keeps NO getter that names a
+ * decline (there is no `declined()` view), so the event is the on-chain fact that does - `decline()` emits
+ * `Declined(claimer)` and a refund emits `HalfRevealed(half, false)` instead.
+ *
+ * THE SEAM IS THE READER, AS EVERYWHERE ELSE: `deps.logs` is `({ address, topics, fromBlock, toBlock }) -> logs`
+ * and by default the chain is read through the page's wallet (`readDeclinedLogs`), so the wallet that reads is
+ * the wallet that would sign. `deps.fromBlock` is the caller's: a caller that knows the escrow's birth height
+ * scans from there instead of walking the whole chain.
+ *
+ * An answer that is not a list of logs is a REFUSAL (`bad-input`), never "no decline": an unread chain must not
+ * be reported as an escrow that declined nothing.
+ */
+export async function orderDecline(escrow, deps = {}) {
+  if (typeof escrow !== "string" || !escrow) throw new SdkError("bad-input", { field: "escrow" });
+  const logs = logReaderOf(deps.logs);
+  const fromBlock = deps.fromBlock === undefined ? "earliest" : blockBoundaryOf(deps.fromBlock);
+  const answer = await logs({ address: escrow, topics: [DECLINED_TOPIC0], fromBlock, toBlock: "latest" });
+  return declinedFromLogs(answer, { escrow, at: Number.isFinite(Number(deps.at)) ? Number(deps.at) : null });
+}
+
 // THE ORDER DEADLINE IS ONE - t1. Before it the claimer takes the ETH by its half and only with the ready mark
 // (:215); from t1 claiming is forbidden (:216), and anyone may refund by PRESENTING THE DEPOSITOR'S HALF
 // (:232-235) - the watchtower does not have it, and that limitation is named in doc 24 section 1. The deadline

package/src/swaps.mjs

@@ -25,9 +25,44 @@ import { primitives } from "./primitives.mjs";
 import { createActions } from "./actions.mjs";
 // THE XMR ARRIVAL CHECK ON TWO NODES (issue #85) - IN THE CORE, from the same mirrored rule and block parser.
 import * as xmrArrival from "./xmr-arrival.mjs";
+// THE MAKER'S DECLINE (issue #40): the escrow's `Declined` event and the node's `declined` + `compliance` status
+// are TWO independent sources of the same state, and either one is enough. The detectors and the neutral
+// vocabulary live in one module, so this file names the state instead of re-reading the two.
+import { declineOf, logReaderOf, blockBoundaryOf, DECLINED_TOPIC0, DECLINED_TERMINAL, DECLINED_CODE } from "./decline.mjs";
 
-// The engine's terminal states -> the contract's codes. An unknown kind is not invented: it comes as "closed".
-const TERMINAL = { success: "success", refunded: "refunded_eth", xmr_returned: "xmr_returned", closed: "closed" };
+// THE ENGINE'S SETTLEMENT KINDS -> THE CONTRACT'S CODES: THE KEY IS THE KIND THE ENGINE REALLY WRITES.
+//
+// The map used to be keyed by names no code path writes - `refunded` for a refund (the engine writes
+// `kind: "refund_eth"`), and `xmr_returned` and `closed`, for which no settlement with that kind is written
+// anywhere in the engine or in this package. A REFUND therefore never met its key and fell into the fallback:
+// get/list/progress told the app `closed` about an order whose ETH was already back in the wallet - the very
+// distinction that became load-bearing once the maker's decline was made a state of its own (issue #40).
+//
+// WHAT CAN BE A KIND, EXHAUSTIVELY. The record's settlement belongs to the engine (engine/core/swap.js, the only
+// module that assigns swap.settlement), and `declined` is the one kind written by us (src/decline.mjs):
+//   `success`    - the swap completed and the XMR is on the depositor's address (sweepNow, the auto-sweep in the
+//                  ticker, and the backend-reported sweep on the live path);
+//   `refund_eth` - the ETH went back to the depositor. TWO WRITERS, ONE KIND: the person's own refund (refundEth)
+//                  and the watchtower inside the ticker both write `kind: "refund_eth"` with the phase
+//                  `refunded_eth`, so there is exactly ONE refund-shaped kind here and nothing is collapsed;
+//   `declined`   - the maker refused a funded order. Not the engine's: the escrow reads `refunded` either way, so
+//                  the engine cannot tell a decline from a refund, and the SDK writes this kind itself when it SEES
+//                  the decline (src/decline.mjs). From then on every surface that reads the record reports it
+//                  without asking the chain again.
+//
+// AND WHAT IS NOT A KEY: an unknown kind is named, not invented - it comes out as "closed", the fallback in
+// toState below, which is why `closed` is a code here and not a key (no settlement carries that kind; the string
+// `closed` in the engine is the XMR SESSION's status vocabulary, not a settlement). The maker taking the XMR back
+// without a ready mark is NOT a kind either: it does not end a swap - the depositor's ETH is still in the escrow -
+// so it is a PHASE of a live swap (`xmr_reclaimed`, engine/core/swap.js, told apart by that code from the maker who
+// never locked), and the swap ends later as `refunded_eth`. `xmr_returned`, which stood in the engine's terminal
+// table and in the `TerminalCode` type as a state nothing could produce, is gone with it. Every one of these facts
+// is asserted by the `terminal` check rather than left to a reader.
+const TERMINAL = {
+  success: "success",
+  refund_eth: "refunded_eth",
+  [DECLINED_TERMINAL]: DECLINED_TERMINAL,
+};
 
 const num = (v) => { const n = Number(v); return Number.isFinite(n) ? n : null; };
 
@@ -159,6 +194,10 @@ export function toState(swap) {
     });
   }
   const active = steps.find((s) => s.active) || [...steps].reverse().find((s) => s.done) || steps[0];
+  // THE TERMINAL STATE IS TRANSLATED ONCE, AND THE DECLINE IS READ OFF IT. A declined order is NOT a refunded
+  // one, and the difference is drawn here and in the action flags below, not left to the screen.
+  const terminal = d.terminal ? (TERMINAL[d.terminal.kind] ?? "closed") : null;
+  const declined = terminal === DECLINED_TERMINAL;
   const chain = swap.network || swap.chain || null;
   // The virtual machine is taken from the network registry. An unknown network has none, and "unknown" is more honest
   // than the network's name: it is visible in the state and does not turn into "probably EVM".
@@ -214,9 +253,16 @@ export function toState(swap) {
       status: d.phase || null,
       txs: (swap.escrow && (swap.escrow.txids || swap.escrow.txs)) || [],
     },
-    actions: { markReady: !!(d.can && d.can.ready), sweep: !!(d.can && d.can.sweep), refund: !!(d.can && d.can.refund) },
+    // A DECLINED ORDER OFFERS NOTHING, AND THAT IS THE POINT OF THE STATE (issue #40). The ETH - the fee
+    // included - is already back in the depositor's wallet and no half was revealed, so there is no ready mark to
+    // place, no XMR to sweep and NO REFUND TO SIGN: the flags are OFF rather than left to whatever the engine's
+    // `can` says about an order whose escrow merely reads `refunded`. The app needs no second source for "there
+    // is nothing to do": this state plus the terminal code says it.
+    actions: declined
+      ? { markReady: false, sweep: false, refund: false }
+      : { markReady: !!(d.can && d.can.ready), sweep: !!(d.can && d.can.sweep), refund: !!(d.can && d.can.refund) },
     simulated: { evm: !!(d.simulated && d.simulated.evm), xmr: !!(d.simulated && d.simulated.xmr) },
-    terminal: d.terminal ? (TERMINAL[d.terminal.kind] ?? "closed") : null,
+    terminal,
   };
 }
 
@@ -268,11 +314,18 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
   // The check on the ACTUAL sender is done in start() below, ONE place, right before the send - the wallet adapter
   // only HANDS OUT the current account (`address()`), it does not carry the policy.
   denylist = null,
-  watch: watchOptions = null } = {}) {
+  watch: watchOptions = null,
+  // THE CHAIN LOG READER FOR THE DECLINE CHECK (issue #40). A seam, as the chain read is: by default the logs are
+  // read through the page's wallet (`readDeclinedLogs`), and from outside a caller brings its own
+  // ({ address, topics, fromBlock, toBlock }) -> logs. It is a READ of the escrow's own event, not a node
+  // substitution - the address is the escrow of the swap being watched.
+  logs: chainLogs = null } = {}) {
   // WHAT READS THE CHAIN AT THE LOCK IS A SEAM, as in actions.mjs: by default the engine's read, from outside you can
   // substitute your own. Otherwise the lock step could not be checked beyond predicting the address - and "the address
   // from the receipt" would remain an argument on trust, not a verified property.
   const reader = typeof call === "function" ? call : engine.evm.readContract;
+  // THE SAME RULE FOR THE LOGS: one reader per facade, chosen once.
+  const logReader = logReaderOf(chainLogs);
   // MARKING READY GOES THROUGH THE SAME READ SEAM as the lock: checking the slots and signing must go one way,
   // otherwise part of the check goes past the wallet and part does not (see actions.mjs).
   const actions = createActions({ call: typeof call === "function" ? call : null });
@@ -880,10 +933,82 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
         if (readyBy) xmrArrival.assertTimeForConfirmations({ readyBySec: readyBy, nowSec: Math.floor(Date.now() / 1000), minConfirmations, blockTimeSec: limitOf("xmrBlockTimeSec", 120) });
       }
       const started = Date.now();
+      // --- THE MAKER'S DECLINE: THE WAIT IS NOT STARTED AT ALL (issue #40). -------------------------------------
+      // A decline leaves the escrow `refunded`, so nothing in the state says "do not wait any longer": without
+      // this, the wait runs to its timeout and the app is told the generic `xmr-timeout` about an order that is
+      // CLOSED and whose ETH is already back - or, worse, the app offers the recovery file and a manual refund
+      // for money nobody can recover.
+      //
+      // THE DECLINE IS ASKED WITH TWO INDEPENDENT SOURCES AND EITHER ONE ENDS THE WAIT:
+      //   * THE CHAIN - the escrow's own `Declined` event, through the same log reader the rest of the core uses;
+      //   * THE WIRE - the status the service answers with (`declined` with the code `compliance`).
+      // A CHAIN READ THAT FAILS is neither a decline nor a refusal of the swap: the wait goes on and the wire may
+      // still answer. What the chain read did is carried out with the result (`chain.checked` / `chain.error`), so
+      // a broken reader is visible instead of silent.
+      // A STORAGE THAT CANNOT BE READ IS NOT A REASON TO REFUSE THE WAIT: the record is what makes the state
+      // durable, and the escrow may also arrive in the request. The watch is not a new user of the store - and it
+      // must not start failing where it did not before.
+      let record = null;
+      try { record = engine.swap.getSwap(id); } catch { record = null; }
+      const escrowAddress = request.escrow || (record && record.escrow && record.escrow.address) || null;
+      // FROM THE ESCROW'S BIRTH HEIGHT when the record knows it: the event cannot be older than the funding, and
+      // walking the whole chain every tick is a cost with no answer behind it.
+      const fromBlock = blockBoundaryOf(record && record.escrow ? record.escrow.birthHeight : null);
+      const chainDecline = { checked: false, error: null, logs: undefined };
+      const readDeclineLogs = async () => {
+        chainDecline.checked = false; chainDecline.error = null; chainDecline.logs = undefined;
+        // NO ESCROW KNOWN, NO CHAIN ANSWER: named, so `checked: false` is never a silent "nothing there".
+        if (!escrowAddress) { chainDecline.error = "no-escrow"; return; }
+        try {
+          chainDecline.logs = await logReader({ address: escrowAddress, topics: [DECLINED_TOPIC0], fromBlock, toBlock: "latest" });
+          chainDecline.checked = true;
+        } catch (error) {
+          chainDecline.error = (error && error.code) || "logs-unread";
+        }
+      };
+      // WRITTEN, NAMED, NOT INFERRED - the rule the record's destination follows too. The decline becomes the
+      // record's OWN settlement once, so later reads of the record report the same state without asking the chain
+      // again, and the state survives a page reload.
+      const settleDecline = (swap, at) => {
+        if (!swap || swap.settlement) return;
+        swap.settlement = { kind: DECLINED_TERMINAL, phase: DECLINED_TERMINAL, at };
+        try { engine.swap.saveSwap(swap); } catch { throw new SdkError("storage-unavailable", { step: "decline" }); }
+      };
+      // THE STATE THE WATCH REPORTS FOR A DECLINE: no arrival, the state's own code, the node's own token and
+      // WHERE it was seen ("event", "status", or "record" when it was already written down). NO reason, category
+      // or provider travels here - the node names none, and the sentence a person reads is the interface's.
+      const declineResult = ({ source, at, waitedMs, address, chainChecked, chainError }) => ({
+        id,
+        escrow: escrowAddress,
+        address: address || null,
+        seen: false,
+        declined: true,
+        terminal: DECLINED_TERMINAL,
+        code: DECLINED_CODE,
+        source,
+        at,
+        waitedMs,
+        chain: { checked: Boolean(chainChecked), error: chainError || null },
+      });
+      if (record && record.settlement && record.settlement.kind === DECLINED_TERMINAL) {
+        const at = Number(record.settlement.at);
+        return declineResult({ source: "record", at: Number.isFinite(at) ? at : Date.now(), waitedMs: 0,
+          address: null, chainChecked: false, chainError: null });
+      }
       let last = null;
       for (;;) {
+        await readDeclineLogs();
         const body = await readWatch(id);
         last = incomingOf(body);
+        // THE DECLINE IS DECIDED BEFORE THE ARRIVAL IS LOOKED AT, and before the "foreign response" refusal below:
+        // a declined swap's answer carries no `receivedXmr` at all, and refusing it as a bad response would name
+        // the wrong thing (the state is known - it is a decline, not a broken answer).
+        const declineNow = declineOf({ logs: chainDecline.logs, status: body, escrow: escrowAddress, at: Date.now() });
+        if (declineNow.declined) {
+          settleDecline(record, declineNow.at);
+          return declineResult({ source: declineNow.source, at: declineNow.at, waitedMs: Date.now() - started,
+            address: body && body.address, chainChecked: chainDecline.checked, chainError: chainDecline.error });
+        }
         // AN EMPTY OR FOREIGN RESPONSE IS NOT AN ARRIVAL: counting it as incoming would mean declaring money that was
         // never seen. This is a named refusal, not "let us wait some more".
         if (!last) throw new SdkError("server-unavailable", { step: "watch", why: "bad-response", id });

package/src/version.mjs

@@ -6,4 +6,4 @@
 // tools/sync-version.mjs. Do not edit it by hand - set the version in package.json and run `npm run sync:version`.
 // The `version` check in tools/check.mjs refuses a mismatch, and refuses a runtime read of package.json here.
 
-export const SDK_VERSION = "0.42.0";
+export const SDK_VERSION = "0.43.1";