@ninsei-labs/sdk 0.56.1 → 0.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/LICENSE-POLICY.md +9 -2
  3. package/README.md +78 -28
  4. package/THIRD_PARTY_NOTICES.md +176 -2
  5. package/assets/vendors/MANIFEST.json +1 -13
  6. package/assets/vendors/sdk/sdk-browser.js +5 -4
  7. package/engine/atomic/dleq2.js +116 -15
  8. package/engine/atomic/order.js +21 -3
  9. package/engine/core/config.js +20 -46
  10. package/engine/core/deployments.generated.js +103 -0
  11. package/engine/core/rfqSource.js +6 -133
  12. package/engine/core/swap.js +8 -8
  13. package/engine/evm/asyncRoute.js +1 -1
  14. package/engine/evm/claimGas.js +2 -1
  15. package/engine/evm/escrow.js +13 -8
  16. package/engine/evm/factory.js +11 -6
  17. package/engine/evm/funding.js +8 -3
  18. package/engine/evm/index.js +5 -6
  19. package/engine/evm/session.js +48 -279
  20. package/engine/monero/address.js +15 -33
  21. package/engine/monero/keys.js +124 -0
  22. package/engine/monero/mnemonic.js +104 -0
  23. package/engine/monero/scan.js +121 -28
  24. package/engine/monero/wallet.js +31 -68
  25. package/engine/monero/wordlist.en.js +210 -0
  26. package/engine/recovery/restore.js +9 -9
  27. package/engine/sdk/bridge.js +9 -187
  28. package/engine/ui/walletModal.js +7 -27
  29. package/index.d.ts +234 -262
  30. package/package.json +7 -6
  31. package/src/actions.mjs +8 -5
  32. package/src/codes.mjs +17 -0
  33. package/src/config.mjs +17 -54
  34. package/src/engine.mjs +9 -6
  35. package/src/feeEstimate.mjs +11 -4
  36. package/src/http.mjs +4 -1
  37. package/src/index.mjs +24 -45
  38. package/src/legs/kyber.mjs +23 -0
  39. package/src/lock.mjs +1 -0
  40. package/src/order.mjs +110 -22
  41. package/src/primitives.mjs +4 -5
  42. package/src/probes.mjs +9 -3
  43. package/src/public/networks.d.ts +45 -0
  44. package/src/public/networks.mjs +10 -1
  45. package/src/public/recovery.d.ts +17 -1
  46. package/src/public/recovery.mjs +1 -0
  47. package/src/public/xmr.mjs +1 -1
  48. package/src/quotePolicy.mjs +25 -0
  49. package/src/quotes.mjs +109 -765
  50. package/src/readyWindow.mjs +76 -0
  51. package/src/recovery-key.mjs +71 -16
  52. package/src/recovery.mjs +11 -28
  53. package/src/relayClaim.mjs +132 -0
  54. package/src/relayFeatures.mjs +25 -13
  55. package/src/relayFirmClient.mjs +36 -7
  56. package/src/relayQuote.mjs +92 -11
  57. package/src/relayView.mjs +3 -3
  58. package/src/swap-flow.mjs +146 -60
  59. package/src/swaps.mjs +521 -357
  60. package/src/sweep-action.mjs +73 -0
  61. package/src/sweep-restore.mjs +8 -4
  62. package/src/sweep.mjs +12 -2
  63. package/src/version.mjs +1 -1
  64. package/src/xmr-arrival.mjs +328 -29
  65. package/src/xmrAmountPolicy.mjs +35 -0
  66. package/assets/vendors/atomic/atomic-browser.js +0 -24
  67. package/assets/vendors/monero/monero-js-browser.js +0 -58
  68. package/assets/vendors/monero-js/LICENSE +0 -9
  69. package/assets/vendors/walletconnect/wc-browser.js +0 -6202
  70. package/engine/atomic/order-client.js +0 -56
  71. package/engine/atomic/order-worker.js +0 -156
  72. package/engine/evm/asyncExec.js +0 -577
  73. package/engine/evm/asyncLegs.js +0 -308
package/package.json CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "name": "@ninsei-labs/sdk",
3
- "version": "0.56.1",
3
+ "version": "0.58.0",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "registry": "https://registry.npmjs.org/"
7
7
  },
8
8
  "packageManager": "pnpm@12.11.2",
9
9
  "description": "XMR <-> EVM swap engine: quotes, guards, order steps, recovery (no DOM, no user-facing strings)",
10
- "license": "MIT",
10
+ "license": "(MIT AND LGPL-3.0-only)",
11
11
  "type": "module",
12
12
  "main": "src/index.mjs",
