@le-space/chains 0.0.0-stage → 0.2.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.
package/src/alchemy.js ADDED
@@ -0,0 +1,648 @@
1
+ // An EVM wallet read through Alchemy, when a key is set up (`pnpm
2
+ // setup:alchemy`). Blockscout without a key answers only a few requests per
3
+ // half hour and IP address; Alchemy with a (free) key many more.
4
+ //
5
+ // The key goes into the request URL to Alchemy and nowhere else: not into a
6
+ // log line, an error message, an answer to the app. Messages name the host
7
+ // (`eth-mainnet.g.alchemy.com`), never the path that holds the key.
8
+ //
9
+ // What is asked, all JSON-RPC over POST to https://<network>.g.alchemy.com/v2/<key>:
10
+ // eth_chainId the endpoint serves the chain it is meant for
11
+ // alchemy_getAssetTransfers fromAddress, then toAddress (both at once
12
+ // would mean "from AND to"), categories
13
+ // external + erc20 (+ internal where Alchemy
14
+ // offers it: Ethereum, Base, Polygon), oldest
15
+ // first, 1000 a page, pageKey paging
16
+ // eth_getTransactionByHash + for every transaction a transfer names this
17
+ // eth_getTransactionReceipt address as its sender: who sent it (a token
18
+ // can leave by transferFrom in someone else's
19
+ // transaction), its nonce, and the gas it
20
+ // cost: gasUsed × effectiveGasPrice;
21
+ // for value received, the receipt only: a
22
+ // reverted transaction books nothing
23
+ // eth_blockNumber, what the transfers cannot show: a transaction
24
+ // eth_getTransactionCount, this address sent that moved nothing (it
25
+ // eth_getBlockByNumber failed, or was an approval). The nonce counts
26
+ // every one of them; where the count rises in
27
+ // a block no known transaction explains, that
28
+ // block is fetched and its transaction found.
29
+ // eth_getBalance, the balance, native and of the listed tokens
30
+ // alchemy_getTokenBalances
31
+ // Several calls go as one batch (a JSON array, at most 50).
32
+ //
33
+ // Alchemy counts compute units (CU) per call – in a batch each call its own
34
+ // – and a free app gets 300 CU a second, over a 10-second token bucket
35
+ // (docs: reference/compute-unit-costs, reference/throughput). The reader
36
+ // spends at most `computeUnitsPerSecond` (250 by default, below the free
37
+ // limit) and waits before a call that would spend more. Calls Alchemy still
38
+ // refuses with 429 – the key's budget is shared with anything else using it
39
+ // – are sent again, only they, after 1, 2, 4, 8, 16 and 16 seconds.
40
+ //
41
+ // The result has the shape of Blockscout's lists (txlist, txlistinternal,
42
+ // tokentx), so evm.js turns both into entries the same way and gives the same
43
+ // transfer the same id whichever source read it (docs/crypto.md): the value
44
+ // `<hash>:value`, the gas `<hash>:fee`, a token transfer
45
+ // `<hash>:erc20:<contract>:<from>:<to>:<value>:<n>` (Blockscout's tokentx has
46
+ // no log index, so neither id uses it). An internal transfer is the one
47
+ // exception: Blockscout numbers it by its place among all of the
48
+ // transaction's calls, Alchemy by its trace address among those that moved
49
+ // value – `<hash>:internal:<index>` against `<hash>:internal:trace:<address>`.
50
+ // The app pairs the two (wallets/wallet-sync.js, reconcileSourceIds), so a
51
+ // change of source books nothing twice.
52
+
53
+ import { createJsonFetcher, WalletError } from './http.js';
54
+
55
+ const PAGE = '0x3e8'; // 1000, Alchemy's most
56
+ const BATCH = 50; // Alchemy: "aim for batches under 50"
57
+ const SPLIT = 16; // a block range with an unexplained nonce is cut into this many parts
58
+
59
+ /** Compute units per call (Alchemy's table); a method not named costs 20. */
60
+ const COMPUTE_UNITS = /** @type {Record<string, number>} */ ({
61
+ eth_chainId: 0,
62
+ eth_blockNumber: 10,
63
+ alchemy_getAssetTransfers: 120
64
+ });
65
+ /** @param {string} method */
66
+ export const computeUnitsOf = (method) => COMPUTE_UNITS[method] ?? 20;
67
+ const BURST_SECONDS = 4; // spent ahead at most; Alchemy's bucket holds 10 seconds
68
+ const LIMIT_ROUNDS = 7; // the first try and six more for calls refused with 429
69
+
70
+ /** @param {string} network */
71
+ export const alchemyBaseUrl = (network) => `https://${network}.g.alchemy.com/v2`;
72
+
73
+ /** What a key looks like: letters, digits, _ and -. Anything else is not sent anywhere. */
74
+ export const isAlchemyKey = (/** @type {unknown} */ key) =>
75
+ typeof key === 'string' && /^[A-Za-z0-9_-]{8,128}$/.test(key);
76
+
77
+ const HEX = /^0x[0-9a-fA-F]+$/;
78
+
79
+ /** @param {unknown} v @returns {bigint} */
80
+ function big(v) {
81
+ if (typeof v !== 'string' || !HEX.test(v)) {
82
+ throw new WalletError('Alchemy answered a number that is none', 'WALLET_DATA');
83
+ }
84
+ return BigInt(v);
85
+ }
86
+
87
+ /** @param {unknown} v */
88
+ const dec = (v) => big(v).toString();
89
+
90
+ /** @param {unknown} iso @returns {string} seconds */
91
+ function secondsOf(iso) {
92
+ const ms = typeof iso === 'string' ? Date.parse(iso) : NaN;
93
+ if (!Number.isFinite(ms)) throw new WalletError('a transfer without a time', 'WALLET_DATA');
94
+ return String(Math.floor(ms / 1000));
95
+ }
96
+
97
+ /** @param {unknown} v */
98
+ const lowerAddress = (v) => (typeof v === 'string' ? v.toLowerCase() : '');
99
+
100
+ /**
101
+ * @param {object} [options]
102
+ * @param {typeof fetch} [options.fetch]
103
+ * @param {number} [options.timeoutMs]
104
+ * @param {(ms: number) => Promise<void>} [options.sleep]
105
+ * @param {number} [options.maxPages] per direction
106
+ * @param {number} [options.maxHiddenBlocks] blocks fetched for transactions the transfers do not show
107
+ * @param {number} [options.computeUnitsPerSecond] spent at most (Alchemy free: 300)
108
+ * @param {() => number} [options.now] milliseconds (tests: a clock that `sleep` moves)
109
+ */
110
+ export function createAlchemyReader({
111
+ fetch: f = fetch,
112
+ timeoutMs,
113
+ sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
114
+ maxPages = 50,
115
+ maxHiddenBlocks = 300,
116
+ computeUnitsPerSecond = 250,
117
+ now = Date.now
118
+ } = {}) {
119
+ // HTTP 429 is waited out below, with the calls refused inside a batch.
120
+ const getJson = createJsonFetcher({ fetch: f, timeoutMs, sleep, retries: 1 });
121
+ const burstUnits = computeUnitsPerSecond * BURST_SECONDS;
122
+
123
+ // The budget as a token bucket kept by time: `due` is when all that was
124
+ // spent is paid back; a call may go while that is at most BURST_SECONDS ahead.
125
+ let due = 0;
126
+ /** @param {number} units */
127
+ async function spend(units) {
128
+ const start = Math.max(due, now());
129
+ due = start + (units / computeUnitsPerSecond) * 1000;
130
+ const wait = due - now() - BURST_SECONDS * 1000;
131
+ if (wait > 0) await sleep(Math.ceil(wait));
132
+ }
133
+ /** Alchemy refused: its bucket is empty, whatever this one thinks. */
134
+ const drained = () => {
135
+ due = Math.max(due, now() + BURST_SECONDS * 1000);
136
+ };
137
+ /** @param {number} round 1… */
138
+ const backoff = (round) =>
139
+ Math.min(1000 * 2 ** (round - 1), 16_000) + Math.floor(Math.random() * 250);
140
+
141
+ /**
142
+ * Alchemy's refusals, in words that carry no key and no address.
143
+ *
144
+ * @param {any} error
145
+ * @param {string} key
146
+ */
147
+ function explain(error, key) {
148
+ if (!(error instanceof WalletError)) return error;
149
+ const scrub = (/** @type {string} */ text) =>
150
+ text
151
+ .split(key)
152
+ .join('…')
153
+ .replace(/https?:\/\/\S+/g, '…')
154
+ .replace(/0x[0-9a-fA-F]{8,}/g, '0x…')
155
+ .slice(0, 100);
156
+ if (error.code === 'WALLET_RATE_LIMIT') {
157
+ return new WalletError(
158
+ 'Alchemy limits requests (compute units per second used up); try again in a minute',
159
+ 'WALLET_ALCHEMY_RATE_LIMIT',
160
+ 429
161
+ );
162
+ }
163
+ if (error.httpStatus === 401) {
164
+ return new WalletError(
165
+ 'Alchemy refused the API key: run `pnpm setup:alchemy` again',
166
+ 'WALLET_ALCHEMY_AUTH'
167
+ );
168
+ }
169
+ if (error.httpStatus === 403) {
170
+ const said = scrub(String(/** @type {any} */ (error.body)?.error?.message ?? ''));
171
+ return new WalletError(
172
+ `Alchemy refused access${said ? ` (${said})` : ''}: is the network enabled for this app in the Alchemy dashboard?`,
173
+ 'WALLET_ALCHEMY_DENIED'
174
+ );
175
+ }
176
+ if (error.code === 'WALLET_ALCHEMY') error.message = scrub(error.message);
177
+ return error;
178
+ }
179
+
180
+ /**
181
+ * @param {any} rpcError
182
+ * @param {string} method
183
+ */
184
+ function rpcFailure(rpcError, method) {
185
+ const code = Number(rpcError?.code);
186
+ const message = String(rpcError?.message ?? '');
187
+ if (code === -32600 && /authenticated|access key/i.test(message)) {
188
+ return new WalletError(
189
+ 'Alchemy refused the API key: run `pnpm setup:alchemy` again',
190
+ 'WALLET_ALCHEMY_AUTH'
191
+ );
192
+ }
193
+ const words = message.replace(/0x[0-9a-fA-F]{8,}/g, '0x…').slice(0, 80);
194
+ return new WalletError(
195
+ `Alchemy refused ${method} (${Number.isFinite(code) ? code : '?'}${words ? `: ${words}` : ''})`,
196
+ 'WALLET_ALCHEMY'
197
+ );
198
+ }
199
+
200
+ /**
201
+ * @param {string} url
202
+ * @param {string} key
203
+ * @param {{ method: string, params: unknown[] }[]} calls
204
+ * @returns {Promise<any[]>} the results, in the order of the calls
205
+ */
206
+ async function batch(url, key, calls) {
207
+ /** @type {any[]} */
208
+ const results = [];
209
+ // Chunks of at most BATCH calls and at most the burst in compute units.
210
+ /** @type {number[][]} indexes into calls */
211
+ const chunks = [];
212
+ let units = Infinity;
213
+ calls.forEach((c, i) => {
214
+ const cost = computeUnitsOf(c.method);
215
+ const last = chunks[chunks.length - 1];
216
+ if (!last || last.length >= BATCH || units + cost > burstUnits) {
217
+ chunks.push([i]);
218
+ units = cost;
219
+ } else {
220
+ last.push(i);
221
+ units += cost;
222
+ }
223
+ });
224
+ for (const chunk of chunks) {
225
+ /** @type {number[]} */
226
+ let pending = chunk;
227
+ for (let round = 0; pending.length; round++) {
228
+ if (round >= LIMIT_ROUNDS)
229
+ throw explain(new WalletError('limited', 'WALLET_RATE_LIMIT'), key);
230
+ if (round > 0) await sleep(backoff(round));
231
+ await spend(pending.reduce((sum, i) => sum + computeUnitsOf(calls[i].method), 0));
232
+ const body = pending.map((i) => ({ jsonrpc: '2.0', id: i + 1, ...calls[i] }));
233
+ let answer;
234
+ try {
235
+ answer = await getJson(url, {
236
+ method: 'POST',
237
+ headers: { 'content-type': 'application/json' },
238
+ body: JSON.stringify(body.length === 1 ? body[0] : body)
239
+ });
240
+ } catch (error) {
241
+ if (/** @type {any} */ (error)?.code === 'WALLET_RATE_LIMIT') {
242
+ drained();
243
+ continue;
244
+ }
245
+ throw explain(error, key);
246
+ }
247
+ const items = Array.isArray(answer) ? answer : [answer];
248
+ if (pending.length > 1 && !Array.isArray(answer)) {
249
+ // A batch refused as a whole answers one error object.
250
+ if (answer?.error?.code === 429) {
251
+ drained();
252
+ continue;
253
+ }
254
+ throw explain(rpcFailure(answer?.error, calls[pending[0]].method), key);
255
+ }
256
+ /** @type {Map<number, any>} */
257
+ const byId = new Map(items.map((item) => [Number(item?.id), item]));
258
+ /** @type {number[]} */
259
+ const refused = [];
260
+ for (const i of pending) {
261
+ const item = byId.get(i + 1);
262
+ if (!item) {
263
+ throw new WalletError(`Alchemy left ${calls[i].method} unanswered`, 'WALLET_ALCHEMY');
264
+ }
265
+ if (item.error?.code === 429) refused.push(i);
266
+ else if (item.error) throw explain(rpcFailure(item.error, calls[i].method), key);
267
+ else results[i] = item.result;
268
+ }
269
+ if (refused.length) drained();
270
+ pending = refused;
271
+ }
272
+ }
273
+ return results;
274
+ }
275
+
276
+ /** @param {string} url @param {string} key @param {string} method @param {unknown[]} params */
277
+ const call = async (url, key, method, params) => (await batch(url, key, [{ method, params }]))[0];
278
+
279
+ /**
280
+ * @param {object} params
281
+ * @param {import('./registry.js').EvmChain} params.chain with `alchemy`
282
+ * @param {string} params.address lower case
283
+ * @param {string} params.key
284
+ * @param {string} params.baseUrl without the key, e.g. https://eth-mainnet.g.alchemy.com/v2
285
+ * @param {() => Promise<any[]>} [params.blockscoutInternal] internal transactions where
286
+ * Alchemy has none (Arbitrum, Optimism)
287
+ */
288
+ async function read({ chain, address, key, baseUrl, blockscoutInternal }) {
289
+ if (!isAlchemyKey(key)) {
290
+ throw new WalletError(
291
+ 'the stored Alchemy key has an unexpected form: run `pnpm setup:alchemy` again',
292
+ 'WALLET_ALCHEMY_AUTH'
293
+ );
294
+ }
295
+ const network = /** @type {import('./registry.js').AlchemyNetwork} */ (chain.alchemy);
296
+ const url = `${baseUrl}/${key}`;
297
+
298
+ const chainId = await call(url, key, 'eth_chainId', []);
299
+ if (typeof chainId !== 'string' || !HEX.test(chainId)) {
300
+ throw new WalletError(
301
+ 'Alchemy does not say which chain it serves',
302
+ 'WALLET_CHAIN_UNVERIFIED'
303
+ );
304
+ }
305
+ if (BigInt(chainId) !== BigInt(chain.chainId)) {
306
+ throw new WalletError(
307
+ `Alchemy serves chain ${BigInt(chainId)}, not ${chain.name} (${chain.chainId})`,
308
+ 'WALLET_WRONG_CHAIN',
309
+ 400
310
+ );
311
+ }
312
+
313
+ // Every transfer from and to the address, each once (to itself: in both lists).
314
+ const categories = ['external', 'erc20', ...(network.internal ? ['internal'] : [])];
315
+ /** @type {Map<string, any>} */
316
+ const transfers = new Map();
317
+ for (const direction of ['fromAddress', 'toAddress']) {
318
+ let pageKey;
319
+ for (let page = 0; ; page++) {
320
+ if (page >= maxPages) {
321
+ throw new WalletError(`more than ${maxPages * 1000} transfers`, 'WALLET_TOO_MANY');
322
+ }
323
+ const result = await call(url, key, 'alchemy_getAssetTransfers', [
324
+ {
325
+ fromBlock: '0x0',
326
+ toBlock: 'latest',
327
+ [direction]: address,
328
+ category: categories,
329
+ withMetadata: true,
330
+ excludeZeroValue: true,
331
+ maxCount: PAGE,
332
+ order: 'asc',
333
+ ...(pageKey ? { pageKey } : {})
334
+ }
335
+ ]);
336
+ if (!Array.isArray(result?.transfers)) {
337
+ throw new WalletError('alchemy_getAssetTransfers without a list', 'WALLET_ALCHEMY');
338
+ }
339
+ for (const t of result.transfers) {
340
+ const hash = lowerAddress(t?.hash);
341
+ if (!/^0x[0-9a-f]{64}$/.test(hash)) {
342
+ throw new WalletError('a transfer without a hash', 'WALLET_DATA');
343
+ }
344
+ const id =
345
+ typeof t.uniqueId === 'string' && t.uniqueId
346
+ ? t.uniqueId
347
+ : `${hash}:${t.category}:${t.from}:${t.to}:${t.rawContract?.value}`;
348
+ transfers.set(id, t);
349
+ }
350
+ pageKey = typeof result.pageKey === 'string' && result.pageKey ? result.pageKey : null;
351
+ if (!pageKey) break;
352
+ }
353
+ }
354
+ const all = [...transfers.values()];
355
+
356
+ // The transactions this address sent, as far as the transfers show them.
357
+ /** @type {Map<string, string>} hash → block time in seconds */
358
+ const timeOf = new Map();
359
+ for (const t of all) timeOf.set(lowerAddress(t.hash), secondsOf(t.metadata?.blockTimestamp));
360
+ const candidates = [
361
+ ...new Set(
362
+ all.filter((t) => lowerAddress(t.from) === address).map((t) => lowerAddress(t.hash))
363
+ )
364
+ ];
365
+ /** @type {Map<string, { tx: any, receipt: any, time: string }>} */
366
+ const sent = new Map();
367
+ const answers = await batch(
368
+ url,
369
+ key,
370
+ candidates.flatMap((hash) => [
371
+ { method: 'eth_getTransactionByHash', params: [hash] },
372
+ { method: 'eth_getTransactionReceipt', params: [hash] }
373
+ ])
374
+ );
375
+ /**
376
+ * Who sent a transaction that moved this address's tokens out, when that
377
+ * was someone else (a token project burning holdings, issue #162).
378
+ *
379
+ * @type {Record<string, string>}
380
+ */
381
+ const senders = {};
382
+ candidates.forEach((hash, i) => {
383
+ const tx = answers[2 * i];
384
+ const receipt = answers[2 * i + 1];
385
+ if (!tx || !receipt) {
386
+ throw new WalletError('Alchemy does not know a transaction it listed', 'WALLET_ALCHEMY');
387
+ }
388
+ if (lowerAddress(tx.from) !== address && /^0x[0-9a-f]{40}$/.test(lowerAddress(tx.from))) {
389
+ senders[hash] = lowerAddress(tx.from);
390
+ }
391
+ if (lowerAddress(tx.from) === address) {
392
+ sent.set(hash, { tx, receipt, time: /** @type {string} */ (timeOf.get(hash)) });
393
+ }
394
+ });
395
+
396
+ await findHidden({ url, key, address, sent });
397
+
398
+ // Value received from someone else's transaction: whether it went through.
399
+ // Alchemy was not seen to list a reverted one, but does not say it never does.
400
+ const received = [
401
+ ...new Set(
402
+ all
403
+ .filter(
404
+ (t) =>
405
+ t.category === 'external' &&
406
+ lowerAddress(t.to) === address &&
407
+ !sent.has(lowerAddress(t.hash))
408
+ )
409
+ .map((t) => lowerAddress(t.hash))
410
+ )
411
+ ];
412
+ const receivedReceipts = await batch(
413
+ url,
414
+ key,
415
+ received.map((hash) => ({ method: 'eth_getTransactionReceipt', params: [hash] }))
416
+ );
417
+ /** @type {Map<string, any>} */
418
+ const receiptOf = new Map();
419
+ received.forEach((hash, i) => {
420
+ if (!receivedReceipts[i]) {
421
+ throw new WalletError(
422
+ 'Alchemy has no receipt for a transaction it listed',
423
+ 'WALLET_ALCHEMY'
424
+ );
425
+ }
426
+ receiptOf.set(hash, receivedReceipts[i]);
427
+ });
428
+
429
+ /**
430
+ * A receipt's outcome. Receipts from before Byzantium (Ethereum block
431
+ * 4 370 000, October 2017) carry no `status`: whether such a
432
+ * transaction went through is unknown here (Blockscout knows it from
433
+ * its traces). Its gas is booked – it was paid either way – its value
434
+ * is not, and the wallet's result counts it (`unknownStatus`).
435
+ *
436
+ * @param {any} receipt
437
+ * @returns {'ok' | 'failed' | 'unknown'}
438
+ */
439
+ const outcome = (receipt) =>
440
+ receipt.status === '0x1' ? 'ok' : receipt.status === '0x0' ? 'failed' : 'unknown';
441
+ let unknownStatus = 0;
442
+
443
+ /** @type {any[]} */
444
+ const normal = [];
445
+ for (const [hash, { tx, receipt, time }] of sent) {
446
+ const state = outcome(receipt);
447
+ if (state === 'unknown') unknownStatus++;
448
+ const ok = state !== 'failed';
449
+ normal.push({
450
+ ...(state === 'unknown' ? { statusUnknown: true } : {}),
451
+ hash,
452
+ blockNumber: dec(receipt.blockNumber),
453
+ timeStamp: time,
454
+ transactionIndex: dec(receipt.transactionIndex),
455
+ from: address,
456
+ to: lowerAddress(tx.to),
457
+ value: dec(tx.value),
458
+ gasUsed: dec(receipt.gasUsed),
459
+ gasPrice: dec(receipt.effectiveGasPrice ?? tx.gasPrice),
460
+ isError: ok ? '0' : '1',
461
+ txreceipt_status: ok ? '1' : '0'
462
+ });
463
+ }
464
+ /** @type {any[]} */
465
+ const internal = [];
466
+ /** @type {any[]} */
467
+ const tokens = [];
468
+ for (const t of all) {
469
+ const hash = lowerAddress(t.hash);
470
+ const base = {
471
+ blockNumber: dec(t.blockNum),
472
+ timeStamp: /** @type {string} */ (timeOf.get(hash)),
473
+ from: lowerAddress(t.from),
474
+ to: lowerAddress(t.to),
475
+ value: dec(t.rawContract?.value)
476
+ };
477
+ if (t.category === 'external') {
478
+ // Sent ones come from the transaction itself, above.
479
+ const state = sent.has(hash) ? null : outcome(receiptOf.get(hash));
480
+ if (state === 'unknown') unknownStatus++;
481
+ if (state === 'ok') {
482
+ normal.push({
483
+ ...base,
484
+ hash,
485
+ gasUsed: '0',
486
+ gasPrice: '0',
487
+ isError: '0',
488
+ txreceipt_status: '1'
489
+ });
490
+ }
491
+ } else if (t.category === 'internal') {
492
+ const trace = /:internal:([0-9A-Za-z_,-]{1,64})$/.exec(String(t.uniqueId ?? ''))?.[1];
493
+ internal.push({ ...base, transactionHash: hash, isError: '0', alchemyTrace: trace ?? '' });
494
+ } else if (t.category === 'erc20') {
495
+ const logIndex = /:logs?:(\d+)$/.exec(String(t.uniqueId ?? ''))?.[1];
496
+ tokens.push({
497
+ ...base,
498
+ hash,
499
+ contractAddress: lowerAddress(t.rawContract?.address),
500
+ // As the token says: only to name it in a swap (evm.js), never to book it.
501
+ tokenSymbol: String(t.asset ?? ''),
502
+ tokenDecimal: /^0x[0-9a-f]+$/i.test(String(t.rawContract?.decimal ?? ''))
503
+ ? String(parseInt(String(t.rawContract?.decimal), 16))
504
+ : '',
505
+ // for the order only: the id is built without it, as from Blockscout
506
+ position: logIndex ?? ''
507
+ });
508
+ }
509
+ }
510
+ if (!network.internal && blockscoutInternal) internal.push(...(await blockscoutInternal()));
511
+
512
+ const contracts = Object.keys(chain.tokens);
513
+ const [native, tokenBalances] = await batch(url, key, [
514
+ { method: 'eth_getBalance', params: [address, 'latest'] },
515
+ { method: 'alchemy_getTokenBalances', params: [address, contracts] }
516
+ ]);
517
+ /** @type {Map<string, bigint>} contract (lower case) or `native` → units */
518
+ const balances = new Map([['native', big(native)]]);
519
+ for (const b of tokenBalances?.tokenBalances ?? []) {
520
+ const contract = lowerAddress(b?.contractAddress);
521
+ if (
522
+ contracts.includes(contract) &&
523
+ typeof b.tokenBalance === 'string' &&
524
+ HEX.test(b.tokenBalance)
525
+ ) {
526
+ balances.set(contract, BigInt(b.tokenBalance));
527
+ }
528
+ }
529
+ return { normal, internal, tokens, balances, unknownStatus, senders };
530
+ }
531
+
532
+ /**
533
+ * The transactions this address sent that no transfer shows: the nonce
534
+ * (eth_getTransactionCount) rises by one for each. A block range in which
535
+ * it rises more than the known transactions explain is cut into parts,
536
+ * the count asked at every cut in one batch, until single blocks are left;
537
+ * those are fetched and their transactions from this address taken.
538
+ *
539
+ * @param {object} params
540
+ * @param {string} params.url
541
+ * @param {string} params.key
542
+ * @param {string} params.address
543
+ * @param {Map<string, { tx: any, receipt: any, time: string }>} params.sent grows
544
+ */
545
+ async function findHidden({ url, key, address, sent }) {
546
+ const head = Number(big(await call(url, key, 'eth_blockNumber', [])));
547
+ const total = Number(
548
+ big(await call(url, key, 'eth_getTransactionCount', [address, `0x${head.toString(16)}`]))
549
+ );
550
+ /** @type {number[]} */
551
+ const known = [...sent.values()]
552
+ .map((s) => Number(big(s.receipt.blockNumber)))
553
+ .filter((b) => b <= head)
554
+ .sort((a, b) => a - b);
555
+ const knownIn = (/** @type {number} */ lo, /** @type {number} */ hi) =>
556
+ known.filter((b) => b > lo && b <= hi).length;
557
+
558
+ /** @type {{ lo: number, hi: number, cLo: number, cHi: number }[]} ranges (lo, hi] */
559
+ let ranges = [{ lo: 0, hi: head, cLo: 0, cHi: total }];
560
+ /** @type {number[]} */
561
+ const blocks = [];
562
+ while (ranges.length) {
563
+ /** @type {typeof ranges} */
564
+ const open = [];
565
+ for (const r of ranges) {
566
+ if (r.cHi - r.cLo <= knownIn(r.lo, r.hi)) continue;
567
+ if (r.hi - r.lo === 1) blocks.push(r.hi);
568
+ else open.push(r);
569
+ }
570
+ if (blocks.length > maxHiddenBlocks) {
571
+ throw new WalletError(
572
+ `more than ${maxHiddenBlocks} blocks with transactions only the nonce shows`,
573
+ 'WALLET_TOO_MANY'
574
+ );
575
+ }
576
+ /** @type {{ range: (typeof ranges)[number], cuts: number[] }[]} */
577
+ const plans = open.map((range) => {
578
+ const step = Math.max(1, Math.ceil((range.hi - range.lo) / SPLIT));
579
+ /** @type {number[]} */
580
+ const cuts = [];
581
+ for (let b = range.lo + step; b < range.hi; b += step) cuts.push(b);
582
+ return { range, cuts };
583
+ });
584
+ const counts = await batch(
585
+ url,
586
+ key,
587
+ plans.flatMap((p) =>
588
+ p.cuts.map((b) => ({
589
+ method: 'eth_getTransactionCount',
590
+ params: [address, `0x${b.toString(16)}`]
591
+ }))
592
+ )
593
+ );
594
+ let k = 0;
595
+ ranges = [];
596
+ for (const { range, cuts } of plans) {
597
+ const points = [
598
+ { b: range.lo, c: range.cLo },
599
+ ...cuts.map((b) => ({ b, c: Number(big(counts[k++])) })),
600
+ { b: range.hi, c: range.cHi }
601
+ ];
602
+ for (let i = 1; i < points.length; i++) {
603
+ ranges.push({
604
+ lo: points[i - 1].b,
605
+ hi: points[i].b,
606
+ cLo: points[i - 1].c,
607
+ cHi: points[i].c
608
+ });
609
+ }
610
+ }
611
+ }
612
+ if (!blocks.length) return;
613
+
614
+ const fetched = await batch(
615
+ url,
616
+ key,
617
+ blocks.map((b) => ({ method: 'eth_getBlockByNumber', params: [`0x${b.toString(16)}`, true] }))
618
+ );
619
+ /** @type {{ tx: any, time: string }[]} */
620
+ const hidden = [];
621
+ for (const block of fetched) {
622
+ if (!Array.isArray(block?.transactions)) {
623
+ throw new WalletError('Alchemy answered a block without transactions', 'WALLET_ALCHEMY');
624
+ }
625
+ const time = String(Number(big(block.timestamp)));
626
+ for (const tx of block.transactions) {
627
+ const hash = lowerAddress(tx?.hash);
628
+ if (lowerAddress(tx?.from) === address && !sent.has(hash)) hidden.push({ tx, time });
629
+ }
630
+ }
631
+ const receipts = await batch(
632
+ url,
633
+ key,
634
+ hidden.map(({ tx }) => ({
635
+ method: 'eth_getTransactionReceipt',
636
+ params: [lowerAddress(tx.hash)]
637
+ }))
638
+ );
639
+ hidden.forEach(({ tx, time }, i) => {
640
+ if (!receipts[i]) {
641
+ throw new WalletError('Alchemy has no receipt for a transaction', 'WALLET_ALCHEMY');
642
+ }
643
+ sent.set(lowerAddress(tx.hash), { tx, receipt: receipts[i], time });
644
+ });
645
+ }
646
+
647
+ return { read };
648
+ }