@ninsei-labs/sdk 0.57.2 → 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 (46) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +64 -27
  3. package/THIRD_PARTY_NOTICES.md +2 -2
  4. package/assets/vendors/MANIFEST.json +1 -9
  5. package/assets/vendors/sdk/sdk-browser.js +4 -4
  6. package/engine/core/config.js +3 -22
  7. package/engine/core/rfqSource.js +6 -133
  8. package/engine/core/swap.js +1 -1
  9. package/engine/evm/index.js +3 -2
  10. package/engine/evm/session.js +46 -277
  11. package/engine/monero/address.js +15 -33
  12. package/engine/monero/keys.js +124 -0
  13. package/engine/monero/mnemonic.js +104 -0
  14. package/engine/monero/scan.js +23 -9
  15. package/engine/monero/wallet.js +31 -68
  16. package/engine/monero/wordlist.en.js +210 -0
  17. package/engine/recovery/restore.js +1 -1
  18. package/engine/sdk/bridge.js +7 -182
  19. package/engine/ui/walletModal.js +7 -27
  20. package/index.d.ts +187 -252
  21. package/package.json +4 -5
  22. package/src/codes.mjs +12 -0
  23. package/src/config.mjs +16 -54
  24. package/src/engine.mjs +3 -0
  25. package/src/index.mjs +24 -45
  26. package/src/order.mjs +2 -2
  27. package/src/public/recovery.d.ts +17 -1
  28. package/src/public/recovery.mjs +1 -0
  29. package/src/quotePolicy.mjs +25 -0
  30. package/src/quotes.mjs +21 -751
  31. package/src/readyWindow.mjs +76 -0
  32. package/src/recovery-key.mjs +39 -2
  33. package/src/recovery.mjs +11 -28
  34. package/src/relayClaim.mjs +132 -0
  35. package/src/relayFirmClient.mjs +3 -0
  36. package/src/relayQuote.mjs +5 -1
  37. package/src/swap-flow.mjs +49 -5
  38. package/src/swaps.mjs +301 -307
  39. package/src/sweep-action.mjs +73 -0
  40. package/src/sweep.mjs +7 -1
  41. package/src/version.mjs +1 -1
  42. package/src/xmr-arrival.mjs +275 -7
  43. package/src/xmrAmountPolicy.mjs +35 -0
  44. package/assets/vendors/monero/monero-js-browser.js +0 -58
  45. package/assets/vendors/monero-js/LICENSE +0 -9
  46. package/assets/vendors/walletconnect/wc-browser.js +0 -6202
package/index.d.ts CHANGED
@@ -35,8 +35,6 @@ export type EvmLogReader = (
35
35
  ) => Promise<readonly EvmLog[]>;
36
36
 
