@ledgerhq/coin-evm 16.2.4 → 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 +24 -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 +1499 -0
  14. package/lib/config.d.ts.map +1 -1
  15. package/lib/config.js +968 -1
  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 +1499 -0
  58. package/lib-es/config.d.ts.map +1 -1
  59. package/lib-es/config.js +967 -0
  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 +993 -0
  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
@@ -9,8 +9,12 @@ import type { Logger } from '@ledgerhq/coin-module-framework/config'
9
9
  import { traceBlockItemsToOperationsByHash } from '../adapters/blockOperations'
10
10
  import { internalTxsToOperationsByHash } from '../adapters/etherscan'
11
11
  import { SourceUnavailableError } from '../errors'
12
+ import { getInternalTransactionsByBlock as getBlockscoutV2InternalTransactionsByBlock } from '../network/blockscoutV2'
12
13
  import { getInternalTransactionsByBlock } from '../network/explorer/etherscan'
13
- import { isEtherscanLikeExplorerConfig } from '../network/explorer/types'
14
+ import {
15
+ isBlockscoutV2ExplorerConfig,
16
+ isEtherscanLikeExplorerConfig,
17
+ } from '../network/explorer/types'
14
18
 
15
19
  export type InternalTxsByHash = Map<string, BlockOperation[]>
16
20
 
@@ -61,6 +65,18 @@ async function runInternalTxSources(
61
65
  throw new Error('no internal tx sources configured')
62
66
  }
63
67
 
68
+ function explorerInternalTxsByBlock(
69
+ explorer: EvmConfigInfo['explorer']
70
+ ): typeof getInternalTransactionsByBlock | undefined {
71
+ if (isBlockscoutV2ExplorerConfig(explorer)) {
72
+ return getBlockscoutV2InternalTransactionsByBlock
73
+ }
74
+ if (isEtherscanLikeExplorerConfig(explorer)) {
75
+ return getInternalTransactionsByBlock
76
+ }
77
+ return undefined
78
+ }
79
+
64
80
  export function composeInternalTxsFetcher(
65
81
  sources: readonly InternalTxSource[],
66
82
  fetchers: Record<InternalTxSource, SourceFetcher>
@@ -107,14 +123,15 @@ export function makeSourceFetchers(
107
123
  .then((items) => traceBlockItemsToOperationsByHash(items, logger))
108
124
  },
109
125
  explorer: (height: number) => {
110
- if (!isEtherscanLikeExplorerConfig(explorer)) {
126
+ const getByBlock = explorerInternalTxsByBlock(explorer)
127
+ if (getByBlock === undefined) {
111
128
  return Promise.reject(
112
129
  new SourceUnavailableError(
113
130
  `explorer internal txs not configured for currency ${config.name}`
114
131
  )
115
132
  )
116
133
  }
117
- return getInternalTransactionsByBlock(config, height)
134
+ return getByBlock(config, height)
118
135
  .then((txs) => internalTxsToOperationsByHash(txs, logger))
119
136
  .catch((error) => {
120
137
  logger('coin-evm', 'debug: explorer internal txs failed, falling through', {
@@ -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
 
@@ -218,6 +222,53 @@ describe('makeSourceFetchers', () => {
218
222
  expect(mockGetInternalTransactionsByBlock).toHaveBeenCalledWith(config, 99)
219
223
  })
220
224
 
225
+ it('reads the block internal transactions from the Blockscout v2 API for a blockscout-v2 explorer', async () => {
226
+ const config = createMockEvmConfigInfo({
227
+ chainId: 534352,
228
+ node: mkExternalNode(),
229
+ explorer: { type: 'blockscout-v2', uri: 'https://blockscout.example/api/v2' },
230
+ })
231
+ jest.mocked(getBlockscoutV2InternalTransactionsByBlock).mockResolvedValueOnce([
232
+ {
233
+ blockNumber: '99',
234
+ hash: '0xabc',
235
+ from: '0x9425E212647518853a92ae7D2C1Ab09D343e70b6',
236
+ to: '0x0459a84952C85c6E9345e5d22d9B110790a5e1Ba',
237
+ value: '9',
238
+ contractAddress: '',
239
+ input: '',
240
+ type: 'call',
241
+ callType: 'call',
242
+ gas: '2300',
243
+ gasUsed: '',
244
+ traceId: '1',
245
+ isError: '0',
246
+ errCode: '',
247
+ },
248
+ ])
249
+
250
+ const fetchers = makeSourceFetchers(config, mockNodeApi(), testLogger)
251
+ const result = await fetchers.explorer(99)
252
+
253
+ expect(getBlockscoutV2InternalTransactionsByBlock).toHaveBeenCalledWith(config, 99)
254
+ expect(getInternalTransactionsByBlock).not.toHaveBeenCalled()
255
+ expect(result.get('0xabc')?.map((op) => op.type === 'transfer' && op.amount)).toEqual([-9n, 9n])
256
+ })
257
+
258
+ it('wraps Blockscout v2 failures as SourceUnavailableError', async () => {
259
+ const config = createMockEvmConfigInfo({
260
+ chainId: 534352,
261
+ node: mkExternalNode(),
262
+ explorer: { type: 'blockscout-v2', uri: 'https://blockscout.example/api/v2' },
263
+ })
264
+ jest
265
+ .mocked(getBlockscoutV2InternalTransactionsByBlock)
266
+ .mockRejectedValueOnce(new Error('explorer error'))
267
+
268
+ const fetchers = makeSourceFetchers(config, mockNodeApi(), testLogger)
269
+ await expect(fetchers.explorer(99)).rejects.toBeInstanceOf(SourceUnavailableError)
270
+ })
271
+
221
272
  it('empty always resolves to an empty map', async () => {
222
273
  const config = createMockEvmConfigInfo({ chainId: 1, node: mkExternalNode() })
223
274
 
@@ -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 }
@@ -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',