@ninsei-labs/sdk 0.60.0 → 0.62.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 (96) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +81 -18
  3. package/assets/vendors/MANIFEST.json +1 -1
  4. package/assets/vendors/sdk/sdk-browser.js +4 -4
  5. package/engine/atomic/dleq2.js +0 -4
  6. package/engine/atomic/halfenc.js +6 -10
  7. package/engine/atomic/halves.js +0 -4
  8. package/engine/atomic/order.js +0 -4
  9. package/engine/atomic/orderContext.js +0 -4
  10. package/engine/atomic/orderHalfCommit.js +0 -4
  11. package/engine/core/chainSource.js +0 -4
  12. package/engine/core/clock.js +0 -4
  13. package/engine/core/config.js +17 -42
  14. package/engine/core/finality.js +0 -4
  15. package/engine/core/format.js +1 -5
  16. package/engine/core/preSignGuards.js +0 -4
  17. package/engine/core/rfqSource.js +0 -3
  18. package/engine/core/sellWindow.js +1 -5
  19. package/engine/core/store.js +11 -7
  20. package/engine/core/swap.js +3 -7
  21. package/engine/evm/amounts.js +2 -6
  22. package/engine/evm/asyncRoute.js +3 -7
  23. package/engine/evm/auth.js +0 -4
  24. package/engine/evm/claimGas.js +2 -6
  25. package/engine/evm/dex.js +1 -5
  26. package/engine/evm/escrow.js +0 -4
  27. package/engine/evm/factory.js +1 -5
  28. package/engine/evm/fees.js +62 -4
  29. package/engine/evm/funding.js +73 -71
  30. package/engine/evm/gasReserve.js +10 -4
  31. package/engine/evm/index.js +7 -11
  32. package/engine/evm/injected.js +0 -4
  33. package/engine/evm/permit.js +0 -4
  34. package/engine/evm/prices.js +3 -4
  35. package/engine/evm/session.js +1 -5
  36. package/engine/mock/chain.js +0 -4
  37. package/engine/monero/address.js +4 -5
  38. package/engine/monero/arrivalRead.js +15 -2
  39. package/engine/monero/halvesSweep.js +0 -4
  40. package/engine/monero/keyImage.js +146 -0
  41. package/engine/monero/keys.js +1 -0
  42. package/engine/monero/mnemonic.js +2 -1
  43. package/engine/monero/node.js +1 -4
  44. package/engine/monero/scan.js +12 -2
  45. package/engine/monero/swapKeys.js +0 -4
  46. package/engine/monero/unlock.js +2 -6
  47. package/engine/monero/wallet.js +0 -3
  48. package/engine/recovery/recoveryFile.js +31 -89
  49. package/engine/recovery/restore.js +0 -4
  50. package/engine/sdk/bridge.js +24 -58
  51. package/engine/ui/dom.js +0 -4
  52. package/engine/ui/walletModal.js +0 -4
  53. package/index.d.ts +436 -42
  54. package/package.json +22 -3
  55. package/src/actions.mjs +72 -6
  56. package/src/addressGuard.mjs +16 -0
  57. package/src/codes.mjs +26 -9
  58. package/src/config.mjs +56 -3
  59. package/src/decline.mjs +23 -74
  60. package/src/engine.mjs +17 -26
  61. package/src/firmRequest.mjs +80 -0
  62. package/src/index.mjs +17 -28
  63. package/src/legs/cow.mjs +2 -2
  64. package/src/legs/evm.mjs +20 -12
  65. package/src/legs/kyber-spec.mjs +2 -2
  66. package/src/legs/kyber.mjs +1 -1
  67. package/src/legs/shape.mjs +1 -1
  68. package/src/legs/uniswaprelay.mjs +16 -4
  69. package/src/legs/uniswapx.mjs +29 -7
  70. package/src/levelsWalkSpec.mjs +1 -1
  71. package/src/lock.mjs +18 -37
  72. package/src/provider/envFile.mjs +3 -3
  73. package/src/provider/sign.mjs +3 -3
  74. package/src/public/evm.d.ts +84 -0
  75. package/src/public/evm.mjs +20 -0
  76. package/src/public/order.mjs +1 -1
  77. package/src/public/provider.mjs +1 -1
  78. package/src/public/recovery.d.ts +4 -3
  79. package/src/public/recovery.mjs +1 -1
  80. package/src/public/xmr.d.ts +2 -2
  81. package/src/quoteEip712Spec.mjs +4 -4
  82. package/src/quotes.mjs +52 -11
  83. package/src/recovery-key.mjs +7 -3
  84. package/src/relayClaim.mjs +17 -3
  85. package/src/relayFirmClient.mjs +4 -0
  86. package/src/relayQuote.mjs +1 -0
  87. package/src/sim.mjs +1 -1
  88. package/src/swap-flow.mjs +28 -41
  89. package/src/swaps.mjs +217 -123
  90. package/src/sweep-inputs.mjs +61 -0
  91. package/src/sweep-reconcile.mjs +71 -0
  92. package/src/sweep-restore.mjs +38 -9
  93. package/src/sweep.mjs +164 -10
  94. package/src/version.mjs +1 -1
  95. package/src/wallet.mjs +1 -1
  96. package/src/xmr-arrival.mjs +1053 -57
