@ninsei-labs/sdk 0.39.2 → 0.39.3

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 0.39.3 — 2026-10-09
+
+A NODE'S ADDRESS DENYLIST REFUSAL REACHES THE APP AS ITS OWN CODE, AND THE INTERFACE CAN CHECK ADDRESSES ITSELF (issue #16).
+A maker's node refuses a firm quote to an address on the maker's denylist (`PUT /v1/denylist`) and answers
+`{ok:false, code:"denied-address", why:"..."}`. Until now `quotes.firm` read the answer with `http.json`, which throws
+`server-unavailable` and LOSES the body on any non-2xx: the app was told the node was unavailable when the node had
+answered and refused, and it could not tell "did not answer" from "answered and refused".
+
+- **`quotes.firm` reads the answer as a VALUE** (`http.tryJson`, `src/quotes.mjs`): a failed CONNECTION is still
+  `server-unavailable`, while an answer that refused is its own refusal code (`quote-refused`), not "unavailable".
+- **The node's `denied-address` refusal reaches the app under the SDK code `address-denied`** (`src/codes.mjs`,
+  `index.d.ts`), WITHOUT the node's `why` text and WITHOUT the address: the node names both, and the interface shows
+  its own neutral message. A backend relaying the quote passes the node's `code` through (the demo's
+  `app/server.mjs` `/api/order-quote` relay now forwards it).
+- **A new optional address check: `createNinsei({ ..., denylist: [addresses] })`** (`src/index.mjs`, `src/quotes.mjs`,
+  `src/swaps.mjs`, `index.d.ts`). Compared WITHOUT CASE; an empty/absent list means "no check"; the SDK fetches
+  nothing - the interface brings the list in. Before `quotes.firm` the order's `locker` is checked (on a purchase the
+  claimer is the node's own address, so it is deliberately not checked); before `swaps.start` the ACTUAL sender is
+  checked - the address the funding transaction will really be sent from, read from the wallet adapter's `address()`
+  (`eth_accounts[0]`) at the moment of sending, because the person may have switched accounts. A barred address is
+  refused with `address-denied` BEFORE any request; an adapter that cannot hand out the current account is refused
+  with `bad-input` rather than skipping the policy silently.
+- Checks (`tools/check-sdk.mjs`): the node's `denied-address` answer yields `address-denied` with neither the address
+  nor the `why` in `params`; a plain refusal yields `quote-refused` while a failed connection yields
+  `server-unavailable`; a denylisted `order.locker` is refused before any request (zero calls seen); a denylisted
+  actual sender stops the lock before it signs (no transaction); the comparison is case-insensitive; an empty list
+  changes nothing. The breaking run removes the `denied-address` mapping and the pre-send check and must redden.
+
 ## Unreleased — 2026-10-08
 
 EVERY ORDER'S ESCROW IS A CLONE, AND THE CLIENT NOW CHECKS THE IMPLEMENTATION IT WILL EXECUTE (issue #114).

package/README.md

