@ledgerhq/coin-evm 16.2.5 → 16.4.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 (110) hide show
  1. package/CHANGELOG.md +18 -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 +24 -23
  14. package/lib/config.d.ts.map +1 -1
  15. package/lib/config.js +0 -16
  16. package/lib/config.js.map +1 -1
  17. package/lib/logic/internalTransactionsFetcher.d.ts.map +1 -1
  18. package/lib/logic/internalTransactionsFetcher.js +13 -2
  19. package/lib/logic/internalTransactionsFetcher.js.map +1 -1
  20. package/lib/network/blockscoutV2.d.ts +35 -0
  21. package/lib/network/blockscoutV2.d.ts.map +1 -0
  22. package/lib/network/blockscoutV2.js +311 -0
  23. package/lib/network/blockscoutV2.js.map +1 -0
  24. package/lib/network/explorer/etherscan.d.ts.map +1 -1
  25. package/lib/network/explorer/etherscan.js +11 -28
  26. package/lib/network/explorer/etherscan.js.map +1 -1
  27. package/lib/network/explorer/index.d.ts.map +1 -1
  28. package/lib/network/explorer/index.js +5 -0
  29. package/lib/network/explorer/index.js.map +1 -1
  30. package/lib/network/explorer/types.d.ts +6 -0
  31. package/lib/network/explorer/types.d.ts.map +1 -1
  32. package/lib/network/explorer/types.js +8 -1
  33. package/lib/network/explorer/types.js.map +1 -1
  34. package/lib/network/rewards.d.ts +11 -0
  35. package/lib/network/rewards.d.ts.map +1 -0
  36. package/lib/network/rewards.js +32 -0
  37. package/lib/network/rewards.js.map +1 -0
  38. package/lib/types/blockscoutV2.d.ts +80 -0
  39. package/lib/types/blockscoutV2.d.ts.map +1 -0
  40. package/lib/types/blockscoutV2.js +5 -0
  41. package/lib/types/blockscoutV2.js.map +1 -0
  42. package/lib/types/index.d.ts +1 -0
  43. package/lib/types/index.d.ts.map +1 -1
  44. package/lib/types/index.js +1 -0
  45. package/lib/types/index.js.map +1 -1
  46. package/lib-es/adapters/blockscoutV2.d.ts +40 -0
  47. package/lib-es/adapters/blockscoutV2.d.ts.map +1 -0
  48. package/lib-es/adapters/blockscoutV2.js +168 -0
  49. package/lib-es/adapters/blockscoutV2.js.map +1 -0
  50. package/lib-es/adapters/index.d.ts +1 -0
  51. package/lib-es/adapters/index.d.ts.map +1 -1
  52. package/lib-es/adapters/index.js +1 -0
  53. package/lib-es/adapters/index.js.map +1 -1
  54. package/lib-es/chains.d.ts +1 -1
  55. package/lib-es/chains.js +1 -1
  56. package/lib-es/chains.js.map +1 -1
  57. package/lib-es/config.d.ts +24 -23
  58. package/lib-es/config.d.ts.map +1 -1
  59. package/lib-es/config.js +0 -16
  60. package/lib-es/config.js.map +1 -1
  61. package/lib-es/logic/internalTransactionsFetcher.d.ts.map +1 -1
  62. package/lib-es/logic/internalTransactionsFetcher.js +14 -3
  63. package/lib-es/logic/internalTransactionsFetcher.js.map +1 -1
  64. package/lib-es/network/blockscoutV2.d.ts +35 -0
  65. package/lib-es/network/blockscoutV2.d.ts.map +1 -0
  66. package/lib-es/network/blockscoutV2.js +271 -0
  67. package/lib-es/network/blockscoutV2.js.map +1 -0
  68. package/lib-es/network/explorer/etherscan.d.ts.map +1 -1
  69. package/lib-es/network/explorer/etherscan.js +2 -19
  70. package/lib-es/network/explorer/etherscan.js.map +1 -1
  71. package/lib-es/network/explorer/index.d.ts.map +1 -1
  72. package/lib-es/network/explorer/index.js +5 -0
  73. package/lib-es/network/explorer/index.js.map +1 -1
  74. package/lib-es/network/explorer/types.d.ts +6 -0
  75. package/lib-es/network/explorer/types.d.ts.map +1 -1
  76. package/lib-es/network/explorer/types.js +6 -0
  77. package/lib-es/network/explorer/types.js.map +1 -1
  78. package/lib-es/network/rewards.d.ts +11 -0
  79. package/lib-es/network/rewards.d.ts.map +1 -0
  80. package/lib-es/network/rewards.js +29 -0
  81. package/lib-es/network/rewards.js.map +1 -0
  82. package/lib-es/types/blockscoutV2.d.ts +80 -0
  83. package/lib-es/types/blockscoutV2.d.ts.map +1 -0
  84. package/lib-es/types/blockscoutV2.js +4 -0
  85. package/lib-es/types/blockscoutV2.js.map +1 -0
  86. package/lib-es/types/index.d.ts +1 -0
  87. package/lib-es/types/index.d.ts.map +1 -1
  88. package/lib-es/types/index.js +1 -0
  89. package/lib-es/types/index.js.map +1 -1
  90. package/package.json +1 -1
  91. package/src/adapters/blockscoutV2.test.ts +296 -0
  92. package/src/adapters/blockscoutV2.ts +244 -0
  93. package/src/adapters/index.ts +1 -0
  94. package/src/api/tests/index.alpen_testnet.integ.test.ts +73 -0
  95. package/src/api/tests/index.integ.test.ts +4 -2
  96. package/src/api/tests/index.scroll.integ.test.ts +168 -0
  97. package/src/api/tests/index.shape.integ.test.ts +34 -0
  98. package/src/chains.ts +1 -1
  99. package/src/config.ts +25 -16
  100. package/src/logic/internalTransactionsFetcher.ts +20 -3
  101. package/src/logic/tests/internalTransactionsFetcher.test.ts +51 -0
  102. package/src/network/blockscoutV2.ts +460 -0
  103. package/src/network/explorer/etherscan.ts +2 -29
  104. package/src/network/explorer/index.ts +5 -0
  105. package/src/network/explorer/types.ts +9 -0
  106. package/src/network/rewards.ts +47 -0
  107. package/src/network/tests/blockscoutV2.test.ts +565 -0
  108. package/src/network/tests/explorer/index.test.ts +21 -0
  109. package/src/types/blockscoutV2.ts +85 -0
  110. package/src/types/index.ts +1 -0
