@ninsei-labs/sdk 0.61.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 (71) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +56 -5
  3. package/assets/vendors/MANIFEST.json +1 -1
  4. package/assets/vendors/sdk/sdk-browser.js +4 -4
  5. package/engine/atomic/halfenc.js +6 -6
  6. package/engine/core/config.js +17 -38
  7. package/engine/core/format.js +1 -1
  8. package/engine/core/sellWindow.js +1 -1
  9. package/engine/core/store.js +11 -3
  10. package/engine/core/swap.js +3 -3
  11. package/engine/evm/amounts.js +2 -2
  12. package/engine/evm/asyncRoute.js +3 -3
  13. package/engine/evm/dex.js +1 -1
  14. package/engine/evm/factory.js +1 -1
  15. package/engine/evm/fees.js +62 -0
  16. package/engine/evm/funding.js +71 -66
  17. package/engine/evm/gasReserve.js +10 -0
  18. package/engine/evm/index.js +2 -2
  19. package/engine/evm/prices.js +3 -0
  20. package/engine/evm/session.js +1 -1
  21. package/engine/monero/address.js +4 -2
  22. package/engine/monero/arrivalRead.js +15 -2
  23. package/engine/monero/keyImage.js +146 -0
  24. package/engine/monero/keys.js +1 -0
  25. package/engine/monero/mnemonic.js +2 -1
  26. package/engine/monero/node.js +1 -0
  27. package/engine/monero/scan.js +12 -2
  28. package/engine/recovery/recoveryFile.js +31 -85
  29. package/engine/sdk/bridge.js +21 -51
  30. package/index.d.ts +412 -19
  31. package/package.json +20 -2
  32. package/src/actions.mjs +72 -6
  33. package/src/addressGuard.mjs +16 -0
  34. package/src/codes.mjs +26 -9
  35. package/src/config.mjs +56 -3
  36. package/src/decline.mjs +23 -74
  37. package/src/firmRequest.mjs +80 -0
  38. package/src/index.mjs +17 -28
  39. package/src/legs/cow.mjs +2 -2
  40. package/src/legs/evm.mjs +20 -12
  41. package/src/legs/kyber-spec.mjs +2 -2
  42. package/src/legs/kyber.mjs +1 -1
  43. package/src/legs/shape.mjs +1 -1
  44. package/src/legs/uniswaprelay.mjs +16 -4
  45. package/src/legs/uniswapx.mjs +29 -7
  46. package/src/levelsWalkSpec.mjs +1 -1
  47. package/src/lock.mjs +18 -37
  48. package/src/provider/envFile.mjs +3 -3
  49. package/src/provider/sign.mjs +3 -3
  50. package/src/public/evm.d.ts +84 -0
  51. package/src/public/evm.mjs +20 -0
  52. package/src/public/order.mjs +1 -1
  53. package/src/public/provider.mjs +1 -1
  54. package/src/public/recovery.d.ts +3 -2
  55. package/src/public/recovery.mjs +1 -1
  56. package/src/public/xmr.d.ts +2 -2
  57. package/src/quoteEip712Spec.mjs +4 -4
  58. package/src/quotes.mjs +52 -11
  59. package/src/recovery-key.mjs +7 -3
  60. package/src/relayFirmClient.mjs +4 -0
  61. package/src/relayQuote.mjs +1 -0
  62. package/src/sim.mjs +1 -1
  63. package/src/swap-flow.mjs +22 -32
  64. package/src/swaps.mjs +63 -56
  65. package/src/sweep-inputs.mjs +61 -0
  66. package/src/sweep-reconcile.mjs +71 -0
  67. package/src/sweep-restore.mjs +38 -9
  68. package/src/sweep.mjs +164 -10
  69. package/src/version.mjs +1 -1
  70. package/src/wallet.mjs +1 -1
  71. package/src/xmr-arrival.mjs +1041 -43
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;
@@ -196,9 +213,9 @@ export interface SwapRecord {
196
213
  }
197
214
 
198
215
  export interface StorageAdapter {
199
- get(key: string): string | null | Promise<string | null>;
200
- set(key: string, value: string): void | Promise<void>;
201
- remove(key: string): void | Promise<void>;
216
+ get(key: string): string | null;
217
+ set(key: string, value: string): void;
218
+ remove(key: string): void;
202
219
  }
203
220
 
