@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
@@ -35,9 +35,7 @@ import {
35
35
  RateLimitError,
36
36
  InvalidExplorerResponse,
37
37
  } from '../../errors'
38
- import { enrichRewardOperationsValue } from '../../staking/rewardsFromReceipt'
39
- import { withApi } from '../node/rpc.common'
40
- import { isExternalNodeConfig } from '../node/types'
38
+ import { enrichRewardOperations } from '../rewards'
41
39
  import { isEtherscanLikeExplorerConfig } from './types'
42
40
 
43
41
  export const ETHERSCAN_TIMEOUT = 5000 // 5 seconds between 2 calls
@@ -327,32 +325,7 @@ export const getCoinOperations = async (params: FetchOperationsParams): Promise<
327
325
  etherscanOperationToOperations(params.address, params.config.chainId, tx, params.logger)
328
326
  )
329
327
 
330
- // Recover REWARD op amounts (claim/compound) from receipt logs — these txs send 0 native
331
- // value, so the amount would otherwise show as 0 in history and operation details.
332
- const node = params.config.node
333
- if (
334
- operations.some((op) => op.type === 'REWARD' && op.value === 0n) &&
335
- isExternalNodeConfig(node)
336
- ) {
337
- try {
338
- await withApi(
339
- params.config,
340
- (api) =>
341
- enrichRewardOperationsValue(
342
- params.config.chainId,
343
- operations,
344
- (hash) => api.getTransactionReceipt(hash),
345
- params.logger
346
- ),
347
- node
348
- )
349
- } catch (e) {
350
- // Enrichment is best-effort, but a rate limit must not be downgraded into a successful
351
- // response reporting 0-value rewards.
352
- if (e instanceof RateLimitError) throw e
353
- params.logger('EVM getOperations', 'reward amount enrichment failed', e)
354
- }
355
- }
328
+ await enrichRewardOperations(params.config, operations, params.logger)
356
329
 
357
330
  const maxBlock = boundBlockFromOperations(operations)
358
331
 
@@ -4,6 +4,7 @@
4
4
  import type { EvmConfigInfo } from '../../config'
5
5
  import type { ExplorerApi } from './types'
6
6
  import { UnknownExplorer } from '../../errors'
7
+ import blockscoutV2Api from '../blockscoutV2'
7
8
  import etherscanLikeApi from './etherscan'
8
9
  import ledgerExplorerApi from './ledger'
9
10
  import noExplorerAPI from './none'
@@ -22,6 +23,10 @@ export const getExplorerApi = (config: EvmConfigInfo): ExplorerApi => {
22
23
  return config.explorer.noCache
23
24
  ? etherscanLikeApi.explorerApiNoCache
24
25
  : etherscanLikeApi.explorerApi
26
+ case 'blockscout-v2':
27
+ return config.explorer.noCache
28
+ ? blockscoutV2Api.explorerApiNoCache
29
+ : blockscoutV2Api.explorerApi
25
30
  case 'ledger':
26
31
  return ledgerExplorerApi
27
32
  case 'none':
@@ -61,6 +61,15 @@ export const isLedgerExplorerConfig = (
61
61
  return explorerConfig?.type === 'ledger'
62
62
  }
63
63
 
64
+ /**
65
+ * Type guard
66
+ */
67
+ export const isBlockscoutV2ExplorerConfig = (
68
+ explorerConfig: ExplorerConfig
69
+ ): explorerConfig is ExplorerConfig & { type: 'blockscout-v2' } => {
70
+ return explorerConfig?.type === 'blockscout-v2'
71
+ }
72
+
64
73
  const ETHERSCAN_LIKE_EXPLORER_TYPES = new Set<string>([
65
74
  'etherscan',
66
75
  'blockscout',
@@ -0,0 +1,47 @@
1
+ // SPDX-FileCopyrightText: © 2026 LEDGER SAS
2
+ // SPDX-License-Identifier: Apache-2.0
3
+
4
+ import type { EvmConfigInfo } from '../config'
5
+ import type { MemoNotSupported, Operation } from '@ledgerhq/coin-module-framework/api/types'
6
+ import type { Logger } from '@ledgerhq/coin-module-framework/config'
7
+ import { RateLimitError } from '../errors'
8
+ import { enrichRewardOperationsValue } from '../staking/rewardsFromReceipt'
9
+ import { withApi } from './node/rpc.common'
10
+ import { isExternalNodeConfig } from './node/types'
11
+
12
+ /**
13
+ * Recover REWARD op amounts (claim/compound) from receipt logs — these txs send 0 native
14
+ * value, so the amount would otherwise show as 0 in history and operation details.
15
+ *
16
+ * Mutates `operations` in place.
17
+ */
18
+ export async function enrichRewardOperations(
19
+ config: EvmConfigInfo,
20
+ operations: Array<Operation<MemoNotSupported>>,
21
+ logger: Logger
22
+ ): Promise<void> {
23
+ const node = config.node
24
+ if (
25
+ operations.some((op) => op.type === 'REWARD' && op.value === 0n) &&
26
+ isExternalNodeConfig(node)
27
+ ) {
28
+ try {
29
+ await withApi(
30
+ config,
31
+ (api) =>
32
+ enrichRewardOperationsValue(
33
+ config.chainId,
34
+ operations,
35
+ (hash) => api.getTransactionReceipt(hash),
36
+ logger
37
+ ),
38
+ node
39
+ )
40
+ } catch (e) {
41
+ // Enrichment is best-effort, but a rate limit must not be downgraded into a successful
42
+ // response reporting 0-value rewards.
43
+ if (e instanceof RateLimitError) throw e
44
+ logger('EVM getOperations', 'reward amount enrichment failed', e)
45
+ }
46
+ }
47
+ }
@@ -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
+ })