@ninsei-labs/sdk 0.42.0 → 0.42.1

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 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/index.d.ts

@@ -500,7 +500,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 +547,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ninsei-labs/sdk",
-  "version": "0.42.0",
+  "version": "0.42.1",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -20,6 +20,8 @@
     "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"
   },
   "types": "./index.d.ts",

package/src/levelsWalkSpec.mjs

@@ -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/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.42.1";