package/index.d.ts CHANGED
@@ -40,7 +40,22 @@ export interface NinseiOptions {
40
40
  * `vm` may be omitted: it is taken from the network registry, and a foreign one cannot be substituted - a network
41
41
  * without a driver answers with the code `not-implemented`, rather than being assumed EVM by default.
42
42
  */
43
- settlement: { chain: string; vm?: string };
43
+ settlement: {
44
+ chain: string;
45
+ vm?: string;
46
+ /**
47
+ * THE LOCAL ANVIL DEPLOYMENT, WHEN THE CALLER CREATED IT. A local chain's factory address depends on the
48
+ * deployer and nonce, so a client cannot use a constant after a fresh `Deploy.s.sol`. This override is accepted
49
+ * only for `local-anvil`; public network pins remain reviewed configuration. It changes addresses, never a check.
50
+ */
51
+ escrow?: {
52
+ readonly address: string;
53
+ readonly cashier?: string | null;
54
+ readonly registry?: string | null;
55
+ readonly implementationCodeHash?: string | null;
56
+ readonly deploymentBlock?: number | null;
57
+ };
58
+ };
44
59
  /**
45
60
  * The Monero network. A value from `sdk.config.xmrNetworks`. Besides mainnet/stagenet/testnet it names
46
61
  * `fakechain` - the official network name monerod reports in regtest mode, which the withdrawal page picks up
@@ -108,7 +123,9 @@ export interface NinseiOptions {
108
123
  * base and priority fees. A missing seam is `quote-tip-unchecked` when a quote carries a non-zero tip; zero tips
109
124
  * (the buy side) never call it.
110
125
  */
111
- evmBlock?: (tag?: string) => Promise<{ readonly baseFeePerGas?: string | number | bigint | null;
126
+ evmBlock?: (tag?: string) => Promise<{ readonly number?: string | number | bigint | null;
127
+ readonly timestamp?: string | number | bigint | null;
128
+ readonly baseFeePerGas?: string | number | bigint | null;
112
129
  readonly baseFeeWei?: string | number | bigint | null;
113
130
  readonly priorityFeePerGas?: string | number | bigint | null;
114
131
  readonly maxPriorityFeePerGas?: string | number | bigint | null;
@@ -169,7 +186,9 @@ export interface NinseiOptions {
169
186
  createRecord?: (request: StartRequest) => Promise<SwapRecord> | SwapRecord;
170
187
  }
171
188
 
172
- /** One durable sender attempt on a sell record, written before the relay POST. */
189
+ /** One durable sender attempt on a sell record, written before the relay POST. This is a diagnostic journal,
190
+ * not a set of senders that must be skipped on a later call. The journal is append-only and is not pruned by the
191
+ * SDK; a host may trim old entries, but must keep the latest `sending`/`unknown` one for its slot wait. */
173
192
  export interface StoredClaimAttempt {
174
193
  readonly sender: string;
175
194
  readonly at?: number;
@@ -194,9 +213,9 @@ export interface SwapRecord {
194
213
  }
195
214
 
196
215
  export interface StorageAdapter {
197
- get(key: string): string | null | Promise<string | null>;
198
- set(key: string, value: string): void | Promise<void>;
199
- remove(key: string): void | Promise<void>;
216
+ get(key: string): string | null;
217
+ set(key: string, value: string): void;
218
+ remove(key: string): void;
200
219
  }
201
220
 
202
221
  export interface HttpResponse {
@@ -438,6 +457,30 @@ export interface QuotesApi {
438
457
  * requested terms and the on-chain registry/factory binding before it is returned.
439
458
  */
440
459
  firmRelay(request: FirmRelayOffer): Promise<FirmRelayAnswer>;
460
+ /**
461
+ * Place `readyBy` and `t1` inside the signed window for one market, side and Monero network, measured from the
462
+ * chain's `chainNow`. It reads nothing and signs nothing; the caller spreads the deadlines into the order.
463
+ */
464
+ firmRequest(request: FirmRequestInput): FirmRequestResult;
465
+ }
466
+
467
+ export interface FirmRequestInput {
468
+ /** The signed public features that carry `firmWindows`. */
469
+ readonly features: Readonly<Record<string, unknown>>;
470
+ readonly side: "ask" | "bid";
471
+ readonly market: string;
472
+ readonly xmrNetwork: string;
473
+ /** The latest chain block time in Unix seconds. */
474
+ readonly chainNow: number;
475
+ }
476
+
477
+ export interface FirmRequestResult {
478
+ readonly market: string;
479
+ readonly side: "ask" | "bid";
480
+ readonly xmrNetwork: string;
481
+ readonly window: ReadyWindow;
482
+ readonly readyBy: number;
483
+ readonly t1: number;
441
484
  }
442
485
 
443
486
  /**
@@ -682,10 +725,15 @@ export interface SwapsApi {
682
725
  * sender. `claimSenders` is the client's ordered list - the relay's own sender first, then the listed makers -
683
726
  * sent one at a time through the relay (`POST /v1/claims/{sender}/{escrow}`). Each sender gets a 15-30 s slot; a
684
727
  * refusal moves on, a txid or unknown answer is followed by reading the escrow, and only `claimed` on chain is
685
- * success. When the list is exhausted the result is `claim-yourself` with the time left before `t1`.
728
+ * success. A later call starts from the first sender again; a previous `sending`/`unknown` entry is waited out
729
+ * for its slot and retried, so a temporary refusal or a restart is recoverable. When the list is exhausted the
730
+ * result is `claim-yourself` with the time left before `t1`.
686
731
  *
687
- * The deal's maker and its quote-key owner are refused before the half leaves the client. No wallet is created or
688
- * used and no chain transaction is signed. `relayUrl` may restate the stored origin; a different origin is refused.
732
+ * The claim window is read with the escrow's chain clock (`evmBlock`), not the device clock. Without a readable
733
+ * clock the result is `claim-window` / `unreadable` and no half leaves the client. The same applies to an escrow
734
+ * read that fails before any POST; after an earlier attempt it remains `claim-unknown`. The deal's maker and its
735
+ * quote-key owner are refused before the half leaves the client. No wallet is created or used and no chain
736
+ * transaction is signed. `relayUrl` may restate the stored origin; a different origin is refused.
689
737
  */
690
738
  claimViaRelay(request: RelayClaimRequest): Promise<RelayClaimResult>;
691
739
  /**
@@ -715,10 +763,35 @@ export interface SwapsApi {
715
763
  * key and `ready` opens only when at least two nodes of DIFFERENT operators see the transaction IN THE SAME BLOCK
716
764
  * (the block hash matches) with the required confirmations. Refusals come as CODES: `xmr-nodes-disagree` (a synced
717
765
  * node has no such transaction there or a different block hash), `xmr-no-nodes` (nothing reachable),
718
- * `xmr-underpaid`, `xmr-locked`, `xmr-too-late`. A waiting state is RETURNED as `state` (`pending` | `one-node`),
719
- * never a silent success.
766
+ * `xmr-underpaid`, `xmr-locked`, `xmr-too-late`. A waiting state is RETURNED as `state` (`pending` | `one-node` |
767
+ * `pool`), never a silent success. `pool` carries the matching txid while the transfer is still in a node's
768
+ * mempool; it is information only and never counts as seen or arrived.
720
769
  */
721
770
  verifyArrival(request: XmrArrivalRequest): Promise<XmrArrivalVerdict>;
771
+ /** The same arrival decision over one recovery read with the explicit `at-least` or `exact` amount rule. */
772
+ verifyArrivalFromRead(request: XmrArrivalRequest): Promise<XmrArrivalVerdict>;
773
+ /**
774
+ * THE RECOVERY READ. Returns every transfer to the address from `fromHeight` with its verified outputs,
775
+ * confirmations, unlock state and the operators that agreed on the observation. There is no expected amount:
776
+ * a short, overpaid or split payment is data, not a refusal. A transfer still in a node's pool is returned
777
+ * with `pool: true` and `confirmed: false`. `agreed` is false when fewer than two operators saw the same
778
+ * observation; `complete` is false when a block or pool read failed.
779
+ */
780
+ verifyRecovery(request: XmrRecoveryRequest): Promise<XmrRecoveryVerdict>;
781
+ /**
782
+ * THE PRIMARY READ. One chosen node from `fromHeight` to its head, with a caller-owned checkpoint, progress
783
+ * events and a resume that continues after the verified block. It is not a two-operator decision; a complete
784
+ * range from this node is the history input on which the independent check (or a later confirmation) is built.
785
+ * A short body, a moved anchor or a broken parent link is `complete: false`, never an empty range.
786
+ */
787
+ readRecovery(request: XmrRecoveryReadRequest): Promise<XmrRecoveryReadVerdict>;
788
+ /**
789
+ * THE WITNESS READ ON A PLAIN MONEROD. It asks for whole fixed windows of the zero-aligned grid, never for the
790
+ * exact start or a payout height, and reads every height and every transaction hash of each window. A matching
791
+ * transfer does not stop the walk. `tipHeight` is the primary read's top; a witness below it is incomplete.
792
+ * The residual privacy leak is the grid bucket that contains the start.
793
+ */
794
+ readRecoveryWitness(request: XmrRecoveryWitnessRequest): Promise<XmrRecoveryWitnessVerdict>;
722
795
  /**
723
796
  * RUN THE EXACT CHECK AND THE WITNESS-V1 SLICE CHECK SIDE BY SIDE. The exact verdict still decides; this
724
797
  * returns both readings and any difference, and changes no swap state. `witnessNodes` must name at least one
@@ -829,17 +902,224 @@ export interface XmrArrivalRequest {
829
902
  readonly nodes: readonly (XmrNode | string)[];
830
903
  readonly address: string;
831
904
  readonly viewSecret: string | bigint;
832
- readonly spendPub: string;
905
+ /** Optional for arrival: the public spend key is read from the address. A supplied key is checked. */
906
+ readonly spendPub?: string;
833
907
  readonly expectedAtomic: string | number | bigint;
908
+ /** `at-least` (buy) or `exact` (sale). Selecting a rule uses the one-read amount path. */
909
+ readonly amountRule?: "at-least" | "exact";
834
910
  readonly minConfirmations?: number;
835
911
  readonly txid?: string | null;
836
912
  readonly fromHeight?: number | null;
837
913
  readonly nowSec?: number;
838
914
  readonly timeoutMs?: number;
915
+ readonly keyImages?: readonly (string | XmrRecoveryKeyImage)[];
839
916
  /** The transport for node and witness reads; absent - the client's `fetch`, otherwise the global fetch. */
840
917
  readonly fetch?: FetchLike;
841
918
  }
842
919
 
920
+ /** Inputs for the recovery read: the same watch identity, but NO quoted amount. */
921
+ export interface XmrRecoveryRequest {
922
+ readonly nodes: readonly (XmrNode | string)[];
923
+ readonly address: string;
924
+ readonly viewSecret: string | bigint;
925
+ /** Optional: the public spend key is read from the address; a supplied key is checked. */
926
+ readonly spendPub?: string;
927
+ readonly fromHeight: number;
928
+ readonly minConfirmations?: number;
929
+ readonly nowSec?: number;
930
+ readonly idleTimeoutMs?: number;
931
+ readonly timeoutMs?: number;
932
+ readonly fetch?: FetchLike;
933
+ /** Key images from `sweep.keyImages`; without them spends and the available remainder are unknown. */
934
+ readonly keyImages?: readonly (string | XmrRecoveryKeyImage)[];
935
+ }
936
+
937
+ /** The caller-owned checkpoint of the primary or witness recovery read. */
938
+ export interface XmrRecoveryCheckpoint {
939
+ readonly version: 1;
940
+ /** Absent on records written before the witness read existed; `"witness"` marks a grid-window record. */
941
+ readonly kind?: "primary" | "witness";
942
+ readonly grid?: number;
943
+ readonly network: string;
944
+ readonly address: string;
945
+ readonly fromHeight: number;
946
+ readonly through: { readonly height: number; readonly hash: string } | null;
947
+ readonly transfers: readonly XmrRecoveryTransfer[];
948
+ readonly outputs: readonly Record<string, unknown>[];
949
+ readonly spends: readonly XmrRecoverySpend[];
950
+ readonly digest: string;
951
+ }
952
+
953
+ export interface XmrRecoveryCheckpointStore {
954
+ read(): XmrRecoveryCheckpoint | null | undefined;
955
+ save(record: XmrRecoveryCheckpoint): void;
956
+ discard?(): void;
957
+ }
958
+
959
+ export interface XmrRecoveryProgress {
960
+ readonly phase: "blocks";
961
+ readonly through: number | null;
962
+ readonly blocksVerified: number;
963
+ readonly blocksTotal: number;
964
+ readonly bytes: number;
965
+ readonly operator: string;
966
+ }
967
+
968
+ /**
969
+ * ONE NODE, FROM `fromHeight` TO ITS HEAD. Unlike `verifyRecovery`, this is a history/progress read, not a
970
+ * two-operator decision: the caller owns the independent check. The checkpoint is stored by the caller; a moved
971
+ * anchor or a digest that does not describe the record makes the SDK replay from `fromHeight`.
972
+ */
973
+ export interface XmrRecoveryReadRequest {
974
+ readonly node: XmrNode | string;
975
+ readonly address: string;
976
+ readonly viewSecret: string | bigint;
977
+ readonly spendPub: string;
978
+ readonly fromHeight: number;
979
+ readonly minConfirmations?: number;
980
+ readonly network?: string;
981
+ readonly nowSec?: number;
982
+ readonly idleTimeoutMs?: number;
983
+ readonly timeoutMs?: number;
984
+ readonly fetch?: FetchLike;
985
+ readonly keyImages?: readonly (string | XmrRecoveryKeyImage)[];
986
+ /** The signed withdrawal hash to note if this walk meets it in a block or in the pool. */
987
+ readonly txid?: string;
988
+ readonly checkpoint?: XmrRecoveryCheckpointStore;
989
+ readonly onProgress?: (event: XmrRecoveryProgress) => void;
990
+ readonly signal?: AbortSignal;
991
+ }
992
+
993
+ export interface XmrRecoveryTarget {
994
+ readonly txid: string;
995
+ readonly height: number | null;
996
+ readonly blockHash: string | null;
997
+ readonly pool: boolean;
998
+ }
999
+
1000
+ export interface XmrRecoveryReadVerdict {
1001
+ readonly transfers: readonly XmrRecoveryTransfer[];
1002
+ readonly tip: number | null;
1003
+ readonly fromHeight: number;
1004
+ readonly minConfirmations: number;
1005
+ readonly complete: boolean;
1006
+ readonly through: { readonly height: number; readonly hash: string } | null;
1007
+ /** The requested `txid`, when the walk met it in a block or in the pool. */
1008
+ readonly target?: XmrRecoveryTarget | null;
1009
+ readonly spends?: readonly XmrRecoverySpend[];
1010
+ /** Verified, confirmed, unlocked funding outputs minus matched spends. Null when the read is incomplete or a key image has no `outputKey`. */
1011
+ readonly availableAtomic?: string | null;
1012
+ /** The primary node that supplied `availableAtomic`; available is a one-node claim, not a two-operator agreement. */
1013
+ readonly availableSource?: { readonly url: string; readonly operator: string };
1014
+ readonly checkpoint: XmrRecoveryCheckpoint | null;
1015
+ readonly blocked: boolean;
1016
+ readonly failed: readonly { readonly url: string; readonly operator: string; readonly code?: string; readonly why?: string; readonly height?: number; readonly status?: number }[];
1017
+ }
1018
+
1019
+ export interface XmrRecoveryWitnessProgress {
1020
+ readonly phase: "witness";
1021
+ readonly through: number | null;
1022
+ readonly blocksVerified: number;
1023
+ readonly blocksTotal: number;
1024
+ readonly bytes: number;
1025
+ readonly operator: string;
1026
+ readonly window: number;
1027
+ }
1028
+
1029
+ /** One plain-monerod witness, read by whole fixed windows; the exact start is only a local grid selector. */
1030
+ export interface XmrRecoveryWitnessRequest {
1031
+ readonly node: XmrNode | string;
1032
+ readonly address: string;
1033
+ readonly viewSecret: string | bigint;
1034
+ readonly spendPub: string;
1035
+ readonly fromHeight: number;
1036
+ /** The top the primary read reached. A witness below it returns `complete: false`. */
1037
+ readonly tipHeight?: number;
1038
+ readonly minConfirmations?: number;
1039
+ readonly network?: string;
1040
+ readonly nowSec?: number;
1041
+ readonly idleTimeoutMs?: number;
1042
+ readonly timeoutMs?: number;
1043
+ readonly fetch?: FetchLike;
1044
+ readonly keyImages?: readonly (string | XmrRecoveryKeyImage)[];
1045
+ readonly checkpoint?: XmrRecoveryCheckpointStore;
1046
+ readonly onProgress?: (event: XmrRecoveryWitnessProgress) => void;
1047
+ readonly signal?: AbortSignal;
1048
+ }
1049
+
1050
+ export interface XmrRecoveryWitnessVerdict {
1051
+ readonly transfers: readonly XmrRecoveryTransfer[];
1052
+ readonly tip: number | null;
1053
+ readonly fromHeight: number;
1054
+ readonly complete: boolean;
1055
+ readonly through: { readonly height: number; readonly hash: string } | null;
1056
+ readonly spends?: readonly XmrRecoverySpend[];
1057
+ /** Verified, confirmed, unlocked funding outputs minus matched spends. Null when the read is incomplete or a key image has no `outputKey`. */
1058
+ readonly availableAtomic?: string | null;
1059
+ /** The primary node that supplied `availableAtomic`; available is a one-node claim, not a two-operator agreement. */
1060
+ readonly availableSource?: { readonly url: string; readonly operator: string };
1061
+ readonly checkpoint: XmrRecoveryCheckpoint | null;
1062
+ readonly blocked: boolean;
1063
+ readonly failed: readonly { readonly url: string; readonly operator: string; readonly code?: string; readonly why?: string; readonly height?: number; readonly status?: number }[];
1064
+ }
1065
+
1066
+ /** One key image supplied by `sweep.keyImages`; `outputKey` is required for the available remainder. */
1067
+ export interface XmrRecoveryKeyImage {
1068
+ readonly keyImage: string;
1069
+ readonly outputKey?: string;
1070
+ }
1071
+
1072
+ /** One input whose key image belongs to the funding outputs. */
1073
+ export interface XmrRecoverySpend {
1074
+ readonly keyImage: string;
1075
+ readonly outputKey: string | null;
1076
+ readonly txid: string;
1077
+ readonly height: number | null;
1078
+ readonly blockHash: string | null;
1079
+ readonly pool: boolean;
1080
+ }
1081
+
1082
+ /** One verified transfer returned by the recovery read. */
1083
+ export interface XmrRecoveryTransfer {
1084
+ readonly txid: string;
1085
+ /** null while the transfer is still in a node's pool. */
1086
+ readonly height: number | null;
1087
+ readonly blockHash: string | null;
1088
+ readonly pool: boolean;
1089
+ readonly confirmations: number;
1090
+ readonly confirmed: boolean;
1091
+ readonly amountAtomic: string;
1092
+ readonly amountVerified: boolean;
1093
+ readonly outputs: readonly { readonly index: number; readonly key: string; readonly amountAtomic: string | null; readonly amountVerified: boolean; readonly derivation: string }[];
1094
+ readonly locked: boolean;
1095
+ readonly unlock: { readonly locked: boolean; readonly untilHeight: number | null; readonly untilTime: number | null } | null;
1096
+ readonly operators: readonly string[];
1097
+ readonly agreed: boolean;
1098
+ readonly agreedBy: readonly { readonly url: string; readonly operator: string; readonly confirmations: number }[];
1099
+ readonly disagreements: readonly { readonly operators: readonly string[]; readonly amountAtomic: string }[];
1100
+ }
1101
+
1102
+ /** The recovery read's answer. `ready` means at least one agreed, confirmed, unlocked transfer exists. */
1103
+ export interface XmrRecoveryVerdict {
1104
+ readonly state: "ready" | "pending" | "one-node" | "none";
1105
+ readonly transfers: readonly XmrRecoveryTransfer[];
1106
+ readonly tip: number;
1107
+ readonly fromHeight: number;
1108
+ readonly minConfirmations: number;
1109
+ /** False when any read failed; a caller must not treat the list as exhaustive. */
1110
+ readonly complete: boolean;
1111
+ readonly completedOperators?: readonly string[];
1112
+ readonly spends?: readonly XmrRecoverySpend[];
1113
+ /** Spends seen by a witness but not by the primary; the available remainder is withheld when non-empty. */
1114
+ readonly spendsDisagreements?: readonly XmrRecoverySpend[];
1115
+ /** Verified, confirmed, unlocked funding outputs minus matched spends. Null when the read is incomplete or a key image has no `outputKey`. */
1116
+ readonly availableAtomic?: string | null;
1117
+ /** The primary node that supplied `availableAtomic`; available is a one-node claim, not a two-operator agreement. */
1118
+ readonly availableSource?: { readonly url: string; readonly operator: string } | null;
1119
+ readonly checked: readonly { readonly url: string; readonly operator: string; readonly height: number; readonly synchronized: boolean }[];
1120
+ readonly failed: readonly { readonly url: string; readonly operator: string; readonly code?: string; readonly why?: string; readonly height?: number; readonly status?: number }[];
1121
+ }
1122
+
843
1123
  /** The slice check's extra input: independent witnesses that serve witness-v1. */
844
1124
  export interface XmrArrivalShadowRequest extends XmrArrivalRequest {
845
1125
  readonly witnessNodes: readonly (XmrNode | string)[];
@@ -886,19 +1166,35 @@ export interface XmrArrivalShadowResult {
886
1166
  /** The XMR state the watch hands to the interface: the fact, the waiting state, or a refusal with a code. */
887
1167
  export interface XmrArrivalVerdict {
888
1168
  readonly seen: boolean;
889
- readonly state: "arrived" | "pending" | "one-node";
1169
+ readonly state: "arrived" | "pending" | "one-node" | "pool";
890
1170
  /** True only when a node completed the walk and found no matching transaction. */
891
1171
  readonly absent?: boolean;
892
1172
  /** The operators whose completed walk found no matching transaction. */
893
1173
  readonly completedOperators?: readonly string[];
894
1174
  readonly txid: string | null;
895
- readonly height?: number;
1175
+ /** A block height; null when the matching transfer is still in a node's pool. */
1176
+ readonly height?: number | null;
896
1177
  readonly blockHash?: string;
897
1178
  readonly amountAtomic?: string;
1179
+ /** Present on a pool match: every reported output passed its Pedersen amount check. */
1180
+ readonly amountVerified?: boolean;
898
1181
  readonly confirmations?: number;
899
1182
  readonly needConfirmations?: number;
1183
+ readonly tip?: number;
900
1184
  readonly operators?: readonly string[];
1185
+ readonly checked?: readonly { readonly url: string; readonly operator: string; readonly height?: number; readonly synchronized?: boolean; readonly state?: string }[];
1186
+ readonly failed?: readonly { readonly url: string; readonly operator: string; readonly code?: string; readonly why?: string; readonly status?: number }[];
1187
+ /** The node that reported the pool match. Present only for `state: "pool"`. */
1188
+ readonly poolFrom?: { readonly url: string; readonly operator: string };
1189
+ /** Whether the transaction's `unlock_time` bars the outputs at the reported tip. */
1190
+ readonly outputs?: readonly { readonly index: number; readonly key: string; readonly amountAtomic: string | null;
1191
+ readonly amountVerified: boolean; readonly derivation: string }[];
1192
+ readonly locked?: boolean;
1193
+ readonly unlock?: { readonly locked: boolean; readonly untilHeight: number | null; readonly untilTime: number | null } | null;
901
1194
  readonly agreedBy?: readonly { readonly url: string; readonly operator: string; readonly blockHash: string; readonly confirmations: number }[];
1195
+ /** Present when the one-read amount path was selected. */
1196
+ readonly amountRule?: "at-least" | "exact";
1197
+ readonly transfers?: readonly XmrRecoveryTransfer[];
902
1198
  }
903
1199
 
904
1200
  /** What the client's own check established on the agreed block. */
@@ -990,12 +1286,9 @@ export interface SellStartRequest {
990
1286
  /** The verified `quotes.firmRelay` answer for the bid side. */
991
1287
  readonly offer: FirmRelayAnswer;
992
1288
  /**
993
- * Optional legacy single sender stored for a no-ETH claim. The ordered list passed to `claimViaRelay` is the
994
- * authority; this scalar is only a one-element fallback for callers written before the list existed. A sender
995
- * naming the deal's maker or its quote-key owner is refused.
1289
+ * Optional ordered senders stored for a no-ETH claim. An explicit list replaces the relay-published sender;
1290
+ * the published sender is used only when no list is passed. The old scalar is retired.
996
1291
  */
997
- readonly claimSender?: string;
998
- /** The ordered senders stored for a later `claimViaRelay`; the relay's published sender is prepended. */
999
1292
  readonly claimSenders?: readonly string[];
1000
1293
  /** The twelve-word key; required only when no key is stored yet. */
1001
1294
  readonly recoveryKey?: string | { readonly mnemonic: string };
@@ -1019,8 +1312,6 @@ export interface SellStart {
1019
1312
  readonly xmrAmount: string;
1020
1313
  readonly claimTip: string | null;
1021
1314
  readonly orderQuote: Readonly<Record<string, unknown>> | null;
1022
- /** The legacy single sender stored by `startSell`, or null when the client supplies the list at claim time. */
1023
- readonly claimSender: string | null;
1024
1315
  /** The ordered senders stored by `startSell`; empty when the client supplies the list at claim time. */
1025
1316
  readonly claimSenders: readonly string[];
1026
1317
  readonly readyWindow: ReadyWindow | null;
@@ -1039,16 +1330,15 @@ export interface SellClaimRequest {
1039
1330
  /**
1040
1331
  * THE NO-WALLET CLAIM'S INPUTS. `id` names the sell record made by `startSell`; the escrow, half and signed tip
1041
1332
  * come from it. `claimSenders` is the client's ordered list: the relay's own sender first, then the listed makers.
1042
- * Each entry is checked for the deal's maker and its quote-key owner. The old scalar `claimSender` is accepted as a
1043
- * one-element fallback for callers written before the list. `relayUrl` is optional and may only repeat the origin
1044
- * stored with the record - a foreign origin is refused.
1333
+ * Each entry is checked for the deal's maker and its quote-key owner. The old scalar `claimSender` is retired and
1334
+ * refused by name. `relayUrl` is optional and may only repeat the origin stored with the record - a foreign origin
1335
+ * is refused. A second call is allowed after a refusal or an unknown answer: the journal is diagnostic and the
1336
+ * sender list is walked from the beginning once any previous slot ends.
1045
1337
  */
1046
1338
  export interface RelayClaimRequest {
1047
1339
  readonly id: string;
1048
1340
  /** Ordered senders. Tried one at a time; the first that lands a claim on chain wins. */
1049
1341
  readonly claimSenders?: readonly string[];
1050
- /** One-element fallback for a caller written before `claimSenders`; may never name the deal's maker. */
1051
- readonly claimSender?: string;
1052
1342
  readonly relayUrl?: string;
1053
1343
  /** One sender's slot; clamped to 15-30 s. Default 20 s. */
1054
1344
  readonly slotMs?: number;
@@ -1074,7 +1364,6 @@ export interface RelayClaimed {
1074
1364
  readonly id: string;
1075
1365
  /** The sender whose slot found the claim; null when the escrow already read claimed before the first POST. */
1076
1366
  readonly provider: string | null;
1077
- readonly claimSender: string | null;
1078
1367
  readonly escrow: string;
1079
1368
  readonly relayUrl: string;
1080
1369
  /** The txid when an answer carried one; `null` when the claim was found on chain without it. */
@@ -1090,7 +1379,6 @@ export interface RelayClaimYourself {
1090
1379
  readonly reason: "senders-exhausted";
1091
1380
  readonly id: string;
1092
1381
  readonly provider: null;
1093
- readonly claimSender: null;
1094
1382
  readonly escrow: string;
1095
1383
  readonly relayUrl: string;
1096
1384
  readonly txid: null;
@@ -1102,15 +1390,15 @@ export interface RelayClaimYourself {
1102
1390
  }
1103
1391
 
1104
1392
  /**
1105
- * The half was not handed to any sender because the escrow's own claim window is not open. The caller must not
1106
- * retry the relay list: the state, not the sender, is the answer.
1393
+ * The half was not handed to any sender because the escrow's own claim window is not open. For a closed,
1394
+ * not-ready, margin or unfunded state the state is the answer; `unreadable` can be retried once the chain clock
1395
+ * and escrow state are readable again.
1107
1396
  */
1108
1397
  export interface RelayClaimWindow {
1109
1398
  readonly state: "claim-window";
1110
1399
  readonly reason: "not-ready" | "window-closed" | "settlement-margin" | "unreadable" | "not-funded" | "escrow-refused" | "escrow-refunded";
1111
1400
  readonly id: string;
1112
1401
  readonly provider: null;
1113
- readonly claimSender: null;
1114
1402
  readonly escrow: string;
1115
1403
  readonly relayUrl: string;
1116
1404
  readonly txid: null;
@@ -1153,7 +1441,8 @@ export interface SellWatchResult {
1153
1441
  export interface SwapWatchRequest {
1154
1442
  /** The local swap record identifier. */
1155
1443
  readonly id: string;
1156
- /** The escrow address for the ready mark (mandatory when `expect` and `wallet` are passed and the record has none). */
1444
+ /** The escrow address for the ready mark. If the record already names an escrow, a different value is refused as
1445
+ * `bad-input` / `record-mismatch` rather than watched under the same id. */
1157
1446
  readonly escrow?: string;
1158
1447
  /** How often to ask the state. Default - `config.limits.watchPollMs`. */
1159
1448
  readonly pollMs?: number;
@@ -1168,7 +1457,8 @@ export interface SwapWatchRequest {
1168
1457
  /**
1169
1458
  * CLIENT-SIDE ARRIVAL CHECK (issue #85). With this the CLIENT decides: it reads the chain itself and `ready`
1170
1459
  * opens only when two operators agree. The backend's `seen` is then only a notification and does not open the
1171
- * button. `verify` is mandatory: without it the watch refuses with `bad-input`.
1460
+ * button. `verify` is mandatory: without it the watch refuses with `bad-input`. `verify.address` must match the
1461
+ * record's `moneroAddress` when the record has one; a different address is `bad-input` / `record-mismatch`.
1172
1462
  */
1173
1463
  readonly verify?: Omit<XmrArrivalRequest, "minConfirmations">;
1174
1464
  /** The confirmation target before `ready`. Default - `config.limits.xmrConfirmations` (10). */
@@ -1435,16 +1725,34 @@ export interface SweepApi {
1435
1725
  */
1436
1726
  keys(request: SweepPlanRequest): Promise<SweepKeys>;
1437
1727
  /**
1438
- * SIGN WITHOUT SENDING. Holds everything up to and including signing (the free remainder -> sign with
1439
- * `relay: false`), and HOLDS the signed transaction, returning the open session's token. An empty remainder stops
1440
- * the withdrawal here with the code `insufficient-funds`. `relay` sends it - so the interface has a place to show
1441
- * the person what will leave, BEFORE sending.
1728
+ * THE KEY IMAGES OF THE VERIFIED FUNDING OUTPUTS. The page has the spend key and the outputs; a wallet would
1729
+ * have to download the block-hash history before it could answer the same question. Every output must be
1730
+ * verified and carry its derivation; a malformed or unverified set is refused as a whole.
1731
+ */
1732
+ keyImages(request: SweepKeyImagesRequest): Promise<readonly SweepKeyImage[]>;
1733
+ /**
1734
+ * SIGN WITHOUT SENDING. Requires a completed `restore` on the same wallet adapter and the verified unspent
1735
+ * `keyImages`: without them the answer is `sweep-scan-incomplete` or `bad-input`. A destination with a bad checksum
1736
+ * or another Monero network is refused before the wallet opens; the signed inputs must be exactly the verified set
1737
+ * (`sweep-inputs-changed` / `sweep-inputs-unknown`), and a sweep that would need more than one transaction is
1738
+ * `sweep-split` before relay.
1442
1739
  */
1443
1740
  sign(request: SweepRunRequest): Promise<SweepSignResult>;
1444
- /** Send what `sign` signed, close the wallet and return the transaction hashes. */
1741
+ /** Send what `sign` signed, close the wallet and return the transaction hashes. A fresh `keyImages` list is
1742
+ * required and must still match the signed inputs. A lost answer throws `sweep-relay-unknown`; the session token
1743
+ * stays valid, and the same signed set is never relayed twice. */
1445
1744
  relay(request: SweepRelayRequest): Promise<SweepRunResult>;
1446
- /** Perform the withdrawal as a whole (`sign` + `relay`). */
1745
+ /**
1746
+ * Perform the withdrawal as a whole (`sign` + `relay`). The relay check receives the same verified `keyImages`
1747
+ * that were used for signing; when a fresh post-sign read matters, call `sign` and `relay` separately.
1748
+ */
1447
1749
  run(request: SweepRunRequest): Promise<SweepRunResult>;
1750
+ /**
1751
+ * A LATER LOOK AFTER THE TOKEN IS GONE. Reads the swap address through the same recovery read and decides whether
1752
+ * the saved signed bytes may be sent again. `present` and `inputs-spent` never resend; `unknown` keeps the bytes and
1753
+ * signs nothing; only `absent` with `resend: true` permits the same bytes, with the same hash, to be sent once.
1754
+ */
1755
+ reconcile(request: SweepReconcileRequest): Promise<SweepReconcileResult>;
1448
1756
  }
1449
1757
 
1450
1758
  /** What `restore` needs: the withdrawal adapter and the height named by the file. */
@@ -1489,7 +1797,7 @@ export interface SweepRestoreResult {
1489
1797
  readonly unlocked: string;
1490
1798
  /** False when the wallet did not reach the node's height after its sync; a zero balance is then not evidence. */
1491
1799
  readonly scanComplete: boolean;
1492
- /** `sync-failed`, `behind-node` or `no-heights` when `scanComplete` is false. */
1800
+ /** `sync-failed`, `rescan-failed`, `behind-node`, `no-heights` or `spent-status-unavailable` when `scanComplete` is false. */
1493
1801
  readonly scanIncompleteReason?: string;
1494
1802
  /** The height the scan actually started from. */
1495
1803
  readonly scanHeight: number;
@@ -1641,6 +1949,8 @@ export interface SweepPlan {
1641
1949
  readonly swapId: string | null;
1642
1950
  /** The joint Monero address the XMR arrived at. */
1643
1951
  readonly address: string;
1952
+ /** The Monero network the recovery file names, or null when it named none. */
1953
+ readonly network: string | null;
1644
1954
  /** Whether there is enough data to dispose of the funds (whether our own spend-key half is present). */
1645
1955
  readonly spendable: boolean;
1646
1956
  /** The restore height: 0 - unknown. */
@@ -1666,12 +1976,43 @@ export interface SweepKeys {
1666
1976
  readonly address: string;
1667
1977
  }
1668
1978
 
1979
+ /** One verified output as the arrival and recovery reads return it. */
1980
+ export interface XmrKeyImageOutput {
1981
+ readonly index: number;
1982
+ readonly key: string;
1983
+ readonly amountAtomic: string | null;
1984
+ readonly amountVerified: boolean;
1985
+ /** The per-output derivation from `scan.js`; required to derive the key image without a wallet. */
1986
+ readonly derivation: string;
1987
+ }
1988
+
1989
+ export interface XmrKeyImageArrival {
1990
+ readonly outputs?: readonly XmrKeyImageOutput[] | undefined;
1991
+ }
1992
+
1993
+ export interface SweepKeyImagesRequest {
1994
+ readonly keys: SweepKeys;
1995
+ /** `verifyArrival` or one transfer from `verifyRecovery`. */
1996
+ readonly arrival: XmrKeyImageArrival;
1997
+ }
1998
+
1999
+ export interface SweepKeyImage {
2000
+ readonly outputKey: string;
2001
+ readonly amountAtomic: string;
2002
+ readonly keyImage: string;
2003
+ }
2004
+
1669
2005
  export type SweepStep = "unlock" | "sync" | "sweep" | "relay";
1670
2006
  export type SweepMissing = "restore-height" | "spendable" | "revealed-half";
1671
2007
 
1672
2008
  export interface SweepRunRequest extends SweepPlanRequest {
1673
2009
  /** Where to withdraw the XMR to. */
1674
2010
  readonly to: string;
2011
+ /**
2012
+ * The verified unspent key images for this withdrawal, from `sweep.keyImages`. Signing refuses when the signed
2013
+ * transaction's inputs are not exactly this set; the list is required, because an omitted list is not an empty one.
2014
+ */
2015
+ readonly keyImages: readonly (string | SweepKeyImage)[];
1675
2016
  /** An already opened and synced adapter, the same one `restore` used. */
1676
2017
  readonly wallet?: MoneroWalletAdapter;
1677
2018
  /** Returns a Monero wallet: the core does not drag in WASM. */
@@ -1742,16 +2083,59 @@ export interface SweepSignResult {
1742
2083
  readonly swept: string;
1743
2084
  }
1744
2085
 
1745
- /** Sending what was signed: the session token `sign` returned. */
2086
+ /** Sending what was signed: the session token `sign` returned. The token stays valid when the answer is unknown. */
1746
2087
  export interface SweepRelayRequest {
1747
2088
  readonly token: string;
2089
+ /**
2090
+ * A fresh unspent set read after signing. Relay refuses `sweep-inputs-changed` unless it is exactly the signed
2091
+ * input set; the session stays open for a correct retry.
2092
+ */
2093
+ readonly keyImages: readonly (string | SweepKeyImage)[];
1748
2094
  }
1749
2095
 
1750
2096
  export interface SweepRunResult {
2097
+ /** Every signed transaction was relayed. A lost answer throws `sweep-relay-unknown` instead. */
2098
+ readonly outcome: "sent";
1751
2099
  readonly txids: readonly string[];
1752
2100
  readonly swept: string;
1753
2101
  }
1754
2102
 
2103
+ /** The saved signed withdrawal, read later without a session token. */
2104
+ export interface SweepReconcileRequest {
2105
+ readonly node: XmrNode | string;
2106
+ readonly address: string;
2107
+ readonly viewSecret: string | bigint;
2108
+ readonly spendPub: string;
2109
+ readonly fromHeight: number;
2110
+ /** The hash the signed bytes already have. */
2111
+ readonly txid: string;
2112
+ /** The same verified unspent set that was used for signing. */
2113
+ readonly keyImages: readonly (string | SweepKeyImage)[];
2114
+ readonly minConfirmations?: number;
2115
+ readonly network?: string;
2116
+ readonly nowSec?: number;
2117
+ readonly timeoutMs?: number;
2118
+ readonly fetch?: FetchLike;
2119
+ readonly signal?: AbortSignal;
2120
+ }
2121
+
2122
+ export interface SweepReconcileResult {
2123
+ /**
2124
+ * `present` - the hash is in a block or in the pool; `inputs-spent` - the hash is absent but an input moved;
2125
+ * `unknown` - the read could not decide; `absent` - the hash is absent and every input is still unspent.
2126
+ */
2127
+ readonly outcome: "present" | "inputs-spent" | "unknown" | "absent";
2128
+ /** True only for `absent`: the same signed bytes, with the same hash, may be sent once. */
2129
+ readonly resend: boolean;
2130
+ readonly txid: string;
2131
+ readonly height: number | null;
2132
+ readonly blockHash: string | null;
2133
+ readonly pool: boolean;
2134
+ /** Whether the underlying recovery read covered every block and the pool. */
2135
+ readonly complete: boolean;
2136
+ readonly failed: readonly { readonly url: string; readonly operator: string; readonly code?: string; readonly why?: string; readonly height?: number; readonly status?: number }[];
2137
+ }
2138
+
1755
2139
  // --- Recovery// --- Recovery ------------------------------------------------------------------------------
1756
2140
 
1757
2141
  /** Order checks and pure order helpers. Checks are BEFORE the signature: after it there is nothing to fix. */
@@ -1770,7 +2154,8 @@ export interface OrderApi {
1770
2154
  * The ONE native amount of a token-funded order: the quote's `payNative` in the network's native decimals.
1771
2155
  * The escrow holds native coin, so the token amount is never used as the escrow amount (a 6-decimal token
1772
2156
  * would be off by 10^12). A quote without a native figure answers `{ ok: false, code: "native-amount-unread" }`;
1773
- * it is never replaced by the payment amount.
2157
+ * it is never replaced by the payment amount. A canonical decimal string is required: extra significant digits,
2158
+ * exponent form and an unsafe `number` are refused rather than rounded.
1774
2159
  */
1775
2160
  escrowNativeWei(request?: { readonly quote?: Readonly<Record<string, unknown>> | null; readonly nativeDecimals?: number }): EscrowNativeAmount;
1776
2161
  /**
@@ -1990,6 +2375,15 @@ export type ErrorCode =
1990
2375
  /** A wallet/node reported a withdrawal fee above the SDK's ceiling; the transfer is refused. */
1991
2376
  | "sweep-fee-too-high"
1992
2377
  | "sweep-fee-unknown"
2378
+ /** The restore did not complete on the wallet's node, so signing would spend blind. */
2379
+ | "sweep-scan-incomplete"
2380
+ /** The sweep needed more than one transaction; a swap address is withdrawn in one. */
2381
+ | "sweep-split"
2382
+ /** The signed transaction's inputs differ from the verified unspent set. */
2383
+ | "sweep-inputs-changed"
2384
+ /** The signed transaction did not expose readable inputs, so the set cannot be checked. */
2385
+ | "sweep-inputs-unknown"
2386
+ | "sweep-relay-unknown"
1993
2387
  /** The maker declines to pay the claim gas; the refusal is shown before the deal (issue #78). */
1994
2388
  | "gas-refused-by-maker"
1995
2389
  /** The claim gas was ordered but the recipient's balance did not grow. */