@ninsei-labs/sdk 0.42.1 → 0.43.3

package/CHANGELOG.md

@@ -1,3 +1,83 @@
+## 0.43.3 — 2026-10-18
+
+THE SAME CONTENT AS 0.43.2, PUBLISHED UNDER A NEW NUMBER. The tag-triggered release for 0.43.2 stopped in
+`pnpm/action-setup` before building anything: the workflow named pnpm 12.10.1 while `packageManager` names
+12.11.2, and the action refuses two versions (`ERR_PNPM_BAD_PM_VERSION`). Nothing reached the registry. The
+workflow now reads `packageManager` and pins no version of its own; this release carries that fix and the
+0.43.2 content unchanged.
+
+- `./provider` (Node only) and the two bound verification helpers in `./order` are as described in 0.43.2.
+- The display-name draw uses `randomInt`, as fixed in 0.43.2.
+- No package code changed between 0.43.2 and 0.43.3; only the release pipeline did.
+
+## 0.43.2 — 2026-10-18
+
+THE PROVIDER SIDE AND THE BOUND VERIFICATION HELPERS ARE PUBLIC. Two things the demo and the node used to reach
+through the node's own files are now package surface: `./order` exports `orderQuoteMissingFields` and
+`recoverOrderQuoteKey` (the spec functions bound to the SDK's primitives), and a new Node-only subpath
+`./provider` carries the provider's identity, signing and env-file helpers. A consumer no longer re-derives the
+provider code rule or the public-key path, and the browser entries stay free of `node:fs` and `node:crypto`.
+
+- `./order` gains two names: `orderQuoteMissingFields(quote)` and `recoverOrderQuoteKey(quote)`. Both are the
+  spec's own functions bound to `primitives.mjs`, so verification has one implementation, not two.
+- `./provider` is a separate entry because it reaches the filesystem and `node:crypto`: the provider code of an
+  address, the public key path beside a private key, key generation, payload signing and verification, and the
+  settings-file helpers (`findEnvFile`, `readEnvFile`, `applyEnvFile`, `substituteEnvVars`).
+- The checks gained a `provider` case: the provider code is the address's own name and stable, the public key
+  path follows the private one, a settings file is found, read and applied, and the bound quote verification
+  names what is missing and recovers nothing from an empty quote.
+
+## 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

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
@@ -32,7 +32,7 @@ value that looks like data is more dangerous than a refusal.
 compares the list of what the SDK returns with what is declared in the contract (both ways).
 
 EVERY PUBLISHED SUBPATH CARRIES ITS OWN DECLARATIONS: `.` (`index.d.ts`), `./xmr`, `./order`, `./evm`,
-`./core` and `./recovery` (`src/public/<entry>.d.ts`). Each of them declares exactly the symbols its barrel
+`./core`, `./recovery` and `./provider` (`src/public/<entry>.d.ts`). Each of them declares exactly the symbols its barrel
 re-exports, so a typed consumer sees the same surface the runtime has, and nothing else.
 `tools/check.mjs --only=types` keeps the two sides equal (a subpath without a `types` target, a declarations
 file that does not read as declarations, or a symbol declared on one side only is red), and
@@ -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
@@ -709,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
@@ -985,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;
@@ -1105,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
@@ -1114,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. */
@@ -1141,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) --------------------------------------------------------
 
@@ -1300,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. */
@@ -1462,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,11 +1,11 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.42.1",
+  "version": "0.43.3",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "packageManager": "pnpm@12.10.1",
+  "packageManager": "pnpm@12.11.2",
   "description": "XMR <-> EVM swap engine: quotes, guards, order steps, recovery (no DOM, no user-facing strings)",
   "license": "MIT",
   "type": "module",
@@ -17,12 +17,18 @@
     "check:surface": "node tools/check.mjs --only=surface",
     "check:mirror": "node tools/check.mjs --only=mirror",
     "check:pack": "node tools/check.mjs --only=pack",
+    "check:pack-teeth": "node tools/check-pack-teeth.mjs",
     "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:sweep": "node tools/sweep-refusal.test.mjs", "sync:version": "node tools/sync-version.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",
   "exports": {
@@ -53,6 +59,10 @@
     "./recovery": {
       "types": "./src/public/recovery.d.ts",
       "default": "./src/public/recovery.mjs"
+    },
+    "./provider": {
+      "types": "./src/public/provider.d.ts",
+      "default": "./src/public/provider.mjs"
     }
   },
   "files": [

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);
+};