From 5454aa91b2ff88a64650c997c0726178ea71f3e5 Mon Sep 17 00:00:00 2001 From: Prithpal Sooriya Date: Mon, 26 Oct 2026 20:35:43 +0000 Subject: [PATCH 1/3] perf(assets-controller): add hand-rolled aggregate3 codecs Encode and decode balance-batch aggregate3 calls without the Ethers ABI coder, and keep the Ethers codecs so tests can require the same bytes. Co-authored-by: Cursor --- packages/assets-controller/CHANGELOG.md | 1 + ...026-10-26-hand-rolled-aggregate3-codecs.md | 105 +++++ .../clients/MulticallClient.test.ts | 25 +- .../clients/MulticallClient.ts | 32 +- .../clients/aggregate3Codec.test.ts | 406 ++++++++++++++++++ .../clients/aggregate3Codec.ts | 317 ++++++++++++++ .../evm-rpc-services/clients/index.ts | 2 + 7 files changed, 866 insertions(+), 22 deletions(-) create mode 100644 packages/assets-controller/docs/decisions/2026-10-26-hand-rolled-aggregate3-codecs.md create mode 100644 packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts create mode 100644 packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.ts diff --git a/packages/assets-controller/CHANGELOG.md b/packages/assets-controller/CHANGELOG.md index d14b37da4d8..c5c3eb03be7 100644 --- a/packages/assets-controller/CHANGELOG.md +++ b/packages/assets-controller/CHANGELOG.md @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Fetch token metadata again when stored metadata is missing a field that controller logic or a client reads (`symbol`, `name`, `decimals`, `image`, `aggregators`, or `occurrences`), instead of treating an `image` as complete - **BREAKING:** Remove `DetectionMiddleware`. A balance refresh prices balances on the current response only when they have no stored price, and excludes hidden assets. The price poll still refreshes stored prices for held balances and custom assets, and does not price metadata that has no balance. `TokenDataSource` fetches metadata for state balances that have none and for response balances, and excludes hidden assets ([#10892](https://github.com/MetaMask/core/pull/10892)) - **BREAKING:** Remove `assetsForPriceUpdate` from `getAssets` options. Refresh an explicit asset list with `syncAssetsPrices` instead ([#10892](https://github.com/MetaMask/core/pull/10892)) +- Use hand-rolled Multicall3 `aggregate3` codecs for balance batches, while retaining the Ethers codecs for byte-identical comparison ([#11078](https://github.com/MetaMask/core/pull/11078)) - Bump `@metamask/account-tree-controller` from `^11.0.1` to `^11.1.1` ([#10891](https://github.com/MetaMask/core/pull/10891), [#10925](https://github.com/MetaMask/core/pull/10925)) - Bump `@metamask/assets-controllers` from `^112.1.2` to `^112.1.3` ([#10925](https://github.com/MetaMask/core/pull/10925)) - Bump `@metamask/network-controller` from `^37.1.0` to `^37.1.1` ([#10982](https://github.com/MetaMask/core/pull/10982)) diff --git a/packages/assets-controller/docs/decisions/2026-10-26-hand-rolled-aggregate3-codecs.md b/packages/assets-controller/docs/decisions/2026-10-26-hand-rolled-aggregate3-codecs.md new file mode 100644 index 00000000000..385554808d4 --- /dev/null +++ b/packages/assets-controller/docs/decisions/2026-10-26-hand-rolled-aggregate3-codecs.md @@ -0,0 +1,105 @@ +# Hand-rolled Multicall3 aggregate3 codecs + +- Date: 2026-10-26 +- Status: Accepted +- Package: `@metamask/assets-controller` + +How balance batches encode and decode Multicall3 `aggregate3` without walking +the general Ethers ABI coder on the hot path. + +## What this change is about + +A balance refresh asks many contracts for `balanceOf`, and asks Multicall3 +itself for native `getEthBalance`. Those calls go out as one +`aggregate3((address target, bool allowFailure, bytes callData)[])`. + +The client used to encode that call and decode the return value with +`@ethersproject/abi`. That coder parses an ABI and handles every Solidity +type. This call has one shape, and it runs for every account and chain on +each refresh. On some low-end Android devices, encoding the batch and +decoding the response each took about 4 seconds +([Slack thread](https://consensys.slack.com/archives/C0AKX44EGH4/p1793027613955669?thread_ts=1793027586.285609&cid=C0AKX44EGH4)). + +The hot path now uses a codec that only knows this function. The Ethers +functions stay in the tree so tests can require the two implementations to +return the same bytes. + +## Where the code lives + +| Piece | Role | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `src/data-sources/evm-rpc-services/clients/aggregate3Codec.ts` | Hand-rolled `encodeAggregate3`, `decodeAggregate3Response`, and `decodeUint256`. `MulticallClient` calls these. | +| `MulticallClient.ts` in the same folder | `encodeAggregate3WithEthers`, `decodeAggregate3ResponseWithEthers`, and `decodeUint256WithEthers`. The reference coder. | +| `aggregate3Codec.test.ts` | Readable batches compared with the Ethers codecs, plus inputs Ethers rejects. | + +`balanceOf` and `getEthBalance` call data is still built with the Ethers +interface. That data depends only on the account, and the client caches it. +The hand-rolled codec is the part that runs again for every batch. + +## How the bytes are laid out + +The call data starts with selector `82ad56cb`, then a single dynamic array. + +```text +selector 82ad56cb +word offset of the array, always 0x20 +word number of calls, N +N words offset of each call, from the first of these words +each call, in order + word target, left-padded to 32 bytes + word allowFailure, 0 or 1 + word offset of callData, always 0x60 + word callData length, in bytes + 32-byte-padded bytes callData +``` + +The first call starts at `32 * N` because that is the size of the offset +table. Each following call starts at the previous offset plus the padded +size of the previous body. A body is 128 bytes (address, bool, callData +offset, and the length word) plus `callData` rounded up to 32 bytes. + +An `eth_call` response has no selector. Its first word points at the result +array. That array is a length, then one offset per result, then +`(bool success, bytes returnData)` tuples. `success` is the tuple's first +word. `returnData` is a length prefix plus bytes. A uint256 balance is the +first 32 bytes of that payload, read as a decimal string. Empty or short +payloads decode as `0`, which is what the Ethers `balanceOf` decoder returns +for the same input. + +Addresses follow the Ethers coder as well: a `0x` prefix, hex digits, and at +most 32 bytes. A target that is not 20 bytes is left-padded. Rejecting those +would change calldata that Ethers currently produces, so the parity tests +cover a 39-nibble target and a 41-nibble target on purpose. + +## Measured cost + +On some low-end Android devices, encoding an aggregate3 balance batch and +decoding the response each took about 4 seconds +([Slack thread](https://consensys.slack.com/archives/C0AKX44EGH4/p1793027613955669?thread_ts=1793027586.285609&cid=C0AKX44EGH4)). +That is the device cost to use when judging this path. + +A desktop Hermes 1.0.0 microbenchmark of the hand-rolled helpers is a +different machine. For a 300-call batch, the median of three optimized runs +was 1.125 ms for the full codec path, 0.625 ms to encode, 0.300 ms to decode, +and 0.200 ms to read a uint256. Splitting the body into the helpers in +`aggregate3Codec.ts` left those desktop medians unchanged. +[MetaMask/core#11010](https://github.com/MetaMask/core/pull/11010) compared +the same style of encoder with the Ethers coder on an earlier Hermes build, +where the Ethers coder dominated that bench. + +## What we gain + +- The batch path writes known words and reads them back, for this one ABI + shape, on every call in the batch. +- The output matches the Ethers coder byte for byte, including the address + widths above. The codec tests run the same batches through both + implementations and compare. +- There is no new dependency. The codec is a pure module, and its tests do + not construct a provider or a `MulticallClient`. + +## What we take on + +The layout is now ours to keep correct. A change to the Multicall3 `aggregate3` +ABI would not show up by itself. The Ethers functions are the spec: the codec +tests encode and decode with both and compare. Those Ethers functions stay +until a later change removes them; they are not what `MulticallClient` calls. diff --git a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.test.ts b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.test.ts index 1c01f91228d..54231b245e4 100644 --- a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.test.ts +++ b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.test.ts @@ -11,8 +11,8 @@ import type { Provider, } from '../types/index.js'; import { - decodeAggregate3Response, - encodeAggregate3, + decodeAggregate3ResponseWithEthers, + encodeAggregate3WithEthers, MulticallClient, } from './MulticallClient.js'; @@ -895,7 +895,7 @@ describe('MulticallClient', () => { }); }); -describe('encodeAggregate3', () => { +describe('encodeAggregate3WithEthers', () => { it('should encode a valid aggregate3 call', () => { const calls = [ { @@ -906,7 +906,7 @@ describe('encodeAggregate3', () => { }, ]; - const result = encodeAggregate3(calls); + const result = encodeAggregate3WithEthers(calls); expect(result).toMatch(/^0x82ad56cb/u); // starts with aggregate3 selector expect(typeof result).toBe('string'); @@ -926,14 +926,13 @@ describe('encodeAggregate3', () => { }, ]; - const result = encodeAggregate3(calls); + const result = encodeAggregate3WithEthers(calls); expect(result).toMatch(/^0x82ad56cb/u); expect(typeof result).toBe('string'); }); it('should produce valid ABI-encoded calldata that can be decoded', () => { - // Test with multiple calls to verify encoding is correct const calls = [ { target: '0x1111111111111111111111111111111111111111' as Address, @@ -947,7 +946,7 @@ describe('encodeAggregate3', () => { }, ]; - const result = encodeAggregate3(calls); + const result = encodeAggregate3WithEthers(calls); // Verify selector is correct (aggregate3) expect(result).toMatch(/^0x82ad56cb/u); @@ -973,7 +972,7 @@ describe('encodeAggregate3', () => { expect(decodedCalls[1].callData.toLowerCase()).toBe(calls[1].callData); }); - it('should produce identical calldata to regular Ethers implementation', () => { + it('should match encodeFunctionData for aggregate3', () => { const multicall3Interface = new Interface([ 'function aggregate3((address target, bool allowFailure, bytes callData)[] calls) payable returns ((bool success, bytes returnData)[])', 'function getEthBalance(address addr) view returns (uint256)', @@ -1011,17 +1010,17 @@ describe('encodeAggregate3', () => { calls, ]); - expect(encodeAggregate3(calls)).toBe(expected); + expect(encodeAggregate3WithEthers(calls)).toBe(expected); }); }); -describe('decodeAggregate3Response', () => { +describe('decodeAggregate3ResponseWithEthers', () => { it('should decode response with viem-encoded data', () => { const mockResponse = buildMockAggregate3Response([ { success: true, balance: '1000000000' }, ]); - const result = decodeAggregate3Response(mockResponse, 1); + const result = decodeAggregate3ResponseWithEthers(mockResponse, 1); expect(result).toHaveLength(1); expect(result[0].success).toBe(true); @@ -1036,7 +1035,7 @@ describe('decodeAggregate3Response', () => { { success: true, balance: '300' }, ]); - const result = decodeAggregate3Response(mockResponse, 3); + const result = decodeAggregate3ResponseWithEthers(mockResponse, 3); expect(result).toHaveLength(3); expect(result[0].success).toBe(true); @@ -1049,7 +1048,7 @@ describe('decodeAggregate3Response', () => { { success: true, balance: '100' }, ]); - expect(() => decodeAggregate3Response(mockResponse, 2)).toThrow( + expect(() => decodeAggregate3ResponseWithEthers(mockResponse, 2)).toThrow( 'Expected 2 results, got 1', ); }); diff --git a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.ts b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.ts index d33a3de9e8d..ea68b961f6d 100644 --- a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.ts +++ b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.ts @@ -15,6 +15,12 @@ import type { Provider, } from '../types/index.js'; import { reduceInBatchesSerially } from '../utils/index.js'; +import { + decodeAggregate3Response, + decodeUint256, + encodeAggregate3, +} from './aggregate3Codec.js'; +import type { Aggregate3Call } from './aggregate3Codec.js'; // ============================================================================= // ABI DEFINITIONS @@ -456,7 +462,7 @@ const balanceCallDataCache = createBalanceCallDataCache(); function buildAggregate3BalanceCalls( batch: BalanceOfRequest[], multicallAddress: Hex, -): { target: Address; allowFailure: boolean; callData: Hex }[] { +): Aggregate3Call[] { return batch.map((req) => { const isNative = req.tokenAddress === ZERO_ADDRESS; const target = isNative ? multicallAddress : req.tokenAddress; @@ -471,13 +477,16 @@ function buildAggregate3BalanceCalls( } /** - * Encode a Multicall3 aggregate3 call. + * Encode a Multicall3 aggregate3 call with the Ethers ABI coder. + * + * `MulticallClient` calls `encodeAggregate3` from `aggregate3Codec.ts`. + * This function stays so those tests can compare the two encodings. * * @param calls - Array of calls with target, allowFailure, and callData. * @returns The encoded aggregate3 call data. */ -export function encodeAggregate3( - calls: readonly { target: Address; allowFailure: boolean; callData: Hex }[], +export function encodeAggregate3WithEthers( + calls: readonly Aggregate3Call[], ): Hex { return encodeFunctionData(multicall3Interface, 'aggregate3', [ calls.map((call) => ({ @@ -489,14 +498,16 @@ export function encodeAggregate3( } /** - * Decode the response from aggregate3. - * Returns array of (success, returnData) tuples. + * Decode the response from aggregate3 with the Ethers ABI coder. + * + * `MulticallClient` calls `decodeAggregate3Response` from `aggregate3Codec.ts`. + * This function stays so those tests can compare the two decodings. * * @param data - The raw response data. * @param callCount - Number of calls made (used for validation). * @returns Array of success and return data. */ -export function decodeAggregate3Response( +export function decodeAggregate3ResponseWithEthers( data: Hex, callCount: number, ): { success: boolean; returnData: Hex }[] { @@ -519,12 +530,15 @@ export function decodeAggregate3Response( } /** - * Decode a uint256 balance from return data. + * Decode a uint256 balance with the Ethers ABI coder. + * + * `MulticallClient` calls `decodeUint256` from `aggregate3Codec.ts`. + * This function stays so those tests can compare the two decodings. * * @param data - The hex return data. * @returns The decoded balance as a string. */ -function decodeUint256(data: Hex): string { +export function decodeUint256WithEthers(data: Hex): string { if (data === '0x' || data.length < 66) { // Empty or invalid data; treat as 0 return '0'; diff --git a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts new file mode 100644 index 00000000000..324a95c0fe5 --- /dev/null +++ b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts @@ -0,0 +1,406 @@ +import { defaultAbiCoder, Interface } from '@ethersproject/abi'; +import type { Hex } from '@metamask/utils'; +import { describe, expect, it } from 'vitest'; + +import type { Address } from '../types/index.js'; +import type { Aggregate3Call } from './aggregate3Codec.js'; +import { + decodeAggregate3Response, + decodeUint256, + encodeAggregate3, +} from './aggregate3Codec.js'; +import { + decodeAggregate3ResponseWithEthers, + decodeUint256WithEthers, + encodeAggregate3WithEthers, +} from './MulticallClient.js'; + +const ACCOUNT: Address = '0x1234567890123456789012345678901234567890'; +const USDC: Address = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; +const USDT: Address = '0xdAC17F958D2ee523a2206206994597C13D831ec7'; +const MULTICALL: Address = '0xcA11bde05977b3631167028862bE2a173976CA11'; +const MAX_UINT256 = (2n ** 256n - 1n).toString(); + +/** + * Encode `(bool, bytes)[]` the way an `eth_call` response arrives. + * + * @param results - Success flags and raw return data. + * @returns ABI-encoded aggregate3 return data. + */ +function encodeResults(results: readonly [boolean, Hex][]): Hex { + return defaultAbiCoder.encode( + ['(bool success, bytes returnData)[]'], + [results], + ) as Hex; +} + +describe('encodeAggregate3', () => { + const erc20Interface = new Interface([ + 'function balanceOf(address account) view returns (uint256)', + ]); + const multicallInterface = new Interface([ + 'function getEthBalance(address addr) view returns (uint256)', + ]); + + const encodeCases: { name: string; calls: Aggregate3Call[] }[] = [ + { + name: 'an empty batch', + calls: [], + }, + { + name: 'a USDC balanceOf and a native getEthBalance', + calls: [ + { + target: USDC, + allowFailure: true, + callData: erc20Interface.encodeFunctionData('balanceOf', [ + ACCOUNT, + ]) as Hex, + }, + { + target: MULTICALL, + allowFailure: true, + callData: multicallInterface.encodeFunctionData('getEthBalance', [ + ACCOUNT, + ]) as Hex, + }, + ], + }, + { + name: 'empty, one-byte, 32-byte, and 33-byte call data', + calls: [ + { + target: ACCOUNT, + allowFailure: true, + callData: '0x', + }, + { + target: USDC, + allowFailure: false, + callData: '0xaa', + }, + { + target: USDT, + allowFailure: true, + callData: `0x${'11'.repeat(32)}`, + }, + { + target: MULTICALL, + allowFailure: false, + callData: `0x${'22'.repeat(33)}`, + }, + ], + }, + { + // Ethers left-pads targets that are not 20 bytes. These three widths + // are the ones that padding has to get right. + name: 'targets of 1, 39, and 41 nibbles', + calls: [ + { + target: '0x1', + allowFailure: true, + callData: '0x', + }, + { + target: `0x${'1'.repeat(39)}`, + allowFailure: false, + callData: '0xaa', + }, + { + target: `0x${'2'.repeat(41)}`, + allowFailure: true, + callData: '0xbbbb', + }, + ], + }, + { + name: 'an uppercase target and call data', + calls: [ + { + target: '0xA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48', + allowFailure: true, + callData: '0x70A08231', + }, + ], + }, + ]; + + it.each(encodeCases)( + 'encodes $name byte-identically to Ethers', + ({ calls }) => { + expect(encodeAggregate3(calls)).toBe(encodeAggregate3WithEthers(calls)); + }, + ); + + // Ethers rejects these. The hand-rolled codec has to reject them too. + const invalidEncodeCases: { name: string; calls: Aggregate3Call[] }[] = [ + { + name: 'a non-hex target', + calls: [ + { + target: '0xnothex', + allowFailure: true, + callData: '0x', + }, + ], + }, + { + name: 'call data without a hex prefix', + calls: [ + { + target: ACCOUNT, + allowFailure: true, + callData: '70a08231' as Hex, + }, + ], + }, + { + name: 'odd-length call data', + calls: [ + { + target: ACCOUNT, + allowFailure: true, + callData: '0xabc', + }, + ], + }, + { + name: 'non-hex call data', + calls: [ + { + target: ACCOUNT, + allowFailure: true, + callData: '0xzz', + }, + ], + }, + ]; + + it.each(invalidEncodeCases)('rejects $name, as Ethers does', ({ calls }) => { + expect(() => encodeAggregate3WithEthers(calls)).toThrow(Error); + expect(() => encodeAggregate3(calls)).toThrow(Error); + }); +}); + +describe('decodeAggregate3Response', () => { + const uint256 = (value: string): Hex => + defaultAbiCoder.encode(['uint256'], [value]) as Hex; + + const decodeCases: { + name: string; + results: readonly [boolean, Hex][]; + }[] = [ + { + name: 'no results', + results: [], + }, + { + name: 'one successful balance', + results: [[true, uint256('1000000000')]], + }, + { + name: 'a failed call between two balances', + results: [ + [true, uint256('100')], + [false, '0x'], + [true, uint256('300')], + ], + }, + { + name: 'one byte of return data', + results: [[true, '0xaa']], + }, + { + name: '33 bytes of return data', + results: [[false, `0x${'ab'.repeat(33)}`]], + }, + ]; + + it.each(decodeCases)('decodes $name identically to Ethers', ({ results }) => { + const response = encodeResults(results); + expect(decodeAggregate3Response(response, results.length)).toStrictEqual( + decodeAggregate3ResponseWithEthers(response, results.length), + ); + }); + + // Ethers rejects these. The hand-rolled codec has to reject them too. + const invalidDecodeCases: { + name: string; + response: Hex; + resultCount: number; + }[] = [ + { + name: 'a response without a hex prefix', + response: '1234' as Hex, + resultCount: 0, + }, + { + name: 'a non-hex word', + response: `0x${'z'.repeat(64)}`, + resultCount: 0, + }, + { + name: 'a truncated response', + response: `0x${'00'.repeat(16)}`, + resultCount: 1, + }, + { + name: 'a result count that does not match', + response: encodeResults([[true, uint256('100')]]), + resultCount: 2, + }, + ]; + + it.each(invalidDecodeCases)( + 'rejects $name, as Ethers does', + ({ response, resultCount }) => { + expect(() => + decodeAggregate3ResponseWithEthers(response, resultCount), + ).toThrow(Error); + expect(() => decodeAggregate3Response(response, resultCount)).toThrow( + Error, + ); + }, + ); +}); + +describe('decodeUint256', () => { + const uint256Cases = [ + { name: 'zero', data: `0x${'0'.repeat(64)}`, expected: '0' }, + { name: 'one', data: `0x${'0'.repeat(63)}1`, expected: '1' }, + { + name: 'max uint256', + data: `0x${'f'.repeat(64)}`, + expected: MAX_UINT256, + }, + { name: 'empty data', data: '0x', expected: '0' }, + { name: 'a short word', data: '0x1234', expected: '0' }, + ] as const; + + it.each(uint256Cases)( + 'decodes $name as $expected, matching Ethers', + ({ data, expected }) => { + const decoded = decodeUint256(data); + expect(decoded).toBe(expected); + expect(decoded).toBe(decodeUint256WithEthers(data)); + }, + ); +}); + +/** + * Random integer from 0 up to, but not including, `max`. + * + * @param max - Exclusive upper bound. + * @returns The random integer. + */ +function randomInt(max: number): number { + return Math.floor(Math.random() * max); +} + +/** + * `byteCount` random bytes as `0x`-prefixed hex. + * + * @param byteCount - How many bytes to return. + * @returns Lowercase hex. + */ +function randomBytesHex(byteCount: number): Hex { + const bytes = new Uint8Array(byteCount); + crypto.getRandomValues(bytes); + return `0x${Buffer.from(bytes).toString('hex')}`; +} + +/** + * Keep the `0x` prefix and randomly upper-case the remaining digits. + * + * @param value - A `0x`-prefixed hex string. + * @returns The same hex with mixed case. + */ +function randomHexCase(value: Hex): Hex { + let mixed = '0x'; + for (const digit of value.slice(2)) { + mixed += Math.random() < 0.5 ? digit : digit.toUpperCase(); + } + return mixed as Hex; +} + +/** + * 1–32 byte address. Half the time, drop one nibble so the length is odd. + * + * @returns A target both encoders accept. Ethers rejects an empty address. + */ +function randomTarget(): Address { + const target = randomBytesHex(randomInt(32) + 1); + if (Math.random() < 0.5) { + return target.slice(0, -1) as Address; + } + return target; +} + +/** + * Random aggregate3 calls that both encoders accept. + * + * @returns Up to four calls. Call data is 0–64 bytes. + */ +function randomAggregate3Calls(): Aggregate3Call[] { + const calls: Aggregate3Call[] = []; + const callCount = randomInt(5); + for (let index = 0; index < callCount; index++) { + calls.push({ + target: randomHexCase(randomTarget()), + allowFailure: Math.random() < 0.5, + callData: randomHexCase(randomBytesHex(randomInt(65))), + }); + } + return calls; +} + +/** + * Random `(success, returnData)` rows for an aggregate3 response. + * + * @returns Up to four rows. Return data is 0–64 bytes. + */ +function randomAggregate3Results(): [boolean, Hex][] { + const results: [boolean, Hex][] = []; + const resultCount = randomInt(5); + for (let index = 0; index < resultCount; index++) { + results.push([ + Math.random() < 0.5, + randomHexCase(randomBytesHex(randomInt(65))), + ]); + } + return results; +} + +/** + * Random uint256 return data: empty, shorter than one word, or one word. + * + * @returns Hex both uint256 decoders accept. + */ +function randomUint256Data(): Hex { + const kind = randomInt(3); + if (kind === 0) { + return '0x'; + } + if (kind === 1) { + return randomHexCase(randomBytesHex(randomInt(32))); + } + return randomHexCase(randomBytesHex(32)); +} + +describe('random comparison with Ethers', () => { + it('encodes and decodes 100 random inputs identically to Ethers', () => { + for (let iteration = 0; iteration < 100; iteration++) { + const calls = randomAggregate3Calls(); + expect(encodeAggregate3(calls)).toBe(encodeAggregate3WithEthers(calls)); + + const results = randomAggregate3Results(); + const response = randomHexCase(encodeResults(results)); + expect(decodeAggregate3Response(response, results.length)).toStrictEqual( + decodeAggregate3ResponseWithEthers(response, results.length), + ); + + const word = randomUint256Data(); + expect(decodeUint256(word)).toBe(decodeUint256WithEthers(word)); + } + }); +}); diff --git a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.ts b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.ts new file mode 100644 index 00000000000..f1003959d10 --- /dev/null +++ b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.ts @@ -0,0 +1,317 @@ +import type { Hex } from '@metamask/utils'; + +import type { Address } from '../types/index.js'; + +// Hand-rolled Multicall3 `aggregate3` codecs. +// +// Balance refreshes pack many `balanceOf` and `getEthBalance` calls into one +// `aggregate3`. This module writes and reads that fixed ABI shape directly. +// `MulticallClient` still has the Ethers codecs (`encodeAggregate3WithEthers`, +// `decodeAggregate3ResponseWithEthers`, `decodeUint256WithEthers`) so tests +// can require the same bytes. +// +// Why this is split out, and what it costs, is recorded in +// `packages/assets-controller/docs/decisions/2026-10-26-hand-rolled-aggregate3-codecs.md`. + +/** + * One Multicall3 `aggregate3` call. + * + * `target` is the contract to call. `allowFailure` lets that call revert + * without failing the batch. `callData` is the ABI-encoded call. + */ +export type Aggregate3Call = { + target: Address; + allowFailure: boolean; + callData: Hex; +}; + +/** + * One encoded `(address, bool, bytes)` tuple, before it is placed in the + * array. `bodyParts` are 32-byte hex words with no `0x` prefix. `byteLength` + * is the padded size of that body and is what the next call's offset adds. + */ +type EncodedAggregate3Call = { + bodyParts: string[]; + byteLength: number; +}; + +/** `aggregate3((address,bool,bytes)[])` selector, without a `0x` prefix. */ +const AGGREGATE3_SELECTOR = '82ad56cb'; + +/** + * 32-byte words written as 64 hex characters, with no `0x` prefix. + * The encoder concatenates them after the selector. + * + * - `WORD_ARRAY_OFFSET` is `0x20`: the calls array begins at the next word. + * - `WORD_CALLDATA_OFFSET` is `0x60`: `callData` begins three words into a tuple. + * - `WORD_ZERO` / `WORD_ONE` are the ABI bool values. + */ +const WORD_ARRAY_OFFSET = `0${'0'.repeat(61)}20`; +const WORD_CALLDATA_OFFSET = `0${'0'.repeat(61)}60`; +const WORD_ZERO = '0'.repeat(64); +const WORD_ONE = `0${'0'.repeat(62)}1`; +const LOWERCASE_HEX_RE = /^[0-9a-f]*$/u; + +/** + * Write a byte count as a 32-byte hex word. + * + * @param value - A byte length or an element count. + * @returns 64 lowercase hex characters, with no `0x` prefix. + */ +function encodeWord(value: number): string { + return value.toString(16).padStart(64, '0'); +} + +/** + * Check a call and return the hex bodies the encoder pads. + * + * Addresses follow the Ethers coder: a `0x` prefix, hex digits, and at most + * 32 bytes. Lengths other than 20 bytes are left-padded, which is what keeps + * short and long targets byte-identical to Ethers. Call data must be + * even-length hex. + * + * @param call - One aggregate3 call. + * @returns Lowercase hex bodies with the `0x` prefix removed. + * @throws When `target` or `callData` is not hex the Ethers coder would accept. + */ +function normalizeAggregate3Call(call: Aggregate3Call): { + targetHex: string; + dataHex: string; +} { + const { target, callData } = call; + if (!target.startsWith('0x')) { + throw new Error(`invalid address value: ${target}`); + } + const targetHex = target.slice(2).toLowerCase(); + if (!LOWERCASE_HEX_RE.test(targetHex) || targetHex.length > 64) { + throw new Error(`invalid address value: ${target}`); + } + + if (!callData.startsWith('0x')) { + throw new Error(`invalid bytes value: ${callData}`); + } + const dataHex = callData.slice(2).toLowerCase(); + if (dataHex.length % 2 !== 0 || !LOWERCASE_HEX_RE.test(dataHex)) { + throw new Error(`invalid bytes value: ${callData}`); + } + return { targetHex, dataHex }; +} + +/** + * Encode one `(address, bool, bytes)` tuple. + * + * The body is five pieces, concatenated: + * + * - `target`, left-padded to 32 bytes + * - `allowFailure` as a 0 or 1 word + * - the offset of `callData`, always `0x60` (three words into the tuple) + * - the `callData` length in bytes + * - `callData`, right-padded with zeros to a multiple of 32 bytes + * + * @param call - One aggregate3 call. + * @returns The tuple body and its padded length in bytes. + */ +function encodeAggregate3Call(call: Aggregate3Call): EncodedAggregate3Call { + const { targetHex, dataHex } = normalizeAggregate3Call(call); + const paddedData = dataHex.padEnd( + dataHex.length + ((64 - (dataHex.length % 64)) % 64), + '0', + ); + + // Three static words (96 bytes) plus the 32-byte length prefix. + return { + bodyParts: [ + targetHex.padStart(64, '0'), + call.allowFailure ? WORD_ONE : WORD_ZERO, + WORD_CALLDATA_OFFSET, + encodeWord(dataHex.length / 2), + paddedData, + ], + byteLength: 128 + paddedData.length / 2, + }; +} + +/** + * Build the array head and the concatenated tuple bodies. + * + * Each head word is a byte offset measured from the first head word. The + * first call therefore starts at `32 * calls.length`, the size of the head + * itself, and every later call starts at the previous offset plus that + * call's padded body length. + * + * @param calls - Aggregate3 call descriptors. + * @returns Hex words for the head and the body, with no `0x` prefixes. + */ +function getAggregate3Parts(calls: readonly Aggregate3Call[]): { + headParts: string[]; + bodyParts: string[]; +} { + const parts = calls.reduce( + (accumulator, call) => { + const encodedCall = encodeAggregate3Call(call); + accumulator.headParts.push(encodeWord(accumulator.nextTupleOffset)); + accumulator.bodyParts.push(...encodedCall.bodyParts); + accumulator.nextTupleOffset += encodedCall.byteLength; + return accumulator; + }, + { + headParts: [] as string[], + bodyParts: [] as string[], + nextTupleOffset: calls.length * 32, + }, + ); + return parts; +} + +/** + * Encode `aggregate3((address,bool,bytes)[])`. + * + * The bytes are the 4-byte selector `82ad56cb`, then one ABI argument: + * + * 1. A word holding the offset of the calls array, always `0x20`. + * 2. A word holding the number of calls. + * 3. One offset word per call. See `getAggregate3Parts`. + * 4. The call bodies, in order. See `encodeAggregate3Call`. + * + * @param calls - Aggregate3 call descriptors. + * @returns Call data that matches `encodeAggregate3WithEthers` for the same input. + * @throws When a target or call data value is not hex the Ethers coder would accept. + */ +export function encodeAggregate3(calls: readonly Aggregate3Call[]): Hex { + const { headParts, bodyParts } = getAggregate3Parts(calls); + + return [ + `0x${AGGREGATE3_SELECTOR}`, + WORD_ARRAY_OFFSET, + encodeWord(calls.length), + ...headParts, + ...bodyParts, + ].join('') as Hex; +} + +/** + * Read one 32-byte word from an aggregate3 response body. + * + * Offsets and lengths in this response are byte counts. The uint256 payload + * inside `returnData` is decoded separately by `decodeUint256`. + * + * @param body - Response hex with the `0x` prefix removed. + * @param charIndex - Index of the first hex character of the word. + * @returns The word as an integer. + * @throws When the word is missing or is not hex. + */ +function readResponseWord(body: string, charIndex: number): number { + if (charIndex < 0 || charIndex + 64 > body.length) { + throw new Error('aggregate3 response data length out-of-bounds'); + } + const value = parseInt(body.slice(charIndex, charIndex + 64), 16); + if (!Number.isFinite(value)) { + throw new Error('aggregate3 response contains a non-hex word'); + } + return value; +} + +/** + * Locate the array head of an aggregate3 return value. + * + * `eth_call` return data has no function selector. Word 0 is the byte offset + * of the result array. At that offset sits the length word, then one offset + * word per result. `headStart` is the hex index of the first of those + * offset words. + * + * @param body - Response hex with the `0x` prefix removed. + * @param callCount - How many results the caller expects. + * @returns The head position and the length stored in the response. + * @throws When the stored length is not `callCount`. + */ +function getAggregate3ResponseHead( + body: string, + callCount: number, +): { headStart: number; resultCount: number } { + const headStart = readResponseWord(body, 0) * 2 + 64; + const resultCount = readResponseWord(body, headStart - 64); + if (resultCount !== callCount) { + throw new Error(`Expected ${callCount} results, got ${resultCount}`); + } + return { headStart, resultCount }; +} + +/** + * Decode one `(bool success, bytes returnData)` result. + * + * The tuple starts at the head plus that result's offset. Its first word is + * `success` (`0` or `1`). Its second word is the offset of `returnData`, + * measured from the start of the tuple. The payload at that offset is a + * length word followed by the raw bytes, which this returns without padding. + * + * @param body - Response hex with the `0x` prefix removed. + * @param headStart - Hex index of the first result-offset word. + * @param resultIndex - Index of the result to decode. + * @returns The success flag and the unpadded return data. + * @throws When the return data runs past the end of `body`. + */ +function decodeAggregate3Result( + body: string, + headStart: number, + resultIndex: number, +): { success: boolean; returnData: Hex } { + const tupleStart = + headStart + readResponseWord(body, headStart + resultIndex * 64) * 2; + const returnDataStart = + tupleStart + readResponseWord(body, tupleStart + 64) * 2; + const returnDataBytes = readResponseWord(body, returnDataStart); + const dataStart = returnDataStart + 64; + if (dataStart + returnDataBytes * 2 > body.length) { + throw new Error('aggregate3 response data length out-of-bounds'); + } + return { + success: readResponseWord(body, tupleStart) !== 0, + returnData: `0x${body + .slice(dataStart, dataStart + returnDataBytes * 2) + .toLowerCase()}`, + }; +} + +/** + * Decode an `aggregate3` return value. + * + * The outer shape is one dynamic array of `(bool success, bytes returnData)` + * tuples. `callCount` is checked against the length word so a short response + * cannot be paired with the wrong batch. + * + * @param data - The raw `eth_call` return data. + * @param callCount - The expected result count. + * @returns One decoded result per call, in call order. + * @throws When `data` is not hex, a word is out of range, or the length word + * does not equal `callCount`. + */ +export function decodeAggregate3Response( + data: Hex, + callCount: number, +): { success: boolean; returnData: Hex }[] { + if (!data.startsWith('0x')) { + throw new Error(`invalid response data value: ${data}`); + } + const body = data.slice(2); + const { headStart, resultCount } = getAggregate3ResponseHead(body, callCount); + return Array.from({ length: resultCount }, (_, resultIndex) => + decodeAggregate3Result(body, headStart, resultIndex), + ); +} + +/** + * Read a uint256 from the first ABI word of return data. + * + * `balanceOf` and `getEthBalance` each return a single 32-byte word. Empty + * data and anything shorter than one word decode as `'0'`, matching + * `decodeUint256WithEthers`. + * + * @param data - Hex return data. + * @returns The integer as a decimal string. + */ +export function decodeUint256(data: Hex): string { + if (data === '0x' || data.length < 66) { + return '0'; + } + return BigInt(data.slice(0, 66)).toString(); +} diff --git a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/index.ts b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/index.ts index 566f9aa961f..a556f2f21c3 100644 --- a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/index.ts +++ b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/index.ts @@ -1,6 +1,8 @@ export { decodeAggregate3Response, encodeAggregate3, +} from './aggregate3Codec.js'; +export { MulticallClient, type MulticallClientConfig, } from './MulticallClient.js'; From bc4dea21fefbbcba00e953c5f331d3ebe6b21dd3 Mon Sep 17 00:00:00 2001 From: Prithpal Sooriya Date: Wed, 28 Oct 2026 14:37:07 +0000 Subject: [PATCH 2/3] test(assets-controller): compare a 300-call aggregate3 batch with Ethers The production batch cap is 300, and the random parity test only builds four calls. Co-authored-by: Cursor --- .../clients/aggregate3Codec.test.ts | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts index 324a95c0fe5..a3f706d39bc 100644 --- a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts +++ b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts @@ -404,3 +404,50 @@ describe('random comparison with Ethers', () => { } }); }); + +describe('production batch cap', () => { + // MulticallClient batches at most 300 calls. These widths sit on the + // 32-byte padding boundaries the offset table has to accumulate. + const callDataByWidth: Hex[] = [ + '0x', + '0xaa', + `0x${'11'.repeat(32)}`, + `0x${'22'.repeat(33)}`, + `0x${'33'.repeat(36)}`, + ]; + const returnDataByWidth: Hex[] = [ + '0x', + '0xaa', + `0x${'ab'.repeat(32)}`, + `0x${'cd'.repeat(33)}`, + ]; + const targets = [ACCOUNT, USDC, USDT, MULTICALL]; + + it('encodes 300 calls byte-identically to Ethers', () => { + const calls: Aggregate3Call[] = []; + for (let index = 0; index < 300; index++) { + calls.push({ + target: targets[index % targets.length], + allowFailure: index % 2 === 0, + callData: callDataByWidth[index % callDataByWidth.length], + }); + } + + expect(encodeAggregate3(calls)).toBe(encodeAggregate3WithEthers(calls)); + }); + + it('decodes 300 results identically to Ethers', () => { + const results: [boolean, Hex][] = []; + for (let index = 0; index < 300; index++) { + results.push([ + index % 2 === 0, + returnDataByWidth[index % returnDataByWidth.length], + ]); + } + const response = encodeResults(results); + + expect(decodeAggregate3Response(response, results.length)).toStrictEqual( + decodeAggregate3ResponseWithEthers(response, results.length), + ); + }); +}); From 08db40af8696487329cbd62cf7f126df172c7c49 Mon Sep 17 00:00:00 2001 From: Prithpal Sooriya Date: Wed, 28 Oct 2026 15:27:45 +0000 Subject: [PATCH 3/3] fix(assets-controller): keep the codec changelog in Unreleased Main released 20.0.0, so the aggregate3 entry has to stay above that version. The codec tests now only compare their output with Ethers. Co-authored-by: Cursor --- packages/assets-controller/CHANGELOG.md | 5 +- .../clients/aggregate3Codec.test.ts | 503 +++++------------- 2 files changed, 126 insertions(+), 382 deletions(-) diff --git a/packages/assets-controller/CHANGELOG.md b/packages/assets-controller/CHANGELOG.md index 0c2ee9e427e..f2856c6bb1d 100644 --- a/packages/assets-controller/CHANGELOG.md +++ b/packages/assets-controller/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- Use hand-rolled Multicall3 `aggregate3` codecs for balance batches, while retaining the Ethers codecs for byte-identical comparison ([#11078](https://github.com/MetaMask/core/pull/11078)) + ## [20.0.1] ### Changed @@ -27,7 +31,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Fetch token metadata again when stored metadata is missing a field that controller logic or a client reads (`symbol`, `name`, `decimals`, `image`, `aggregators`, or `occurrences`), instead of treating an `image` as complete - **BREAKING:** Remove `DetectionMiddleware`. A balance refresh prices balances on the current response only when they have no stored price, and excludes hidden assets. The price poll still refreshes stored prices for held balances and custom assets, and does not price metadata that has no balance. `TokenDataSource` fetches metadata for state balances that have none and for response balances, and excludes hidden assets ([#10892](https://github.com/MetaMask/core/pull/10892)) - **BREAKING:** Remove `assetsForPriceUpdate` from `getAssets` options. Refresh an explicit asset list with `syncAssetsPrices` instead ([#10892](https://github.com/MetaMask/core/pull/10892)) -- Use hand-rolled Multicall3 `aggregate3` codecs for balance batches, while retaining the Ethers codecs for byte-identical comparison ([#11078](https://github.com/MetaMask/core/pull/11078)) - Bump `@metamask/account-tree-controller` from `^11.0.1` to `^11.2.0` ([#10891](https://github.com/MetaMask/core/pull/10891), [#10925](https://github.com/MetaMask/core/pull/10925), [#11092](https://github.com/MetaMask/core/pull/11092)) - Bump `@metamask/assets-controllers` from `^112.1.2` to `^112.2.0` ([#10925](https://github.com/MetaMask/core/pull/10925), [#11092](https://github.com/MetaMask/core/pull/11092)) - Bump `@metamask/network-controller` from `^37.1.0` to `^37.1.1` ([#10982](https://github.com/MetaMask/core/pull/10982)) diff --git a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts index a3f706d39bc..97d49e1723b 100644 --- a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts +++ b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codec.test.ts @@ -1,4 +1,4 @@ -import { defaultAbiCoder, Interface } from '@ethersproject/abi'; +import { defaultAbiCoder } from '@ethersproject/abi'; import type { Hex } from '@metamask/utils'; import { describe, expect, it } from 'vitest'; @@ -15,380 +15,126 @@ import { encodeAggregate3WithEthers, } from './MulticallClient.js'; -const ACCOUNT: Address = '0x1234567890123456789012345678901234567890'; -const USDC: Address = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; -const USDT: Address = '0xdAC17F958D2ee523a2206206994597C13D831ec7'; -const MULTICALL: Address = '0xcA11bde05977b3631167028862bE2a173976CA11'; -const MAX_UINT256 = (2n ** 256n - 1n).toString(); - -/** - * Encode `(bool, bytes)[]` the way an `eth_call` response arrives. - * - * @param results - Success flags and raw return data. - * @returns ABI-encoded aggregate3 return data. - */ -function encodeResults(results: readonly [boolean, Hex][]): Hex { - return defaultAbiCoder.encode( - ['(bool success, bytes returnData)[]'], - [results], - ) as Hex; -} - -describe('encodeAggregate3', () => { - const erc20Interface = new Interface([ - 'function balanceOf(address account) view returns (uint256)', - ]); - const multicallInterface = new Interface([ - 'function getEthBalance(address addr) view returns (uint256)', - ]); - - const encodeCases: { name: string; calls: Aggregate3Call[] }[] = [ - { - name: 'an empty batch', - calls: [], - }, - { - name: 'a USDC balanceOf and a native getEthBalance', - calls: [ - { - target: USDC, - allowFailure: true, - callData: erc20Interface.encodeFunctionData('balanceOf', [ - ACCOUNT, - ]) as Hex, - }, - { - target: MULTICALL, - allowFailure: true, - callData: multicallInterface.encodeFunctionData('getEthBalance', [ - ACCOUNT, - ]) as Hex, - }, - ], - }, - { - name: 'empty, one-byte, 32-byte, and 33-byte call data', - calls: [ - { - target: ACCOUNT, - allowFailure: true, - callData: '0x', - }, - { - target: USDC, - allowFailure: false, - callData: '0xaa', - }, - { - target: USDT, - allowFailure: true, - callData: `0x${'11'.repeat(32)}`, - }, - { - target: MULTICALL, - allowFailure: false, - callData: `0x${'22'.repeat(33)}`, - }, - ], - }, - { - // Ethers left-pads targets that are not 20 bytes. These three widths - // are the ones that padding has to get right. - name: 'targets of 1, 39, and 41 nibbles', - calls: [ - { - target: '0x1', - allowFailure: true, - callData: '0x', - }, - { - target: `0x${'1'.repeat(39)}`, - allowFailure: false, - callData: '0xaa', - }, - { - target: `0x${'2'.repeat(41)}`, - allowFailure: true, - callData: '0xbbbb', - }, - ], - }, - { - name: 'an uppercase target and call data', - calls: [ - { - target: '0xA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48', - allowFailure: true, - callData: '0x70A08231', - }, - ], - }, - ]; - - it.each(encodeCases)( - 'encodes $name byte-identically to Ethers', - ({ calls }) => { - expect(encodeAggregate3(calls)).toBe(encodeAggregate3WithEthers(calls)); - }, - ); - - // Ethers rejects these. The hand-rolled codec has to reject them too. - const invalidEncodeCases: { name: string; calls: Aggregate3Call[] }[] = [ - { - name: 'a non-hex target', - calls: [ - { - target: '0xnothex', - allowFailure: true, - callData: '0x', - }, - ], - }, - { - name: 'call data without a hex prefix', - calls: [ - { - target: ACCOUNT, - allowFailure: true, - callData: '70a08231' as Hex, - }, - ], - }, - { - name: 'odd-length call data', - calls: [ - { - target: ACCOUNT, - allowFailure: true, - callData: '0xabc', - }, - ], - }, - { - name: 'non-hex call data', - calls: [ - { - target: ACCOUNT, - allowFailure: true, - callData: '0xzz', - }, - ], - }, - ]; - - it.each(invalidEncodeCases)('rejects $name, as Ethers does', ({ calls }) => { - expect(() => encodeAggregate3WithEthers(calls)).toThrow(Error); - expect(() => encodeAggregate3(calls)).toThrow(Error); - }); -}); - -describe('decodeAggregate3Response', () => { - const uint256 = (value: string): Hex => - defaultAbiCoder.encode(['uint256'], [value]) as Hex; - - const decodeCases: { - name: string; - results: readonly [boolean, Hex][]; - }[] = [ - { - name: 'no results', - results: [], - }, - { - name: 'one successful balance', - results: [[true, uint256('1000000000')]], - }, - { - name: 'a failed call between two balances', - results: [ - [true, uint256('100')], - [false, '0x'], - [true, uint256('300')], - ], - }, - { - name: 'one byte of return data', - results: [[true, '0xaa']], - }, - { - name: '33 bytes of return data', - results: [[false, `0x${'ab'.repeat(33)}`]], - }, - ]; - - it.each(decodeCases)('decodes $name identically to Ethers', ({ results }) => { - const response = encodeResults(results); - expect(decodeAggregate3Response(response, results.length)).toStrictEqual( - decodeAggregate3ResponseWithEthers(response, results.length), - ); - }); - - // Ethers rejects these. The hand-rolled codec has to reject them too. - const invalidDecodeCases: { - name: string; - response: Hex; - resultCount: number; - }[] = [ - { - name: 'a response without a hex prefix', - response: '1234' as Hex, - resultCount: 0, - }, - { - name: 'a non-hex word', - response: `0x${'z'.repeat(64)}`, - resultCount: 0, - }, - { - name: 'a truncated response', - response: `0x${'00'.repeat(16)}`, - resultCount: 1, - }, - { - name: 'a result count that does not match', - response: encodeResults([[true, uint256('100')]]), - resultCount: 2, - }, - ]; - - it.each(invalidDecodeCases)( - 'rejects $name, as Ethers does', - ({ response, resultCount }) => { - expect(() => - decodeAggregate3ResponseWithEthers(response, resultCount), - ).toThrow(Error); - expect(() => decodeAggregate3Response(response, resultCount)).toThrow( - Error, - ); - }, - ); -}); - -describe('decodeUint256', () => { - const uint256Cases = [ - { name: 'zero', data: `0x${'0'.repeat(64)}`, expected: '0' }, - { name: 'one', data: `0x${'0'.repeat(63)}1`, expected: '1' }, - { - name: 'max uint256', - data: `0x${'f'.repeat(64)}`, - expected: MAX_UINT256, - }, - { name: 'empty data', data: '0x', expected: '0' }, - { name: 'a short word', data: '0x1234', expected: '0' }, - ] as const; - - it.each(uint256Cases)( - 'decodes $name as $expected, matching Ethers', - ({ data, expected }) => { - const decoded = decodeUint256(data); - expect(decoded).toBe(expected); - expect(decoded).toBe(decodeUint256WithEthers(data)); - }, - ); -}); - -/** - * Random integer from 0 up to, but not including, `max`. - * - * @param max - Exclusive upper bound. - * @returns The random integer. - */ -function randomInt(max: number): number { - return Math.floor(Math.random() * max); -} +describe('aggregate3 codec', () => { + const ACCOUNT: Address = '0x1234567890123456789012345678901234567890'; + const USDC: Address = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; + const USDT: Address = '0xdAC17F958D2ee523a2206206994597C13D831ec7'; + const MULTICALL: Address = '0xcA11bde05977b3631167028862bE2a173976CA11'; + + /** + * Encode `(bool, bytes)[]` the way an `eth_call` response arrives. + * + * @param results - Success flags and raw return data. + * @returns ABI-encoded aggregate3 return data. + */ + function encodeResults(results: readonly [boolean, Hex][]): Hex { + return defaultAbiCoder.encode( + ['(bool success, bytes returnData)[]'], + [results], + ) as Hex; + } -/** - * `byteCount` random bytes as `0x`-prefixed hex. - * - * @param byteCount - How many bytes to return. - * @returns Lowercase hex. - */ -function randomBytesHex(byteCount: number): Hex { - const bytes = new Uint8Array(byteCount); - crypto.getRandomValues(bytes); - return `0x${Buffer.from(bytes).toString('hex')}`; -} + /** + * Random integer from 0 up to, but not including, `max`. + * + * @param max - Exclusive upper bound. + * @returns The random integer. + */ + function randomInt(max: number): number { + return Math.floor(Math.random() * max); + } -/** - * Keep the `0x` prefix and randomly upper-case the remaining digits. - * - * @param value - A `0x`-prefixed hex string. - * @returns The same hex with mixed case. - */ -function randomHexCase(value: Hex): Hex { - let mixed = '0x'; - for (const digit of value.slice(2)) { - mixed += Math.random() < 0.5 ? digit : digit.toUpperCase(); + /** + * `byteCount` random bytes as `0x`-prefixed hex. + * + * @param byteCount - How many bytes to return. + * @returns Lowercase hex. + */ + function randomBytesHex(byteCount: number): Hex { + const bytes = new Uint8Array(byteCount); + crypto.getRandomValues(bytes); + return `0x${Buffer.from(bytes).toString('hex')}`; } - return mixed as Hex; -} -/** - * 1–32 byte address. Half the time, drop one nibble so the length is odd. - * - * @returns A target both encoders accept. Ethers rejects an empty address. - */ -function randomTarget(): Address { - const target = randomBytesHex(randomInt(32) + 1); - if (Math.random() < 0.5) { - return target.slice(0, -1) as Address; + /** + * Keep the `0x` prefix and randomly upper-case the remaining digits. + * + * @param value - A `0x`-prefixed hex string. + * @returns The same hex with mixed case. + */ + function randomHexCase(value: Hex): Hex { + let mixed = '0x'; + for (const digit of value.slice(2)) { + mixed += Math.random() < 0.5 ? digit : digit.toUpperCase(); + } + return mixed as Hex; } - return target; -} -/** - * Random aggregate3 calls that both encoders accept. - * - * @returns Up to four calls. Call data is 0–64 bytes. - */ -function randomAggregate3Calls(): Aggregate3Call[] { - const calls: Aggregate3Call[] = []; - const callCount = randomInt(5); - for (let index = 0; index < callCount; index++) { - calls.push({ - target: randomHexCase(randomTarget()), - allowFailure: Math.random() < 0.5, - callData: randomHexCase(randomBytesHex(randomInt(65))), - }); + /** + * 1–32 byte address. Half the time, drop one nibble so the length is odd. + * + * @returns A target both encoders accept. Ethers rejects an empty address. + */ + function randomTarget(): Address { + const target = randomBytesHex(randomInt(32) + 1); + if (Math.random() < 0.5) { + return target.slice(0, -1) as Address; + } + return target; } - return calls; -} -/** - * Random `(success, returnData)` rows for an aggregate3 response. - * - * @returns Up to four rows. Return data is 0–64 bytes. - */ -function randomAggregate3Results(): [boolean, Hex][] { - const results: [boolean, Hex][] = []; - const resultCount = randomInt(5); - for (let index = 0; index < resultCount; index++) { - results.push([ - Math.random() < 0.5, - randomHexCase(randomBytesHex(randomInt(65))), - ]); + /** + * Random aggregate3 calls that both encoders accept. + * + * @returns Up to four calls. Call data is 0–64 bytes. + */ + function randomAggregate3Calls(): Aggregate3Call[] { + const calls: Aggregate3Call[] = []; + const callCount = randomInt(5); + for (let index = 0; index < callCount; index++) { + calls.push({ + target: randomHexCase(randomTarget()), + allowFailure: Math.random() < 0.5, + callData: randomHexCase(randomBytesHex(randomInt(65))), + }); + } + return calls; } - return results; -} -/** - * Random uint256 return data: empty, shorter than one word, or one word. - * - * @returns Hex both uint256 decoders accept. - */ -function randomUint256Data(): Hex { - const kind = randomInt(3); - if (kind === 0) { - return '0x'; + /** + * Random `(success, returnData)` rows for an aggregate3 response. + * + * @returns Up to four rows. Return data is 0–64 bytes. + */ + function randomAggregate3Results(): [boolean, Hex][] { + const results: [boolean, Hex][] = []; + const resultCount = randomInt(5); + for (let index = 0; index < resultCount; index++) { + results.push([ + Math.random() < 0.5, + randomHexCase(randomBytesHex(randomInt(65))), + ]); + } + return results; } - if (kind === 1) { - return randomHexCase(randomBytesHex(randomInt(32))); + + /** + * Random uint256 return data: empty, shorter than one word, or one word. + * + * @returns Hex both uint256 decoders accept. + */ + function randomUint256Data(): Hex { + const kind = randomInt(3); + if (kind === 0) { + return '0x'; + } + if (kind === 1) { + return randomHexCase(randomBytesHex(randomInt(32))); + } + return randomHexCase(randomBytesHex(32)); } - return randomHexCase(randomBytesHex(32)); -} -describe('random comparison with Ethers', () => { - it('encodes and decodes 100 random inputs identically to Ethers', () => { + it('matches Ethers on 100 random inputs', () => { for (let iteration = 0; iteration < 100; iteration++) { const calls = randomAggregate3Calls(); expect(encodeAggregate3(calls)).toBe(encodeAggregate3WithEthers(calls)); @@ -403,27 +149,16 @@ describe('random comparison with Ethers', () => { expect(decodeUint256(word)).toBe(decodeUint256WithEthers(word)); } }); -}); - -describe('production batch cap', () => { - // MulticallClient batches at most 300 calls. These widths sit on the - // 32-byte padding boundaries the offset table has to accumulate. - const callDataByWidth: Hex[] = [ - '0x', - '0xaa', - `0x${'11'.repeat(32)}`, - `0x${'22'.repeat(33)}`, - `0x${'33'.repeat(36)}`, - ]; - const returnDataByWidth: Hex[] = [ - '0x', - '0xaa', - `0x${'ab'.repeat(32)}`, - `0x${'cd'.repeat(33)}`, - ]; - const targets = [ACCOUNT, USDC, USDT, MULTICALL]; it('encodes 300 calls byte-identically to Ethers', () => { + const callDataByWidth: Hex[] = [ + '0x', + '0xaa', + `0x${'11'.repeat(32)}`, + `0x${'22'.repeat(33)}`, + `0x${'33'.repeat(36)}`, + ]; + const targets = [ACCOUNT, USDC, USDT, MULTICALL]; const calls: Aggregate3Call[] = []; for (let index = 0; index < 300; index++) { calls.push({ @@ -437,6 +172,12 @@ describe('production batch cap', () => { }); it('decodes 300 results identically to Ethers', () => { + const returnDataByWidth: Hex[] = [ + '0x', + '0xaa', + `0x${'ab'.repeat(32)}`, + `0x${'cd'.repeat(33)}`, + ]; const results: [boolean, Hex][] = []; for (let index = 0; index < 300; index++) { results.push([