@lifi/sdk-provider-sui 4.2.6 → 4.2.8

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 (56) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/README.md +9 -0
  3. package/dist/esm/actions/getSuiBalance.d.ts.map +1 -1
  4. package/dist/esm/actions/getSuiBalance.js +5 -4
  5. package/dist/esm/actions/getSuiBalance.js.map +1 -1
  6. package/dist/esm/client/suiClient.d.ts +2 -1
  7. package/dist/esm/client/suiClient.d.ts.map +1 -1
  8. package/dist/esm/client/suiClient.js +14 -15
  9. package/dist/esm/client/suiClient.js.map +1 -1
  10. package/dist/esm/core/SuiStepExecutor.d.ts.map +1 -1
  11. package/dist/esm/core/SuiStepExecutor.js +4 -3
  12. package/dist/esm/core/SuiStepExecutor.js.map +1 -1
  13. package/dist/esm/core/constants.d.ts +7 -0
  14. package/dist/esm/core/constants.d.ts.map +1 -0
  15. package/dist/esm/core/constants.js +9 -0
  16. package/dist/esm/core/constants.js.map +1 -0
  17. package/dist/esm/core/tasks/SuiSignAndExecuteTask.d.ts.map +1 -1
  18. package/dist/esm/core/tasks/SuiSignAndExecuteTask.js +54 -7
  19. package/dist/esm/core/tasks/SuiSignAndExecuteTask.js.map +1 -1
  20. package/dist/esm/core/tasks/SuiWaitForTransactionTask.d.ts.map +1 -1
  21. package/dist/esm/core/tasks/SuiWaitForTransactionTask.js +110 -12
  22. package/dist/esm/core/tasks/SuiWaitForTransactionTask.js.map +1 -1
  23. package/dist/esm/core/tasks/helpers/callWithinDeadline.d.ts +19 -0
  24. package/dist/esm/core/tasks/helpers/callWithinDeadline.d.ts.map +1 -0
  25. package/dist/esm/core/tasks/helpers/callWithinDeadline.js +45 -0
  26. package/dist/esm/core/tasks/helpers/callWithinDeadline.js.map +1 -0
  27. package/dist/esm/core/tasks/helpers/isSuiTransactionDropped.d.ts +24 -0
  28. package/dist/esm/core/tasks/helpers/isSuiTransactionDropped.d.ts.map +1 -0
  29. package/dist/esm/core/tasks/helpers/isSuiTransactionDropped.js +141 -0
  30. package/dist/esm/core/tasks/helpers/isSuiTransactionDropped.js.map +1 -0
  31. package/dist/esm/errors/parseSuiErrors.js +5 -4
  32. package/dist/esm/errors/parseSuiErrors.js.map +1 -1
  33. package/dist/esm/utils/getSuiTxLink.d.ts +5 -0
  34. package/dist/esm/utils/getSuiTxLink.d.ts.map +1 -0
  35. package/dist/esm/utils/getSuiTxLink.js +6 -0
  36. package/dist/esm/utils/getSuiTxLink.js.map +1 -0
  37. package/dist/esm/utils/suiSignedTransaction.d.ts +39 -0
  38. package/dist/esm/utils/suiSignedTransaction.d.ts.map +1 -0
  39. package/dist/esm/utils/suiSignedTransaction.js +73 -0
  40. package/dist/esm/utils/suiSignedTransaction.js.map +1 -0
  41. package/dist/esm/version.d.ts +1 -1
  42. package/dist/esm/version.js +1 -1
  43. package/dist/esm/version.js.map +1 -1
  44. package/package.json +3 -3
  45. package/src/actions/getSuiBalance.ts +40 -24
  46. package/src/client/suiClient.ts +21 -18
  47. package/src/core/SuiStepExecutor.ts +19 -5
  48. package/src/core/constants.ts +21 -0
  49. package/src/core/tasks/SuiSignAndExecuteTask.ts +107 -8
  50. package/src/core/tasks/SuiWaitForTransactionTask.ts +249 -22
  51. package/src/core/tasks/helpers/callWithinDeadline.ts +48 -0
  52. package/src/core/tasks/helpers/isSuiTransactionDropped.ts +292 -0
  53. package/src/errors/parseSuiErrors.ts +19 -19
  54. package/src/utils/getSuiTxLink.ts +4 -0
  55. package/src/utils/suiSignedTransaction.ts +109 -0
  56. package/src/version.ts +1 -1