204
221
  export interface HttpResponse {
@@ -440,6 +457,30 @@ export interface QuotesApi {
440
457
  * requested terms and the on-chain registry/factory binding before it is returned.
441
458
  */
442
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;
443
484
  }
444
485
 
445
486
  /**
@@ -722,10 +763,35 @@ export interface SwapsApi {
722
763
  * key and `ready` opens only when at least two nodes of DIFFERENT operators see the transaction IN THE SAME BLOCK
723
764
  * (the block hash matches) with the required confirmations. Refusals come as CODES: `xmr-nodes-disagree` (a synced
724
765
  * node has no such transaction there or a different block hash), `xmr-no-nodes` (nothing reachable),
725
- * `xmr-underpaid`, `xmr-locked`, `xmr-too-late`. A waiting state is RETURNED as `state` (`pending` | `one-node`),
726
- * 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.
727
769
  */
728
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>;
729
795
  /**
730
796
  * RUN THE EXACT CHECK AND THE WITNESS-V1 SLICE CHECK SIDE BY SIDE. The exact verdict still decides; this
731
797
  * returns both readings and any difference, and changes no swap state. `witnessNodes` must name at least one
@@ -836,17 +902,224 @@ export interface XmrArrivalRequest {
836
902
  readonly nodes: readonly (XmrNode | string)[];
837
903
  readonly address: string;
838
904
  readonly viewSecret: string | bigint;
839
- 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;
840
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";
841
910
  readonly minConfirmations?: number;
842
911
  readonly txid?: string | null;
843
912
  readonly fromHeight?: number | null;
844
913
  readonly nowSec?: number;
845
914
  readonly timeoutMs?: number;
915
+ readonly keyImages?: readonly (string | XmrRecoveryKeyImage)[];
846
916
  /** The transport for node and witness reads; absent - the client's `fetch`, otherwise the global fetch. */
847
917
  readonly fetch?: FetchLike;
848
918
  }
849
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
+
850
1123
  /** The slice check's extra input: independent witnesses that serve witness-v1. */