37
37
  export interface NinseiOptions {
38
- /** The service's HTTP API base. Default is "/api" (the interface proxies it to our server). */
39
- apiBase?: string;
40
38
  /**
41
39
  * The settlement network. `chain` is an identifier from `sdk.config.chains` (e.g. "arbitrum-sepolia", "solana").
42
40
  * `vm` may be omitted: it is taken from the network registry, and a foreign one cannot be substituted - a network
@@ -71,7 +69,7 @@ export interface NinseiOptions {
71
69
  */
72
70
  routing?: { prefer?: readonly string[] };
73
71
  /**
74
- * ADDRESSES AND PATHS SUPPLIED FROM OUTSIDE. The default is our service and our explorers; the options are for
72
+ * READ-ONLY ADDRESSES SUPPLIED FROM OUTSIDE. The default is our explorers and RPC endpoints; the options are for
75
73
  * whoever runs the swap themselves. ADDRESSES ARE CONFIGURABLE, NOT CHECKS: the pre-signature guards stay enabled
76
74
  * under any configuration.
77
75
  */
@@ -79,11 +77,6 @@ export interface NinseiOptions {
79
77
  readonly explorer?: { readonly evmTx?: string; readonly evmAddr?: string; readonly evmName?: string; readonly xmrTx?: string };
80
78
  readonly rpc?: { readonly evm?: string; readonly monero?: string };
81
79
  };
82
- /**
83
- * Renaming API paths by name: { swaps, swap, evmSwaps, orderQuote, orderSell, revealedHalf, swept }.
84
- * An unknown name is bad-input (a typo must not silently fall back to the default).
85
- */
86
- routes?: Readonly<Record<string, string>>;
87
80
  /**
88
81
  * READING THE CHAIN FROM OUTSIDE - a seam for whoever runs the SDK outside a browser. By default the chain is read
89
82
  * by the page's wallet (the engine's readContract), and in Node there is no such wallet: predict, the order state
@@ -149,7 +142,7 @@ export interface NinseiOptions {
149
142
  * THE INTERFACE'S ADDRESS DENYLIST (issue #16) - policy, not proof, next to allowedProviders. Addresses the
150
143
  * interface will not trade to or from, compared WITHOUT CASE. The SDK fetches nothing: the interface brings the
151
144
  * list in. An empty/absent list means "no check".
152
- * Before `quotes.firm` the order's `locker` is checked (on a purchase the claimer is the node's own address, so
145
+ * Before a relay quote the order's `locker` is checked (on a purchase the claimer is the node's own address, so
153
146
  * it is deliberately not checked), and before `swaps.start` the ACTUAL sender - the address the funding will be
154
147
  * sent from (`eth_accounts[0]` read from the wallet adapter at the moment of sending on demand; the person may
155
148
  * have switched accounts). A barred address is refused with `address-denied` BEFORE any request. A node's own
@@ -157,15 +150,6 @@ export interface NinseiOptions {
157
150
  * address: the interface shows its own neutral message.
158
151
  */
159
152
  denylist?: readonly string[];
160
- /**
161
- * A PASS TO OUR SERVICE for the "server" step (recording the swap with us). Only a wallet can sign the sign-in
162
- * message, and the wallet's role in the SDK is an adapter: windows and message signatures remain the interface's,
163
- * and the core receives a READY pass through the same seam the interface obtains it with today
164
- * (www/js/evm/auth.js, signIn).
165
- * A missing option is not an error: the "server" step then names the app's refusal with a code (`server-refused`,
166
- * 401), rather than going in blind.
167
- */
168
- serverAuth?: () => Promise<string | null> | string | null;
169
153
  /**
170
154
  * POLLING THE MONERO ADDRESS: the rate and the timeout for the XMR arrival. The defaults come from the engine's
171
155
  * settings (the page's rate `API.pollMs`; the timeout - `blockTimeReal x confirmTarget`, that is, the time to
@@ -251,17 +235,12 @@ export interface SdkConfig {
251
235
  /** The witness nodes for one Monero network; a network with no nodes answers an empty list. */
252
236
  nodesFor(network: string): readonly (XmrNode | string)[];
253
237
  readonly assetsBase: string;
254
- readonly apiBase: string;
255
238
  readonly mode: "live" | "sim";
256
239
  /** Addresses already resolved: the default from the network registry, the override from the options. */
257
240
  readonly endpoints: {
258
241
  readonly explorer: { readonly evmTx: string | null; readonly evmAddr: string | null; readonly evmName: string | null; readonly xmrTx: string | null };
259
242
  readonly rpc: { readonly evm: string | null; readonly monero: string | null };
260
243
  };
261
- /** Named API paths: name -> template, already with the overrides from the options. */
262
- readonly routes: Readonly<Record<string, string>>;
263
- /** Assemble a path by name and params (route("swept", { id })). An unknown name is bad-input. */
264
- route(name: string, params?: Readonly<Record<string, string>>): string;
265
244
  /** The protocol's thresholds (windows, confirmations, limits) - data, not interface constants. */
266
245
  readonly limits: {
267
246
  readonly minAmount: number | null;
@@ -269,10 +248,6 @@ export interface SdkConfig {
269
248
  readonly stepAmount: number | null;
270
249
  readonly xmrConfirmTarget: number | null;
271
250
  readonly readyLeadWarnSec: number | null;
272
- /** How often the SDK polls the market (from the engine's settings). */
273
- readonly quotePollMs: number;
274
- /** The timeout of a single request to the service. */
275
- readonly httpTimeoutMs: number;
276
251
  /** How often the SDK polls the watch on the Monero address (an engine setting or the `watch` option). */
277
252
  readonly watchPollMs: number;
278
253
  /** How long the SDK waits for the XMR to arrive before answering with the code `xmr-timeout`. */
@@ -305,11 +280,18 @@ export interface ChainConfig {
305
280
  readonly nativeSymbol: string;
306
281
  readonly tokens: readonly TokenConfig[];
307
282
  readonly dex: { readonly routes: readonly unknown[] } | null;
308
- /** The escrow deployment on this network, when there is one. `deploymentBlock` is the block that holds the factory's creation. */
283
+ /**
284
+ * The escrow deployment on this network, when there is one. `deploymentBlock` is the block that holds the
285
+ * factory's creation. `cashier`, `registry` and `implementationCodeHash` are the network's pins, carried here
286
+ * so a client built from a network name alone compares a quote against them; a simulated network has nulls.
287
+ */
309
288
  readonly escrow: {
310
289
  readonly address: string | null;
311
290
  readonly mode: string | null;
312
291
  readonly deploymentBlock: number | null;
292
+ readonly registry: string | null;
293
+ readonly cashier: string | null;
294
+ readonly implementationCodeHash: string | null;
313
295
  } | null;
314
296
  }
315
297
 
@@ -435,132 +417,12 @@ export interface Balance {
435
417
 
436
418
  // --- Quotes -------------------------------------------------------------------------------------
437
419
 
438
- export interface FirmQuoteRequest {
439
- /** Who gives the quote. Without it there is no one to ask - this is not "the first one at hand". */
440
- readonly providerId: string;
441
- /** The order terms: how much, to whom, the deadlines, the salt. The context the signature is bound to is assembled from them. */
442
- readonly order: Readonly<Record<string, unknown>>;
443
- /**
444
- * THE TAKER'S MAKER VIEW HALF, when the order was built from a recovery key. Sent top-level to the node; the quote
445
- * must echo it, so the joint view key can be rebuilt from the twelve words.
446
- */
447
- readonly viewHalfClaimer?: string;
448
- }
449
-
450
420
  export interface QuotesApi {
451
- /**
452
- * Live indicative quotes. Returns an unsubscribe function.
453
- * A snapshot arrives on every tick and contains only data. The last one to unsubscribe stops the polling.
454
- */
455
- watch(request: QuoteRequest, onSnapshot: (snapshot: QuoteSnapshot) => void): () => void;
456
- /** The last snapshot without waiting: needed by whoever subscribed later than the first poll. */
457
- snapshot(): QuoteSnapshot | null;
458
- /** A binding quote with a TTL. A refusal comes as a code, not text. */
459
- firm(offer: FirmOffer): Promise<Quote>;
460
421
  /**
461
422
  * A firm quote through a relay, built from one recovery key. The relay answer is verified against the
462
423
  * requested terms and the on-chain registry/factory binding before it is returned.
463
424
  */
464
425
  firmRelay(request: FirmRelayOffer): Promise<FirmRelayAnswer>;
465
- /**
466
- * A reverse-mode ticket: the maker sells XMR. The request is the node's `request` object; the answer carries the
467
- * signed order quote and its claim tip, which is checked against the gas price before it is returned.
468
- */
469
- sale(request: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>>>;
470
- }
471
-
472
- export interface QuoteRequest {
473
- readonly direction: "buy" | "sell";
474
- /** A token identifier from config ("usdc", "usdt", "dai", ...). For a sell - what the user receives. */
475
- readonly token?: string;
476
- /** The size on the user's side: for a buy - how much they pay, for a sell - how much XMR they give. */
477
- readonly amount?: number;
478
- /**
479
- * THE EXPLICIT REQUEST SIZE in units of `unit` (buy - XMR, sell - token). Needed by whoever has already aligned
480
- * the volume to the provider's grid themselves: the core asks for EXACTLY this number rather than deriving the
481
- * size from `amount` anew.
482
- * Not set - the size is derived from `amount`, as before.
483
- */
484
- readonly size?: number;
485
- }
486
-
487
- export interface QuoteSnapshot {
488
- readonly direction: "buy" | "sell";
489
- readonly token: string;
490
- /** The amount on the user's side, as they entered it: for a buy - in the token, for a sell - in XMR. */
491
- readonly amount: number | null;
492
- /** The size asked of the provider, in units of `unit`. The price does not depend on it: it is needed so the
493
- * provider says whether it takes such a size. */
494
- readonly size: number;
495
- /** The unit of the size: XMR for a buy, the token for a sell. */
496
- readonly unit: string | null;
497
- /** The best offer's price: non-XMR coins per 1 XMR. null - there is no offer (and then it is not zero). */
498
- readonly rate: number | null;
499
- /** How much XMR for this size (buy) or how much XMR the person gives (sell). null - not computed. */
500
- readonly xmr: number | null;
501
- /** When the snapshot was received, milliseconds of the epoch. */
502
- readonly at: number;
503
- /** The provider node whose price is in the snapshot. */
504
- readonly providerId: string | null;
505
- /** The best offer for the requested volume and side, AS THE SERVICE NAMED IT. The core does not recompute it:
506
- * these are response data by which the interface confirms its own "best" mark by pair and provider. */
507
- readonly best: QuoteBest | null;
508
- /** Is the size ready: the node's grid and range are data, not an interface check. */
509
- readonly sizeOk: boolean;
510
- /** Why the size is not ready: `bad-size`, `below-min`, `above-max`, `no-offer`. `null` - ready. */
511
- readonly sizeCode: QuoteSizeCode;
512
- /** The provider's packet number: liveness of the market is counted by it, not by the clock. */
513
- readonly seq: number | null;
514
- /** All offers for this size. Indicative: only `quotes.firm` binds. */
515
- readonly offers: readonly QuoteOffer[];
516
- /** Book rows that did not become offers, with the reason as a code: `malformed`, `disabled`, `stale`. */
517
- readonly refused: readonly QuoteRefusal[];
518
- /** Reference rates (the price benchmark), as the service returned them. Not a swap offer. */
519
- readonly references: readonly QuoteReference[];
520
- /** Are there offers and is the service's response alive. */
521
- readonly ok: boolean;
522
- /** Why there is no market: a code, no text. */
523
- readonly error?: { readonly code: ErrorCode };
524
- }
525
-
526
- export type QuoteSizeCode = "bad-size" | "below-min" | "above-max" | "no-offer" | null;
527
-
528
- /** The best, as the service named it: the pair and the node. The core does not recompute the price. */
529
- export interface QuoteBest {
530
- readonly providerId: string;
531
- readonly pair: string;
532
- }
533
-
534
- export interface QuoteOffer {
535
- readonly providerId: string;
536
- readonly displayName: string | null;
537
- readonly pair: string;
538
- readonly asset: string | null;
539
- readonly currency: string | null;
540
- readonly rate: number;
541
- readonly rateQuote: number;
542
- /** The claim tip in native-token wei; a sale is ranked by the payout AFTER it. */
543
- readonly claimTip: string;
544
- readonly min: number | null;
545
- readonly max: number | null;
546
- readonly step: number | null;
547
- readonly ttlMs: number | null;
548
- readonly at: number | null;
549
- readonly seq: number | null;
550
- readonly finality: string | null;
551
- /** The network of the XMR side and of the settlement side, as the quote named them. Not named - null, not our network. */
552
- readonly assetNetwork: string | null;
553
- readonly currencyNetwork: string | null;
554
- readonly networkStated: boolean;
555
- /** The networks were filled in by the receiver / not named at all - this is a fact about the quote, not "matched". */
556
- readonly networksDerived: boolean;
557
- readonly networksUnnamed: boolean;
558
- /** The reason named by the provider, as is; the package's signature and key; the age by its own mark. */
559
- readonly why: string | null;
560
- readonly signature: string | null;
561
- readonly keyId: string | null;
562
- readonly ageMs: number | null;
563
- readonly networks: { readonly asset: string | null; readonly currency: string | null; readonly stated: boolean };
564
426
  }
565
427
 
566
428
  /**
@@ -638,44 +500,6 @@ export interface RouteRefusalTables {
638
500
  readonly UNISWAPRELAY_REFUSAL_CODES: readonly RouteRefusalCode[];
639
501
  }
640
502
 
641
- export interface QuoteRefusal {
642
- readonly providerId: string;
643
- readonly displayName: string | null;
644
- readonly pair: string;
645
- readonly asset: string | null;
646
- readonly currency: string | null;
647
- readonly rate: number | null;
648
- readonly rateQuote: number | null;
649
- readonly min: number | null;
650
- readonly max: number | null;
651
- readonly step: number | null;
652
- readonly ttlMs: number | null;
653
- readonly at: number | null;
654
- readonly seq: number | null;
655
- readonly ageMs: number | null;
656
- readonly assetNetwork: string | null;
657
- readonly currencyNetwork: string | null;
658
- readonly networkStated: boolean;
659
- readonly code: "malformed" | "disabled" | "stale";
660
- /** The reason named by the provider, as is: this is data, not our wording. */
661
- readonly why: string | null;
662
- }
663
-
664
- export interface QuoteReference {
665
- readonly source: string;
666
- readonly value: number | null;
667
- readonly at: number | null;
668
- }
669
-
670
- export interface FirmOffer {
671
- /** Who gives the quote. Without it there is no one to ask. */
672
- readonly providerId: string;
673
- /** The order terms the signature is bound to. */
674
- readonly order: Readonly<Record<string, unknown>>;
675
- /** The taker's maker view half when the order was built from a recovery key. */
676
- readonly viewHalfClaimer?: string;
677
- }
678
-
679
503
  export interface FirmRelayOffer {
680
504
  /** Relay origin, without the `/v1/quote` path. */
681
505
  readonly relayUrl: string;
@@ -702,6 +526,8 @@ export interface FirmRelayAnswer {
702
526
  readonly orderQuote: Readonly<Record<string, unknown>>;
703
527
  /** The exact order terms the quote is bound to. */
704
528
  readonly order: Readonly<Record<string, unknown>>;
529
+ /** The node's signed ready window for this side: the wait, the late boundary and the refund lead. */
530
+ readonly readyWindow: ReadyWindow;
705
531
  readonly nodeHalf: Readonly<Record<string, unknown>>;
706
532
  /** Ready to pass as `swaps.start({ counterparty })`: proof, claimer commitment and maker view half. */
707
533
  readonly counterparty: Readonly<Record<string, unknown>>;
@@ -724,29 +550,30 @@ export interface FirmRelayAnswer {
724
550
  recoveryKey: unknown;
725
551
  recoverySalt: string;
726
552
  }>;
553
+ /** The relay origin that answered. `startSell` stores it for the later no-wallet claim. */
554
+ readonly relayUrl: string;
727
555
  readonly relay: string | null;
728
556
  readonly offered: number | null;
729
557
  readonly forwarded: Readonly<Record<string, unknown>> | null;
730
558
  readonly answer: Readonly<Record<string, unknown>>;
731
559
  }
732
560
 
561
+ // --- Ready windows ------------------------------------------------------------------------------
562
+
733
563
  /**
734
- * A binding quote. The SDK does not reassemble the signature body: the signed fields are passed on as is - otherwise
735
- * the signature stops matching.
564
+ * The signed `firmWindows` entry the relay answer came with. `readyMinSeconds` and `readyMaxSeconds` bound the
565
+ * quote's readiness horizon; the SDK derives the late-arrival boundary and the refund lead from them instead of
566
+ * keeping its own 1200 s / 20-minute numbers.
736
567
  */
737
- export interface Quote {
738
- readonly id: string;
739
- readonly direction: "buy" | "sell";
740
- readonly providerId: string;
741
- readonly chain: string;
742
- readonly token: string;
743
- readonly amount: number;
744
- readonly xmr: number;
745
- readonly rate: number;
746
- /** The moment after which the quote must not be signed, milliseconds of the epoch. */
747
- readonly expiresAt: number;
748
- readonly receiveTo: string;
749
- readonly signedPayload: unknown;
568
+ export interface ReadyWindow {
569
+ readonly market: string | null;
570
+ readonly side: string | null;
571
+ readonly xmrNetwork: string | null;
572
+ readonly readyMinSeconds: number;
573
+ readonly readyMaxSeconds: number;
574
+ readonly settlementMinSeconds: number | null;
575
+ readonly settlementMaxSeconds: number | null;
576
+ readonly quoteTtlSeconds: number | null;
750
577
  }
751
578
 
752
579
  // --- Pre-signature checks -----------------------------------------------------------------------
@@ -805,7 +632,7 @@ export type CheckCode =
805
632
  | "unknown";
806
633
 
807
634
  /** The same as Quote, but a node response body is allowed too: the SDK does not reassemble the signed fields. */
808
- export type QuoteLike = Quote | (Record<string, unknown> & { signedPayload?: unknown });
635
+ export type QuoteLike = Readonly<Record<string, unknown>> & { readonly signedPayload?: unknown };
809
636
 
810
637
  // --- Swaps --------------------------------------------------------------------------------------
811
638
 
@@ -828,6 +655,18 @@ export interface SwapsApi {
828
655
  startSell(request: SellStartRequest): Promise<SellStart>;
829
656
  /** CLAIM THE ETH on a sell from the record: the half and the expectations are the ones stored by `startSell`. */
830
657
  sellClaim(request: SellClaimRequest, wallet: WalletAdapter): Promise<unknown>;
658
+ /**
659
+ * CLAIM THE ETH ON A SELL WITHOUT A WALLET. The seller holds XMR and no ETH, so the signed `claimTip` pays the
660
+ * sender. The half goes to the sender the client chose - a listed maker OTHER than the deal's maker - through
661
+ * the relay that answered the quote (`POST /v1/claims/{sender}/{escrow}`). No wallet is created or used and no
662
+ * chain transaction is signed.
663
+ *
664
+ * The sender is stored by `startSell`; a request may supply `claimSender` only when the record has none, and
665
+ * may never name the deal's maker. `relayUrl` may restate the stored origin; a different origin is refused. A
666
+ * node refusal is `quote-refused` with its own code in `params.code`; a lost answer is `claim-unknown` (the
667
+ * claim may have been sent), never success.
668
+ */
669
+ claimViaRelay(request: RelayClaimRequest): Promise<RelayClaimResult>;
831
670
  /**
832
671
  * WAIT FOR THE XMR TO ARRIVE at the order's joint address. The polling uses the same request as the page's
833
672
  * (GET /swaps/{id}), the rate and the timeout - from `config.limits` and overridable here.
@@ -859,6 +698,12 @@ export interface SwapsApi {
859
698
  * never a silent success.
860
699
  */
861
700
  verifyArrival(request: XmrArrivalRequest): Promise<XmrArrivalVerdict>;
701
+ /**
702
+ * RUN THE EXACT CHECK AND THE WITNESS-V1 SLICE CHECK SIDE BY SIDE. The exact verdict still decides; this
703
+ * returns both readings and any difference, and changes no swap state. `witnessNodes` must name at least one
704
+ * node with `protocol: "witness-v1"`. It is the staging step before slice-only verification.
705
+ */
706
+ verifyArrivalShadow(request: XmrArrivalShadowRequest): Promise<XmrArrivalShadowResult>;
862
707
  /** Fewer seconds before the ready deadline than the confirmations take - a named refusal (`xmr-too-late`). */
863
708
  assertTimeForConfirmations(request: XmrDeadlineRequest): number | null;
864
709
  /**
@@ -867,23 +712,13 @@ export interface SwapsApi {
867
712
  * without the ready mark, and the early window is gone. The arrival is decided by THE SAME check as the watch
868
713
  * (`verifyArrival`). Only a verdict with `absent: true` refunds; a transaction that is seen (`pending` with a txid or
869
714
  * 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
871
- * confirmations' time is left before `readyBy` (`minConfirmations * blockTimeSec`, overridable with `leadSec`).
715
+ * signs nothing. It fires only when less than the node's refund lead is left before `readyBy` (the headroom of
716
+ * the signed `readyWindow` stored with the record, overridable with `leadSec`).
872
717
  */
873
718
  refundIfXmrMissing(request: AutoRefundRequest, deps?: AutoRefundDeps): Promise<AutoRefundVerdict>;
874
719
  /** Unfinished swaps after a page reload. */
875
720
  list(): Promise<readonly SwapState[]>;
876
721
  get(id: string): Promise<SwapState | null>;
877
- /**
878
- * THE SERVICE'S SWAP LIST, MERGED INTO THE LOCAL ONE. The path is the page's (www/js/evm/auth.js,
879
- * loadServerSwaps: GET /api/evm-swaps), and the merge rule is the ENGINE'S (core/swap.js, addServerSwaps): a
880
- * local record always wins, the service only adds what this browser does not have, and a record that came
881
- * from the service is marked `source: "server"`. The pass is obtained by the interface and only presented by
882
- * the core (the `serverAuth` seam): without it the service's own refusal comes as a code. `added` says how
883
- * many records the merge brought in - the interface decides by it whether the list changed, instead of
884
- * guessing.
885
- */
886
- sync(): Promise<SwapSync>;
887
722
  /**
888
723
  * REMOVE A RECORD FROM THE LOCAL LIST. The record leaves THIS store alone: on the service and in the
889
724
  * contract everything stays, so this is a tidy-up of the list, not a cancellation of the swap. `false` means
@@ -956,17 +791,12 @@ export interface SwapProgressView {
956
791
  readonly terminal: unknown;
957
792
  }
958
793
 
959
- /** The outcome of merging the service's list: how many rows the service gave, how many were new locally. */
960
- export interface SwapSync {
961
- readonly ok: true;
962
- readonly added: number;
963
- readonly seen: number;
964
- }
965
-
966
- /** ONE WITNESS NODE: the address, and whose node it is (two nodes of one operator are one opinion). */
794
+ /** ONE WITNESS NODE: the address, whose node it is, and the optional slice protocol. */
967
795
  export interface XmrNode {
968
796
  readonly url: string;
969
797
  readonly operator?: string;
798
+ /** `witness-v1` when this URL serves `POST /v1/witness/slice`; absent for a standard daemon. */
799
+ readonly protocol?: "witness-v1" | string;
970
800
  }
971
801
 
972
802
  /**
@@ -987,6 +817,37 @@ export interface XmrArrivalRequest {
987
817
  readonly timeoutMs?: number;
988
818
  }
989
819
 
820
+ /** The slice check's extra input: independent witnesses that serve witness-v1. */
821
+ export interface XmrArrivalShadowRequest extends XmrArrivalRequest {
822
+ readonly witnessNodes: readonly (XmrNode | string)[];
823
+ /** Overrides the network derived from the address; normally left out. */
824
+ readonly network?: string;
825
+ }
826
+
827
+ /** What one witness returned from the slice walk. */
828
+ export interface XmrWitnessShadowReading {
829
+ readonly state: "seen" | "pending";
830
+ readonly txid: string | null;
831
+ readonly height: number | null;
832
+ readonly blockHash: string | null;
833
+ readonly amountAtomic: string | null;
834
+ readonly operator?: string;
835
+ readonly url?: string;
836
+ readonly completed: boolean;
837
+ readonly checked: readonly Record<string, unknown>[];
838
+ readonly failed: readonly Record<string, unknown>[];
839
+ }
840
+
841
+ /** The exact verdict and the slice reading, side by side. This is not a swap decision. */
842
+ export interface XmrArrivalShadowResult {
843
+ readonly exact: XmrArrivalVerdict | null;
844
+ readonly exactError: { readonly code: string; readonly params: Record<string, unknown> } | null;
845
+ readonly witness: XmrWitnessShadowReading;
846
+ /** True when the two readings agree; null when there is nothing comparable to agree on. */
847
+ readonly agrees: boolean | null;
848
+ readonly problems: readonly string[];
849
+ }
850
+
990
851
  /** The XMR state the watch hands to the interface: the fact, the waiting state, or a refusal with a code. */
991
852
  export interface XmrArrivalVerdict {
992
853
  readonly seen: boolean;
@@ -1042,8 +903,11 @@ export interface AutoRefundRequest {
1042
903
  readonly fromHeight?: number | null;
1043
904
  readonly txid?: string | null;
1044
905
  readonly minConfirmations?: number;
906
+ /** Retained for callers that used to derive the lead locally; the refund no longer reads it. */
1045
907
  readonly blockTimeSec?: number;
1046
- /** How long before `readyBy` the refund becomes due. Defaults to `minConfirmations * blockTimeSec`. */
908
+ /** The node's signed window, when it is not read from `swap.readyWindow`. */
909
+ readonly readyWindow?: ReadyWindow;
910
+ /** How long before `readyBy` the refund becomes due. Defaults to the window's own headroom. */
1047
911
  readonly leadSec?: number;
1048
912
  readonly timeoutMs?: number;
1049
913
  readonly nowSec?: number;
@@ -1070,8 +934,9 @@ export interface AutoRefundVerdict {
1070
934
  }
1071
935
 
1072
936
  /**
1073
- * THE OUTCOME OF A START: funds locked, the swap recorded with us, the address watch opened.
937
+ * THE OUTCOME OF A START: funds locked, the swap recorded locally, and the joint address returned.
1074
938
  * There is NO XMR arrival here YET - the state is named (`step: "xmr-incoming"`), not passed off as completion.
939
+ * No backend watch is opened: the caller watches the chain with `swaps.watch` and its own `verify` inputs.
1075
940
  */
1076
941
  export interface SwapStart {
1077
942
  readonly id: string | null;
@@ -1080,32 +945,21 @@ export interface SwapStart {
1080
945
  /** The order's joint Monero address - the one the XMR arrives at. */
1081
946
  readonly address: string;
1082
947
  readonly step: "xmr-incoming";
1083
- readonly server: {
1084
- readonly marked: boolean;
1085
- /** The service's response code to the mark. */
1086
- readonly httpStatus: number;
1087
- /** What the service said about tying the quote to the escrow (its refusal does not abort the swap). */
1088
- readonly orderBinding: unknown;
1089
- };
1090
- readonly watch: {
1091
- readonly registered: boolean;
1092
- readonly httpStatus: number;
1093
- /** The watch record's identifier at the service: the state is queried by it. */
1094
- readonly id: string | null;
1095
- readonly address: string;
1096
- readonly status: string | null;
1097
- readonly expectedXmr: number;
1098
- readonly receivedXmr: number;
1099
- readonly confirmations: number;
1100
- readonly txids: readonly string[];
1101
- };
1102
948
  /** The named next step: wait for the arrival. */
1103
949
  readonly next: "watch";
950
+ /** The node's signed window, when the start came from a relay answer. */
951
+ readonly readyWindow?: ReadyWindow | null;
1104
952
  }
1105
953
 
1106
954
  export interface SellStartRequest {
1107
955
  /** The verified `quotes.firmRelay` answer for the bid side. */
1108
956
  readonly offer: FirmRelayAnswer;
957
+ /**
958
+ * The sender the client chose for a later no-ETH claim: a listed maker other than the deal's maker. It is
959
+ * stored with the record so a reload claims through the same node; the relay route names it as `provider`.
960
+ * Omitted for a record that will only use the own-wallet path.
961
+ */
962
+ readonly claimSender?: string;
1109
963
  /** The twelve-word key; required only when no key is stored yet. */
1110
964
  readonly recoveryKey?: string | { readonly mnemonic: string };
1111
965
  /** The recovery file's passphrase. In memory; the interface puts it on disk if it deems fit. */
@@ -1128,6 +982,9 @@ export interface SellStart {
1128
982
  readonly xmrAmount: string;
1129
983
  readonly claimTip: string | null;
1130
984
  readonly orderQuote: Readonly<Record<string, unknown>> | null;
985
+ /** The no-wallet claim sender stored by `startSell`, or null when only the own-wallet path is available. */
986
+ readonly claimSender: string | null;
987
+ readonly readyWindow: ReadyWindow | null;
1131
988
  readonly resumed: boolean;
1132
989
  readonly next: "send-xmr";
1133
990
  }
@@ -1140,11 +997,43 @@ export interface SellClaimRequest {
1140
997
  readonly onStep?: (step: unknown) => void;
1141
998
  }
1142
999
 
1000
+ /**
1001
+ * THE NO-WALLET CLAIM'S INPUTS. `id` names the sell record made by `startSell`; the escrow, half and signed tip
1002
+ * come from it. `claimSender` is the list-member node that will send the claim: it must be a listed maker other than
1003
+ * the deal's maker, and is normally stored by `startSell`. `relayUrl` is optional and may only repeat the origin
1004
+ * stored with the record - a foreign origin is refused.
1005
+ */
1006
+ export interface RelayClaimRequest {
1007
+ readonly id: string;
1008
+ /** Only for a record made before the sender was stored; it may never name the deal's maker. */
1009
+ readonly claimSender?: string;
1010
+ readonly relayUrl?: string;
1011
+ readonly fetchImpl?: typeof fetch;
1012
+ readonly timeoutMs?: number;
1013
+ }
1014
+
1015
+ /** The claim the relay sent for the record. Only a validated on-chain transaction hash is returned here. */
1016
+ export interface RelayClaimResult {
1017
+ readonly id: string;
1018
+ /** The sender the client chose; `claimSender` repeats it for callers that think in that name. */
1019
+ readonly provider: string;
1020
+ readonly claimSender: string;
1021
+ readonly escrow: string;
1022
+ readonly relayUrl: string;
1023
+ readonly txid: string;
1024
+ /** The address that sent the claim transaction (the sender node's sender, not the seller). */
1025
+ readonly from: string;
1026
+ /** The signed tip, in wei, paid out of the claim. */
1027
+ readonly tipWei: string;
1028
+ }
1029
+
1143
1030
  export interface SellWatchRequest {
1144
1031
  /** The escrow predicted by the relay adapter. */
1145
1032
  readonly escrow: string;
1146
1033
  readonly timeoutMs?: number;
1147
1034
  readonly pollMs?: number;
1035
+ /** The node's window, if the caller does not rely on the record found by `escrow`. */
1036
+ readonly readyWindow?: ReadyWindow;
1148
1037
  }
1149
1038
 
1150
1039
  export interface SellWatchResult {
@@ -1162,7 +1051,7 @@ export interface SellWatchResult {
1162
1051
  }
1163
1052
 
1164
1053
  export interface SwapWatchRequest {
1165
- /** The watch record's identifier at the service (from SwapStart.watch.id). */
1054
+ /** The local swap record identifier. */
1166
1055
  readonly id: string;
1167
1056
  /** The escrow address for the ready mark (mandatory when `expect` and `wallet` are passed). */
1168
1057
  readonly escrow?: string;
@@ -1186,6 +1075,8 @@ export interface SwapWatchRequest {
1186
1075
  readonly minConfirmations?: number;
1187
1076
  /** The ready deadline in unix seconds; with less time left than the confirmations take it refuses with a code. */
1188
1077
  readonly readyBySec?: number;
1078
+ /** The node's window, if the record does not carry one. Required for a client-side arrival check. */
1079
+ readonly readyWindow?: ReadyWindow;
1189
1080
  }
1190
1081
 
1191
1082
  /**
@@ -1238,7 +1129,7 @@ export interface SwapWatch {
1238
1129
  }
1239
1130
 
1240
1131
  export interface StartRequest {
1241
- readonly quote: Quote;
1132
+ readonly quote: QuoteLike;
1242
1133
  /**
1243
1134
  * THE ORDER TERMS - the context the DLEQ proof and the firm quote's signature are bound to
1244
1135
  * (`orderContext`, fields: chainId, factory, locker, claimer, amount, readyBy, t1, salt). The core ALSO builds our
@@ -1592,6 +1483,28 @@ export interface SweepFromOrderRequest {
1592
1483
  readonly passphrase?: string;
1593
1484
  }
1594
1485
 
1486
+ /**
1487
+ * The order expectations the action's slot check compares against the live escrow. `amount`, `readyBy`, `t1`,
1488
+ * `salt` and `factory` travel with the action for the caller's own window and context checks; the slot guard
1489
+ * itself compares the points and commitments.
1490
+ */
1491
+ export interface SweepActionExpect {
1492
+ readonly chainId: number;
1493
+ readonly factory: string;
1494
+ readonly locker: string;
1495
+ readonly claimer: string;
1496
+ /** The native escrow amount in wei, as a decimal string. */
1497
+ readonly amount: string;
1498
+ readonly readyBy: number;
1499
+ readonly t1: number;
1500
+ readonly salt: string;
1501
+ readonly commitHalfLocker: string;
1502
+ readonly commitHalfClaimer: string;
1503
+ readonly edPointLocker: string;
1504
+ readonly edPointClaimer: string;
1505
+ readonly edViewPointLocker: string;
1506
+ }
1507
+
1595
1508
  export interface SweepFromOrderResult {
1596
1509
  /** The payload `buildPayload` produced; the same fields a recovery file carries. */
1597
1510
  readonly payload: unknown;
@@ -1599,6 +1512,15 @@ export interface SweepFromOrderResult {
1599
1512
  readonly contents: string;
1600
1513
  /** The joint Monero address built from the key and the order. */
1601
1514
  readonly address: string;
1515
+ /** The side of the recovered taker: a locker refunds, a claimer claims. */
1516
+ readonly side: "locker" | "claimer";
1517
+ /** The ETH action the recovered half authorizes. */
1518
+ readonly kind: "refund" | "claim";
1519
+ readonly escrow: string;
1520
+ /** The recovered taker's spend half, ready for `actions.refund` or `actions.claim`. */
1521
+ readonly half: string;
1522
+ readonly claimer: string;
1523
+ readonly expect: SweepActionExpect;
1602
1524
  }
1603
1525
 
1604
1526
  export interface SweepPlanRequest {
@@ -1829,8 +1751,8 @@ export interface RecoveryApi {
1829
1751
  /** Parse the recovery file. Without the right passphrase - a refusal with a code, not an exception. */
1830
1752
  open(file: { readonly contents: string } | string, passphrase?: string): Promise<RecoveredWallet>;
1831
1753
  /**
1832
- * WHICH HEIGHT TO SCAN FROM, AND WHERE IT CAME FROM. The service's height wins when it knows one (it watches
1833
- * the address), the file's is the fallback, and no height is a named state - the person can type one.
1754
+ * WHICH HEIGHT TO SCAN FROM. The height written into the file is the only source; no height is a named state -
1755
+ * the person can type one.
1834
1756
  */
1835
1757
  restoreHeight(request: RestoreHeightRequest): Promise<RestoreHeightResult>;
1836
1758
  }
@@ -1844,12 +1766,12 @@ export interface RestoreHeightResult {
1844
1766
  readonly address: string | null;
1845
1767
  /** 0 when no source knows a height. */
1846
1768
  readonly height: number;
1847
- readonly source: "app" | "file" | "none";
1769
+ readonly source: "file" | "none";
1848
1770
  readonly fileHeight: number;
1849
1771
  readonly appHeight: number;
1850
- /** Whether the service was asked at all (it is absent in a package without a service). */
1772
+ /** Whether the retired service was asked. Always false: the SDK no longer carries that route. */
1851
1773
  readonly appAsked: boolean;
1852
- /** When `source` is "none": "unreachable" | "no-row" | "no-height". Null when a height was found. */
1774
+ /** When `source` is "none": "no-height". Null when a height was found. */
1853
1775
  readonly appProblem: string | null;
1854
1776
  }
1855
1777
 
@@ -1889,7 +1811,7 @@ export type ErrorCode =
1889
1811
  | "quote-unavailable"
1890
1812
  | "quote-refused"
1891
1813
  /**
1892
- * An address on the interface's `denylist` refused BEFORE any request - the order's `locker` before `quotes.firm`,
1814
+ * An address on the interface's `denylist` refused BEFORE any request - the order's `locker` before a relay quote,
1893
1815
  * or the actual sender before `swaps.start` (issue #16). Also names the node's own `denied-address` refusal as it
1894
1816
  * reaches the app: WITHOUT the node's `why` text and WITHOUT the address, so the interface shows its own message.
1895
1817
  */
@@ -1903,6 +1825,8 @@ export type ErrorCode =
1903
1825
  | "quote-field-unbound"
1904
1826
  /** The quote's own `validUntil` has passed. */
1905
1827
  | "quote-expired"
1828
+ /** The quote arrived with less than the start margin left; ask again before showing a confirmation. */
1829
+ | "quote-too-short"
1906
1830
  /** There was no chain read to ask the registry whose key it is: the claim stays unproven. */
1907
1831
  | "quote-registry-unchecked"
1908
1832
  /** The registry has no provider for this key: nobody owns it. */
@@ -1927,6 +1851,11 @@ export type ErrorCode =
1927
1851
  | "server-unavailable"
1928
1852
  /** The service answered and did not accept: the connection got through, the request did not (status and reason in params). */
1929
1853
  | "server-refused"
1854
+ /**
1855
+ * THE CLAIM WAS POSTED BUT NO REAL ANSWER CAME BACK: a timeout, a reset, or a body without a usable transaction
1856
+ * hash. The relay may have sent the claim; the caller must read the escrow before acting again. Never success.
1857
+ */
1858
+ | "claim-unknown"
1930
1859
  /** The funding transaction was sent, but no status-1 receipt with the expected OrderCreated proves the escrow. */
1931
1860
  | "funding-pending"
1932
1861
  /** The wait for the XMR to arrive expired: a separate code, because this is a state of the money, not a breakdown. */
@@ -1943,7 +1872,9 @@ export type ErrorCode =
1943
1872
  | "xmr-no-nodes"
1944
1873
  /** The amount that arrived is below the expected one. */
1945
1874
  | "xmr-underpaid"
1946
- /** Less time remains before the ready deadline than the required confirmations take. */
1875
+ /** The view key or spend key does not belong to the address being watched. */
1876
+ | "xmr-address-mismatch"
1877
+ /** The ready deadline cannot fit the confirmations the arrival needs. */
1947
1878
  | "xmr-too-late"
1948
1879
  | "contract-reverted"
1949
1880
  | "insufficient-funds"
@@ -1971,6 +1902,10 @@ export declare class SdkError extends Error {
1971
1902
 
1972
1903
  /** The step codes the SDK works with (`state.step`): the same list as the `StepCode` type. */
1973
1904
  export declare const SDK_VERSION: string;
1905
+ /** The minimum remaining lifetime of a quote when a swap starts, in seconds. */
1906
+ export declare const LOCK_START_MARGIN_SEC: number;
1907
+ /** The default firm quote lifetime, in seconds. A node may override it; the SDK default stays authoritative. */
1908
+ export declare const DEFAULT_ORDER_QUOTE_TTL_SEC: number;
1974
1909
  export declare const STEP_CODES: readonly StepCode[];
1975
1910
  /** The check codes a preflight verdict names (`checks[].code`): the same list as the `CheckCode` type. */
1976
1911
  export declare const CHECK_CODES: readonly CheckCode[];