13
13
  "scripts": {
@@ -20,11 +20,11 @@
20
20
  "check:mirror": "node tools/check.mjs --only=mirror",
21
21
  "check:pack": "node tools/check.mjs --only=pack",
22
22
  "check:pack-teeth": "node tools/run-teeth-isolated.mjs tools/check-pack-teeth.mjs",
23
+ "check:guard-teeth": "node tools/run-teeth-isolated.mjs tools/check-guard-teeth.mjs",
23
24
  "check:secrets": "node tools/check.mjs --only=secrets",
24
25
  "check:vendor-bundles": "node tools/check.mjs --only=vendor-bundles",
25
26
  "check:dleq-vectors": "node tools/check-dleq-vectors.mjs",
26
27
  "check:swap-network": "node tools/check.mjs --only=swap-network",
27
- "check:quote-ttl": "node tools/check.mjs --only=quote-ttl",
28
28
  "check:dleq-oracle": "node tools/check-dleq-oracle.mjs",
29
29
  "check:vendor-bundles-teeth": "node tools/run-teeth-isolated.mjs tools/check-vendor-bundles-teeth.mjs",
30
30
  "check:types": "node tools/check.mjs --only=types",
@@ -39,14 +39,12 @@
39
39
  "check:sweep-half": "node tools/check-sweep-half.mjs",
40
40
  "sync:version": "node tools/sync-version.mjs",
41
41
  "check:restore": "node tools/check-restore.mjs",
42
- "check:restore-height": "node tools/check-restore-height.mjs",
43
42
  "check:wallet-factory": "node tools/check-wallet-factory.mjs",
44
43
  "check:xmr-amount": "node tools/check-xmr-amount.mjs",
45
44
  "check:sign-preview": "node tools/check-sign-preview.mjs",
46
45
  "check:destination": "node tools/check-destination.mjs",
47
46
  "check:codes-meta": "node tools/check-codes-meta.mjs",
48
47
  "check:arrival-read": "node tools/check-arrival-read.mjs",
49
- "check:sale-auth": "node tools/check-sale-auth.mjs",
50
48
  "check:backup-confirmation": "node tools/check-backup-confirmation.mjs",
51
49
  "check:key-view": "node tools/check-key-view.mjs",
52
50
  "check:relay-view": "node tools/check-relay-view.mjs",
@@ -59,6 +57,7 @@
59
57
  "check:sell-watch": "node tools/check-sell-watch.mjs",
60
58
  "check:sell-start": "node tools/check-sell-start.mjs",
61
59
  "check:arrival-consensus": "node tools/check-arrival-consensus.mjs",
60
+ "check:arrival-shadow": "node tools/check-arrival-shadow.mjs",
62
61
  "check:arrival-real": "node tools/check-arrival-real.mjs",
63
62
  "check:order-proof": "node tools/check-order-proof.mjs",
64
63
  "check:daemon-address": "node tools/check-daemon-address.mjs",
@@ -69,8 +68,10 @@
69
68
  "check:factory-selectors": "node tools/check-factory-selectors.mjs",
70
69
  "check:fee-estimate": "node tools/check-fee-estimate.mjs",
71
70
  "check:deadline-scale": "node tools/check-deadline-scale.mjs",
71
+ "check:deployment-pins": "node tools/check-deployment-pins.mjs",
72
72
  "check:node-probe": "node tools/check-node-probe.mjs",
73
73
  "check:recovery-key": "node tools/check.mjs --only=recovery-key",
74
+ "check:monero-keys": "node tools/check.mjs --only=monero-keys",
74
75
  "check:recovery-open": "node tools/check-recovery-open.mjs",
75
76
  "check:contract-vectors": "node tools/check-contract-vectors.mjs",
76
77
  "check:live-contract": "node tools/check-live-contract.mjs",
@@ -169,7 +170,7 @@
169
170
  },
