@ledgerhq/coin-evm 16.2.5 → 16.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/lib/adapters/blockscoutV2.d.ts +40 -0
  3. package/lib/adapters/blockscoutV2.d.ts.map +1 -0
  4. package/lib/adapters/blockscoutV2.js +177 -0
  5. package/lib/adapters/blockscoutV2.js.map +1 -0
  6. package/lib/adapters/index.d.ts +1 -0
  7. package/lib/adapters/index.d.ts.map +1 -1
  8. package/lib/adapters/index.js +1 -0
  9. package/lib/adapters/index.js.map +1 -1
  10. package/lib/chains.d.ts +1 -1
  11. package/lib/chains.js +1 -1
  12. package/lib/chains.js.map +1 -1
  13. package/lib/config.d.ts +51 -24
  14. package/lib/config.d.ts.map +1 -1
  15. package/lib/config.js +21 -19
  16. package/lib/config.js.map +1 -1
  17. package/lib/logic/getBlock.d.ts.map +1 -1
  18. package/lib/logic/getBlock.js +14 -1
  19. package/lib/logic/getBlock.js.map +1 -1
  20. package/lib/logic/internalTransactionsFetcher.d.ts.map +1 -1
  21. package/lib/logic/internalTransactionsFetcher.js +58 -20
  22. package/lib/logic/internalTransactionsFetcher.js.map +1 -1
  23. package/lib/network/blockscoutV2.d.ts +35 -0
  24. package/lib/network/blockscoutV2.d.ts.map +1 -0
  25. package/lib/network/blockscoutV2.js +311 -0
  26. package/lib/network/blockscoutV2.js.map +1 -0
  27. package/lib/network/explorer/etherscan.d.ts.map +1 -1
  28. package/lib/network/explorer/etherscan.js +11 -28
  29. package/lib/network/explorer/etherscan.js.map +1 -1
  30. package/lib/network/explorer/index.d.ts.map +1 -1
  31. package/lib/network/explorer/index.js +5 -0
  32. package/lib/network/explorer/index.js.map +1 -1
  33. package/lib/network/explorer/types.d.ts +6 -0
  34. package/lib/network/explorer/types.d.ts.map +1 -1
  35. package/lib/network/explorer/types.js +8 -1
  36. package/lib/network/explorer/types.js.map +1 -1
  37. package/lib/network/rewards.d.ts +11 -0
  38. package/lib/network/rewards.d.ts.map +1 -0
  39. package/lib/network/rewards.js +32 -0
  40. package/lib/network/rewards.js.map +1 -0
  41. package/lib/types/blockscoutV2.d.ts +80 -0
  42. package/lib/types/blockscoutV2.d.ts.map +1 -0
  43. package/lib/types/blockscoutV2.js +5 -0
  44. package/lib/types/blockscoutV2.js.map +1 -0
  45. package/lib/types/index.d.ts +1 -0
  46. package/lib/types/index.d.ts.map +1 -1
  47. package/lib/types/index.js +1 -0
  48. package/lib/types/index.js.map +1 -1
  49. package/lib-es/adapters/blockscoutV2.d.ts +40 -0
  50. package/lib-es/adapters/blockscoutV2.d.ts.map +1 -0
  51. package/lib-es/adapters/blockscoutV2.js +168 -0
  52. package/lib-es/adapters/blockscoutV2.js.map +1 -0
  53. package/lib-es/adapters/index.d.ts +1 -0
  54. package/lib-es/adapters/index.d.ts.map +1 -1
  55. package/lib-es/adapters/index.js +1 -0
  56. package/lib-es/adapters/index.js.map +1 -1
  57. package/lib-es/chains.d.ts +1 -1
  58. package/lib-es/chains.js +1 -1
  59. package/lib-es/chains.js.map +1 -1
  60. package/lib-es/config.d.ts +51 -24
  61. package/lib-es/config.d.ts.map +1 -1
  62. package/lib-es/config.js +21 -19
  63. package/lib-es/config.js.map +1 -1
  64. package/lib-es/logic/getBlock.d.ts.map +1 -1
  65. package/lib-es/logic/getBlock.js +14 -1
  66. package/lib-es/logic/getBlock.js.map +1 -1
  67. package/lib-es/logic/internalTransactionsFetcher.d.ts.map +1 -1
  68. package/lib-es/logic/internalTransactionsFetcher.js +59 -21
  69. package/lib-es/logic/internalTransactionsFetcher.js.map +1 -1
  70. package/lib-es/network/blockscoutV2.d.ts +35 -0
  71. package/lib-es/network/blockscoutV2.d.ts.map +1 -0
  72. package/lib-es/network/blockscoutV2.js +271 -0
  73. package/lib-es/network/blockscoutV2.js.map +1 -0
  74. package/lib-es/network/explorer/etherscan.d.ts.map +1 -1
  75. package/lib-es/network/explorer/etherscan.js +2 -19
  76. package/lib-es/network/explorer/etherscan.js.map +1 -1
  77. package/lib-es/network/explorer/index.d.ts.map +1 -1
  78. package/lib-es/network/explorer/index.js +5 -0
  79. package/lib-es/network/explorer/index.js.map +1 -1
  80. package/lib-es/network/explorer/types.d.ts +6 -0
  81. package/lib-es/network/explorer/types.d.ts.map +1 -1
  82. package/lib-es/network/explorer/types.js +6 -0
  83. package/lib-es/network/explorer/types.js.map +1 -1
  84. package/lib-es/network/rewards.d.ts +11 -0
  85. package/lib-es/network/rewards.d.ts.map +1 -0
  86. package/lib-es/network/rewards.js +29 -0
  87. package/lib-es/network/rewards.js.map +1 -0
  88. package/lib-es/types/blockscoutV2.d.ts +80 -0
  89. package/lib-es/types/blockscoutV2.d.ts.map +1 -0
  90. package/lib-es/types/blockscoutV2.js +4 -0
  91. package/lib-es/types/blockscoutV2.js.map +1 -0
  92. package/lib-es/types/index.d.ts +1 -0
  93. package/lib-es/types/index.d.ts.map +1 -1
  94. package/lib-es/types/index.js +1 -0
  95. package/lib-es/types/index.js.map +1 -1
  96. package/package.json +3 -3
  97. package/src/adapters/blockscoutV2.test.ts +296 -0
  98. package/src/adapters/blockscoutV2.ts +244 -0
  99. package/src/adapters/index.ts +1 -0
  100. package/src/api/tests/index.alpen_testnet.integ.test.ts +73 -0
  101. package/src/api/tests/index.integ.test.ts +4 -2
  102. package/src/api/tests/index.scroll.integ.test.ts +168 -0
  103. package/src/api/tests/index.shape.integ.test.ts +34 -0
  104. package/src/chains.ts +1 -1
  105. package/src/config.ts +46 -19
  106. package/src/logic/getBlock.ts +18 -1
  107. package/src/logic/internalTransactionsFetcher.ts +73 -24
  108. package/src/logic/tests/getBlock.test.ts +59 -3
  109. package/src/logic/tests/internalTransactionsFetcher.test.ts +98 -1
  110. package/src/network/blockscoutV2.ts +460 -0
  111. package/src/network/explorer/etherscan.ts +2 -29
  112. package/src/network/explorer/index.ts +5 -0
  113. package/src/network/explorer/types.ts +9 -0
  114. package/src/network/rewards.ts +47 -0
  115. package/src/network/tests/blockscoutV2.test.ts +565 -0
  116. package/src/network/tests/explorer/index.test.ts +21 -0
  117. package/src/types/blockscoutV2.ts +85 -0
  118. package/src/types/index.ts +1 -0