@@ -96,7 +96,7 @@ Terminal states (`state.terminal`): `success`, `refunded_eth`, `xmr_returned`, `
 ### Errors (`error.code`, `SdkError.code`)
 
 `not-implemented`, `bad-input`, `wallet-not-connected`, `wallet-rejected`, `wrong-chain`, `quote-unavailable`,
-`quote-refused`, `quote-stale`, `recovery-declined`, `recovery-failed`, `storage-unavailable`,
+`quote-refused`, `address-denied`, `quote-stale`, `recovery-declined`, `recovery-failed`, `storage-unavailable`,
 `server-unavailable`, `server-refused`, `xmr-timeout`, `xmr-locked`, `contract-reverted`, `insufficient-funds`, `unknown`.
 
 Three refusals that are easy to merge into one are named DIFFERENTLY, because the advice differs:
@@ -105,6 +105,9 @@ reason and status are in `params`; investigate); `xmr-timeout` — the wait for
 state of the money, not a breakdown); `xmr-locked` — XMR is on the address but the transaction's `unlock_time`
 barred it until a height or a date (`params.until`), so the funds are not an arrival and the ready mark is not
 signed (issue #84).
+`address-denied` (issue #16) - the address is on the interface's `denylist` (refused before any
+request) or the node's own `denied-address` refusal, WITHOUT the node's `why` text and WITHOUT the address: the
+interface shows its own neutral message.
 
 ## Quotes
 

package/index.d.ts

@@ -105,6 +105,18 @@ export interface NinseiOptions {
    * An empty/absent list means "no policy": the pair is still read and the implementation's code must be non-empty.
    */
   knownImplementationCodes?: readonly string[];
+  /**
+   * THE INTERFACE'S ADDRESS DENYLIST (issue #16) - policy, not proof, next to allowedProviders. Addresses the
+   * interface will not trade to or from, compared WITHOUT CASE. The SDK fetches nothing: the interface brings the
+   * list in. An empty/absent list means "no check".
+   * Before `quotes.firm` the order's `locker` is checked (on a purchase the claimer is the node's own address, so
+   * it is deliberately not checked), and before `swaps.start` the ACTUAL sender - the address the funding will be
+   * sent from (`eth_accounts[0]` read from the wallet adapter at the moment of sending on demand; the person may
+   * have switched accounts). A barred address is refused with `address-denied` BEFORE any request. A node's own
+   * `denied-address` refusal reaches the app under the same code, WITHOUT the node's `why` text and WITHOUT the
+   * address: the interface shows its own neutral message.
+   */
+  denylist?: readonly string[];
   /**
    * A PASS TO OUR SERVICE for the "server" step (recording the swap with us). Only a wallet can sign the sign-in
    * message, and the wallet's role in the SDK is an adapter: windows and message signatures remain the interface's,
@@ -1278,6 +1290,12 @@ export type ErrorCode =
   | "wrong-chain"
   | "quote-unavailable"
   | "quote-refused"
+  /**
+   * An address on the interface's `denylist` refused BEFORE any request - the order's `locker` before `quotes.firm`,
+   * or the actual sender before `swaps.start` (issue #16). Also names the node's own `denied-address` refusal as it
+   * reaches the app: WITHOUT the node's `why` text and WITHOUT the address, so the interface shows its own message.
+   */
+  | "address-denied"
   | "quote-stale"
   /** The order-quote signature (EIP-712, v6) did not recover to any address. */
   | "quote-signature-invalid"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.39.2",
+  "version": "0.39.3",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/codes.mjs

@@ -42,6 +42,11 @@ export const ERROR_CODES = [
   "wrong-chain",
   "quote-unavailable",
   "quote-refused",
+  // A NODE'S ADDRESS DENYLIST REFUSAL (issue #16): the maker's node answers {ok:false, code:"denied-address", why}
+  // before it prices the order, and that refusal reaches the app under THIS code - WITHOUT the node's `why` text
+  // and WITHOUT the address, because the interface shows the person its own neutral message. It is its own code,
+  // not "quote-refused": the advice to the interface differs ("this address is barred" vs "the quote was refused").
+  "address-denied",
   "quote-stale",
   // THE ORDER-QUOTE SIGNATURE (EIP-712, quote format v7). Four different refusals, because the interface owes the
   // person a different piece of advice for each:

package/src/index.mjs

@@ -105,6 +105,12 @@ const normalizeOptions = (options) => {
   if (o.knownImplementationCodes !== undefined && o.knownImplementationCodes !== null && !Array.isArray(o.knownImplementationCodes)) {
     fail("bad-input", { field: "knownImplementationCodes" });
   }
+  // THE INTERFACE'S ADDRESS DENYLIST (issue #16): policy, like allowedProviders - addresses the interface will not
+  // trade to or from. An empty/absent list means "no check"; an entry that is not a string is a typo, not a silent
+  // no-op. The SDK fetches nothing: the interface brings the list in.
+  if (o.denylist !== undefined && o.denylist !== null) {
+    if (!Array.isArray(o.denylist) || o.denylist.some((a) => typeof a !== "string")) fail("bad-input", { field: "denylist" });
+  }
   // A PASS TO OUR SERVICE - A SEAM FROM OUTSIDE, like the wallet: only a wallet can sign the sign-in message
   // (www/js/evm/auth.js, signIn), and requiring it of the core would mean opening windows and signing messages
   // inside the SDK. The core receives a ready pass and presents it. A missing pass is NOT an option error: the
@@ -146,6 +152,7 @@ const normalizeOptions = (options) => {
     allowedProviders: o.allowedProviders === undefined ? null : o.allowedProviders,
     knownFactoryCodes: o.knownFactoryCodes === undefined ? null : o.knownFactoryCodes,
     knownImplementationCodes: o.knownImplementationCodes === undefined ? null : o.knownImplementationCodes,
+    denylist: o.denylist === undefined ? null : o.denylist,
     serverAuth: o.serverAuth || null,
     watch: o.watch || null,
     createRecord: o.createRecord || null,
@@ -194,8 +201,15 @@ export function createNinsei(options) {
     const set = new Set(a.map((v) => String(v).toLowerCase()));
     return (provider) => set.has(String(provider).toLowerCase());
   })();
+  // THE DENYLIST IS LOWER-CASED ONCE HERE, so the comparison rule (case-insensitive membership) lives in ONE
+  // place and BOTH the quote check (`quotes.firm`) and the lock check (`swaps.start`) use it. An empty list is
+  // "no policy" (null), not an empty check.
+  const denylist = Array.isArray(o.denylist) && o.denylist.length
+    ? new Set(o.denylist.map((a) => String(a).toLowerCase()))
+    : null;
   const quotes = createQuotes({ config, http, now: o.now || (() => Date.now()), evmCall: o.evmCall || null,
-    evmCode: o.evmCode || null, providerAllowed, knownFactoryCodes: o.knownFactoryCodes, knownImplementationCodes: o.knownImplementationCodes });
+    evmCode: o.evmCode || null, providerAllowed, knownFactoryCodes: o.knownFactoryCodes, knownImplementationCodes: o.knownImplementationCodes,
+    denylist });
   // THE SAME CHAIN-READ SEAM AS THE LOCK AND THE CORE: checking the slots and signing must go one way, otherwise
   // part of the check goes past the wallet and part does not.
   const actions = createActions({ call: o.evmCall });
@@ -246,7 +260,7 @@ 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,
-      config, auth: o.serverAuth, watch: o.watch,
+      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 }),
     // XMR WITHDRAWAL: parsing the file and requesting data work; the withdrawal itself is named (the Monero

package/src/quotes.mjs

@@ -208,7 +208,7 @@ const compactOffer = (o) => ({
 // the price of the failed row to tell the person WHY there is no offer (and not just "none").
 const compactRefusal = (r) => ({ ...compactOffer(r), code: r.code, why: r.why });
 
-export function createQuotes({ config, http, now = () => Date.now(), evmCall = null, evmCode = null, providerAllowed = null, knownFactoryCodes = null, knownImplementationCodes = null }) {
+export function createQuotes({ config, http, now = () => Date.now(), evmCall = null, evmCode = null, providerAllowed = null, knownFactoryCodes = null, knownImplementationCodes = null, denylist = null }) {
   // THE INTERFACE'S FACTORY POLICY (#103): the code hashes of factories it is willing to trade through
   // (extcodehash semantics = keccak256 of the runtime code). An EMPTY list is "no policy" (like
   // allowedProviders); a NON-EMPTY one refuses any factory whose code is not on it. Lower-cased once.
@@ -340,9 +340,19 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
       if (!request || typeof request !== "object") fail("bad-input", { field: "request" });
       if (typeof request.providerId !== "string" || !request.providerId) fail("bad-input", { field: "providerId" });
       if (!request.order || typeof request.order !== "object") fail("bad-input", { field: "order" });
-      let body = null;
+      // THE INTERFACE'S OWN ADDRESS DENYLIST (issue #16): POLICY, not proof - the interface refuses to ask for a
+      // quote for an address on its own list, and does it BEFORE any request is made. `order.locker` is the
+      // address the funds come from on a purchase (the claimer there is the node's own address, so it is
+      // deliberately not checked). An empty/absent list is "no policy"; the comparison is WITHOUT CASE.
+      if (denylist && typeof request.order.locker === "string" && denylist.has(request.order.locker.toLowerCase())) {
+        fail("address-denied", { step: "order-quote" });
+      }
+      let res = null;
       try {
-        body = await http.json(config.route("orderQuote"), {
+        // THE ANSWER IS READ AS A VALUE (tryJson), NOT AS AN EXCEPTION: "did not answer" and "answered and
+        // refused" must stay different, and a refusal's own body carries the reason. `json` throws
+        // server-unavailable and LOSES that body.
+        res = await http.tryJson(config.route("orderQuote"), {
           method: "POST",
           headers: { "content-type": "application/json" },
           body: JSON.stringify({ providerId: request.providerId, order: request.order }),
@@ -351,7 +361,15 @@ export function createQuotes({ config, http, now = () => Date.now(), evmCall = n
         if (error && error.code === "bad-input") throw error;
         fail("server-unavailable", { step: "order-quote" });
       }
-      if (!body || body.ok !== true || !body.quote) fail("quote-refused", { step: "order-quote" });
+      // A NODE'S DENYLIST REFUSAL REACHES THE APP UNDER ITS OWN NEUTRAL SDK CODE, WITHOUT the `why` text and
+      // WITHOUT the address: the node names both (the maker's denylist and the address), and the interface shows
+      // the person its own neutral message. Every other refusal keeps its existing code (quote-refused etc.).
+      const refusedCode = res && res.body && typeof res.body.code === "string" ? res.body.code : null;
+      if (refusedCode === "denied-address") fail("address-denied", { step: "order-quote" });
+      if (!res || res.ok !== true || !res.body || res.body.ok !== true || !res.body.quote) {
+        fail("quote-refused", { step: "order-quote" });
+      }
+      const body = res.body;
       const quote = body.quote;
       // A MISSING FIELD OF THE SIGNED SET IS NOT "PROBABLY ZERO": the digest cannot be built, so the quote is
       // not verifiable and is refused (its own code, so the interface can say which field is unbound).

package/src/swaps.mjs

@@ -264,6 +264,10 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
   // adapter (send/receipt): windows and message signatures remain the interface's. A READY pass arrives here (as
   // www/js/evm/auth.js, signIn obtains it today), and the core merely presents it.
   auth = null,
+  // THE INTERFACE'S ADDRESS DENYLIST (issue #16), a Set of lower-cased addresses already assembled by the facade.
+  // 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 } = {}) {
   // 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
@@ -757,6 +761,19 @@ export function createSwaps({ preflight, http, createRecord, mode = null, xmrNet
       if (!wallet || typeof wallet.send !== "function" || typeof wallet.receipt !== "function") {
         throw new SdkError("bad-input", { field: "wallet", missing: ["send", "receipt"], surface: "swaps.start", step: "lock" });
       }
+      // THE INTERFACE'S ADDRESS DENYLIST, ON THE ACTUAL SENDER (issue #16). The person may have switched accounts
+      // in the wallet, so what matters is the address the funding transaction will really be sent from AT THIS
+      // MOMENT, not `order.locker` checked earlier. The wallet adapter hands out the current account (the adapter's
+      // `address()` reads `eth_accounts[0]`); the comparison lives HERE, one place, right before the send - not
+      // inside the adapter. The refusal happens BEFORE any request: no transaction is signed or sent.
+      if (denylist) {
+        const sender = typeof wallet.address === "function" ? await wallet.address() : null;
+        if (typeof sender !== "string" || !sender) {
+          // A HALF-ADAPTER CANNOT BE APPLIED THE POLICY TO: silently skipping would make the list skippable.
+          throw new SdkError("bad-input", { field: "wallet", missing: ["address"], surface: "swaps.start", step: "lock" });
+        }
+        if (denylist.has(sender.toLowerCase())) throw new SdkError("address-denied", { step: "lock" });
+      }
       // THE LOCK TERMS ARE THE SAME AS THE ORDER'S, and are taken from the caller: exactly these fields enter the
       // context the DLEQ proof is bound to (orderContext.js, FIELDS). The deadlines and composition are checked by the
       // engine (lock.send -> escrow.orderTerms) BEFORE sending, not by our own arithmetic: the contract sets the rules.