170
171
  "dependencies": {
171
172
  "@hpke/chacha20poly1305": "1.8.0",
172
- "@hpke/core": "1.9.0",
173
+ "@hpke/core": "1.10.0",
173
174
  "@hpke/dhkem-x25519": "1.8.0",
174
175
  "@noble/curves": "^2.4.0",
175
176
  "@noble/hashes": "^2.4.0",
package/src/actions.mjs CHANGED
@@ -68,8 +68,11 @@ export function createActions({ call = null, blockTime = null } = {}) {
68
68
  if (!provider || typeof provider.request !== "function") {
69
69
  return async () => { throw new SdkError("wallet-not-connected", { surface: "actions.read" }); };
70
70
  }
71
- return async ({ to, data }) => {
72
- const result = await provider.request({ method: "eth_call", params: [{ to, data }, "latest"] });
71
+ return async ({ to, data, from }) => {
72
+ // The simulation needs the same sender as the transaction: mark-ready and claim are sender-bound. For a
73
+ // plain read the field is simply absent.
74
+ const tx = from ? { to, data, from } : { to, data };
75
+ const result = await provider.request({ method: "eth_call", params: [tx, "latest"] });
73
76
  if (typeof result !== "string" || !result.startsWith("0x")) {
74
77
  throw new SdkError("contract-reverted", { surface: "actions.read" });
75
78
  }
@@ -77,8 +80,8 @@ export function createActions({ call = null, blockTime = null } = {}) {
77
80
  };
78
81
  };
79
82
  // THE LATEST BLOCK TIMESTAMP IS THE CLOCK THE CONTRACT USES. It comes from the same provider as the contract
80
- // reads; an absent provider or an unreadable block leaves it null, and the time rule is skipped rather than
81
- // guessed from the device clock or from another instance's provider.
83
+ // reads; an absent provider or an unreadable block leaves it null, and the half-revealing action refuses with
84
+ // `clock-unreadable` rather than signing without a time verdict.
82
85
  const clockFor = (wallet) => typeof blockTime === "function" ? blockTime : async () => {
83
86
  try {
84
87
  const provider = providerOf(wallet);
@@ -96,7 +99,7 @@ export function createActions({ call = null, blockTime = null } = {}) {
96
99
  if (typeof sender !== "string" || !sender.trim()) throw new SdkError("bad-input", { field: "wallet.address", step });
97
100
  return sender;
98
101
  };
99
- const deps = (wallet, chainId, from) => ({ call: readerFor(wallet), send: (tx) => wallet.send({ ...tx, chainId, from }), receipt: (h) => wallet.receipt(h), blockTime: clockFor(wallet) });
102
+ const deps = (wallet, chainId, from) => ({ call: readerFor(wallet), from, send: (tx) => wallet.send({ ...tx, chainId, from }), receipt: (h) => wallet.receipt(h), blockTime: clockFor(wallet) });
100
103
  return {
101
104
  /** Marking "I saw the XMR on the shared address". Without it, claiming is forbidden by the contract. */
102
105
  async markReady(request, wallet) {
package/src/codes.mjs CHANGED
@@ -67,6 +67,9 @@ export const ERROR_CODES = [
67
67
  "quote-key-mismatch",
68
68
  "quote-field-unbound",
69
69
  "quote-expired",
70
+ // THE QUOTE ARRIVED WITH LESS THAN THE START MARGIN LEFT. The lock would refuse it seconds later, after the proof
71
+ // and the record work, so the answer is refused as soon as it arrives and the caller can ask again.
72
+ "quote-too-short",
70
73
  // WHO OWNS THE KEY - ASKED OF THE CHAIN (maker registry, providerOf). The signature alone proves only that
71
74
  // SOME key signed; these four name what the registry (and the interface's policy) said:
72
75
  // quote-registry-unchecked - there was no way to ask the chain, so the claim stays unproven;
@@ -83,10 +86,12 @@ export const ERROR_CODES = [
83
86
  // quote-factory-unknown - the record names no factory (zero);
84
87
  // quote-factory-mismatch - the signed quote names a DIFFERENT factory than the record;
85
88
  // quote-factory-code-unknown - the factory's code is not a build this interface knows.
89
+ // quote-cashier-mismatch - the signed quote names a cashier other than the network's vault.
86
90
  "quote-factory-unchecked",
87
91
  "quote-factory-unknown",
88
92
  "quote-factory-mismatch",
89
93
  "quote-factory-code-unknown",
94
+ "quote-cashier-mismatch",
90
95
  "recovery-declined",
91
96
  "recovery-failed",
92
97
  "storage-unavailable",
@@ -95,6 +100,11 @@ export const ERROR_CODES = [
95
100
  // through - server-unavailable, while the service answered and did not accept - server-refused (with the
96
101
  // status and its own reason). The advice to the interface differs: "retry" versus "investigate".
97
102
  "server-refused",
103
+ // THE CLAIM WAS POSTED BUT NO REAL ANSWER CAME BACK. A timeout, a reset or a body without a usable transaction
104
+ // hash leaves the outcome UNKNOWN: the relay may have sent the claim, and the half is already out of the client.
105
+ // It is NOT `server-unavailable` (which would invite a blind retry) and NOT a success: the caller must read the
106
+ // escrow before doing anything else. `params.why` names the lost part (`answer-lost`, `answer-txid`, ...).
107
+ "claim-unknown",
98
108
  // THE TRANSACTION WAS SENT BUT THE RECEIPT DOES NOT PROVE AN ESCROW: no receipt yet, no expected OrderCreated,
99
109
  // or a receipt from another factory. The tx hash is the handle for a retry read; nothing was saved as funded.
100
110
  "funding-pending",
@@ -117,12 +127,14 @@ export const ERROR_CODES = [
117
127
  "xmr-no-nodes",
118
128
  "xmr-underpaid",
119
129
  "xmr-too-late",
130
+ "xmr-address-mismatch",
120
131
  "contract-reverted",
121
132
  "insufficient-funds",
122
133
  // A FEE REPORTED BY A WALLET/NODE IS DATA, NOT AN INSTRUCTION. Without a ceiling a malicious node can take
123
134
  // most of the withdrawal. The refusal names the fee and the limit so the interface does not present it as a
124
135
  // normal transfer.
125
136
  "sweep-fee-too-high",
137
+ "sweep-fee-unknown",
126
138
  // CLAIM GAS FOR THE XMR SELLER (issue #78). The seller comes from Monero and has no coin on the EVM side to pay
127
139
  // for the claim, so the maker may send it - but only when asked for, and only after the core has CONFIRMED the
128
140
  // gas actually arrived. The three codes name the three states the interface must not blur together:
@@ -165,6 +177,7 @@ export const ERROR_META = Object.freeze({
165
177
  "quote-key-mismatch": { retryable: false, side: "provider" },
166
178
  "quote-field-unbound": { retryable: false, side: "provider" },
167
179
  "quote-expired": { retryable: true, side: "provider" },
180
+ "quote-too-short": { retryable: true, side: "provider" },
168
181
  "quote-registry-unchecked": { retryable: true, side: "chain" },
169
182
  "quote-key-unknown": { retryable: false, side: "chain" },
170
183
  "quote-provider-mismatch": { retryable: false, side: "chain" },
@@ -173,11 +186,13 @@ export const ERROR_META = Object.freeze({
173
186
  "quote-factory-unknown": { retryable: false, side: "chain" },
174
187
  "quote-factory-mismatch": { retryable: false, side: "chain" },
175
188
  "quote-factory-code-unknown": { retryable: false, side: "chain" },
189
+ "quote-cashier-mismatch": { retryable: false, side: "chain" },
176
190
  "recovery-declined": { retryable: false, side: "wallet" },
177
191
  "recovery-failed": { retryable: false, side: "wallet" },
178
192
  "storage-unavailable": { retryable: true, side: "service" },
179
193
  "server-unavailable": { retryable: true, side: "service" },
180
194
  "server-refused": { retryable: false, side: "service" },
195
+ "claim-unknown": { retryable: false, side: "chain" },
181
196
  "funding-pending": { retryable: true, side: "chain" },
182
197
  "xmr-timeout": { retryable: true, side: "chain" },
183
198
  "xmr-locked": { retryable: true, side: "chain" },
@@ -185,9 +200,11 @@ export const ERROR_META = Object.freeze({
185
200
  "xmr-no-nodes": { retryable: true, side: "chain" },
186
201
  "xmr-underpaid": { retryable: false, side: "chain" },
187
202
  "xmr-too-late": { retryable: false, side: "chain" },
203
+ "xmr-address-mismatch": { retryable: false, side: "caller" },
188
204
  "contract-reverted": { retryable: false, side: "chain" },
189
205
  "insufficient-funds": { retryable: false, side: "wallet" },
190
206
  "sweep-fee-too-high": { retryable: false, side: "chain" },
207
+ "sweep-fee-unknown": { retryable: true, side: "chain" },
191
208
  "gas-refused-by-maker": { retryable: false, side: "provider" },
192
209
  "gas-not-arrived": { retryable: true, side: "chain" },
193
210
  "gas-too-little": { retryable: false, side: "provider" },
package/src/config.mjs CHANGED
@@ -56,9 +56,18 @@ const chainConfig = (chain) => ({
56
56
  dex: chain.dex ? { routes: chain.dex.routes || [] } : null,
57
57
  // THE ESCROW'S BIRTH HEIGHT, when the network has an escrow. A caller can hand it to findSwaps instead of
58
58
  // inventing a start block or asking from genesis, which public RPCs refuse.
59
+ //
60
+ // THE VAULT AND THE IMPLEMENTATION PIN TRAVEL WITH THE NETWORK, not only with the deployment record. `quotes`
61
+ // refuses an answer whose `cashier` is not this network's vault, and the funding path fills the order terms
62
+ // from the same projection. A projection that drops the field leaves a client built from a network NAME with
63
+ // no vault at all, so every relay quote ends as `no-pinned-cashier` - a defect in the profile, not in the
64
+ // answer (sdk#291). Nothing else fills these fields: the projection is the one place both facades read.
59
65
  escrow: chain.escrow ? {
60
66
  address: chain.escrow.address || null,
61
67
  mode: chain.escrow.mode || null,
68
+ registry: chain.escrow.registry || null,
69
+ cashier: chain.escrow.cashier || null,
70
+ implementationCodeHash: chain.escrow.implementationCodeHash || null,
62
71
  deploymentBlock: Number.isSafeInteger(chain.escrow.deploymentBlock) ? chain.escrow.deploymentBlock : null,
63
72
  } : null,
64
73
  });
@@ -75,25 +84,9 @@ const chainConfig = (chain) => ({
75
84
  // configurability" would become a way to switch the checks off with a single field, which is exactly what the
76
85
  // core exists to prevent.
77
86
  //
78
- // PATHS ARE NAMED BY NAMES, NOT BY STRINGS IN CODE. `route("swept", { id })` substitutes the value and encodes
79
- // it; the path holds `{id}`. So changing the host or using a third-party server is an edit of an object, not an
80
- // edit of the core.
81
- // WHY THESE PATHS DID NOT EXIST BEFORE AND WHERE THEY COME FROM. The "server" step (recording the swap with us
82
- // and watching the Monero address) is done with THE SAME requests as the current interface, so the paths are
83
- // named after its calls, not invented: the watch state - GET /swaps/{id} (www/js/core/chainSource.js:184,
84
- // fetchSession), the factory record of a swap - POST /evm-swaps (www/js/evm/auth.js:111, saveServerSwap; in app
85
- // the full path /api/evm-swaps is declared by the template /^\/api\/evm-swaps$/ in app/server.mjs:1230).
86
- export const DEFAULT_ROUTES = Object.freeze({
87
- swaps: "/swaps",
88
- swap: "/swaps/{id}",
89
- evmSwaps: "/evm-swaps",
90
- // A quote for an order: the provider's commitment under keys, not a market snapshot.
91
- orderQuote: "/order-quote",
92
- // A reverse-mode ticket: the maker supplies the XMR fields, the node answers with a signed quote and its claim tip.
93
- orderSell: "/order-sell",
94
- revealedHalf: "/escrow/revealed-half",
95
- swept: "/swaps/{id}/swept",
96
- });
87
+ // THE SDK TALKS TO A MAKER THROUGH A RELAY AND READS THE CHAIN THROUGH THE SEAMS THE CALLER BRINGS. It does not
88
+ // carry a client for the old node's HTTP surface: those routes were retired, and a client that still names them
89
+ // would silently make every request against a service that no longer exists.
97
90
 
98
91
  // THE MONERO NODES THE ARRIVAL IS CHECKED AGAINST. Defaults are the list verified on 2026-10-02 (issue #85):
99
92
  // mainnet - four public nodes of different operators; stagenet - our node and the one independent public node.
@@ -145,28 +138,10 @@ const nodesOf = (options, selected) => {
145
138
  return out;
146
139
  };
147
140
 
148
- const pathOf = (template, params) => template.replace(/\{([a-z]+)\}/g, (whole, name) => {
149
- const value = params ? params[name] : undefined;
150
- if (value === undefined || value === null || value === "") fail("bad-input", { field: "route.param", param: name });
151
- return encodeURIComponent(String(value));
152
- });
153
-
154
- const routesOf = (options) => {
155
- const custom = (options && options.routes) || {};
156
- for (const name of Object.keys(custom)) {
157
- // AN UNKNOWN NAME IS A TYPO, NOT "let's add our own": otherwise the path silently fails to apply, and the
158
- // call falls back to a default nobody knows about.
159
- if (!(name in DEFAULT_ROUTES)) fail("bad-input", { field: "routes", unknown: name, known: Object.keys(DEFAULT_ROUTES) });
160
- if (typeof custom[name] !== "string" || !custom[name]) fail("bad-input", { field: "routes." + name });
161
- }
162
- return { ...DEFAULT_ROUTES, ...custom };
163
- };
164
-
165
141
  // THE POLL RATE AND TIMEOUT FOR WATCHING THE MONERO ADDRESS. The defaults come from the engine's settings, not
166
- // from numbers in the code: the rate is the same as the page's (www/js/core/chainSource.js, pollInterval =
167
- // API.pollMs), and the timeout is from the Monero timings (blockTimeReal x confirmTarget): that is how long it
168
- // takes to gather the confirmations of the target, and declaring the wait expired before that would be lying
169
- // about the money. Both numbers are overridable by the `watch` option.
142
+ // from numbers in the code: the rate is the same as the page's and the timeout is blockTimeReal x confirmTarget,
143
+ // so the wait is never declared expired before the target's confirmations can gather. Both are overridable by
144
+ // the `watch` option.
170
145
  const positive = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Number(v) : null);
171
146
  const watchOf = (options) => {
172
147
  const w = (options && options.watch) || {};
@@ -208,7 +183,6 @@ export function buildConfig(options) {
208
183
  const chosen = chains.find((c) => c.id === options.settlement.chain) || null;
209
184
  if (!chosen) fail("bad-input", { field: "settlement.chain", known: chains.map((c) => c.id) });
210
185
  const rawChain = engine.config.CHAINS.find((c) => c.id === options.settlement.chain) || {};
211
- const routes = routesOf(options);
212
186
  const watch = watchOf(options);
213
187
  const endpoints = endpointsOf(rawChain, options);
214
188
  const nodes = nodesOf(options, options.xmrNetwork);
@@ -249,7 +223,6 @@ export function buildConfig(options) {
249
223
  chains,
250
224
  xmrNetworks,
251
225
  assetsBase: options.assetsBase,
252
- apiBase: options.apiBase,
253
226
  mode: options.mode,
254
227
  limits: {
255
228
  // SIZE LIMITS COME WITH THE LIVE QUOTE, NOT FROM A FILE: the provider node declares them, and different
@@ -268,25 +241,15 @@ export function buildConfig(options) {
268
241
  xmrConfirmations: engine.config.MONERO.confirmTarget ?? 10,
269
242
  xmrBlockTimeSec: Math.round((engine.config.MONERO.blockTimeReal ?? 120000) / 1000),
270
243
  readyLeadWarnSec: guards.readyLeadWarnSec ?? null,
271
- // THE PRICE POLL RATE AND THE REQUEST TIMEOUT - from the engine's settings, not from numbers in the SDK:
272
- // two numbers in two places would silently diverge, and polling would become more frequent than the
273
- // backend allows.
274
- quotePollMs: engine.config.API.pollMs ?? 5000,
275
- httpTimeoutMs: engine.config.API.timeoutMs ?? 20000,
276
244
  },
277
245
  routing: { providers: known, prefer },
278
- // NAMED PATHS AND ADDRESSES: `route` substitutes parameters, `endpoints` carries the already-resolved values
279
- // (the default from the registry, the override from the options).
280
- routes: { ...routes },
246
+ // NAMED ADDRESSES: `endpoints` carries the already-resolved values (the default from the registry, the
247
+ // override from the options).
281
248
  endpoints,
282
249
  // THE NODES THE XMR ARRIVAL IS CHECKED AGAINST - by network, with the defaults from the verified list and any
283
250
  // overrides the caller (or the user) brought. `nodesFor` is the pick for one network.
284
251
  xmrNodes: nodes,
285
252
  nodesFor: (network) => (nodes && nodes[network]) ? nodes[network] : [],
286
- route: (name, params) => {
287
- if (!(name in routes)) fail("bad-input", { field: "route", unknown: name, known: Object.keys(routes) });
288
- return pathOf(routes[name], params);
289
- },
290
253
  codes: { steps: STEP_CODES, checks: CHECK_CODES, errors: ERROR_CODES },
291
254
  };
292
255
  }
package/src/engine.mjs CHANGED
@@ -25,9 +25,9 @@ export * as recoveryFile from "../engine/recovery/recoveryFile.js";
25
25
  export * as halves from "../engine/atomic/halves.js";
26
26
  export * as orderContext from "../engine/atomic/orderContext.js";
27
27
  export * as order from "../engine/atomic/order.js";
28
- // HALF TRANSFER: the byte format and opening are the very same ones the page worker uses
29
- // (www/js/atomic/order-worker.js). The core keeps no copy of the format: the commitment is computed over those
30
- // exact bytes, and a second copy would silently drift from the calldata.
28
+ // HALF TRANSFER: the byte format and opening are the very same ones the engine's order builder uses. The core
29
+ // keeps no copy of the format: the commitment is computed over those exact bytes, and a second copy would
30
+ // silently drift from the calldata.
31
31
  export * as halfenc from "../engine/atomic/halfenc.js";
32
32
  // The engine's EVM layer: talking to the chain (order terms, sending, reading) - through this seam.
33
33
  export * as evm from "../engine/evm/index.js";
@@ -37,9 +37,9 @@ export * as evm from "../engine/evm/index.js";
37
37
  export * as dex from "../engine/evm/dex.js";
38
38
  // THE DEAL ENGINE NO LONGER LIVES IN www/js (#32, wave 3): the order flow moved into the package
39
39
  // (sdk/src/swap-flow.mjs) and is declared in sdk/index.d.ts. The page reaches it through the bridge, so the
40
- // mirror no longer carries core/swap-flow.js - what stays in the seam is the ORDER CLIENT (the half worker),
41
- // the ORDER QUOTE source and the shared CLAIM GAS LIMIT that the moved flow reads through this same seam.
42
- export * as orderClient from "../engine/atomic/order-client.js";
40
+ // mirror no longer carries core/swap-flow.js - what stays in the seam is the ORDER QUOTE source and the shared
41
+ // CLAIM GAS LIMIT that the moved flow reads through this same seam. The order side is built by engine/atomic/order.js.
42
+
43
43
  export * as rfqSource from "../engine/core/rfqSource.js";
44
44
  export * as claimGas from "../engine/evm/claimGas.js";
45
45
  export * as escrow from "../engine/evm/escrow.js";
@@ -55,3 +55,6 @@ export * as xmrAddress from "../engine/monero/address.js";
55
55
  // the engine mirror. check-sdk-engine reddens on any drift, so the two cannot diverge silently.
56
56
  export * as xmrUnlock from "../engine/monero/unlock.js";
57
57
  export * as xmrScan from "../engine/monero/scan.js";
58
+ // THE ADDRESS AND ITS PUBLIC KEYS, for the arrival check: the view secret and spend key are bound to the address,
59
+ // not merely used as labels.
60
+ export * as xmrArrivalRead from "../engine/monero/arrivalRead.js";
@@ -2,7 +2,7 @@
2
2
  //
3
3
  // THE FEE = THE PRICE OF A BYTE × THE SIZE OF THE TRANSACTION. The price belongs to the network, not to the wallet:
4
4
  // on Monero it moves with the median block load, so it is not set but ASKED - `get_fee_estimate` returns a price per
5
- // kilobyte for several priorities. The size is known only after the transaction is assembled (rings, inputs, outputs),
5
+ // byte for several priorities. The size is known only after the transaction is assembled (rings, inputs, outputs),
6
6
  // so this module answers the PRICE, and `feeForBytes` is the only arithmetic that turns it into a sum.
7
7
  //
8
8
  // The page used to learn the fee only after signing; a person deciding whether to withdraw should see it before.
@@ -59,14 +59,21 @@ export async function moneroFeeEstimate({ url, fetchImpl = globalThis.fetch, tim
59
59
  signal: controller ? controller.signal : undefined,
60
60
  });
61
61
  } catch (error) {
62
+ if (timer) clearTimeout(timer);
62
63
  const aborted = error && (error.name === "AbortError" || error.code === "ABORT_ERR");
63
64
  return { ok: false, why: aborted ? "timeout" : "unreachable" };
64
- } finally {
65
+ }
66
+ if (!response || !response.ok) {
65
67
  if (timer) clearTimeout(timer);
68
+ return { ok: false, why: "http", status: response ? response.status : null };
66
69
  }
67
- if (!response || !response.ok) return { ok: false, why: "http", status: response ? response.status : null };
68
70
  let body = null;
69
- try { body = await response.json(); } catch { return { ok: false, why: "not-json" }; }
71
+ // THE TIMER COVERS THE BODY TOO. The headers do not make the answer complete.
72
+ try { body = await response.json(); } catch {
73
+ if (timer) clearTimeout(timer);
74
+ return { ok: false, why: "not-json" };
75
+ }
76
+ if (timer) clearTimeout(timer);
70
77
  if (!body || body.error) return { ok: false, why: "rpc", rpc: body && body.error ? body.error.code ?? null : null };
71
78
  const result = body.result || {};
72
79
  // THE DAEMON'S OWN UNITS. `fee` and each entry of `fees` are atomic units PER BYTE; `quantization_mask` is the
package/src/http.mjs CHANGED
@@ -60,7 +60,10 @@ export function createHttp({ apiBase, fetchImpl = null, timeoutMs = 20_000 }) {
60
60
  const res = await impl(apiBase + path, init);
61
61
  if (!res || typeof res.ok !== "boolean") throw new SdkError("server-unavailable", { why: "bad-response" });
62
62
  let parsed = null;
63
- try { parsed = await res.json(); } catch { parsed = null; }
63
+ // A BODY CUT BY THE TIMEOUT IS NOT AN EMPTY ANSWER. Returning null made a broken response look like a
64
+ // service that answered with no data; the caller then reported the wrong refusal.
65
+ try { parsed = await res.json(); }
66
+ catch { throw new SdkError("server-unavailable", { why: "body" }); }
64
67
  return { ok: res.ok, status: res.status, body: parsed };
65
68
  } catch (error) {
66
69
  if (error instanceof SdkError) throw error;
package/src/index.mjs CHANGED
@@ -1,7 +1,6 @@
1
1
  // THE SDK ENTRY POINT. Assembles the facades and holds rules common to all: no DOM, no texts, no windows.
2
2
  import { buildConfig } from "./config.mjs";
3
3
  import { factoryCodesForChain, implementationCodesForChain } from "./factoryPolicy.mjs";
4
- import { createHttp } from "./http.mjs";
5
4
  import { createQuotes } from "./quotes.mjs";
6
5
  import { createPreflight } from "./preflight.mjs";
7
6
  import { createRecovery } from "./recovery.mjs";
@@ -26,7 +25,6 @@ import { ERROR_CODES, ERROR_META, ERROR_SIDES, STEP_CODES, CHECK_CODES } from ".
26
25
  // value that looks like data. The stage number is named so the interface understands what to expect
27
26
  // (sdk/README.md, "Stages").
28
27
  const stageOf = {
29
- "quotes.firm": 2,
30
28
  "swaps.start": 2,
31
29
  "swaps.list": 2,
32
30
  "swaps.get": 2,
@@ -57,16 +55,18 @@ const normalizeOptions = (options) => {
57
55
  }
58
56
  if (o.fetch !== undefined && typeof o.fetch !== "function") fail("bad-input", { field: "fetch" });
59
57
  if (o.now !== undefined && typeof o.now !== "function") fail("bad-input", { field: "now" });
58
+ // THE DIRECT-NODE OPTIONS ARE RETIRED, NOT SILENTLY IGNORED. A caller that still brings `apiBase`, `routes` or
59
+ // `serverAuth` is asking for a surface this release no longer carries; ignoring the field would make the old
60
+ // configuration look accepted while the request never happens.
61
+ for (const retired of ["apiBase", "routes", "serverAuth"]) {
62
+ if (o[retired] !== undefined) fail("bad-input", { field: retired, why: "retired" });
63
+ }
60
64
  if (o.routing !== undefined) {
61
65
  const r = o.routing;
62
66
  if (!r || typeof r !== "object" || (r.prefer !== undefined && !Array.isArray(r.prefer))) fail("bad-input", { field: "routing" });
63
67
  }
64
- // PATHS AND ADDRESSES: the shape is checked here, the meaning - when the configuration is built (where the
65
- // registry's defaults live). They must not be silently dropped: an override nobody knows about is worse than
66
- // a refusal.
67
- if (o.routes !== undefined && (!o.routes || typeof o.routes !== "object" || Array.isArray(o.routes))) {
68
- fail("bad-input", { field: "routes" });
69
- }
68
+ // PATHS AND ADDRESSES: only ADDRESSES remain configurable. The retired node routes are not part of the SDK any
69
+ // more; `endpoints` is checked here and resolved in the configuration.
70
70
  if (o.endpoints !== undefined && (!o.endpoints || typeof o.endpoints !== "object" || Array.isArray(o.endpoints))) {
71
71
  fail("bad-input", { field: "endpoints" });
72
72
  }
@@ -121,11 +121,6 @@ const normalizeOptions = (options) => {
121
121
  if (o.denylist !== undefined && o.denylist !== null) {
122
122
  if (!Array.isArray(o.denylist) || o.denylist.some((a) => typeof a !== "string")) fail("bad-input", { field: "denylist" });
123
123
  }
124
- // A PASS TO OUR SERVICE - A SEAM FROM OUTSIDE, like the wallet: only a wallet can sign the sign-in message
125
- // (www/js/evm/auth.js, signIn), and requiring it of the core would mean opening windows and signing messages
126
- // inside the SDK. The core receives a ready pass and presents it. A missing pass is NOT an option error: the
127
- // "server" step then answers with the app's refusal (401) under a named code.
128
- if (o.serverAuth !== undefined && typeof o.serverAuth !== "function") fail("bad-input", { field: "serverAuth" });
129
124
  // YOUR OWN SWAP RECORD - A CAPABILITY, NOT A REQUIREMENT. By default the core builds the record and the order
130
125
  // side itself (record.mjs + order.mjs) and uses that side both for the record and for the lock terms. The
131
126
  // function is for whoever wants to bring THEIR OWN side; it must be a function, otherwise it is a typo, not a
@@ -143,17 +138,12 @@ const normalizeOptions = (options) => {
143
138
  return {
144
139
  settlement: { chain: settlement.chain, vm: settlement.vm },
145
140
  xmrNetwork: o.xmrNetwork,
146
- apiBase: typeof o.apiBase === "string" && o.apiBase ? o.apiBase : null,
147
141
  assetsBase: typeof o.assetsBase === "string" && o.assetsBase ? o.assetsBase : "/",
148
142
  mode,
149
143
  storage: o.storage || null,
150
144
  fetch: o.fetch || null,
151
145
  now: o.now || null,
152
146
  routing: o.routing || null,
153
- // PATHS AND ADDRESSES PASS ON AS THEY ARE: their meaning is worked out when the configuration is built,
154
- // where the registry's defaults live. They must not be dropped here - an override nobody knows about is
155
- // worse than a refusal.
156
- routes: o.routes || null,
157
147
  endpoints: o.endpoints || null,
158
148
  nodes: o.nodes === undefined ? null : o.nodes,
159
149
  addNodes: o.addNodes === undefined ? null : o.addNodes,
@@ -165,7 +155,6 @@ const normalizeOptions = (options) => {
165
155
  knownFactoryCodes: o.knownFactoryCodes === undefined ? null : o.knownFactoryCodes,
166
156
  knownImplementationCodes: o.knownImplementationCodes === undefined ? null : o.knownImplementationCodes,
167
157
  denylist: o.denylist === undefined ? null : o.denylist,
168
- serverAuth: o.serverAuth || null,
169
158
  watch: o.watch || null,
170
159
  createRecord: o.createRecord || null,
171
160
  };
@@ -176,15 +165,13 @@ export function createNinsei(options) {
176
165
  const config = buildConfig({
177
166
  settlement: o.settlement,
178
167
  xmrNetwork: o.xmrNetwork,
179
- apiBase: o.apiBase,
180
168
  assetsBase: o.assetsBase,
181
169
  mode: o.mode,
182
170
  routing: o.routing,
183
- routes: o.routes,
184
- endpoints: o.endpoints,
185
- watch: o.watch,
186
- nodes: o.nodes,
187
- addNodes: o.addNodes,
171
+ endpoints: o.endpoints,
172
+ watch: o.watch,
173
+ nodes: o.nodes,
174
+ addNodes: o.addNodes,
188
175
  });
189
176
  // THE NETWORK'S PINS REACH THE CORE. The bridge passed them explicitly; a caller with default options did not,
190
177
  // so the factory policy was null and the quote could name any factory. An explicit caller list still wins.
@@ -209,7 +196,6 @@ export function createNinsei(options) {
209
196
  // ONE CLIENT, ONE STORE - WITHOUT A PROCESS-WIDE EXCLUSIVE BINDING. Each facade gets a store over its own
210
197
  // adapter; two clients with different storages coexist and neither can take over the other's records.
211
198
  const store = engine.store.createStore(o.storage || engine.store.storage());
212
- const http = createHttp({ apiBase: config.apiBase, fetchImpl: o.fetch, timeoutMs: config.limits.httpTimeoutMs });
213
199
  // THE CHAIN READ AND THE ALLOW-LIST GO INTO THE QUOTE CHECK: without the read the signature certifies itself,
214
200
  // so the same evmCall seam the lock and the actions use is handed to the quotes too.
215
201
  const providerAllowed = (() => {
@@ -220,12 +206,12 @@ export function createNinsei(options) {
220
206
  return (provider) => set.has(String(provider).toLowerCase());
221
207
  })();
222
208
  // THE DENYLIST IS LOWER-CASED ONCE HERE, so the comparison rule (case-insensitive membership) lives in ONE
223
- // place and BOTH the quote check (`quotes.firm`) and the lock check (`swaps.start`) use it. An empty list is
209
+ // place and BOTH the quote check (`firmRelay`) and the lock check (`swaps.start`) use it. An empty list is
224
210
  // "no policy" (null), not an empty check.
225
211
  const denylist = Array.isArray(o.denylist) && o.denylist.length
226
212
  ? new Set(o.denylist.map((a) => String(a).toLowerCase()))
227
213
  : null;
228
- const quotes = createQuotes({ config, http, now: o.now || (() => Date.now()), evmCall: o.evmCall || null,
214
+ const quotes = createQuotes({ config, now: o.now || (() => Date.now()), evmCall: o.evmCall || null,
229
215
  evmCode: o.evmCode || null, evmBlock: o.evmBlock || null,
230
216
  providerAllowed, knownFactoryCodes, knownImplementationCodes,
231
217
  denylist });
@@ -244,7 +230,7 @@ export function createNinsei(options) {
244
230
  config,
245
231
  wallet,
246
232
  preflight,
247
- recovery: createRecovery({ http, config }),
233
+ recovery: createRecovery(),
248
234
 
249
235
  // THE ORDER: checking the counterparty's side and the joint address. Both checks - BEFORE signing: after it
250
236
  // there is nothing to fix.
@@ -273,17 +259,8 @@ export function createNinsei(options) {
273
259
  },
274
260
  sim,
275
261
  quotes: {
276
- // LIVE INDICATIVE QUOTES. The subscription delivers data on every poll tick and is removed by the function
277
- // watch returned; the last listener to leave stops the polling.
278
- watch: (request, onSnapshot) => quotes.watch(request, onSnapshot),
279
- snapshot: () => quotes.snapshot(),
280
- // A firm quote is stage 2: it is signed with a key and lives in the order protocol, not in a market snapshot.
281
- // A FIRM QUOTE: accepted only with a confirmed provider signature.
282
- firm: (request) => quotes.firm(request),
283
- // THE RELAY PATH: one recovery key in, signed orderQuote and its maker view half out.
262
+ // THE ONLY QUOTE PATH: one recovery key in, a signed orderQuote and the maker's view half out.
284
263
  firmRelay: (request) => quotes.firmRelay(request),
285
- // A REVERSE TICKET: the node signs it; its claim tip is checked here before the caller sees it.
286
- sale: (request) => quotes.sale(request),
287
264
  },
288
265
  // READING STATE WORKS, STARTING IS NAMED HONESTLY: list/get raise swaps from storage after a page reload;
289
266
  // start holds the step order and runs into the step that creates the record (stage 2).
@@ -292,24 +269,26 @@ export function createNinsei(options) {
292
269
  // non-existent side), and the network is needed to build the shared Monero address.
293
270
  // THE CHAIN READER GOES INTO THE SWAP START: it will check the escrow address, the order state and the fee
294
271
  // before signing.
295
- // THE PATHS, THE POLL TIMINGS AND THE PASS GO INTO THE START: without the configuration the "server" step
296
- // would not know where to knock, and without the pass there is nothing to present to the service (and that
297
- // is a refusal with a CODE, not an invented path).
298
- swaps: createSwaps({ preflight, http, mode: o.mode, xmrNetwork: o.xmrNetwork, call: o.evmCall, store,
272
+ // THE CHAIN READER GOES INTO THE SWAP START: it will check the escrow address, the order state and the fee
273
+ // before signing. The Monero watch reads the chain through the same seam; there is no backend watcher.
274
+ swaps: createSwaps({ preflight, mode: o.mode, xmrNetwork: o.xmrNetwork, call: o.evmCall, now: o.now || null, evmBlock: o.evmBlock || null, store,
299
275
  // THE LOG SEAM FOR THE DECLINE CHECK: the watch asks the escrow for its `Declined` event on every tick, so
300
276
  // a declined order stops the wait at once instead of running to `xmr-timeout`.
301
277
  logs: o.evmLogs || null,
302
- config, auth: o.serverAuth, denylist, watch: o.watch,
278
+ config, denylist, watch: o.watch,
303
279
  // THE RECORD IS BUILT HERE ITSELF, and one brought from outside is only the caller's preference.
304
280
  createRecord: o.createRecord }),
305
281
  // XMR WITHDRAWAL: parsing the file and requesting data work; the withdrawal itself is named (the Monero
306
282
  // wallet as an adapter).
307
- sweep: createSweep({ http, config, call: o.evmCall }),
283
+ sweep: createSweep({ call: o.evmCall }),
308
284
  });
309
285
  }
310
286
 
311
287
  export { SdkError, ERROR_CODES, ERROR_META, ERROR_SIDES, STEP_CODES, CHECK_CODES };
312
288
  export { SDK_VERSION } from "./version.mjs";
289
+ // THE QUOTE LIFETIME AND THE START MARGIN ARE ONE PUBLIC DEFAULT. A node imports the lifetime, so its signed quote
290
+ // cannot be shorter than the margin the SDK enforces before it opens the wallet.
291
+ export { LOCK_START_MARGIN_SEC, DEFAULT_ORDER_QUOTE_TTL_SEC } from "./quotePolicy.mjs";
313
292
 
314
293
  // THE LEVEL WALK IS ON THE PACKAGE SURFACE. A maker publishes a level set (chunks of volume with their own prices)
315
294
  // and both the node and the client compute a firm price by WALKING it - the client must reach the SAME price before
@@ -229,6 +229,29 @@ export async function kyberUnsignedOrder({ params, chainId = null, fetchImpl = n
229
229
  if (typeNames !== expectedNames) return refusal("kyber-bad-response", { where: "sign-message", field: "types" });
230
230
  const missing = kyberOrderMissingFields(message);
231
231
  if (missing.length) return refusal("kyber-bad-response", { where: "sign-message", missing });
232
+ // THE SERVICE MUST SIGN THE ORDER WE ASKED FOR. A receiver, maker or asset it chooses for us is a valid order
233
+ // for someone else; compare every field the request fixed before the typed data reaches the wallet.
234
+ const addresses = ["maker", "makerAsset", "takerAsset", "receiver"];
235
+ for (const field of addresses) {
236
+ if (String(message[field] || "").toLowerCase() !== String(params[field] || "").toLowerCase()) {
237
+ return refusal("kyber-bad-response", { where: "sign-message", field });
238
+ }
239
+ }
240
+ for (const field of ["makingAmount", "takingAmount"]) {
241
+ if (String(message[field]) !== String(params[field])) {
242
+ return refusal("kyber-bad-response", { where: "sign-message", field });
243
+ }
244
+ }
245
+ // A REQUEST THAT LIMITS WHO MAY FILL THE ORDER MUST NOT BE WIDENED. The signed field is one address; zero means
246
+ // anyone. When the request fixed a list, the service must name one of its members (a narrower choice is fine,
247
+ // "anyone" is not).
248
+ const allowed = params.allowedSenders === undefined || params.allowedSenders === null
249
+ ? null
250
+ : (Array.isArray(params.allowedSenders) ? params.allowedSenders : [params.allowedSenders])
251
+ .map((value) => String(value || "").toLowerCase());
252
+ if (allowed && allowed.length && !allowed.includes(String(message.allowedSender || "").toLowerCase())) {
253
+ return refusal("kyber-bad-response", { where: "sign-message", field: "allowedSender" });
254
+ }
232
255
  let digest;
233
256
  try {
234
257
  digest = kyberOrderDigestHex({ order: message, chainId: id, contract });
package/src/lock.mjs CHANGED
@@ -98,6 +98,7 @@ export async function send(request, wallet, deps = {}) {
98
98
  return await evm.fundOrder({
99
99
  ...canonical,
100
100
  call: reader,
101
+ onPredicted: deps.onPredicted,
101
102
  send: (tx) => wallet.send({ ...tx, chainId: canonical.chainId, from: canonical.locker }),
102
103
  // NORMALISING THE RECEIPT ARGUMENT'S SHAPE - HERE, AT THE CORE'S BOUNDARY, NOT AT EVERY CALLER.
103
104
  //