851
1124
  export interface XmrArrivalShadowRequest extends XmrArrivalRequest {
852
1125
  readonly witnessNodes: readonly (XmrNode | string)[];
@@ -893,19 +1166,35 @@ export interface XmrArrivalShadowResult {
893
1166
  /** The XMR state the watch hands to the interface: the fact, the waiting state, or a refusal with a code. */
894
1167
  export interface XmrArrivalVerdict {
895
1168
  readonly seen: boolean;
896
- readonly state: "arrived" | "pending" | "one-node";
1169
+ readonly state: "arrived" | "pending" | "one-node" | "pool";
897
1170
  /** True only when a node completed the walk and found no matching transaction. */
898
1171
  readonly absent?: boolean;
899
1172
  /** The operators whose completed walk found no matching transaction. */
900
1173
  readonly completedOperators?: readonly string[];
901
1174
  readonly txid: string | null;
902
- readonly height?: number;
1175
+ /** A block height; null when the matching transfer is still in a node's pool. */
1176
+ readonly height?: number | null;
903
1177
  readonly blockHash?: string;
904
1178
  readonly amountAtomic?: string;
1179
+ /** Present on a pool match: every reported output passed its Pedersen amount check. */
1180
+ readonly amountVerified?: boolean;
905
1181
  readonly confirmations?: number;
906
1182
  readonly needConfirmations?: number;
1183
+ readonly tip?: number;
907
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;
908
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[];
909
1198
  }
910
1199
 
911
1200
  /** What the client's own check established on the agreed block. */
@@ -1436,16 +1725,34 @@ export interface SweepApi {
1436
1725
  */
1437
1726
  keys(request: SweepPlanRequest): Promise<SweepKeys>;
1438
1727
  /**
1439
- * SIGN WITHOUT SENDING. Holds everything up to and including signing (the free remainder -> sign with
1440
- * `relay: false`), and HOLDS the signed transaction, returning the open session's token. An empty remainder stops
1441
- * the withdrawal here with the code `insufficient-funds`. `relay` sends it - so the interface has a place to show
1442
- * 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.
1443
1739
  */
1444
1740
  sign(request: SweepRunRequest): Promise<SweepSignResult>;
1445
- /** 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. */
1446
1744
  relay(request: SweepRelayRequest): Promise<SweepRunResult>;
1447
- /** 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
+ */
1448
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>;
1449
1756
  }
1450
1757
 
1451
1758
  /** What `restore` needs: the withdrawal adapter and the height named by the file. */
@@ -1490,7 +1797,7 @@ export interface SweepRestoreResult {
1490
1797
  readonly unlocked: string;
1491
1798
  /** False when the wallet did not reach the node's height after its sync; a zero balance is then not evidence. */
1492
1799
  readonly scanComplete: boolean;
1493
- /** `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. */
1494
1801
  readonly scanIncompleteReason?: string;
1495
1802
  /** The height the scan actually started from. */
1496
1803
  readonly scanHeight: number;
@@ -1642,6 +1949,8 @@ export interface SweepPlan {
1642
1949
  readonly swapId: string | null;
1643
1950
  /** The joint Monero address the XMR arrived at. */
1644
1951
  readonly address: string;
1952
+ /** The Monero network the recovery file names, or null when it named none. */
1953
+ readonly network: string | null;
1645
1954
  /** Whether there is enough data to dispose of the funds (whether our own spend-key half is present). */
1646
1955
  readonly spendable: boolean;
1647
1956
  /** The restore height: 0 - unknown. */
@@ -1667,12 +1976,43 @@ export interface SweepKeys {
1667
1976
  readonly address: string;
1668
1977
  }
1669
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
+
1670
2005
  export type SweepStep = "unlock" | "sync" | "sweep" | "relay";
1671
2006
  export type SweepMissing = "restore-height" | "spendable" | "revealed-half";
1672
2007
 
1673
2008
  export interface SweepRunRequest extends SweepPlanRequest {
1674
2009
  /** Where to withdraw the XMR to. */
1675
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)[];
1676
2016
  /** An already opened and synced adapter, the same one `restore` used. */
1677
2017
  readonly wallet?: MoneroWalletAdapter;
1678
2018
  /** Returns a Monero wallet: the core does not drag in WASM. */
@@ -1743,16 +2083,59 @@ export interface SweepSignResult {
1743
2083
  readonly swept: string;
1744
2084
  }
1745
2085
 
1746
- /** 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. */
1747
2087
  export interface SweepRelayRequest {
1748
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)[];
1749
2094
  }
1750
2095
 
1751
2096
  export interface SweepRunResult {
2097
+ /** Every signed transaction was relayed. A lost answer throws `sweep-relay-unknown` instead. */
2098
+ readonly outcome: "sent";
1752
2099
  readonly txids: readonly string[];
1753
2100
  readonly swept: string;
1754
2101
  }
1755
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
+
1756
2139
  // --- Recovery// --- Recovery ------------------------------------------------------------------------------
1757
2140
 
1758
2141
  /** Order checks and pure order helpers. Checks are BEFORE the signature: after it there is nothing to fix. */
@@ -1771,7 +2154,8 @@ export interface OrderApi {
1771
2154
  * The ONE native amount of a token-funded order: the quote's `payNative` in the network's native decimals.
1772
2155
  * The escrow holds native coin, so the token amount is never used as the escrow amount (a 6-decimal token
1773
2156
  * would be off by 10^12). A quote without a native figure answers `{ ok: false, code: "native-amount-unread" }`;
1774
- * 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.
1775
2159
  */
1776
2160
  escrowNativeWei(request?: { readonly quote?: Readonly<Record<string, unknown>> | null; readonly nativeDecimals?: number }): EscrowNativeAmount;
1777
2161
  /**
@@ -1991,6 +2375,15 @@ export type ErrorCode =
1991
2375
  /** A wallet/node reported a withdrawal fee above the SDK's ceiling; the transfer is refused. */
1992
2376
  | "sweep-fee-too-high"
1993
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"
1994
2387
  /** The maker declines to pay the claim gas; the refusal is shown before the deal (issue #78). */
1995
2388
  | "gas-refused-by-maker"
1996
2389
  /** The claim gas was ordered but the recipient's balance did not grow. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ninsei-labs/sdk",
3
- "version": "0.61.0",
3
+ "version": "0.62.0",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "registry": "https://registry.npmjs.org/"
@@ -38,6 +38,11 @@
38
38
  "check:terminal-teeth": "node tools/run-teeth-isolated.mjs tools/check-terminal-teeth.mjs",
39
39
  "check:sweep": "node tools/sweep-refusal.test.mjs",
40
40
  "check:sweep-half": "node tools/check-sweep-half.mjs",
41
+ "check:sweep-relay": "node tools/check-sweep-relay.mjs",
42
+ "check:sweep-sign-guards": "node tools/check-sweep-sign-guards.mjs",
43
+ "check:sweep-inputs": "node tools/check-sweep-inputs.mjs",
44
+ "check:sweep-reconcile": "node tools/check-sweep-reconcile.mjs",
45
+ "check:quote-figures": "node tools/check-quote-figures.mjs",
41
46
  "sync:version": "node tools/sync-version.mjs",
42
47
  "check:restore": "node tools/check-restore.mjs",
43
48
  "check:wallet-factory": "node tools/check-wallet-factory.mjs",
@@ -48,6 +53,10 @@
48
53
  "check:arrival-read": "node tools/check-arrival-read.mjs",
49
54
  "check:backup-confirmation": "node tools/check-backup-confirmation.mjs",
50
55
  "check:key-view": "node tools/check-key-view.mjs",
56
+ "check:key-image": "node tools/check-key-image.mjs",
57
+ "check:key-image-teeth": "node tools/check-key-image-teeth.mjs",
58
+ "check:key-image-oracle": "node tools/check-key-image-oracle.mjs",
59
+ "check:key-image-stand": "node tools/check-key-image-stand.mjs",
51
60
  "check:relay-view": "node tools/check-relay-view.mjs",
52
61
  "check:relay-terms": "node tools/check-relay-terms.mjs",
53
62
  "check:relay-features": "node tools/check-relay-features.mjs",
@@ -58,6 +67,12 @@
58
67
  "check:sell-watch": "node tools/check-sell-watch.mjs",
59
68
  "check:sell-start": "node tools/check-sell-start.mjs",
60
69
  "check:arrival-consensus": "node tools/check-arrival-consensus.mjs",
70
+ "check:arrival-recovery": "node tools/check-arrival-recovery.mjs",
71
+ "check:recovery-read": "node tools/check.mjs --only=recovery-read",
72
+ "check:recovery-read-live": "node tools/check-recovery-read-live.mjs",
73
+ "check:recovery-witness": "node tools/check.mjs --only=recovery-witness",
74
+ "check:recovery-witness-live": "node tools/check-recovery-witness-live.mjs",
75
+ "check:recovery-acceptance": "node tools/check-recovery-acceptance.mjs",
61
76
  "check:arrival-shadow": "node tools/check-arrival-shadow.mjs",
62
77
  "check:arrival-real": "node tools/check-arrival-real.mjs",
63
78
  "check:order-proof": "node tools/check-order-proof.mjs",
@@ -77,6 +92,7 @@
77
92
  "check:contract-vectors": "node tools/check-contract-vectors.mjs",
78
93
  "check:live-contract": "node tools/check-live-contract.mjs",
79
94
  "check:anvil-fork": "node tools/check-anvil-fork.mjs",
95
+ "check:anvil-fee": "node tools/check-anvil-fee.mjs",
80
96
  "check:dex": "node tools/check.mjs --only=cow,cow-refusal,kyber,kyber-refusal,uniswapx,uniswapx-refusal,uniswap-relay,uniswap-relay-refusal",
81
97
  "check:anvil-uniswap": "node tools/check-anvil-uniswap.mjs",
82
98
  "check:atomic-flow": "node tools/check-atomic-flow.mjs",
@@ -85,6 +101,7 @@
85
101
  "check:types-consumer": "node node_modules/typescript/bin/tsc -p tools/ts-consumer/tsconfig.json",
86
102
  "check:monero-live": "node tools/check-monero-live.mjs",
87
103
  "check:native-amount": "node tools/check-native-amount.mjs",
104
+ "check:native-amount-teeth": "node tools/run-teeth-isolated.mjs tools/check-native-amount-teeth.mjs",
88
105
  "check:ci-boundary": "node tools/check-ci-boundary.mjs",
89
106
  "coverage": "node tools/coverage.mjs"
90
107
  },
@@ -144,7 +161,7 @@
144
161
  "THIRD_PARTY_NOTICES.md"
145
162
  ],
146
163
  "engines": {
147
- "node": ">=24.22.1"
164
+ "node": ">=24.22.3"
148
165
  },
149
166
  "keywords": [
150
167
  "xmr",
@@ -181,6 +198,7 @@
181
198
  "sideEffects": false,
182
199
  "devDependencies": {
183
200
  "esbuild": "0.28.2",
201
+ "monero-ts": "0.11.22",
184
202
  "typescript": "7.0.2"
185
203
  },
186
204
  "allowScripts": {