@@ -0,0 +1,565 @@
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
+ BlockscoutV2TokenTransfer,
8
+ BlockscoutV2Transaction,
9
+ } from '../../types'
10
+ import type { AxiosRequestConfig } from 'axios'
11
+ import { InvalidParameterError } from '@ledgerhq/coin-module-framework/errors'
12
+ import { delay } from '@ledgerhq/coin-module-framework/promises'
13
+ import axios from 'axios'
14
+ import { InvalidExplorerResponse, RateLimitError } from '../../errors'
15
+ import {
16
+ createMockEvmConfigInfo,
17
+ mkExternalNode,
18
+ testLogger,
19
+ } from '../../fixtures/context.fixtures'
20
+ import blockscoutV2Api, { getInternalTransactionsByBlock } from '../blockscoutV2'
21
+ import { getNodeApi } from '../node'
22
+ import { mockNodeApi } from './node/node.fixtures'
23
+
24
+ jest.mock('axios')
25
+ jest.mock('@ledgerhq/coin-module-framework/promises', () => ({
26
+ ...jest.requireActual('@ledgerhq/coin-module-framework/promises'),
27
+ delay: jest.fn(),
28
+ }))
29
+ jest.mock('../node')
30
+
31
+ const { getOperations, discoverTokenAssets } = blockscoutV2Api.explorerApiNoCache
32
+
33
+ const uri = 'https://blockscout.example/api/v2'
34
+ const address = '0x0459a84952C85c6E9345e5d22d9B110790a5e1Ba'
35
+ const other = '0x9425E212647518853a92ae7D2C1Ab09D343e70b6'
36
+ const contract = '0x5300000000000000000000000000000000000004'
37
+
38
+ const config: EvmConfigInfo = createMockEvmConfigInfo({
39
+ chainId: 534352,
40
+ node: mkExternalNode({ uri: 'https://node.example' }),
41
+ explorer: { type: 'blockscout-v2', uri, retries: 0 },
42
+ })
43
+
44
+ const timestamp = '2024-01-01T00:00:00.000000Z'
45
+
46
+ function transaction(hash: string, block: number, fee = '1000'): BlockscoutV2Transaction {
47
+ return {
48
+ hash,
49
+ block_number: block,
50
+ position: 0,
51
+ timestamp,
52
+ nonce: 1,
53
+ from: { hash: address },
54
+ to: { hash: other },
55
+ created_contract: null,
56
+ value: '5',
57
+ fee: { type: 'actual', value: fee },
58
+ gas_used: '21000',
59
+ gas_price: '1',
60
+ gas_limit: '21000',
61
+ status: 'ok',
62
+ raw_input: '0x',
63
+ method: null,
64
+ }
65
+ }
66
+
67
+ function tokenTransfer(hash: string, block: number, logIndex = 0): BlockscoutV2TokenTransfer {
68
+ return {
69
+ transaction_hash: hash,
70
+ block_hash: `0xblock${block}`,
71
+ block_number: block,
72
+ log_index: logIndex,
73
+ timestamp,
74
+ from: { hash: other },
75
+ to: { hash: address },
76
+ token: { address_hash: contract, name: 'Token', symbol: 'TKN', decimals: '18', type: 'ERC-20' },
77
+ token_type: 'ERC-20',
78
+ total: { value: '7' },
79
+ }
80
+ }
81
+
82
+ function internalTransaction(hash: string, block: number): BlockscoutV2InternalTransaction {
83
+ return {
84
+ transaction_hash: hash,
85
+ block_number: block,
86
+ index: 1,
87
+ timestamp,
88
+ from: { hash: other },
89
+ to: { hash: address },
90
+ created_contract: null,
91
+ value: '9',
92
+ type: 'call',
93
+ success: true,
94
+ error: null,
95
+ gas_limit: '2300',
96
+ }
97
+ }
98
+
99
+ type Pages = Record<string, Array<{ items: unknown[]; next_page_params: unknown }>>
100
+
101
+ /** Serve each list endpoint from its own queue of pages, record every request. */
102
+ function mockLists(pages: Pages): jest.SpyInstance {
103
+ const queues = Object.fromEntries(Object.entries(pages).map(([path, list]) => [path, [...list]]))
104
+ return jest.spyOn(axios, 'request').mockImplementation(async (request: AxiosRequestConfig) => {
105
+ const path = request.url!.replace(`${uri}/addresses/${address}`, '')
106
+ const page = queues[path]?.shift() ?? { items: [], next_page_params: null }
107
+ return { data: page }
108
+ })
109
+ }
110
+
111
+ function requestsTo(spy: jest.SpyInstance, path: string): Array<Record<string, unknown>> {
112
+ return spy.mock.calls
113
+ .map(([request]: [AxiosRequestConfig]) => request)
114
+ .filter((request) => request.url === `${uri}/addresses/${address}${path}`)
115
+ .map((request) => request.params)
116
+ }
117
+
118
+ const getBlockByHeight = jest.fn()
119
+
120
+ describe('blockscout-v2 explorer', () => {
121
+ beforeEach(() => {
122
+ jest.mocked(delay).mockResolvedValue(undefined)
123
+ getBlockByHeight.mockImplementation(async (height: number) => ({
124
+ hash: `0xnode${height}`,
125
+ height,
126
+ timestamp: 0,
127
+ parentHash: '0x',
128
+ }))
129
+ jest.mocked(getNodeApi).mockReturnValue(mockNodeApi({ getBlockByHeight }))
130
+ // axios is fully mocked — restore isAxiosError to its real behaviour
131
+ jest
132
+ .spyOn(axios, 'isAxiosError')
133
+ .mockImplementation(
134
+ (e: unknown): boolean => typeof e === 'object' && e !== null && 'isAxiosError' in e
135
+ )
136
+ })
137
+
138
+ afterEach(() => {
139
+ jest.resetAllMocks()
140
+ })
141
+
142
+ describe('getOperations', () => {
143
+ it('rejects ascending pages', async () => {
144
+ await expect(
145
+ getOperations(config, testLogger, address, 0, undefined, undefined, 10, 'asc')
146
+ ).rejects.toBeInstanceOf(InvalidParameterError)
147
+ })
148
+
149
+ it('rejects an invalid cursor', async () => {
150
+ await expect(
151
+ getOperations(config, testLogger, address, 0, undefined, 'nope', 10, 'desc')
152
+ ).rejects.toBeInstanceOf(InvalidParameterError)
153
+ })
154
+
155
+ it('reads every list down to fromBlock without a limit', async () => {
156
+ const spy = mockLists({
157
+ '/transactions': [
158
+ {
159
+ items: [transaction('0xa', 30), transaction('0xb', 20)],
160
+ next_page_params: { block_number: 20, index: 0, items_count: 50 },
161
+ },
162
+ { items: [transaction('0xc', 10), transaction('0xd', 5)], next_page_params: null },
163
+ ],
164
+ '/token-transfers': [{ items: [tokenTransfer('0xe', 25)], next_page_params: null }],
165
+ '/internal-transactions': [
166
+ { items: [internalTransaction('0xf', 15)], next_page_params: null },
167
+ ],
168
+ })
169
+
170
+ const result = await getOperations(
171
+ config,
172
+ testLogger,
173
+ address,
174
+ 8,
175
+ undefined,
176
+ undefined,
177
+ undefined,
178
+ 'desc'
179
+ )
180
+
181
+ expect(result.lastCoinOperations.map((op) => op.tx.hash)).toEqual(['0xa', '0xb', '0xc'])
182
+ expect(result.lastTokenOperations.map((op) => op.tx.hash)).toEqual(['0xe'])
183
+ expect(result.lastInternalOperations.map((op) => op.tx.hash)).toEqual(['0xf'])
184
+ expect(result.lastNftOperations).toEqual([])
185
+ expect(result.nextPagingToken).toEqual('')
186
+ expect(requestsTo(spy, '/transactions')).toEqual([
187
+ {},
188
+ { block_number: 20, index: 0, items_count: 50 },
189
+ ])
190
+ expect(requestsTo(spy, '/token-transfers')).toEqual([{ type: 'ERC-20' }])
191
+ })
192
+
193
+ it('starts each list right above the cursor', async () => {
194
+ const spy = mockLists({})
195
+
196
+ await getOperations(config, testLogger, address, 0, undefined, '100', 10, 'desc')
197
+
198
+ expect(requestsTo(spy, '/transactions')).toEqual([{ block_number: 101, index: 0 }])
199
+ expect(requestsTo(spy, '/token-transfers')).toEqual([
200
+ { type: 'ERC-20', block_number: 101, index: 0 },
201
+ ])
202
+ expect(requestsTo(spy, '/internal-transactions')).toEqual([
203
+ { block_number: 101, index: 0, transaction_index: 0 },
204
+ ])
205
+ })
206
+
207
+ it('requests the NFT transfers the network supports', async () => {
208
+ const spy = mockLists({})
209
+
210
+ await getOperations(
211
+ { ...config, supportedTokens: ['erc721', 'erc1155'] },
212
+ testLogger,
213
+ address,
214
+ 0,
215
+ undefined,
216
+ undefined,
217
+ 10,
218
+ 'desc'
219
+ )
220
+
221
+ expect(requestsTo(spy, '/token-transfers')).toEqual([{ type: 'ERC-20,ERC-721,ERC-1155' }])
222
+ })
223
+
224
+ it('ends the page at the lowest block every list has fully read', async () => {
225
+ mockLists({
226
+ // stops after block 20, which is complete: 0xc is the first item of a lower block
227
+ '/transactions': [
228
+ {
229
+ items: [
230
+ transaction('0xa', 30),
231
+ transaction('0xb', 20),
232
+ transaction('0xb2', 20),
233
+ transaction('0xc', 10),
234
+ ],
235
+ next_page_params: null,
236
+ },
237
+ ],
238
+ // stops after block 25: everything below it is left to the next page
239
+ '/token-transfers': [
240
+ {
241
+ items: [tokenTransfer('0xd', 28), tokenTransfer('0xe', 25), tokenTransfer('0xg', 12)],
242
+ next_page_params: null,
243
+ },
244
+ ],
245
+ // read down to the floor, its item below block 25 is left to the next page
246
+ '/internal-transactions': [
247
+ { items: [internalTransaction('0xf', 22)], next_page_params: null },
248
+ ],
249
+ })
250
+
251
+ const result = await getOperations(config, testLogger, address, 0, undefined, '40', 2, 'desc')
252
+
253
+ expect(result.lastCoinOperations.map((op) => op.tx.hash)).toEqual(['0xa'])
254
+ expect(result.lastTokenOperations.map((op) => op.tx.hash)).toEqual(['0xd', '0xe'])
255
+ expect(result.lastInternalOperations).toEqual([])
256
+ expect(result.nextPagingToken).toEqual('24')
257
+ })
258
+
259
+ it('ends the pages when every list is read down to fromBlock', async () => {
260
+ mockLists({
261
+ '/transactions': [
262
+ { items: [transaction('0xa', 30), transaction('0xb', 5)], next_page_params: null },
263
+ ],
264
+ })
265
+
266
+ const result = await getOperations(
267
+ config,
268
+ testLogger,
269
+ address,
270
+ 10,
271
+ undefined,
272
+ '40',
273
+ 5,
274
+ 'desc'
275
+ )
276
+
277
+ expect(result.lastCoinOperations.map((op) => op.tx.hash)).toEqual(['0xa'])
278
+ expect(result.nextPagingToken).toEqual('')
279
+ })
280
+
281
+ it('ends the pages when the next one would start below fromBlock', async () => {
282
+ mockLists({
283
+ '/transactions': [
284
+ {
285
+ items: [transaction('0xa', 30), transaction('0xb', 10), transaction('0xc', 9)],
286
+ next_page_params: null,
287
+ },
288
+ ],
289
+ })
290
+
291
+ const result = await getOperations(
292
+ config,
293
+ testLogger,
294
+ address,
295
+ 10,
296
+ undefined,
297
+ '40',
298
+ 2,
299
+ 'desc'
300
+ )
301
+
302
+ expect(result.lastCoinOperations.map((op) => op.tx.hash)).toEqual(['0xa', '0xb'])
303
+ expect(result.nextPagingToken).toEqual('')
304
+ })
305
+
306
+ it('skips pending transactions', async () => {
307
+ mockLists({
308
+ '/transactions': [
309
+ {
310
+ items: [{ ...transaction('0xp', 0), block_number: null }, transaction('0xa', 30)],
311
+ next_page_params: null,
312
+ },
313
+ ],
314
+ })
315
+
316
+ const result = await getOperations(config, testLogger, address, 0, undefined, '40', 5, 'desc')
317
+
318
+ expect(result.lastCoinOperations.map((op) => op.tx.hash)).toEqual(['0xa'])
319
+ })
320
+
321
+ it('reports the v2 fee and resolves block hashes the lists do not report', async () => {
322
+ mockLists({
323
+ '/transactions': [
324
+ {
325
+ items: [transaction('0xa', 30, '123456'), transaction('0xb', 25)],
326
+ next_page_params: null,
327
+ },
328
+ ],
329
+ '/token-transfers': [{ items: [tokenTransfer('0xb', 25)], next_page_params: null }],
330
+ '/internal-transactions': [
331
+ { items: [internalTransaction('0xc', 20)], next_page_params: null },
332
+ ],
333
+ })
334
+
335
+ const result = await getOperations(config, testLogger, address, 0, undefined, '40', 5, 'desc')
336
+
337
+ expect(result.lastCoinOperations.map((op) => [op.tx.fees, op.tx.block.hash])).toEqual([
338
+ [123456n, '0xnode30'],
339
+ [1000n, '0xblock25'],
340
+ ])
341
+ expect(result.lastInternalOperations[0].tx.block.hash).toEqual('0xnode20')
342
+ // block 25 is known from its token transfer
343
+ expect(getBlockByHeight.mock.calls.map(([height]) => height).sort()).toEqual([20, 30])
344
+ })
345
+
346
+ // Blockscout v9 (e.g. v9.0.2 on Alpen Testnet) reports the token standard only in `token.type`
347
+ it.each([
348
+ { type: 'ERC-20', total: { value: '7' }, list: 'lastTokenOperations', opType: 'IN' },
349
+ { type: 'ERC-721', total: { token_id: '42' }, list: 'lastNftOperations', opType: 'NFT_IN' },
350
+ {
351
+ type: 'ERC-1155',
352
+ total: { value: '3', token_id: '42' },
353
+ list: 'lastNftOperations',
354
+ opType: 'NFT_IN',
355
+ },
356
+ ] as const)(
357
+ 'lists a $type transfer that only reports its type in token.type (Blockscout v9)',
358
+ async ({ type, total, list, opType }) => {
359
+ const { token_type: _, ...transfer } = tokenTransfer('0xa', 30)
360
+ mockLists({
361
+ '/token-transfers': [
362
+ {
363
+ items: [{ ...transfer, token: { ...transfer.token, type }, total }],
364
+ next_page_params: null,
365
+ },
366
+ ],
367
+ })
368
+
369
+ const result = await getOperations(
370
+ { ...config, supportedTokens: ['erc721', 'erc1155'] },
371
+ testLogger,
372
+ address,
373
+ 0,
374
+ undefined,
375
+ '40',
376
+ 5,
377
+ 'desc'
378
+ )
379
+
380
+ const operations = [...result.lastTokenOperations, ...result.lastNftOperations]
381
+ expect(result[list]).toHaveLength(1)
382
+ expect(operations).toHaveLength(1)
383
+ expect(result[list][0]).toEqual(
384
+ expect.objectContaining({
385
+ type: opType,
386
+ asset: expect.objectContaining({ type: type.toLowerCase().replace('-', '') }),
387
+ tx: expect.objectContaining({
388
+ hash: '0xa',
389
+ block: expect.objectContaining({ height: 30, hash: '0xblock30' }),
390
+ }),
391
+ })
392
+ )
393
+ }
394
+ )
395
+
396
+ it('prefers token_type over token.type when both are reported', async () => {
397
+ const transfer = tokenTransfer('0xa', 30)
398
+ mockLists({
399
+ '/token-transfers': [
400
+ {
401
+ items: [{ ...transfer, token: { ...transfer.token, type: 'ERC-721' } }],
402
+ next_page_params: null,
403
+ },
404
+ ],
405
+ })
406
+
407
+ const result = await getOperations(config, testLogger, address, 0, undefined, '40', 5, 'desc')
408
+
409
+ expect(result.lastTokenOperations).toHaveLength(1)
410
+ expect(result.lastNftOperations).toEqual([])
411
+ })
412
+
413
+ it('drops the transfers of contracts that mirror the native asset', async () => {
414
+ mockLists({
415
+ '/token-transfers': [{ items: [tokenTransfer('0xa', 30)], next_page_params: null }],
416
+ })
417
+
418
+ const result = await getOperations(
419
+ { ...config, nativeContracts: [contract.toLowerCase()] },
420
+ testLogger,
421
+ address,
422
+ 0,
423
+ undefined,
424
+ '40',
425
+ 5,
426
+ 'desc'
427
+ )
428
+
429
+ expect(result.lastTokenOperations).toEqual([])
430
+ })
431
+
432
+ it('rejects a malformed response', async () => {
433
+ jest.spyOn(axios, 'request').mockResolvedValue({ data: '<html>Bad Gateway</html>' })
434
+
435
+ await expect(
436
+ getOperations(config, testLogger, address, 0, undefined, undefined, 5, 'desc')
437
+ ).rejects.toBeInstanceOf(InvalidExplorerResponse)
438
+ })
439
+
440
+ it('retries a failed request', async () => {
441
+ const spy = jest
442
+ .spyOn(axios, 'request')
443
+ .mockRejectedValueOnce(new Error('upstream error'))
444
+ .mockResolvedValue({ data: { items: [], next_page_params: null } })
445
+
446
+ await getOperations(
447
+ { ...config, explorer: { type: 'blockscout-v2', uri, retries: 1 } },
448
+ testLogger,
449
+ address,
450
+ 0,
451
+ undefined,
452
+ undefined,
453
+ 5,
454
+ 'desc'
455
+ )
456
+
457
+ expect(spy).toHaveBeenCalledTimes(4)
458
+ })
459
+
460
+ it('surfaces a 429 HTTP response as RateLimitError without retrying', async () => {
461
+ const spy = jest.spyOn(axios, 'request').mockRejectedValue(
462
+ Object.assign(new Error('Request failed with status code 429'), {
463
+ isAxiosError: true,
464
+ response: { status: 429 },
465
+ })
466
+ )
467
+
468
+ await expect(
469
+ getOperations(
470
+ { ...config, explorer: { type: 'blockscout-v2', uri, retries: 3 } },
471
+ testLogger,
472
+ address,
473
+ 0,
474
+ undefined,
475
+ undefined,
476
+ 5,
477
+ 'desc'
478
+ )
479
+ ).rejects.toBeInstanceOf(RateLimitError)
480
+ expect(spy).toHaveBeenCalledTimes(1)
481
+ })
482
+ })
483
+
484
+ describe('getInternalTransactionsByBlock', () => {
485
+ it('reads every page of the block internal transactions, mapped onto Etherscan records', async () => {
486
+ const spy = jest
487
+ .spyOn(axios, 'request')
488
+ .mockResolvedValueOnce({
489
+ data: {
490
+ items: [internalTransaction('0xa', 99)],
491
+ next_page_params: { block_number: 99, index: 1, transaction_index: 0, items_count: 50 },
492
+ },
493
+ })
494
+ .mockResolvedValueOnce({
495
+ data: {
496
+ items: [
497
+ { ...internalTransaction('0xb', 99), to: null, created_contract: { hash: other } },
498
+ ],
499
+ next_page_params: null,
500
+ },
501
+ })
502
+
503
+ const internalTransactions = await getInternalTransactionsByBlock(config, 99)
504
+
505
+ expect(internalTransactions).toMatchObject([
506
+ { hash: '0xa', blockNumber: '99', from: other, to: address, value: '9', isError: '0' },
507
+ { hash: '0xb', to: other, contractAddress: other },
508
+ ])
509
+ expect(
510
+ spy.mock.calls.map(([request]: [AxiosRequestConfig]) => [request.url, request.params])
511
+ ).toEqual([
512
+ [`${uri}/blocks/99/internal-transactions`, {}],
513
+ [
514
+ `${uri}/blocks/99/internal-transactions`,
515
+ { block_number: 99, index: 1, transaction_index: 0, items_count: 50 },
516
+ ],
517
+ ])
518
+ })
519
+
520
+ it('does not retry: getBlock falls back to the next source', async () => {
521
+ const spy = jest.spyOn(axios, 'request').mockRejectedValue(new Error('upstream error'))
522
+
523
+ await expect(
524
+ getInternalTransactionsByBlock(
525
+ { ...config, explorer: { type: 'blockscout-v2', uri, retries: 3 } },
526
+ 99
527
+ )
528
+ ).rejects.toThrow('upstream error')
529
+ expect(spy).toHaveBeenCalledTimes(1)
530
+ })
531
+ })
532
+
533
+ describe('discoverTokenAssets', () => {
534
+ it('returns each ERC-20 contract once, down to fromBlock', async () => {
535
+ const otherContract = '0x06eFdBFf2a14a7c8E15944D1F4A48F9F95F663A4'
536
+ const spy = mockLists({
537
+ '/token-transfers': [
538
+ {
539
+ items: [
540
+ tokenTransfer('0xa', 30),
541
+ tokenTransfer('0xb', 20),
542
+ {
543
+ ...tokenTransfer('0xc', 15),
544
+ token: { ...tokenTransfer('0xc', 15).token, address_hash: otherContract },
545
+ },
546
+ {
547
+ ...tokenTransfer('0xd', 5),
548
+ token: { ...tokenTransfer('0xd', 5).token, address_hash: other },
549
+ },
550
+ ],
551
+ next_page_params: null,
552
+ },
553
+ ],
554
+ })
555
+
556
+ const assets = await discoverTokenAssets(config, testLogger, address, 10)
557
+
558
+ expect(assets).toEqual([
559
+ { type: 'erc20', assetReference: contract, assetOwner: address },
560
+ { type: 'erc20', assetReference: otherContract, assetOwner: address },
561
+ ])
562
+ expect(requestsTo(spy, '/token-transfers')).toEqual([{ type: 'ERC-20' }])
563
+ })
564
+ })
565
+ })
@@ -11,6 +11,7 @@ import {
11
11
  mkLedgerExplorer,
12
12
  testLogger,
13
13
  } from '../../../fixtures/context.fixtures'