@@ -0,0 +1,292 @@
1
+ import {
2
+ CLOCK_SKEW_MARGIN_MS,
3
+ isKnownToStatusApi,
4
+ type LiFiStepExtended,
5
+ MAX_RESEND_AGE_MS,
6
+ type SDKClient,
7
+ } from '@lifi/sdk'
8
+ import { GrpcStatusCode, GrpcTypes, type SuiGrpcClient } from '@mysten/sui/grpc'
9
+ import { callSuiWithRetry } from '../../../client/suiClient.js'
10
+ import {
11
+ SUI_CANARY_TIP_OFFSET,
12
+ SUI_HEAD_MARGIN_MS,
13
+ SUI_LOOKUP_TIMEOUT_MS,
14
+ SUI_MIN_CHECKPOINT_INTERVAL_MS,
15
+ } from '../../constants.js'
16
+ import { callWithinDeadline } from './callWithinDeadline.js'
17
+
18
+ // A canary search skips at most this many checkpoints without a user
19
+ // transaction.
20
+ const MAX_SKIPPED_CHECKPOINTS = 10
21
+
22
+ // The kind of a user transaction. System transactions (the consensus commit
23
+ // prologue, randomness updates, programmable system transactions, epoch
24
+ // changes) have other kinds.
25
+ const PROGRAMMABLE_TRANSACTION =
26
+ GrpcTypes.TransactionKind_Kind.PROGRAMMABLE_TRANSACTION
27
+
28
+ interface CheckpointInfo {
29
+ sequenceNumber: bigint
30
+ timestampMs: number
31
+ /**
32
+ * The digest of the last user transaction of the checkpoint, the last one
33
+ * whose kind is `PROGRAMMABLE_TRANSACTION`. A transaction without a kind
34
+ * does not count.
35
+ */
36
+ userTransactionDigest?: string
37
+ }
38
+
39
+ interface Canaries {
40
+ /** Landed before the earliest landing time. */
41
+ before: string
42
+ /** Landed after the latest landing time + margin. */
43
+ after: string
44
+ }
45
+
46
+ /**
47
+ * True only when the digest can no longer land and no source knows it (see
48
+ * the resume rules in `transactionState.ts`):
49
+ * (a) the resend age cap has passed, so the SDK never sends the bytes again.
50
+ * An unknown signing time never drops, and nor does one in the future:
51
+ * a refused resend does not mean that the cap passed;
52
+ * (b) a node answers "not found" for the digest in the same
53
+ * `BatchGetTransactions` response that finds one canary user transaction
54
+ * from before the earliest landing time and one from after the latest
55
+ * landing time + margin, and no node returns the digest. The canaries
56
+ * prove that this very response covers the whole landing window; a
57
+ * separate coverage request can reach another backend of a load-balanced
58
+ * RPC;
59
+ * (c) the LI.FI status API does not know the digest (veto only).
60
+ *
61
+ * Any lookup error leaves the outcome unknown and returns false. Each call
62
+ * to a node has `SUI_LOOKUP_TIMEOUT_MS` to answer; a node that does not
63
+ * counts as failed, so the next node is asked.
64
+ */
65
+ export async function isSuiTransactionDropped(
66
+ client: SDKClient,
67
+ step: LiFiStepExtended,
68
+ digest: string
69
+ ): Promise<boolean> {
70
+ const signedAt = step.execution?.signedAt
71
+ if (signedAt === undefined || Date.now() - signedAt < MAX_RESEND_AGE_MS) {
72
+ return false
73
+ }
74
+ try {
75
+ // `signedAt` is the local clock; the skew margin widens the window on
76
+ // both sides.
77
+ const earliest = signedAt - CLOCK_SKEW_MARGIN_MS
78
+ const latest =
79
+ signedAt + MAX_RESEND_AGE_MS + CLOCK_SKEW_MARGIN_MS + SUI_HEAD_MARGIN_MS
80
+ // `findCanaries` throws when a node cannot supply them, so that
81
+ // `callSuiWithRetry` asks the next node.
82
+ const canaries = await callSuiWithRetry(client, (suiClient) =>
83
+ findCanaries(suiClient, earliest, latest)
84
+ )
85
+ if ((await lookUpWithCanaries(client, digest, canaries)) !== 'not-found') {
86
+ return false
87
+ }
88
+ return !(await isKnownToStatusApi(client, step, digest))
89
+ } catch {
90
+ return false
91
+ }
92
+ }
93
+
94
+ /**
95
+ * Any node may supply the canaries; the proof is in the lookup response.
96
+ * Throws when this node cannot supply them.
97
+ */
98
+ async function findCanaries(
99
+ suiClient: SuiGrpcClient,
100
+ earliest: number,
101
+ latest: number
102
+ ): Promise<Canaries> {
103
+ const tip = await getCheckpoint(suiClient)
104
+ if (tip.timestampMs <= latest) {
105
+ throw new Error('The chain is not yet past the latest landing time.')
106
+ }
107
+
108
+ // Prefer a checkpoint behind the tip; the search moves toward the tip.
109
+ let afterStart = await getCheckpoint(
110
+ suiClient,
111
+ tip.sequenceNumber > SUI_CANARY_TIP_OFFSET
112
+ ? tip.sequenceNumber - SUI_CANARY_TIP_OFFSET
113
+ : 0n
114
+ )
115
+ if (afterStart.timestampMs <= latest) {
116
+ afterStart = tip
117
+ }
118
+ const after = await findUserTransaction(
119
+ suiClient,
120
+ afterStart,
121
+ 1n,
122
+ (checkpoint) =>
123
+ checkpoint.timestampMs > latest &&
124
+ checkpoint.sequenceNumber <= tip.sequenceNumber
125
+ )
126
+
127
+ const before = await findUserTransaction(
128
+ suiClient,
129
+ await findCheckpointBefore(suiClient, tip, earliest),
130
+ -1n,
131
+ (checkpoint) => checkpoint.timestampMs < earliest
132
+ )
133
+ return { before, after }
134
+ }
135
+
136
+ /** A checkpoint older than `earliest`. Throws if none is found. */
137
+ async function findCheckpointBefore(
138
+ suiClient: SuiGrpcClient,
139
+ tip: CheckpointInfo,
140
+ earliest: number
141
+ ): Promise<CheckpointInfo> {
142
+ // Estimated with the shortest interval, the guess lands at or before
143
+ // `earliest`; step further back if the interval was even shorter.
144
+ let distance = BigInt(
145
+ Math.ceil((tip.timestampMs - earliest) / SUI_MIN_CHECKPOINT_INTERVAL_MS)
146
+ )
147
+ for (let attempt = 0; attempt < 3; attempt++) {
148
+ const sequenceNumber =
149
+ tip.sequenceNumber > distance ? tip.sequenceNumber - distance : 0n
150
+ const checkpoint = await getCheckpoint(suiClient, sequenceNumber)
151
+ if (checkpoint.timestampMs < earliest) {
152
+ return checkpoint
153
+ }
154
+ if (sequenceNumber === 0n) {
155
+ throw new Error('The chain starts after the earliest landing time.')
156
+ }
157
+ distance *= 2n
158
+ }
159
+ throw new Error('No checkpoint before the earliest landing time was found.')
160
+ }
161
+
162
+ /**
163
+ * From `start`, steps one checkpoint at a time in `direction` over
164
+ * checkpoints without a user transaction, and returns the first user
165
+ * transaction digest. Every checkpoint on the way must be `inRange`.
166
+ */
167
+ async function findUserTransaction(
168
+ suiClient: SuiGrpcClient,
169
+ start: CheckpointInfo,
170
+ direction: bigint,
171
+ inRange: (checkpoint: CheckpointInfo) => boolean
172
+ ): Promise<string> {
173
+ let checkpoint = start
174
+ for (let skipped = 0; inRange(checkpoint); skipped++) {
175
+ if (checkpoint.userTransactionDigest) {
176
+ return checkpoint.userTransactionDigest
177
+ }
178
+ const next = checkpoint.sequenceNumber + direction
179
+ if (skipped === MAX_SKIPPED_CHECKPOINTS || next < 0n) {
180
+ break
181
+ }
182
+ checkpoint = await getCheckpoint(suiClient, next)
183
+ }
184
+ throw new Error('No checkpoint in range holds a user transaction.')
185
+ }
186
+
187
+ /**
188
+ * The latest checkpoint without `sequenceNumber`. Throws when the sequence
189
+ * number or the timestamp is missing.
190
+ */
191
+ async function getCheckpoint(
192
+ suiClient: SuiGrpcClient,
193
+ sequenceNumber?: bigint
194
+ ): Promise<CheckpointInfo> {
195
+ const { response } = await callWithinDeadline(
196
+ (abort) =>
197
+ suiClient.ledgerService.getCheckpoint(
198
+ {
199
+ checkpointId:
200
+ sequenceNumber === undefined
201
+ ? { oneofKind: undefined }
202
+ : { oneofKind: 'sequenceNumber', sequenceNumber },
203
+ readMask: {
204
+ paths: [
205
+ 'sequence_number',
206
+ 'summary.timestamp',
207
+ 'transactions.digest',
208
+ 'transactions.transaction.kind',
209
+ ],
210
+ },
211
+ },
212
+ { abort }
213
+ ),
214
+ SUI_LOOKUP_TIMEOUT_MS
215
+ )
216
+ const checkpoint = response.checkpoint
217
+ const timestamp = checkpoint?.summary?.timestamp
218
+ const timestampMs = timestamp
219
+ ? Number(timestamp.seconds) * 1000 + Math.floor(timestamp.nanos / 1e6)
220
+ : 0
221
+ // A zero timestamp is the protobuf default, so it counts as missing.
222
+ if (checkpoint?.sequenceNumber === undefined || timestampMs <= 0) {
223
+ throw new Error('The checkpoint has no sequence number or timestamp.')
224
+ }
225
+ return {
226
+ sequenceNumber: checkpoint.sequenceNumber,
227
+ timestampMs,
228
+ userTransactionDigest: checkpoint.transactions.findLast(
229
+ ({ transaction }) => transaction?.kind?.kind === PROGRAMMABLE_TRANSACTION
230
+ )?.digest,
231
+ }
232
+ }
233
+
234
+ /**
235
+ * Asks every node with one batch request each. `found` as soon as one returns
236
+ * the digest; `not-found` when none returns it and at least one response
237
+ * finds both canaries but not the digest; `unknown` otherwise.
238
+ */
239
+ async function lookUpWithCanaries(
240
+ client: SDKClient,
241
+ digest: string,
242
+ canaries: Canaries
243
+ ): Promise<'found' | 'not-found' | 'unknown'> {
244
+ let coveringNotFound = 0
245
+ try {
246
+ await callSuiWithRetry(client, async (suiClient) => {
247
+ const { response } = await callWithinDeadline(
248
+ (abort) =>
249
+ suiClient.ledgerService.batchGetTransactions(
250
+ {
251
+ digests: [digest, canaries.before, canaries.after],
252
+ readMask: { paths: ['digest'] },
253
+ },
254
+ { abort }
255
+ ),
256
+ SUI_LOOKUP_TIMEOUT_MS
257
+ )
258
+ const [target, before, after] = response.transactions
259
+ // A node that returns the digest vetoes, in any position.
260
+ if (
261
+ target?.result.oneofKind === 'transaction' ||
262
+ response.transactions.some(
263
+ ({ result }) =>
264
+ result.oneofKind === 'transaction' &&
265
+ result.transaction.digest === digest
266
+ )
267
+ ) {
268
+ return
269
+ }
270
+ // Each canary must sit at its own request position: then the result at
271
+ // the target position belongs to the target, even if a node ever
272
+ // breaks the request order.
273
+ const covers =
274
+ response.transactions.length === 3 &&
275
+ before?.result.oneofKind === 'transaction' &&
276
+ before.result.transaction.digest === canaries.before &&
277
+ after?.result.oneofKind === 'transaction' &&
278
+ after.result.transaction.digest === canaries.after
279
+ const notFound =
280
+ target?.result.oneofKind === 'error' &&
281
+ target.result.error.code === GrpcStatusCode.NOT_FOUND
282
+ if (covers && notFound) {
283
+ coveringNotFound++
284
+ }
285
+ // Throw so that `callSuiWithRetry` asks the next node as well.
286
+ throw new Error('The node does not return the transaction.')
287
+ })
288
+ return 'found'
289
+ } catch {
290
+ return coveringNotFound > 0 ? 'not-found' : 'unknown'
291
+ }
292
+ }
@@ -25,35 +25,35 @@ export const parseSuiErrors = async (
25
25
  return new SDKError(baseError, step, action)
26
26
  }