@@ -656,6 +656,39 @@ describe('getBlock', () => {
656
656
  expect(mockGetTransaction).toHaveBeenCalledWith('0xtx1')
657
657
  })
658
658
 
659
+ it('throws both errors when the transactions and the internal transactions fetch fail', async () => {
660
+ const context = createMockEvmContext(
661
+ createMockEvmConfigInfo({
662
+ chainId: 1,
663
+ node: mkExternalNode(),
664
+ getBlockInternalTxsSources: internalTxSourcesFromList(['trace_block']),
665
+ })
666
+ )
667
+
668
+ const receiptsError = new Error('receipts timeout')
669
+ const traceError = new Error('trace down')
670
+
671
+ mockGetBlockNodeApi(
672
+ mockNodeApi({
673
+ getBlockByHeight: jest.fn().mockResolvedValue(
674
+ makeNodeBlock({
675
+ height: 12345,
676
+ transactions: [makeNodeBlockTx({ hash: '0xtx1' })],
677
+ })
678
+ ),
679
+ getBlockReceipts: jest.fn().mockRejectedValue(receiptsError),
680
+ getTransaction: jest.fn(),
681
+ traceBlockErigon: jest.fn().mockRejectedValue(traceError),
682
+ })
683
+ )
684
+
685
+ await expect(getBlock(context, 12345)).rejects.toMatchObject({
686
+ errors: [receiptsError, traceError],
687
+ message:
688
+ 'getBlock 12345 failed: transactions: receipts timeout; internal transactions: trace down',
689
+ })
690
+ })
691
+
659
692
  it('does not fallback when getBlockReceipts fails for another reason', async () => {
660
693
  const context = createMockEvmContext(
661
694
  createMockEvmConfigInfo({ chainId: 1, node: mkExternalNode() })
@@ -1136,7 +1169,15 @@ describe('getBlock', () => {
1136
1169
  const mockGetInternalTransactionsByBlock = jest.mocked(getInternalTransactionsByBlock)
1137
1170
  mockGetInternalTransactionsByBlock.mockRejectedValueOnce(new Error('explorer error'))
1138
1171
 
1139
- await expect(getBlock(context, 12345)).rejects.toThrow(error)
1172
+ await expect(getBlock(context, 12345)).rejects.toMatchObject({
1173
+ errors: [
1174
+ expect.objectContaining({
1175
+ name: 'SourceUnavailableError',
1176
+ cause: new Error('explorer error'),
1177
+ }),
1178
+ error,
1179
+ ],
1180
+ })
1140
1181
 
1141
1182
  expect(mockGetInternalTransactionsByBlock).toHaveBeenCalledWith(expect.anything(), 12345)
1142
1183
  expect(mockTraceBlock).toHaveBeenCalledWith(12345)
@@ -1182,7 +1223,14 @@ describe('getBlock', () => {
1182
1223
  mockGetInternalTransactionsByBlock.mockRejectedValueOnce(new Error('explorer error'))
1183
1224
 
1184
1225
  await expect(getBlock(context, 12345)).rejects.toMatchObject({
1185
- errors: [erigonError, gethError],
1226
+ errors: [
1227
+ expect.objectContaining({
1228
+ name: 'SourceUnavailableError',
1229
+ cause: new Error('explorer error'),
1230
+ }),
1231
+ erigonError,
1232
+ gethError,
1233
+ ],
1186
1234
  })
1187
1235
  expect(mockTraceBlockErigon).toHaveBeenCalledWith(12345)
1188
1236
  expect(mockTraceBlockGeth).toHaveBeenCalledWith(12345)
@@ -1282,7 +1330,15 @@ describe('getBlock', () => {
1282
1330
  const mockGetInternalTransactionsByBlock = jest.mocked(getInternalTransactionsByBlock)
1283
1331
  mockGetInternalTransactionsByBlock.mockRejectedValueOnce(new Error('explorer error'))
1284
1332
 
1285
- await expect(getBlock(context, 12345)).rejects.toThrow(erigonError)
1333
+ await expect(getBlock(context, 12345)).rejects.toMatchObject({
1334
+ errors: [
1335
+ expect.objectContaining({
1336
+ name: 'SourceUnavailableError',
1337
+ cause: new Error('explorer error'),
1338
+ }),
1339
+ erigonError,
1340
+ ],
1341
+ })
1286
1342
  expect(mockTraceBlockErigon).toHaveBeenCalledWith(12345)
1287
1343
  })
1288
1344
 
@@ -12,6 +12,7 @@ import {
12
12
  mkLedgerExplorer,
13
13
  testLogger,
14
14
  } from '../../fixtures/context.fixtures'
15
+ import { getInternalTransactionsByBlock as getBlockscoutV2InternalTransactionsByBlock } from '../../network/blockscoutV2'
15
16
  import { getInternalTransactionsByBlock } from '../../network/explorer/etherscan'
16
17
  import { mockNodeApi } from '../../network/tests/node/node.fixtures'
17
18
  import { composeInternalTxsFetcher, makeSourceFetchers } from '../internalTransactionsFetcher'
@@ -19,6 +20,9 @@ import { composeInternalTxsFetcher, makeSourceFetchers } from '../internalTransa
19
20
  jest.mock('../../network/explorer/etherscan', () => ({
20
21
  getInternalTransactionsByBlock: jest.fn().mockResolvedValue([]),
21
22
  }))
23
+ jest.mock('../../network/blockscoutV2', () => ({
24
+ getInternalTransactionsByBlock: jest.fn().mockResolvedValue([]),
25
+ }))
22
26
 
23
27
  const rejectFetcher = () => Promise.reject(new Error('not implemented'))
24
28
 
@@ -117,6 +121,7 @@ describe('composeInternalTxsFetcher', () => {
117
121
 
118
122
  await expect(fetch(height)).rejects.toMatchObject({
119
123
  errors: [explorerError, traceError],
124
+ message: 'internal tx sources failed: [explorer] explorer down; [trace_block] trace down',
120
125
  })
121
126
  })
122
127
 
@@ -133,9 +138,48 @@ describe('composeInternalTxsFetcher', () => {
133
138
 
134
139
  await expect(fetch(height)).rejects.toMatchObject({
135
140
  errors: [explorerError, traceError],
141
+ message: 'internal tx sources failed: [explorer] explorer down; [trace_block] trace down',
142
+ })
143
+ })
144
+
145
+ it('reports the cause of an unavailable source next to the real errors', async () => {
146
+ const explorerUnavailable = new SourceUnavailableError('explorer internal txs failed', {
147
+ cause: new Error('rate limited'),
148
+ })
149
+ const traceError = new Error('trace down')
150
+ const fetch = composeInternalTxsFetcher(
151
+ ['explorer', 'trace_block'],
152
+ makeFetchers({
153
+ explorer: jest.fn().mockRejectedValue(explorerUnavailable),
154
+ trace_block: jest.fn().mockRejectedValue(traceError),
155
+ })
156
+ )
157
+
158
+ await expect(fetch(height)).rejects.toMatchObject({
159
+ errors: [explorerUnavailable, traceError],
160
+ message:
161
+ 'internal tx sources failed: [explorer] explorer internal txs failed (cause: rate limited); [trace_block] trace down',
136
162
  })
137
163
  })
138
164
 
165
+ it('reports the cause of unavailable sources when all sources are unavailable', async () => {
166
+ const fetch = composeInternalTxsFetcher(
167
+ ['explorer', 'trace_block'],
168
+ makeFetchers({
169
+ explorer: jest.fn().mockRejectedValue(
170
+ new SourceUnavailableError('explorer internal txs failed', {
171
+ cause: new Error('rate limited'),
172
+ })
173
+ ),
174
+ trace_block: jest.fn().mockRejectedValue(new SourceUnavailableError('trace not supported')),
175
+ })
176
+ )
177
+
178
+ await expect(fetch(height)).rejects.toThrow(
179
+ 'all internal tx sources unavailable: [explorer] explorer internal txs failed (cause: rate limited)'
180
+ )
181
+ })
182
+
139
183
  it('falls back from trace_block to debug_traceBlockByNumber', async () => {
140
184
  const gethResult = new Map<string, BlockOperation[]>([['0x3', []]])
141
185
  const fetch = composeInternalTxsFetcher(
@@ -199,7 +243,10 @@ describe('makeSourceFetchers', () => {
199
243
  mockGetInternalTransactionsByBlock.mockRejectedValueOnce(new Error('explorer error'))
200
244
 
201
245
  const fetchers = makeSourceFetchers(config, mockNodeApi(), testLogger)
202
- await expect(fetchers.explorer(99)).rejects.toBeInstanceOf(SourceUnavailableError)
246
+ await expect(fetchers.explorer(99)).rejects.toMatchObject({
247
+ name: 'SourceUnavailableError',
248
+ cause: new Error('explorer error'),
249
+ })
203
250
  })
204
251
 
205
252
  it('calls getInternalTransactionsByBlock for explorer when configured', async () => {
@@ -218,6 +265,56 @@ describe('makeSourceFetchers', () => {
218
265
  expect(mockGetInternalTransactionsByBlock).toHaveBeenCalledWith(config, 99)
219
266
  })
220
267
 
268
+ it('reads the block internal transactions from the Blockscout v2 API for a blockscout-v2 explorer', async () => {
269
+ const config = createMockEvmConfigInfo({
270
+ chainId: 534352,
271
+ node: mkExternalNode(),
272
+ explorer: { type: 'blockscout-v2', uri: 'https://blockscout.example/api/v2' },
273
+ })
274
+ jest.mocked(getBlockscoutV2InternalTransactionsByBlock).mockResolvedValueOnce([
275
+ {
276
+ blockNumber: '99',
277
+ hash: '0xabc',
278
+ from: '0x9425E212647518853a92ae7D2C1Ab09D343e70b6',
279
+ to: '0x0459a84952C85c6E9345e5d22d9B110790a5e1Ba',
280
+ value: '9',
281
+ contractAddress: '',
282
+ input: '',
283
+ type: 'call',
284
+ callType: 'call',
285
+ gas: '2300',
286
+ gasUsed: '',
287
+ traceId: '1',
288
+ isError: '0',
289
+ errCode: '',
290
+ },
291
+ ])
292
+
293
+ const fetchers = makeSourceFetchers(config, mockNodeApi(), testLogger)
294
+ const result = await fetchers.explorer(99)
295
+
296
+ expect(getBlockscoutV2InternalTransactionsByBlock).toHaveBeenCalledWith(config, 99)
297
+ expect(getInternalTransactionsByBlock).not.toHaveBeenCalled()
298
+ expect(result.get('0xabc')?.map((op) => op.type === 'transfer' && op.amount)).toEqual([-9n, 9n])
299
+ })
300
+
301
+ it('wraps Blockscout v2 failures as SourceUnavailableError', async () => {
302
+ const config = createMockEvmConfigInfo({
303
+ chainId: 534352,
304
+ node: mkExternalNode(),
305
+ explorer: { type: 'blockscout-v2', uri: 'https://blockscout.example/api/v2' },
306
+ })
307
+ jest
308
+ .mocked(getBlockscoutV2InternalTransactionsByBlock)
309
+ .mockRejectedValueOnce(new Error('explorer error'))
310
+
311
+ const fetchers = makeSourceFetchers(config, mockNodeApi(), testLogger)
312
+ await expect(fetchers.explorer(99)).rejects.toMatchObject({
313
+ name: 'SourceUnavailableError',
314
+ cause: new Error('explorer error'),
315
+ })
316
+ })
317
+
221
318
  it('empty always resolves to an empty map', async () => {
222
319
  const config = createMockEvmConfigInfo({ chainId: 1, node: mkExternalNode() })
223
320
 
@@ -0,0 +1,460 @@
1
+ // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+
4
+ import type { EvmConfigInfo } from '../config'
5
+ import type {
6
+ BlockscoutV2InternalTransaction,
7
+ EtherscanInternalTransaction,
8
+ BlockscoutV2Page,
9
+ BlockscoutV2TokenTransfer,
10
+ BlockscoutV2Transaction,
11
+ } from '../types'
12
+ import type { ExplorerApi } from './explorer/types'
13
+ import type { AssetInfo } from '@ledgerhq/coin-module-framework/api/types'
14
+ import type { Logger } from '@ledgerhq/coin-module-framework/config'
15
+ import { InvalidParameterError } from '@ledgerhq/coin-module-framework/errors'
16
+ import { delay, promiseAllBatched } from '@ledgerhq/coin-module-framework/promises'
17
+ import { makeLRUCache } from '@ledgerhq/live-network/cache'
18
+ import axios, { isAxiosError } from 'axios'
19
+ import eip55 from 'eip55'
20
+ import {
21
+ blockscoutV2ERC1155TransfersToOperations,
22
+ blockscoutV2ERC20TransfersToOperations,
23
+ blockscoutV2ERC721TransfersToOperations,
24
+ blockscoutV2InternalTransactionToEtherscan,
25
+ blockscoutV2InternalTransactionsToOperations,
26
+ blockscoutV2TransactionToOperations,
27
+ } from '../adapters'
28
+ import { InvalidExplorerResponse, RateLimitError } from '../errors'
29
+ import { isBlockscoutV2ExplorerConfig, NO_TOKEN } from './explorer/types'
30
+ import { getNodeApi } from './node'
31
+ import { enrichRewardOperations } from './rewards'
32
+
33
+ /**
34
+ * Explorer backed by the Blockscout v2 REST API (`/api/v2`).
35
+ *
36
+ * The address transactions, token transfers and internal transactions are three keyset-paginated
37
+ * lists, sorted by descending block. A request can start at any block by seeding the cursor with
38
+ * that block, which is how pages are resumed. The lists cannot be read in ascending order, so this
39
+ * explorer only serves descending pages.
40
+ *
41
+ * Unlike the Etherscan-compatible v1 API, the v2 API reports the fee actually paid by each
42
+ * transaction, including the L1 data fee of rollups.
43
+ */
44
+
45
+ /** Wait between 2 attempts of a failed request, and lifetime of the cached responses */
46
+ const BLOCKSCOUT_V2_TIMEOUT = 5000
47
+
48
+ /** Retries of a failed request, unless the explorer config sets `retries` */
49
+ const DEFAULT_RETRIES_API = 8
50
+
51
+ /** Node requests in flight at once to resolve block hashes (ethers sends them as one JSON-RPC batch) */
52
+ const BLOCK_HASH_BATCH_SIZE = 100
53
+
54
+ type PageParams = Record<string, string | number | null>
55
+
56
+ function isObject(data: unknown): data is object {
57
+ return typeof data === 'object' && data !== null
58
+ }
59
+
60
+ function isPage(data: unknown): data is BlockscoutV2Page<unknown> {
61
+ return isObject(data) && 'items' in data && Array.isArray(data.items)
62
+ }
63
+
64
+ async function fetchPage<T>(
65
+ url: string,
66
+ params: PageParams,
67
+ retries: number
68
+ ): Promise<BlockscoutV2Page<T>> {
69
+ try {
70
+ const { data } = await axios.request<unknown>({ method: 'GET', url, params })
71
+ if (!isPage(data)) {
72
+ throw new InvalidExplorerResponse(`Unexpected Blockscout v2 API response from ${url}`)
73
+ }
74
+ // oxlint-disable-next-line consistent-type-assertions -- the item shape is the documented Blockscout v2 one, only the envelope is checked
75
+ return data as BlockscoutV2Page<T>
76
+ } catch (e) {
77
+ if (isAxiosError(e) && e.response?.status === 429) {
78
+ throw new RateLimitError()
79
+ }
80
+ if (retries) {
81
+ // wait the API timeout before trying again
82
+ await delay(BLOCKSCOUT_V2_TIMEOUT)
83
+ return fetchPage<T>(url, params, retries - 1)
84
+ }
85
+ throw e
86
+ }
87
+ }
88
+
89
+ type StreamItem = { block_number: number | null }
90
+
91
+ type StreamRead<T> = {
92
+ /** Items in descending block order, all at or above the floor */
93
+ items: T[]
94
+ /**
95
+ * Block of the last item when the read stopped because `limit` was reached: more items may exist
96
+ * below it. The block itself is always complete. `undefined` when the list was read down to the
97
+ * floor.
98
+ */
99
+ boundBlock: number | undefined
100
+ }
101
+
102
+ type Stream = {
103
+ /** List endpoint, relative to the explorer URI */
104
+ path: string
105
+ /** Fixed query params (filters) */
106
+ params: PageParams
107
+ /** Cursor that starts the list right below `block` */
108
+ seed: (block: number) => PageParams
109
+ }
110
+
111
+ /**
112
+ * Visit each item of a list from `ceiling` (inclusive, or the chain head) down to `floor`
113
+ * (inclusive), one page at a time, until `visit` returns `false`. Pending items are skipped.
114
+ */
115
+ async function walkStream<T extends StreamItem>(
116
+ uri: string,
117
+ stream: Stream,
118
+ floor: number,
119
+ ceiling: number | undefined,
120
+ retries: number,
121
+ visit: (item: T, block: number) => boolean
122
+ ): Promise<void> {
123
+ let params: PageParams | null = {
124
+ ...stream.params,
125
+ ...(ceiling !== undefined && stream.seed(ceiling + 1)),
126
+ }
127
+
128
+ while (params) {
129
+ const page: BlockscoutV2Page<T> = await fetchPage<T>(`${uri}${stream.path}`, params, retries)
130
+ for (const item of page.items) {
131
+ // Pending transactions have no block yet
132
+ if (item.block_number === null) continue
133
+ if (item.block_number < floor || !visit(item, item.block_number)) return
134
+ }
135
+ // The next page params do not repeat the filters
136
+ params = page.next_page_params && { ...stream.params, ...page.next_page_params }
137
+ }
138
+ }
139
+
140
+ /**
141
+ * Read a list from `ceiling` (inclusive, or the chain head) down to `floor` (inclusive).
142
+ *
143
+ * With a `limit`, stop once `limit` items are read and the block of the last one is complete, so
144
+ * that the next page can start right below it without splitting a block.
145
+ */
146
+ async function readStream<T extends StreamItem>(
147
+ uri: string,
148
+ stream: Stream,
149
+ floor: number,
150
+ ceiling: number | undefined,
151
+ limit: number | undefined,
152
+ retries: number
153
+ ): Promise<StreamRead<T>> {
154
+ const items: T[] = []
155
+ let lastBlock: number | undefined
156
+ let boundBlock: number | undefined
157
+
158
+ await walkStream<T>(uri, stream, floor, ceiling, retries, (item, block) => {
159
+ if (
160
+ limit !== undefined &&
161
+ items.length >= limit &&
162
+ lastBlock !== undefined &&
163
+ block < lastBlock
164
+ ) {
165
+ boundBlock = lastBlock
166
+ return false
167
+ }
168
+ items.push(item)
169
+ lastBlock = block
170
+ return true
171
+ })
172
+
173
+ return { items, boundBlock }
174
+ }
175
+
176
+ const TRANSACTIONS = (address: string): Stream => ({
177
+ path: `/addresses/${address}/transactions`,
178
+ params: {},
179
+ seed: (block): PageParams => ({ block_number: block, index: 0 }),
180
+ })
181
+
182
+ const TOKEN_TRANSFERS = (address: string, types: string[]): Stream => ({
183
+ path: `/addresses/${address}/token-transfers`,
184
+ params: { type: types.join(',') },
185
+ seed: (block): PageParams => ({ block_number: block, index: 0 }),
186
+ })
187
+
188
+ const INTERNAL_TRANSACTIONS = (address: string): Stream => ({
189
+ path: `/addresses/${address}/internal-transactions`,
190
+ params: {},
191
+ seed: (block): PageParams => ({ block_number: block, index: 0, transaction_index: 0 }),
192
+ })
193
+
194
+ /**
195
+ * Get all the internal transactions of a block, for the `explorer` internal transaction source of
196
+ * `getBlock`. Not retried: `getBlock` falls back to the next source on failure.
197
+ */
198
+ export async function getInternalTransactionsByBlock(
199
+ config: EvmConfigInfo,
200
+ blockHeight: number
201
+ ): Promise<EtherscanInternalTransaction[]> {
202
+ const { explorer } = config
203
+ if (!isBlockscoutV2ExplorerConfig(explorer)) return []
204
+
205
+ const internalTransactions: EtherscanInternalTransaction[] = []
206
+ await walkStream<BlockscoutV2InternalTransaction>(
207
+ explorer.uri,
208
+ {
209
+ path: `/blocks/${blockHeight}/internal-transactions`,
210
+ params: {},
211
+ // Only ever read from the first page
212
+ seed: (): PageParams => ({}),
213
+ },
214
+ blockHeight,
215
+ undefined,
216
+ 0,
217
+ (internalTx) => {
218
+ internalTransactions.push(blockscoutV2InternalTransactionToEtherscan(internalTx))
219
+ return true
220
+ }
221
+ )
222
+ return internalTransactions
223
+ }
224
+
225
+ function tokenTypes(config: EvmConfigInfo): string[] {
226
+ return [
227
+ 'ERC-20',
228
+ ...(config.supportedTokens?.includes('erc721') ? ['ERC-721'] : []),
229
+ ...(config.supportedTokens?.includes('erc1155') ? ['ERC-1155'] : []),
230
+ ]
231
+ }
232
+
233
+ /**
234
+ * Resolve the hash of each block: the v2 transaction and internal transaction lists only report the
235
+ * block number. Hashes already known from token transfers are reused, the others are read from the
236
+ * node.
237
+ */
238
+ async function getBlockHashes(
239
+ config: EvmConfigInfo,
240
+ logger: Logger,
241
+ heights: Set<number>,
242
+ known: Map<number, string>
243
+ ): Promise<Map<number, string>> {
244
+ const missing = [...heights].filter((height) => !known.has(height))
245
+ if (missing.length === 0) return known
246
+
247
+ const nodeApi = getNodeApi(config, logger)
248
+ const blocks = await promiseAllBatched(BLOCK_HASH_BATCH_SIZE, missing, (height) =>
249
+ nodeApi.getBlockByHeight(height)
250
+ )
251
+ return new Map([
252
+ ...known,
253
+ ...blocks.map((block, index): [number, string] => [missing[index], block.hash]),
254
+ ])
255
+ }
256
+
257
+ /** Parse a cursor: the highest block (inclusive) of the next page. */
258
+ function parseCursor(cursor: string | undefined): number | undefined {
259
+ if (cursor === undefined || cursor === NO_TOKEN) return undefined
260
+ const block = Number(cursor)
261
+ if (!Number.isSafeInteger(block) || block < 0) {
262
+ throw new InvalidParameterError(`Invalid Blockscout v2 explorer cursor: ${cursor}`)
263
+ }
264
+ return block
265
+ }
266
+
267
+ /** The lowest of two optional block bounds, or `undefined` when both are unbounded. */
268
+ function lowestBound(a: number | undefined, b: number | undefined): number | undefined {
269
+ if (a === undefined) return b
270
+ if (b === undefined) return a
271
+ return Math.min(a, b)
272
+ }
273
+
274
+ /**
275
+ * Returns all operation types from an address, in descending block order.
276
+ *
277
+ * Each list is read from the cursor (or `toBlock`, or the chain head) down to `fromBlock`. With a
278
+ * `limit`, each list stops after `limit` items and a complete block. The page then ends at the
279
+ * highest of those last blocks, the lowest block that every list has fully read, and the cursor
280
+ * resumes right below it. So a page holds at most about 3 × `limit` items and never splits a block.
281
+ */
282
+ export const getOperations = makeLRUCache<
283
+ [
284
+ config: EvmConfigInfo,
285
+ logger: Logger,
286
+ address: string,
287
+ fromBlock: number,
288
+ toBlock: number | undefined,
289
+ pagingToken: string | undefined,
290
+ limit: number | undefined,
291
+ order: 'asc' | 'desc' | undefined,
292
+ ],
293
+ Awaited<ReturnType<ExplorerApi['getOperations']>>
294
+ >(
295
+ async (config, logger, address, fromBlock, toBlock, pagingToken, limit, order = 'desc') => {
296
+ const { explorer } = config
297
+ if (!isBlockscoutV2ExplorerConfig(explorer)) {
298
+ throw new InvalidParameterError(
299
+ `Blockscout v2 explorer used incorrectly with currency: ${config.name}`
300
+ )
301
+ }
302
+ if (order === 'asc' && limit !== undefined) {
303
+ throw new InvalidParameterError(
304
+ `Ascending order is not supported by the Blockscout v2 explorer of ${config.name}`
305
+ )
306
+ }
307
+
308
+ try {
309
+ const retries = explorer.retries ?? DEFAULT_RETRIES_API
310
+ const cursor = parseCursor(pagingToken)
311
+ const ceiling = lowestBound(cursor, toBlock)
312
+
313
+ // ⚠ Sequential on purpose, parallel requests would hit the rate limits
314
+ const read = <T extends StreamItem>(stream: Stream): Promise<StreamRead<T>> =>
315
+ readStream<T>(explorer.uri, stream, fromBlock, ceiling, limit, retries)
316
+ const transactions = await read<BlockscoutV2Transaction>(TRANSACTIONS(address))
317
+ const tokenTransfers = await read<BlockscoutV2TokenTransfer>(
318
+ TOKEN_TRANSFERS(address, tokenTypes(config))
319
+ )
320
+ const internalTransactions = await read<BlockscoutV2InternalTransaction>(
321
+ INTERNAL_TRANSACTIONS(address)
322
+ )
323
+
324
+ // A list that stopped early may hold items below the blocks another list has fully read
325
+ const boundBlocks = [transactions, tokenTransfers, internalTransactions].flatMap((r) =>
326
+ r.boundBlock === undefined ? [] : [r.boundBlock]
327
+ )
328
+ const boundBlock = boundBlocks.length > 0 ? Math.max(...boundBlocks) : undefined
329
+ const inPage = (item: { block_number: number | null }): boolean =>
330
+ boundBlock === undefined || (item.block_number ?? 0) >= boundBlock
331
+
332
+ const pageTransactions = transactions.items.filter(inPage)
333
+ const pageTokenTransfers = tokenTransfers.items.filter(inPage)
334
+ const pageInternalTransactions = internalTransactions.items.filter(inPage)
335
+
336
+ const blockHashes = await getBlockHashes(
337
+ config,
338
+ logger,
339
+ new Set(
340
+ [...pageTransactions, ...pageInternalTransactions].map((item) => item.block_number ?? 0)
341
+ ),
342
+ new Map(pageTokenTransfers.map((transfer) => [transfer.block_number, transfer.block_hash]))
343
+ )
344
+
345
+ const lastCoinOperations = pageTransactions.flatMap((tx) =>
346
+ blockscoutV2TransactionToOperations(
347
+ address,
348
+ config.chainId,
349
+ tx,
350
+ blockHashes.get(tx.block_number ?? 0) ?? '',
351
+ logger
352
+ )
353
+ )
354
+ await enrichRewardOperations(config, lastCoinOperations, logger)
355
+
356
+ // Drop ERC20 Transfer events on contracts that mirror the native asset
357
+ const nativeContracts = new Set(
358
+ (config.nativeContracts ?? []).map((contract) => contract.toLowerCase())
359
+ )
360
+ const byType = (type: string): BlockscoutV2TokenTransfer[] =>
361
+ pageTokenTransfers.filter(
362
+ (transfer) => (transfer.token_type ?? transfer.token.type) === type
363
+ )
364
+ const lastTokenOperations = blockscoutV2ERC20TransfersToOperations(
365
+ address,
366
+ byType('ERC-20').filter(
367
+ (transfer) => !nativeContracts.has(transfer.token.address_hash.toLowerCase())
368
+ ),
369
+ logger
370
+ )
371
+ const lastNftOperations = [
372
+ ...blockscoutV2ERC721TransfersToOperations(address, byType('ERC-721'), logger),
373
+ ...blockscoutV2ERC1155TransfersToOperations(address, byType('ERC-1155'), logger),
374
+ ].sort((a, b) => b.tx.block.height - a.tx.block.height)
375
+ const lastInternalOperations = blockscoutV2InternalTransactionsToOperations(
376
+ address,
377
+ pageInternalTransactions,
378
+ blockHashes,
379
+ logger
380
+ )
381
+
382
+ const nextPagingToken =
383
+ boundBlock === undefined || boundBlock - 1 < fromBlock ? NO_TOKEN : String(boundBlock - 1)
384
+
385
+ return {
386
+ lastCoinOperations,
387
+ lastTokenOperations,
388
+ lastNftOperations,
389
+ lastInternalOperations,
390
+ nextPagingToken,
391
+ }
392
+ } catch (err) {
393
+ if (err instanceof RateLimitError || err instanceof InvalidParameterError) throw err
394
+ logger('EVM getOperations', 'Error while fetching data from Blockscout v2 API', err)
395
+ const message = err instanceof Error ? `${err.name} - ${err.message}` : String(err)
396
+ throw new InvalidExplorerResponse(
397
+ `${config.name} - ${message}`,
398
+ { currencyName: config.name },
399
+ { cause: err }
400
+ )
401
+ }
402
+ },
403
+ (config, _logger, address, fromBlock, toBlock, pagingToken, limit, order) =>
404
+ `${config.chainId}:${address}:${fromBlock}:${toBlock ?? ''}:${pagingToken ?? ''}:${limit ?? ''}:${order ?? 'desc'}`,
405
+ { ttl: BLOCKSCOUT_V2_TIMEOUT }
406
+ )
407
+
408
+ /**
409
+ * Discover which tokens an address holds by walking its ERC-20 transfers down to `fromBlock`.
410
+ */
411
+ export const discoverTokenAssets = makeLRUCache<
412
+ [config: EvmConfigInfo, logger: Logger, address: string, fromBlock?: number],
413
+ AssetInfo[]
414
+ >(
415
+ async (config, _logger, address, fromBlock = 0) => {
416
+ const { explorer } = config
417
+ if (!isBlockscoutV2ExplorerConfig(explorer)) {
418
+ throw new InvalidParameterError(
419
+ `Blockscout v2 explorer used incorrectly with currency: ${config.name}`
420
+ )
421
+ }
422
+
423
+ // Skip the contracts that mirror the native asset, as `getOperations` does
424
+ const nativeContracts = new Set(
425
+ (config.nativeContracts ?? []).map((contract) => contract.toLowerCase())
426
+ )
427
+ // Fold each transfer into the asset map as it is read: memory stays bounded by the number of
428
+ // distinct contracts, not by the length of the history
429
+ const assets = new Map<string, AssetInfo>()
430
+ await walkStream<BlockscoutV2TokenTransfer>(
431
+ explorer.uri,
432
+ TOKEN_TRANSFERS(address, ['ERC-20']),
433
+ fromBlock,
434
+ undefined,
435
+ explorer.retries ?? DEFAULT_RETRIES_API,
436
+ (transfer) => {
437
+ if (!nativeContracts.has(transfer.token.address_hash.toLowerCase())) {
438
+ const contract = eip55.encode(transfer.token.address_hash)
439
+ assets.set(contract, { type: 'erc20', assetReference: contract, assetOwner: address })
440
+ }
441
+ return true
442
+ }
443
+ )
444
+ return Array.from(assets.values())
445
+ },
446
+ (config, _logger, address, fromBlock) => `${config.chainId}:${address}:${fromBlock ?? 0}`,
447
+ { ttl: BLOCKSCOUT_V2_TIMEOUT }
448
+ )
449
+
450
+ const explorerApi: ExplorerApi = {
451
+ getOperations,
452
+ discoverTokenAssets,
453
+ }
454
+
455
+ const explorerApiNoCache: ExplorerApi = {
456
+ getOperations: getOperations.force,
457
+ discoverTokenAssets: discoverTokenAssets.force,
458
+ }
459
+
460
+ export default { explorerApi, explorerApiNoCache }