Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions packages/assets-controller/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ import type {
Provider,
} from '../types/index.js';
import {
decodeAggregate3Response,
encodeAggregate3,
decodeAggregate3ResponseWithEthers,
encodeAggregate3WithEthers,
MulticallClient,
} from './MulticallClient.js';

Expand Down Expand Up @@ -895,7 +895,7 @@ describe('MulticallClient', () => {
});
});

describe('encodeAggregate3', () => {
describe('encodeAggregate3WithEthers', () => {
it('should encode a valid aggregate3 call', () => {
const calls = [
{
Expand All @@ -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');
Expand All @@ -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,
Expand All @@ -947,7 +946,7 @@ describe('encodeAggregate3', () => {
},
];

const result = encodeAggregate3(calls);
const result = encodeAggregate3WithEthers(calls);

// Verify selector is correct (aggregate3)
expect(result).toMatch(/^0x82ad56cb/u);
Expand All @@ -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)',
Expand Down Expand Up @@ -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);
Expand All @@ -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);
Expand All @@ -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',
);
});
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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;
Expand All @@ -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) => ({
Expand All @@ -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 }[] {
Expand All @@ -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';
Expand Down
Loading
Loading