27
27
 
28
- const handleSpecificErrors = (e: any) => {
29
- const isRejection =
30
- typeof e === 'string'
31
- ? e.toLowerCase().includes('reject')
32
- : e.message?.toLowerCase().includes('reject')
33
-
34
- if (isRejection) {
35
- return new TransactionError(LiFiErrorCode.SignatureRejected, e.message, e)
28
+ const handleSpecificErrors = (e: any): BaseError => {
29
+ // A code the SDK set on purpose wins over message matching. A wallet
30
+ // rejection is tagged where it happens (SuiSignAndExecuteTask), so "reject"
31
+ // is not read here: a node or RPC message that says "reject" is not the
32
+ // user's.
33
+ if (e instanceof BaseError) {
34
+ return e
36
35
  }
37
36
 
37
+ // `e` can be any thrown value: also `undefined`, `null`, a string, or an
38
+ // object whose `message` is not a string. A TypeError here would escape the
39
+ // catch of the step executor.
40
+ const message: string = typeof e?.message === 'string' ? e.message : ''
41
+ const lowerCaseMessage = message.toLowerCase()
42
+
38
43
  if (
39
- e.message?.toLowerCase().includes('transaction') &&
40
- (e.message?.toLowerCase().includes('failed') ||
41
- e.message?.toLowerCase().includes('error'))
44
+ lowerCaseMessage.includes('transaction') &&
45
+ (lowerCaseMessage.includes('failed') || lowerCaseMessage.includes('error'))
42
46
  ) {
43
- return new TransactionError(LiFiErrorCode.TransactionFailed, e.message, e)
47
+ return new TransactionError(LiFiErrorCode.TransactionFailed, message, e)
44
48
  }
45
49
 
46
- if (e.message?.includes('simulate') || e.message?.includes('simulation')) {
50
+ if (message.includes('simulate') || message.includes('simulation')) {
47
51
  return new TransactionError(
48
52
  LiFiErrorCode.TransactionSimulationFailed,
49
- e.message,
53
+ message,
50
54
  e
51
55
  )
52
56
  }
53
57
 
54
- if (e instanceof BaseError) {
55
- return e
56
- }
57
-
58
- return new UnknownError(e.message || ErrorMessage.UnknownError, e)
58
+ return new UnknownError(message || ErrorMessage.UnknownError, e)
59
59
  }
@@ -0,0 +1,4 @@
1
+ import type { ExtendedChain } from '@lifi/sdk'
2
+
3
+ export const getSuiTxLink = (chain: ExtendedChain, digest: string): string =>
4
+ `${chain.metamask.blockExplorerUrls[0]}txblock/${digest}`
@@ -0,0 +1,109 @@
1
+ import { bcs } from '@mysten/sui/bcs'
2
+ import { TransactionDataBuilder } from '@mysten/sui/transactions'
3
+ import { fromBase64, toBase64 } from '@mysten/sui/utils'
4
+ import { isValidTransactionSignature } from '@mysten/sui/verify'
5
+
6
+ export interface SuiSignedTransaction {
7
+ /** The BCS `TransactionData` bytes that were signed. */
8
+ bytes: Uint8Array
9
+ /** The serialized signature returned by `signer.signTransaction`. */
10
+ signature: string
11
+ /** The transaction digest, derived from `bytes`. */
12
+ digest: string
13
+ }
14
+
15
+ /**
16
+ * Reads a signed transaction back from `ExecutionAction.txHex`
17
+ * (JSON `{ bytes: base64, signature }`).
18
+ *
19
+ * Returns `undefined` unless the bytes decode as a `TransactionData` and the
20
+ * signature decodes as non-empty base64, so the digest and the re-execution
21
+ * both work.
22
+ */
23
+ export function parseSuiSignedTransaction(
24
+ txHex: string
25
+ ): SuiSignedTransaction | undefined {
26
+ try {
27
+ const { bytes, signature } = JSON.parse(txHex) as {
28
+ bytes?: unknown
29
+ signature?: unknown
30
+ }
31
+ if (typeof bytes !== 'string' || typeof signature !== 'string') {
32
+ return undefined
33
+ }
34
+ const transactionBytes = fromBase64(bytes)
35
+ // The gRPC client decodes the signature before it sends, so a signature
36
+ // that is not base64 never reaches the chain. `fromBase64('')` is an
37
+ // empty array, not an error.
38
+ if (!transactionBytes.length || !fromBase64(signature).length) {
39
+ return undefined
40
+ }
41
+ // Throws on anything that is not a `TransactionData`.
42
+ TransactionDataBuilder.fromBytes(transactionBytes)
43
+ // `fromBytes` reads a `TransactionData` prefix and ignores the bytes after
44
+ // it, which still change the digest.
45
+ if (!isCanonicalTransactionData(transactionBytes)) {
46
+ return undefined
47
+ }
48
+ return {
49
+ bytes: transactionBytes,
50
+ signature,
51
+ digest: TransactionDataBuilder.getDigestFromBytes(transactionBytes),
52
+ }
53
+ } catch {
54
+ return undefined
55
+ }
56
+ }
57
+
58
+ /** Whether the canonical BCS encoding of the parsed bytes is exactly `bytes`. */
59
+ function isCanonicalTransactionData(bytes: Uint8Array): boolean {
60
+ const canonical = bcs.TransactionData.serialize(
61
+ bcs.TransactionData.parse(bytes)
62
+ ).toBytes()
63
+ return (
64
+ canonical.length === bytes.length &&
65
+ canonical.every((byte, index) => byte === bytes[index])
66
+ )
67
+ }
68
+
69
+ /**
70
+ * Verifies that `signature` signs `bytes` and that the signer is the sender
71
+ * of the transaction, so stored bytes that were changed after signing are
72
+ * detected.
73
+ *
74
+ * Resolves `false` only for a definite failure: the bytes have no sender, or
75
+ * the signature is malformed, is not valid for the bytes, or is not the
76
+ * sender's. Rejects when the verification cannot run, so that such a failure
77
+ * never counts as damaged bytes. A well-formed zkLogin signature, also as a
78
+ * multisig member, needs a client to verify, so it rejects here.
79
+ */
80
+ export async function verifySuiSignedTransaction(
81
+ transaction: SuiSignedTransaction
82
+ ): Promise<boolean> {
83
+ let sender: string | null
84
+ try {
85
+ sender = TransactionDataBuilder.fromBytes(transaction.bytes).sender
86
+ } catch {
87
+ return false
88
+ }
89
+ if (!sender) {
90
+ return false
91
+ }
92
+ return isValidTransactionSignature(transaction.bytes, transaction.signature, {
93
+ address: sender,
94
+ })
95
+ }
96
+
97
+ /**
98
+ * Serializes signed transaction bytes for `ExecutionAction.txHex`.
99
+ *
100
+ * Returns `undefined` when the result would not read back with
101
+ * `parseSuiSignedTransaction`, so a stored value is always usable on resume.
102
+ */
103
+ export function serializeSuiSignedTransaction(
104
+ bytes: Uint8Array,
105
+ signature: string
106
+ ): string | undefined {
107
+ const txHex = JSON.stringify({ bytes: toBase64(bytes), signature })
108
+ return parseSuiSignedTransaction(txHex) ? txHex : undefined
109
+ }
package/src/version.ts CHANGED
@@ -1,2 +1,2 @@
1
1
  export const name = '@lifi/sdk-provider-sui'
2
- export const version = '4.2.6'
2
+ export const version = '4.2.8'