14
+ import blockscoutV2Api from '../../blockscoutV2'
14
15
  import etherscanLikeApi from '../../explorer/etherscan'
15
16
  import { getExplorerApi } from '../../explorer/index'
16
17
  import ledgerExplorerApi from '../../explorer/ledger'
@@ -49,6 +50,18 @@ const configFor = (chainName: string): EvmConfigInfo => {
49
50
  node,
50
51
  explorer: { type: 'blockscout', uri: 'working', noCache: true },
51
52
  })
53
+ case 'blockscout-v2-coin':
54
+ return createMockEvmConfigInfo({
55
+ chainId: 1,
56
+ node,
57
+ explorer: { type: 'blockscout-v2', uri: 'working' },
58
+ })
59
+ case 'blockscout-v2-coin-no-cache':
60
+ return createMockEvmConfigInfo({
61
+ chainId: 1,
62
+ node,
63
+ explorer: { type: 'blockscout-v2', uri: 'working', noCache: true },
64
+ })
52
65
  case 'ledger-coin':
53
66
  return createMockEvmConfigInfo({
54
67
  chainId: 1,
@@ -93,6 +106,13 @@ describe('EVM Family', () => {
93
106
  expect(explorerB).toBe(etherscanLikeApi.explorerApiNoCache)
94
107
  })
95
108
 
109
+ it('should return the blockscout v2 api', () => {
110
+ expect(getExplorerApi(configFor('blockscout-v2-coin'))).toBe(blockscoutV2Api.explorerApi)
111
+ expect(getExplorerApi(configFor('blockscout-v2-coin-no-cache'))).toBe(
112
+ blockscoutV2Api.explorerApiNoCache
113
+ )
114
+ })
115
+
96
116
  it('should return the ledger api', () => {
97
117
  const explorerA = getExplorerApi(configFor('ledger-coin'))
98
118
 
@@ -107,6 +127,7 @@ describe('EVM Family', () => {
107
127
 
108
128
  it.each([
109
129
  ['etherscan', 'etherscan-coin'],
130
+ ['blockscout-v2', 'blockscout-v2-coin'],
110
131
  ['ledger', 'ledger-coin'],
111
132
  ['none', 'none-coin'],
112
133
  ])('%s arm exposes discoverTokenAssets', (_type, chainName) => {
@@ -0,0 +1,85 @@
1
+ // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+
4
+ // Blockscout v2 REST API (`/api/v2`) response types. Only the fields the adapters read are declared.
5
+
6
+ export type BlockscoutV2Address = {
7
+ hash: string
8
+ }
9
+
10
+ /** Item of `GET /addresses/{address}/transactions` */
11
+ export type BlockscoutV2Transaction = {
12
+ hash: string
13
+ /** `null` while the transaction is pending */
14
+ block_number: number | null
15
+ /** Index of the transaction in its block */
16
+ position: number | null
17
+ timestamp: string | null
18
+ nonce: number
19
+ from: BlockscoutV2Address
20
+ /** `null` for a contract creation */
21
+ to: BlockscoutV2Address | null
22
+ created_contract: BlockscoutV2Address | null
23
+ value: string
24
+ /** Fee actually paid (`actual`) once mined, including the L1 data fee of rollups */
25
+ fee: { type: 'actual' | 'maximum'; value: string }
26
+ gas_used: string | null
27
+ gas_price: string | null
28
+ gas_limit: string
29
+ /** `null` while the transaction is pending */
30
+ status: 'ok' | 'error' | null
31
+ raw_input: string | null
32
+ /** Decoded method name, or the method id when it cannot be decoded */
33
+ method: string | null
34
+ }
35
+
36
+ /** Item of `GET /addresses/{address}/token-transfers` */
37
+ export type BlockscoutV2TokenTransfer = {
38
+ transaction_hash: string
39
+ block_hash: string
40
+ block_number: number
41
+ log_index: number
42
+ timestamp: string | null
43
+ from: BlockscoutV2Address
44
+ to: BlockscoutV2Address
45
+ token: {
46
+ address_hash: string
47
+ name: string | null
48
+ symbol: string | null
49
+ decimals: string | null
50
+ /** e.g. `ERC-20`, `ERC-721`, `ERC-1155` */
51
+ type: string
52
+ }
53
+ /** Same as `token.type`. Absent before Blockscout v10 (e.g. v9.0.2 on Alpen Testnet). */
54
+ token_type?: string | undefined
55
+ total: {
56
+ /** Amount, for ERC-20 and ERC-1155 */
57
+ value?: string | null
58
+ /** Token id, for ERC-721 and ERC-1155 */
59
+ token_id?: string | null
60
+ } | null
61
+ }
62
+
63
+ /** Item of `GET /addresses/{address}/internal-transactions` */
64
+ export type BlockscoutV2InternalTransaction = {
65
+ transaction_hash: string
66
+ block_number: number
67
+ /** Index of the internal transaction in its transaction */
68
+ index: number
69
+ timestamp: string | null
70
+ from: BlockscoutV2Address
71
+ to: BlockscoutV2Address | null
72
+ created_contract: BlockscoutV2Address | null
73
+ value: string
74
+ /** Call type, e.g. `call`, `delegatecall`, `staticcall`, `create` */
75
+ type: string
76
+ success: boolean
77
+ error: string | null
78
+ gas_limit: string | null
79
+ }
80
+
81
+ /** Keyset-paginated list: `next_page_params` are the query params of the next (older) page */
82
+ export type BlockscoutV2Page<T> = {
83
+ items: T[]
84
+ next_page_params: Record<string, string | number | null> | null
85
+ }
@@ -4,6 +4,7 @@
4
4
  /* istanbul ignore file: pure exports, bridge tested by live-common with bridge.integration.test.ts */
5
5
 
6
6
  export * from './assets'
7
+ export * from './blockscoutV2'
7
8
  export * from './editTransaction'
8
9
  export * from './etherscan'
9
10
  export * from './ledger'