@ninsei-labs/sdk 0.55.4 → 0.57.2

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 (68) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/LICENSE-POLICY.md +9 -2
  3. package/README.md +51 -24
  4. package/THIRD_PARTY_NOTICES.md +174 -0
  5. package/assets/vendors/MANIFEST.json +18 -0
  6. package/assets/vendors/sdk/sdk-browser.js +2059 -2
  7. package/engine/atomic/dleq2.js +187 -22
  8. package/engine/atomic/order.js +21 -3
  9. package/engine/core/config.js +17 -24
  10. package/engine/core/deployments.generated.js +103 -0
  11. package/engine/core/store.js +25 -4
  12. package/engine/core/swap.js +54 -52
  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 +24 -26
  17. package/engine/evm/funding.js +8 -3
  18. package/engine/evm/index.js +2 -4
  19. package/engine/evm/session.js +3 -3
  20. package/engine/monero/scan.js +101 -22
  21. package/engine/recovery/restore.js +8 -8
  22. package/engine/sdk/bridge.js +3 -6
  23. package/index.d.ts +57 -27
  24. package/package.json +25 -8
  25. package/src/actions.mjs +52 -9
  26. package/src/adapters/evm-wallet.mjs +24 -5
  27. package/src/adapters/index.d.ts +66 -0
  28. package/src/adapters/index.mjs +0 -6
  29. package/src/codes.mjs +14 -0
  30. package/src/config.mjs +1 -0
  31. package/src/engine.mjs +6 -6
  32. package/src/feeEstimate.mjs +11 -4
  33. package/src/http.mjs +4 -1
  34. package/src/index.mjs +4 -3
  35. package/src/legs/kyber.mjs +23 -0
  36. package/src/lock.mjs +2 -1
  37. package/src/order.mjs +108 -20
  38. package/src/primitives.mjs +4 -5
  39. package/src/probes.mjs +9 -3
  40. package/src/provider/envFile.mjs +11 -1
  41. package/src/public/networks.d.ts +45 -0
  42. package/src/public/networks.mjs +10 -1
  43. package/src/public/order.d.ts +4 -0
  44. package/src/public/recovery.d.ts +40 -54
  45. package/src/public/recovery.mjs +2 -8
  46. package/src/public/xmr.d.ts +14 -3
  47. package/src/public/xmr.mjs +1 -1
  48. package/src/quoteEip712Spec.mjs +9 -1
  49. package/src/quotes.mjs +118 -49
  50. package/src/record.mjs +3 -3
  51. package/src/recovery-key.mjs +161 -237
  52. package/src/relayFeatures.mjs +25 -13
  53. package/src/relayFirmClient.mjs +69 -6
  54. package/src/relayQuote.mjs +87 -10
  55. package/src/relayRequest.mjs +12 -3
  56. package/src/relayView.mjs +3 -3
  57. package/src/swap-flow.mjs +153 -67
  58. package/src/swaps.mjs +346 -174
  59. package/src/sweep-restore.mjs +14 -6
  60. package/src/sweep.mjs +34 -11
  61. package/src/version.mjs +1 -1
  62. package/src/xmr-arrival.mjs +55 -24
  63. package/assets/vendors/atomic/atomic-browser.js +0 -24
  64. package/engine/atomic/order-client.js +0 -56
  65. package/engine/atomic/order-worker.js +0 -156
  66. package/engine/evm/asyncExec.js +0 -577
  67. package/engine/evm/asyncLegs.js +0 -308
  68. package/src/adapters/node-test-evm-wallet.mjs +0 -357
@@ -144,17 +144,72 @@ export function derivedOutputKey(derivation, outputIndex, spendPubHex) {
144
144
 
145
145
  // Helper: the tx public key sits in the transaction extra, tag 0x01, 32 bytes. We read extra as is - the same
146
146
  // parse the wallet does. extra arrives from the node as a BYTE ARRAY (not hex), so both forms are accepted.
147
- export function txPublicKeyFromExtra(extra) {
147
+ //
148
+ // MONERO'S EXTRA IS A TAGGED SEQUENCE, NOT A FIXED LAYOUT. The tags we must know here:
149
+ // 0x00 padding - a run of zero bytes (the tag itself is one of them), no length field;
150
+ // 0x01 public key - 32 bytes;
151
+ // 0x02 nonce - varint length, then that many bytes;
152
+ // 0x03 merge mining - a length-prefixed string holding varint depth + 32-byte hash;
153
+ // 0x04 additional - varint count, then count * 32-byte public keys, ONE PER OUTPUT INDEX.
154
+ // The old parser treated 0x00 as an additional key and skipped it with `1 + b[i+1]`, and it stopped at 0x04.
155
+ // A subaddress payment in a mixed transaction then looked absent: the main key does not derive that output.
156
+ function readExtraVarint(bytes, at) {
157
+ let value = 0n;
158
+ let shift = 0n;
159
+ let i = at;
160
+ for (let count = 0; count < 10 && i < bytes.length; count++) {
161
+ const byte = bytes[i++];
162
+ value |= BigInt(byte & 0x7f) << shift;
163
+ if ((byte & 0x80) === 0) return { value, next: i };
164
+ shift += 7n;
165
+ }
166
+ return null;
167
+ }
168
+
169
+ /** The transaction keys in `extra`: the main key(s) and the per-output additional keys (tag 0x04). */
170
+ export function txKeysFromExtra(extra) {
148
171
  const b = Array.isArray(extra) ? Uint8Array.from(extra) : hexToBytes(extra);
172
+ const txPublicKeys = [];
173
+ const additionalPublicKeys = [];
149
174
  let i = 0;
150
175
  while (i < b.length) {
151
- const tag = b[i];
152
- if (tag === 0x01) return bytesToHex(b.subarray(i + 1, i + 33));
153
- if (tag === 0x02) { i += 1 + b[i + 1]; continue; } // nonce
154
- if (tag === 0x00) { i += 1 + b[i + 1]; continue; } // additional public key
155
- return null; // unknown tag: we do not guess
176
+ const tag = b[i++];
177
+ if (tag === 0x00) {
178
+ // Padding is a run of zeros; the next non-zero byte is the next tag (or the end).
179
+ while (i < b.length && b[i] === 0x00) i++;
180
+ continue;
181
+ }
182
+ if (tag === 0x01) {
183
+ if (i + 32 > b.length) break;
184
+ txPublicKeys.push(bytesToHex(b.subarray(i, i + 32)));
185
+ i += 32;
186
+ continue;
187
+ }
188
+ if (tag === 0x02 || tag === 0x03) {
189
+ const size = readExtraVarint(b, i);
190
+ if (!size || size.value > BigInt(b.length - size.next)) break;
191
+ i = size.next + Number(size.value);
192
+ continue;
193
+ }
194
+ if (tag === 0x04) {
195
+ const count = readExtraVarint(b, i);
196
+ if (!count || count.value > BigInt(Math.floor((b.length - count.next) / 32))) break;
197
+ i = count.next;
198
+ for (let n = 0; n < Number(count.value); n++) {
199
+ additionalPublicKeys.push(bytesToHex(b.subarray(i, i + 32)));
200
+ i += 32;
201
+ }
202
+ continue;
203
+ }
204
+ // An unknown tag is not a guess: stop before it and use only what was parsed unambiguously.
205
+ break;
156
206
  }
157
- return null;
207
+ return { txPublicKeys, additionalPublicKeys };
208
+ }
209
+
210
+ /** The first tx public key in `extra`, or null. Kept for callers that only need the primary key. */
211
+ export function txPublicKeyFromExtra(extra) {
212
+ return txKeysFromExtra(extra).txPublicKeys[0] || null;
158
213
  }
159
214
 
160
215
  // Amount and mask decryption. THE ENCODING IS CHOSEN BY THE RingCT TYPE, not by a boolean:
@@ -201,20 +256,32 @@ export function decodeMask(ecdhMaskHex, scalarLE, rctType) {
201
256
  }
202
257
 
203
258
  // MAIN: parse a transaction and return OUR outputs (their indices, keys and amounts).
204
- // txView - { txPublicKey, vout: [{key, index}], ecdhAmounts: [...], ecdhMasks: [...], outPk: [...], rctVersion }
205
- export function findOurOutputs({ txPublicKey, viewSecretHex, spendPubHex, outputs, ecdhAmounts = [], ecdhMasks = [], outPk = [], rctVersion = 2 }) {
206
- if (!txPublicKey) throw new Error("the transaction has no public key (extra tag 0x01) - nothing to parse");
259
+ // txView - { txPublicKey(s), additionalPublicKeys, vout: [{key, index}], ecdhAmounts: [...], ecdhMasks: [...], outPk: [...], rctVersion }
260
+ //
261
+ // ADDITIONAL KEYS ARE PER OUTPUT, NOT PER TRANSACTION. A transaction paying several subaddresses carries tag 0x04:
262
+ // key i belongs to output i. Trying only the main key misses those outputs; trying every additional key against
263
+ // every output would be wrong in the other direction and can match another recipient's output. The main key is
264
+ // tried first, then this output's own additional key, exactly as the wallet does.
265
+ export function findOurOutputs({ txPublicKey = null, txPublicKeys = null, additionalPublicKeys = [], viewSecretHex, spendPubHex, outputs, ecdhAmounts = [], ecdhMasks = [], outPk = [], rctVersion = 2 }) {
266
+ const primaryKeys = Array.isArray(txPublicKeys) ? txPublicKeys.filter(Boolean)
267
+ : (txPublicKey ? [txPublicKey] : []);
268
+ const additional = Array.isArray(additionalPublicKeys) ? additionalPublicKeys : [];
269
+ if (!primaryKeys.length && !additional.length) throw new Error("the transaction has no public key (extra tag 0x01/0x04) - nothing to parse");
207
270
  // The key form is tried EXPLICITLY; the winner's name goes up so the log shows what was used. If none matched,
208
271
  // the first meaningful form is returned, not nothing.
209
272
  const usable = viewSecretCandidates(viewSecretHex).filter(([, v]) => v !== null);
210
273
  const first = usable[0] || ["unparsed", null];
211
274
  for (const [form, secret] of usable) {
212
- const derivation = keyDerivation(txPublicKey, secret);
275
+ const primaryDerivations = primaryKeys.map((key) => keyDerivation(key, secret));
213
276
  const found = [];
214
277
  for (const o of outputs) {
215
- const scalar = hashToScalar(derivation, varint(o.index));
216
- const derived = derivedOutputKey(derivation, o.index, spendPubHex);
217
- if (derived.toLowerCase() === String(o.key).toLowerCase()) {
278
+ // The main keys first, then only THIS output's additional key.
279
+ const candidates = primaryDerivations.slice();
280
+ if (additional[o.index]) candidates.push(keyDerivation(additional[o.index], secret));
281
+ for (const derivation of candidates) {
282
+ const scalar = hashToScalar(derivation, varint(o.index));
283
+ const derived = derivedOutputKey(derivation, o.index, spendPubHex);
284
+ if (derived.toLowerCase() !== String(o.key).toLowerCase()) continue;
218
285
  // The amount decryption uses THIS output's SCALAR, least-significant first.
219
286
  const amount = ecdhAmounts[o.index] ? decodeAmount(ecdhAmounts[o.index], scalarToBytesLE(scalar), rctVersion) : null;
220
287
  // THE COMMITMENT CHECK: outPk[i] = mask*G + amount*H. A node can flip a bit of the encrypted amount
@@ -230,13 +297,14 @@ export function findOurOutputs({ txPublicKey, viewSecretHex, spendPubHex, output
230
297
  amountVerified = amountMaskCommitment(amount, mask).toLowerCase() === String(outPk[o.index]).replace(/^0x/, "").toLowerCase();
231
298
  } catch { amountVerified = false; }
232
299
  }
233
- found.push({ index: o.index, key: o.key, amountAtomic: amount, maskAtomic: mask, amountVerified });
300
+ found.push({ index: o.index, key: o.key, amountAtomic: amount, maskAtomic: mask, amountVerified, derivation: bytesToHex(derivation) });
301
+ break; // one derivation per output; a later key cannot make it ours twice
234
302
  }
235
303
  }
236
- if (found.length) return { derivation: bytesToHex(derivation), outputs: found, viewKeyForm: form };
304
+ if (found.length) return { derivation: found[0].derivation, outputs: found, viewKeyForm: form };
237
305
  }
238
306
  return {
239
- derivation: first[1] === null ? null : bytesToHex(keyDerivation(txPublicKey, first[1])),
307
+ derivation: first[1] === null || !primaryKeys.length ? null : bytesToHex(keyDerivation(primaryKeys[0], first[1])),
240
308
  outputs: [],
241
309
  viewKeyForm: first[0],
242
310
  };
@@ -260,10 +328,15 @@ const baseUrl = (value) => {
260
328
  return out;
261
329
  };
262
330
 
263
- export async function fetchBlock(daemonUrl, height, fetchImpl = globalThis.fetch) {
331
+ export async function fetchBlock(daemonUrl, height, fetchImpl = globalThis.fetch, timeoutMs = 8000) {
332
+ // THE DEADLINE COVERS THE BODY, NOT ONLY THE HEADERS. Without a signal a daemon that sends `{` and stops holds
333
+ // the whole scan forever.
334
+ const signal = typeof AbortSignal !== "undefined" && AbortSignal.timeout
335
+ ? AbortSignal.timeout(Math.max(1, Number(timeoutMs) || 8000)) : undefined;
264
336
  const res = await fetchImpl(`${baseUrl(daemonUrl)}/json_rpc`, {
265
337
  method: "POST", headers: { "Content-Type": "application/json" },
266
338
  body: JSON.stringify({ jsonrpc: "2.0", id: "block", method: "get_block", params: { height } }),
339
+ signal,
267
340
  });
268
341
  const j = await res.json();
269
342
  // A BUSY ANSWER IS NOT AN EMPTY BLOCK. The daemon answers BUSY while it is still indexing; a reader that treats
@@ -281,11 +354,14 @@ export async function fetchBlock(daemonUrl, height, fetchImpl = globalThis.fetch
281
354
 
282
355
  // Transactions by hash list. We hit the PATH /get_transactions, not /json_rpc: over JSON-RPC this method
283
356
  // silently returns empty, which looks like "no transactions".
284
- export async function fetchTransactions(daemonUrl, hashes, fetchImpl = globalThis.fetch) {
357
+ export async function fetchTransactions(daemonUrl, hashes, fetchImpl = globalThis.fetch, timeoutMs = 8000) {
285
358
  if (!hashes.length) return [];
359
+ const signal = typeof AbortSignal !== "undefined" && AbortSignal.timeout
360
+ ? AbortSignal.timeout(Math.max(1, Number(timeoutMs) || 8000)) : undefined;
286
361
  const res = await fetchImpl(`${baseUrl(daemonUrl)}/get_transactions`, {
287
362
  method: "POST", headers: { "Content-Type": "application/json" },
288
363
  body: JSON.stringify({ txs_hashes: hashes, decode_as_json: true }),
364
+ signal,
289
365
  });
290
366
  const j = await res.json();
291
367
  // A BUSY ANSWER IS NOT AN EMPTY BLOCK. The daemon says BUSY while it is still indexing; returning [] would turn
@@ -327,8 +403,10 @@ export async function fetchTransactions(daemonUrl, hashes, fetchImpl = globalThi
327
403
  // is taken as a number, LE-hex or BE-hex. The result carries viewKeyForm: the form name that matched.
328
404
  export function matchTransaction(tx, watched, { height = null, tipHeight = null, nowSec = null } = {}) {
329
405
  const out = [];
330
- const txPublicKey = txPublicKeyFromExtra(tx.extra);
331
- if (!txPublicKey) return out; // no key in extra - nothing to look at
406
+ // BOTH KEY LISTS ARE PART OF THE TRANSACTION. A subaddress output carries its own key under tag 0x04; using only
407
+ // `txPublicKeyFromExtra` drops exactly those outputs.
408
+ const keys = txKeysFromExtra(tx.extra);
409
+ if (!keys.txPublicKeys.length && !keys.additionalPublicKeys.length) return out;
332
410
  // WHETHER THE OUTPUT IS LOCKED IS DECIDED HERE, ONCE PER TRANSACTION: all its outputs carry one unlock_time.
333
411
  // A normal transaction (unlock_time = 0) goes as before; the height comes from the block holding the transfer.
334
412
  const blockHeight = height === null || height === undefined ? (tx.block_height ?? null) : height;
@@ -346,7 +424,8 @@ export function matchTransaction(tx, watched, { height = null, tipHeight = null,
346
424
  const rctVersion = (tx.rct_signatures || {}).type || 2;
347
425
  for (const w of watched) {
348
426
  const r = findOurOutputs({
349
- txPublicKey, viewSecretHex: w.viewSecret, spendPubHex: w.spendPub,
427
+ txPublicKeys: keys.txPublicKeys, additionalPublicKeys: keys.additionalPublicKeys,
428
+ viewSecretHex: w.viewSecret, spendPubHex: w.spendPub,
350
429
  outputs, ecdhAmounts, ecdhMasks, outPk, rctVersion: Number(rctVersion) || 1,
351
430
  });
352
431
  if (r.outputs.length) out.push({ address: w.address, index: w.index ?? null, outputs: r.outputs, derivation: r.derivation, viewKeyForm: r.viewKeyForm, unlockTime: Number(tx.unlock_time) || 0, unlock });
@@ -20,8 +20,8 @@ import { swapAddressFromHalves, watchViewSeedHex } from "../monero/swapKeys.js";
20
20
  // carries HALVES, and has NO full spend key: each side has only its half, the second is revealed on chain at ETH
21
21
  // claim. So a v3 file builds a VIEWING wallet; spending becomes possible only after the reveal.
22
22
  //
23
- // deps is needed for testability: in the browser the libraries come from the vendored bundle (loaded dynamically,
24
- // as a static bundle import would break Node runs), in tests they are passed in.
23
+ // deps is needed for testability: the SDK passes its own primitives here, and tests pass their own. There is no
24
+ // second browser bundle for this branch.
25
25
  export async function restoreWalletFromPayload(payload, deps = {}) {
26
26
  const { warnings } = validatePayload(payload);
27
27
  const m = payload.moneroWallet;
@@ -70,14 +70,14 @@ export async function restoreFromHalves(payload, warnings = [], deps = {}) {
70
70
  const libs = deps.halves && deps.addressFromKeys
71
71
  ? { halves: deps.halves, addressFromKeys: deps.addressFromKeys, keccak256: deps.keccak256 }
72
72
  : await (async () => {
73
- const vendor = await import("../../assets/vendors/atomic/atomic-browser.js?v=2c038c56");
73
+ // THE SDK'S OWN PRIMITIVES, NOT A SECOND BROWSER BUNDLE. The five names are the same @noble packages
74
+ // the package already ships, and a separate build of them was exactly the duplicated crypto path this
75
+ // recovery branch used to keep alive.
76
+ const { primitives } = await import("../../src/primitives.mjs");
74
77
  const { createHalves } = await import("../atomic/halves.js");
75
78
  const { addressFromKeys } = await import("../monero/address.js");
76
- const halves = createHalves({
77
- ed25519: vendor.ed25519, secp256k1: vendor.secp256k1,
78
- keccak256: vendor.keccak256, randomBytes: vendor.randomBytes,
79
- });
80
- return { halves, addressFromKeys, keccak256: vendor.keccak256 };
79
+ const halves = createHalves(primitives);
80
+ return { halves, addressFromKeys, keccak256: primitives.keccak256 };
81
81
  })();
82
82
  if (!libs.keccak256) throw new Error("no keccak256: the address cannot be checked without it");
83
83
 
@@ -68,7 +68,7 @@ import { height as nodeHeightValue } from "../monero/node.js";
68
68
 
69
69
  // THE CORE ADDRESS AS A STRING - THE BUILT BUNDLE SHIPPED WITH THE PACKAGE. A relative URL resolves both in the
70
70
  // published `engine/` tree and in the page that serves this shim from `www/js/sdk/`; ?v=<hash> keeps the cache fresh.
71
- const SDK_BUNDLE = new URL("../../assets/vendors/sdk/sdk-browser.js?v=69d79c13", import.meta.url).href;
71
+ const SDK_BUNDLE = new URL("../../assets/vendors/sdk/sdk-browser.js?v=fa7dc71a", import.meta.url).href;
72
72
 
73
73
  // A NAMED SEAM FOR CHECKS - THE SAME TECHNIQUE AS sdkBookUse BELOW. The asynchronous path is driven against a
74
74
  // stand-in order book (the demo network has no provider), and the ordinary escrow funding that follows a settled
@@ -121,7 +121,7 @@ function modeOf(chain) {
121
121
  function optionsFor(chain) {
122
122
  return {
123
123
  settlement: { chain: chain.id },
124
- xmrNetwork: MONERO.networkType,
124
+ xmrNetwork: (chain.monero && chain.monero.networkType) || MONERO.networkType,
125
125
  // NO BACKEND BY DEFAULT: a page that needs one passes its base explicitly.
126
126
  assetsBase: "/",
127
127
  mode: modeOf(chain),
@@ -599,8 +599,6 @@ export async function sdkAddressNetwork(address) {
599
599
  // modules, and the screen gets them through the seam, not by a second road into the engine;
600
600
  // * networkFromShape/networkLabel - the Monero address shape and its name: the same format module the core
601
601
  // mirrors (there is no second prefix table);
602
- // * createOrderWorker - the atomic-swap halves worker: the cryptography lives in one place and is called by a
603
- // worker so the main thread does not freeze;
604
602
  // * createSwap/createReverseSwap/activeSwaps - the RECORD of the demo and reverse deal (the record is kept by
605
603
  // the engine; the core exposes its STATE via swaps.list/swaps.progress).
606
604
  // * createSwapWallet - THE FORM'S DEAL WALLET (state between screens, ui/formState.js): the page wallet with
@@ -614,11 +612,10 @@ import { orderGasReservePlan } from "../evm/gasReserve.js";
614
612
  import { quoteDexOut, dexLegVerdict } from "../evm/dex.js";
615
613
  import { toWei } from "../evm/funding.js";
616
614
  import { cachedFeeTerms, feeWeiFor, ensureFeeTerms } from "../evm/fees.js";
617
- import { createOrderWorker } from "../atomic/order-client.js";
618
615
  import { activeSwaps, createSwap, createReverseSwap } from "../core/swap.js";
619
616
 
620
617
  export { evm, networkFromShape };
621
618
  export * as swapCore from "../core/swap.js";
622
619
  export * as moneroNode from "../monero/node.js";
623
- export { networkLabel, probeMode, createSwapWallet, amountInputValue, refreshChainPrices, priceLabel, orderGasReservePlan, quoteDexOut, dexLegVerdict, toWei, cachedFeeTerms, feeWeiFor, ensureFeeTerms, createOrderWorker, activeSwaps, createSwap, createReverseSwap };
620
+ export { networkLabel, probeMode, createSwapWallet, amountInputValue, refreshChainPrices, priceLabel, orderGasReservePlan, quoteDexOut, dexLegVerdict, toWei, cachedFeeTerms, feeWeiFor, ensureFeeTerms, activeSwaps, createSwap, createReverseSwap };
624
621
 
package/index.d.ts CHANGED
@@ -49,7 +49,7 @@ export interface NinseiOptions {
49
49
  * from the node on the CI contour.
50
50
  */
51
51
  xmrNetwork: "mainnet" | "stagenet" | "testnet" | "fakechain";
52
- /** Where to load workers and WASM from (order-worker, the Monero bundles). Default "/". */
52
+ /** Where to load the Monero bundles from. Default "/". */
53
53
  assetsBase?: string;
54
54
  /** Storage for unfinished swaps and sessions. Default - a localStorage adapter, if present. */
55
55
  storage?: StorageAdapter;
@@ -94,11 +94,11 @@ export interface NinseiOptions {
94
94
  */
95
95
  evmCall?: (request: { readonly to: string; readonly data: string }) => Promise<string>;
96
96
  /**
97
- * READING THE CONTRACT CODE FROM OUTSIDE (issue #103): ({ address }) -> hex code. Needed for the factory-code
97
+ * READING THE CONTRACT CODE FROM OUTSIDE (issue #103): (address) -> hex code. Needed for the factory-code
98
98
  * check - `extcodehash` is keccak256 of this code, and the factory a provider names in its registry record is
99
99
  * matched against the interface's known builds. Same rule as evmCall: a read, not a node substitution.
100
100
  */
101
- evmCode?: (request: { readonly address: string }) => Promise<string>;
101
+ evmCode?: (address: string) => Promise<string>;
102
102
  /**
103
103
  * READING THE ESCROW'S LOGS FROM OUTSIDE (issue #40): `({ address, topics, fromBlock, toBlock }) -> logs`, for
104
104
  * the MAKER'S DECLINE. The escrow emits `Declined(claimer)` and keeps NO getter that names it, while `status()`
@@ -110,11 +110,14 @@ export interface NinseiOptions {
110
110
  evmLogs?: EvmLogReader;
111
111
  /**
112
112
  * READING A SETTLEMENT BLOCK FROM OUTSIDE (`(tag) => block`): the claim-tip check needs the chain's current
113
- * `baseFeePerGas`. A missing seam is `quote-tip-unchecked` when a quote carries a non-zero tip; zero tips (the
114
- * buy side) never call it.
113
+ * base and priority fees. A missing seam is `quote-tip-unchecked` when a quote carries a non-zero tip; zero tips
114
+ * (the buy side) never call it.
115
115
  */
116
116
  evmBlock?: (tag?: string) => Promise<{ readonly baseFeePerGas?: string | number | bigint | null;
117
- readonly baseFeeWei?: string | number | bigint | null }>;
117
+ readonly baseFeeWei?: string | number | bigint | null;
118
+ readonly priorityFeePerGas?: string | number | bigint | null;
119
+ readonly maxPriorityFeePerGas?: string | number | bigint | null;
120
+ readonly gasPrice?: string | number | bigint | null }>;
118
121
  /**
119
122
  * THE INTERFACE'S OWN ADMISSION LIST - policy, not proof. The chain (maker registry, providerOf, taken from the
120
123
  * quote) proves whose key signed; this says whom THIS interface trades with at all. An array of provider
@@ -393,7 +396,7 @@ export interface WalletAdapter {
393
396
  * Send a leg transaction (lock, marking ready, claim, refund). The request shape is what this VM calls a transfer;
394
397
  * for EVM it is `{ to, data, value }` and the transaction hash in response.
395
398
  */
396
- send(request: { readonly to: string; readonly data?: string; readonly value?: bigint | number | string }): Promise<string>;
399
+ send(request: { readonly to: string; readonly data?: string; readonly value?: bigint | number | string; readonly gas?: bigint | number | string; readonly chainId?: number; readonly from?: string }): Promise<string>;
397
400
  /**
398
401
  * The transaction receipt: asked ONCE, returns the receipt or null (not in a block yet). The waiting policy is set
399
402
  * by the caller, not the adapter - otherwise two calls would wait differently.
@@ -684,8 +687,6 @@ export interface FirmRelayOffer {
684
687
  readonly recoveryKey: string | { readonly mnemonic: string };
685
688
  /** A fresh salt the client owns; it must equal `order.salt`. Defaults to `order.salt`. */
686
689
  readonly recoverySalt?: string;
687
- /** The v1 index; it is mutually exclusive with `recoverySalt`. */
688
- readonly recoveryIndex?: number;
689
690
  /** The market's chain and asset, for example `421614:ETH`. Derived when exactly one window matches. */
690
691
  readonly market?: string;
691
692
  readonly xmrNetwork?: string;
@@ -713,8 +714,16 @@ export interface FirmRelayAnswer {
713
714
  readonly jointAddress: string;
714
715
  /** The escrow address predicted from the signed quote and the depositor's half. */
715
716
  readonly escrow: string;
716
- readonly recovery: { readonly kind: "salt-v2"; readonly salt: string }
717
- | { readonly kind: "index-v1"; readonly index: number };
717
+ readonly recovery: { readonly kind: "salt-v2"; readonly salt: string };
718
+ /** Everything `swaps.start` can take from the relay; the caller adds its wallet, `receiveTo` and height. */
719
+ readonly startRequest: Readonly<{
720
+ quote: Readonly<Record<string, unknown>>;
721
+ order: Readonly<Record<string, unknown>>;
722
+ orderQuote: Readonly<Record<string, unknown>>;
723
+ counterparty: Readonly<Record<string, unknown>>;
724
+ recoveryKey: unknown;
725
+ recoverySalt: string;
726
+ }>;
718
727
  readonly relay: string | null;
719
728
  readonly offered: number | null;
720
729
  readonly forwarded: Readonly<Record<string, unknown>> | null;
@@ -856,8 +865,9 @@ export interface SwapsApi {
856
865
  * THE CLIENT'S OWN EARLY REFUND WHEN THE XMR DID NOT ARRIVE (issue #88). While the interface is open, a depositor
857
866
  * who sees no XMR on the joint address takes the ETH back BEFORE `readyBy` - after it the maker may claim even
858
867
  * without the ready mark, and the early window is gone. The arrival is decided by THE SAME check as the watch
859
- * (`verifyArrival`). Only a positive `pending`/`one-node` verdict refunds; an `arrived` verdict does not; a failure
860
- * to check (no nodes, a disagreement) throws its own code and signs nothing. It fires only when less than the
868
+ * (`verifyArrival`). Only a verdict with `absent: true` refunds; a transaction that is seen (`pending` with a txid or
869
+ * height, `one-node`, `arrived`) does not; a failure to check (no nodes, a disagreement) throws its own code and
870
+ * signs nothing. It fires only when less than the
861
871
  * confirmations' time is left before `readyBy` (`minConfirmations * blockTimeSec`, overridable with `leadSec`).
862
872
  */
863
873
  refundIfXmrMissing(request: AutoRefundRequest, deps?: AutoRefundDeps): Promise<AutoRefundVerdict>;
@@ -981,6 +991,10 @@ export interface XmrArrivalRequest {
981
991
  export interface XmrArrivalVerdict {
982
992
  readonly seen: boolean;
983
993
  readonly state: "arrived" | "pending" | "one-node";
994
+ /** True only when a node completed the walk and found no matching transaction. */
995
+ readonly absent?: boolean;
996
+ /** The operators whose completed walk found no matching transaction. */
997
+ readonly completedOperators?: readonly string[];
984
998
  readonly txid: string | null;
985
999
  readonly height?: number;
986
1000
  readonly blockHash?: string;
@@ -1046,7 +1060,8 @@ export interface AutoRefundDeps {
1046
1060
  /** What the client's own refund decided: refunded, waiting, still time, or the XMR is there. */
1047
1061
  export interface AutoRefundVerdict {
1048
1062
  readonly refunded: boolean;
1049
- readonly state: "refunded" | "waiting" | "claim-window" | "arrived";
1063
+ readonly state: "refunded" | "waiting" | "claim-window" | "arrival-pending" | "arrived" |
1064
+ "arrival-underpaid" | "arrival-locked";
1050
1065
  readonly hash?: string | null;
1051
1066
  readonly leftSec: number;
1052
1067
  readonly needSec?: number;
@@ -1093,6 +1108,15 @@ export interface SellStartRequest {
1093
1108
  readonly offer: FirmRelayAnswer;
1094
1109
  /** The twelve-word key; required only when no key is stored yet. */
1095
1110
  readonly recoveryKey?: string | { readonly mnemonic: string };
1111
+ /** The recovery file's passphrase. In memory; the interface puts it on disk if it deems fit. */
1112
+ readonly passphrase?: string;
1113
+ /** Asked when the key is new or not yet confirmed. Returning anything but `true` refuses before `send-xmr`. */
1114
+ onRecoveryKey?(file: RecoveryFile): Promise<boolean>;
1115
+ /**
1116
+ * The EVM wallet whose provider supplies the block number and timestamp for the one-block escrow gate.
1117
+ * Optional: without it the gate falls back to `latest` and the facade clock. The same wallet that will claim.
1118
+ */
1119
+ readonly wallet?: Pick<WalletAdapter, "driver">;
1096
1120
  }
1097
1121
 
1098
1122
  export interface SellStart {
@@ -1125,12 +1149,14 @@ export interface SellWatchRequest {
1125
1149
 
1126
1150
  export interface SellWatchResult {
1127
1151
  readonly escrow: string;
1128
- readonly state: "ready" | "claimed" | "refunded";
1152
+ readonly state: "ready" | "claim-open" | "claimed" | "refunded";
1129
1153
  readonly funded: boolean;
1130
1154
  readonly claimed: boolean;
1131
1155
  readonly refunded: boolean;
1132
1156
  /** `null` for a terminal claim/refund: the ready mark is not part of that answer. */
1133
1157
  readonly ready: boolean | null;
1158
+ /** True when the escrow's readyBy has passed and no ready mark or terminal action was seen. */
1159
+ readonly claimOpen: boolean;
1134
1160
  readonly balanceWei: string;
1135
1161
  readonly waitedMs: number;
1136
1162
  }
@@ -1252,14 +1278,8 @@ export interface StartRequest {
1252
1278
  * kept through the SDK's storage adapter.
1253
1279
  */
1254
1280
  recoveryKey?: string | { readonly mnemonic: string };
1255
- /** The swap number, when the caller already reserved one. Absent - the SDK reserves the next free number. */
1256
- recoveryIndex?: number;
1257
- /** The per-order salt the caller put into the signed quote. When present, the key uses the v2 salt binding and
1258
- * no index is reserved; it must equal `order.salt`. */
1281
+ /** The per-order salt the caller put into the signed quote; it must equal `order.salt`. */
1259
1282
  recoverySalt?: string | number | bigint;
1260
- /** The first block for the on-chain number check. Absent - the chain registry's escrow deployment block, and
1261
- * zero only when the registry has no height. */
1262
- fromBlock?: string | number;
1263
1283
  /** The Monero height the swap starts at. Absent - the SDK asks the configured nodes (`get_info`) and refuses
1264
1284
  * the start if none answers on the swap's network. */
1265
1285
  restoreHeight?: number;
@@ -1283,8 +1303,8 @@ export interface RecoveryFile {
1283
1303
  export interface SwapState {
1284
1304
  readonly id: string;
1285
1305
  readonly direction: "buy" | "sell";
1286
- readonly pay: { readonly token: string; readonly amount: number };
1287
- readonly get: { readonly xmr: number };
1306
+ readonly pay: { readonly token: string; readonly amount: number | null };
1307
+ readonly get: { readonly xmr: number | null };
1288
1308
  /** The current step's code. The texts are the interface's. */
1289
1309
  readonly step: StepCode;
1290
1310
  /** All steps in the order of passage: what is done, what is running now, what failed. */
@@ -1341,7 +1361,7 @@ export interface SwapState {
1341
1361
  /** The swap has a settlement record: the list splits live from settled by THIS flag, not by the phase's text. */
1342
1362
  readonly settled: boolean;
1343
1363
  /** WHAT HAS ALREADY MOVED: the sum seen at the address and whether the record holds a lock or a secret. */
1344
- readonly funds: { readonly receivedXmr: number; readonly escrowLocked: boolean };
1364
+ readonly funds: { readonly receivedXmr: number | null; readonly escrowLocked: boolean };
1345
1365
  }
1346
1366
 
1347
1367
  export interface StepState {
@@ -1453,6 +1473,11 @@ export interface SweepRestoreRequest {
1453
1473
  readonly toHeight: number;
1454
1474
  readonly tipHeight: number;
1455
1475
  readonly fallback?: boolean;
1476
+ /**
1477
+ * EXPLICIT PERMISSION TO SEND KEY IMAGES TO `nodeUrl` for the spent check. Absent/false: key images never leave
1478
+ * the wallet in the window path, and the result names `spentWhy: "untrusted-node"` with an incomplete scan.
1479
+ */
1480
+ readonly trustedNode?: boolean;
1456
1481
  };
1457
1482
  /** The fetch used for `get_block`; absent - the global fetch. */
1458
1483
  readonly fetchImpl?: typeof fetch;
@@ -1553,8 +1578,7 @@ export interface SweepFromOrderRequest {
1553
1578
  readonly edPointLocker: string;
1554
1579
  readonly edPointClaimer: string;
1555
1580
  readonly edViewPointLocker: string;
1556
- readonly index?: number | null;
1557
- readonly derivation?: "index-v1" | "salt-v2";
1581
+ readonly derivation?: "salt-v2";
1558
1582
  readonly factory?: string;
1559
1583
  readonly salt?: string;
1560
1584
  readonly side: "locker" | "claimer";
@@ -1861,6 +1885,7 @@ export type ErrorCode =
1861
1885
  | "wallet-not-connected"
1862
1886
  | "wallet-rejected"
1863
1887
  | "wrong-chain"
1888
+ | "wrong-account"
1864
1889
  | "quote-unavailable"
1865
1890
  | "quote-refused"
1866
1891
  /**
@@ -1894,6 +1919,8 @@ export type ErrorCode =
1894
1919
  | "quote-factory-mismatch"
1895
1920
  /** The factory's runtime code is not a build this interface knows (`extcodehash`). */
1896
1921
  | "quote-factory-code-unknown"
1922
+ /** The signed quote names a cashier other than the network's vault. */
1923
+ | "quote-cashier-mismatch"
1897
1924
  | "recovery-declined"
1898
1925
  | "recovery-failed"
1899
1926
  | "storage-unavailable"
@@ -1920,6 +1947,9 @@ export type ErrorCode =
1920
1947
  | "xmr-too-late"
1921
1948
  | "contract-reverted"
1922
1949
  | "insufficient-funds"
1950
+ /** A wallet/node reported a withdrawal fee above the SDK's ceiling; the transfer is refused. */
1951
+ | "sweep-fee-too-high"
1952
+ | "sweep-fee-unknown"
1923
1953
  /** The maker declines to pay the claim gas; the refusal is shown before the deal (issue #78). */
1924
1954
  | "gas-refused-by-maker"
1925
1955
  /** The claim gas was ordered but the recipient's balance did not grow. */
package/package.json CHANGED
@@ -1,32 +1,41 @@
1
1
  {
2
2
  "name": "@ninsei-labs/sdk",
3
- "version": "0.55.4",
3
+ "version": "0.57.2",
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": {
14
14
  "check": "node tools/check.mjs",
15
+ "build:sdk": "node tools/build-sdk.mjs",
16
+ "build:sdk:docker": "node tools/build-sdk-docker.mjs",
15
17
  "check:syntax": "node tools/check.mjs --only=syntax",
16
18
  "check:import": "node tools/check.mjs --only=import",
17
19
  "check:surface": "node tools/check.mjs --only=surface",
18
20
  "check:mirror": "node tools/check.mjs --only=mirror",
19
21
  "check:pack": "node tools/check.mjs --only=pack",
20
- "check:pack-teeth": "node tools/check-pack-teeth.mjs",
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",
21
24
  "check:secrets": "node tools/check.mjs --only=secrets",
25
+ "check:vendor-bundles": "node tools/check.mjs --only=vendor-bundles",
26
+ "check:dleq-vectors": "node tools/check-dleq-vectors.mjs",
27
+ "check:swap-network": "node tools/check.mjs --only=swap-network",
28
+ "check:quote-ttl": "node tools/check.mjs --only=quote-ttl",
29
+ "check:dleq-oracle": "node tools/check-dleq-oracle.mjs",
30
+ "check:vendor-bundles-teeth": "node tools/run-teeth-isolated.mjs tools/check-vendor-bundles-teeth.mjs",
22
31
  "check:types": "node tools/check.mjs --only=types",
23
- "check:types-teeth": "node tools/check-types-teeth.mjs",
32
+ "check:types-teeth": "node tools/run-teeth-isolated.mjs tools/check-types-teeth.mjs",
24
33
  "check:refusals": "node tools/check.mjs --only=refusals",
25
- "check:refusals-teeth": "node tools/check-refusals-teeth.mjs",
34
+ "check:refusals-teeth": "node tools/run-teeth-isolated.mjs tools/check-refusals-teeth.mjs",
26
35
  "check:decline": "node tools/check.mjs --only=decline",
27
- "check:decline-teeth": "node tools/check-decline-teeth.mjs",
36
+ "check:decline-teeth": "node tools/run-teeth-isolated.mjs tools/check-decline-teeth.mjs",
28
37
  "check:terminal": "node tools/check.mjs --only=terminal",
29
- "check:terminal-teeth": "node tools/check-terminal-teeth.mjs",
38
+ "check:terminal-teeth": "node tools/run-teeth-isolated.mjs tools/check-terminal-teeth.mjs",
30
39
  "check:sweep": "node tools/sweep-refusal.test.mjs",
31
40
  "check:sweep-half": "node tools/check-sweep-half.mjs",
32
41
  "sync:version": "node tools/sync-version.mjs",
@@ -61,6 +70,7 @@
61
70
  "check:factory-selectors": "node tools/check-factory-selectors.mjs",
62
71
  "check:fee-estimate": "node tools/check-fee-estimate.mjs",
63
72
  "check:deadline-scale": "node tools/check-deadline-scale.mjs",
73
+ "check:deployment-pins": "node tools/check-deployment-pins.mjs",
64
74
  "check:node-probe": "node tools/check-node-probe.mjs",
65
75
  "check:recovery-key": "node tools/check.mjs --only=recovery-key",
66
76
  "check:recovery-open": "node tools/check-recovery-open.mjs",
@@ -75,7 +85,8 @@
75
85
  "check:types-consumer": "node node_modules/typescript/bin/tsc -p tools/ts-consumer/tsconfig.json",
76
86
  "check:monero-live": "node tools/check-monero-live.mjs",
77
87
  "check:native-amount": "node tools/check-native-amount.mjs",
78
- "check:ci-boundary": "node tools/check-ci-boundary.mjs"
88
+ "check:ci-boundary": "node tools/check-ci-boundary.mjs",
89
+ "coverage": "node tools/coverage.mjs"
79
90
  },
80
91
  "types": "./index.d.ts",
81
92
  "exports": {
@@ -85,6 +96,7 @@
85
96
  "default": "./src/index.mjs"
86
97
  },
87
98
  "./adapters": {
99
+ "types": "./src/adapters/index.d.ts",
88
100
  "default": "./src/adapters/index.mjs"
89
101
  },
90
102
  "./xmr": {
@@ -168,6 +180,11 @@
168
180
  },
169
181
  "sideEffects": false,
170
182
  "devDependencies": {
183
+ "esbuild": "0.28.2",
171
184
  "typescript": "7.0.2"
185
+ },
186
+ "allowScripts": {
187
+ "esbuild": true,
188
+ "keccak": true
172
189
  }
173
190
  }