diff --git a/.auto/bench/.gitignore b/.auto/bench/.gitignore new file mode 100644 index 00000000000..45e5134bed9 --- /dev/null +++ b/.auto/bench/.gitignore @@ -0,0 +1,5 @@ +tmp/ +bundle*.js +run_*.out +viem_run_*.out +tsc.log diff --git a/.auto/bench/build.sh b/.auto/bench/build.sh new file mode 100755 index 00000000000..e15c6e5a9c8 --- /dev/null +++ b/.auto/bench/build.sh @@ -0,0 +1,17 @@ +#!/bin/bash +# Playground build: prepare tree -> tsc -> single-file Hermes bundle. +set -euo pipefail +ROOT="$(git rev-parse --show-toplevel)" +cd "$ROOT" + +node .auto/bench/prepare.mjs "$ROOT" + +# Type errors do not block emit (noEmitOnError false); syntax errors kill the +# emit, caught below by the missing bench.js. +node_modules/.bin/tsc -p .auto/bench/tmp/tsconfig.json > .auto/bench/tsc.log 2>&1 || true + +node .auto/bench/bundle.mjs "$ROOT" + +# Syntax gate on the final bundle (Node parses, does not run it). +node --check .auto/bench/bundle.js +echo "build: OK (.auto/bench/bundle.js)" diff --git a/.auto/bench/bundle.mjs b/.auto/bench/bundle.mjs new file mode 100644 index 00000000000..5070273f9f2 --- /dev/null +++ b/.auto/bench/bundle.mjs @@ -0,0 +1,144 @@ +#!/usr/bin/env node +// Playground build step 2: concatenate the tsc-emitted CJS tree in +// .auto/bench/tmp/dist into a single self-contained JS file runnable by the +// Hermes CLI (no require, no filesystem) — .auto/bench/bundle.js. +import fs from 'node:fs'; +import path from 'node:path'; + +const ROOT = path.resolve(process.argv[2] ?? process.cwd()); +const DIST = path.join(ROOT, '.auto/bench/tmp/dist'); +const VENDOR = path.join(ROOT, '.auto/bench/tmp/vendor'); +const ENTRY = process.env.BENCH_ENTRY ?? 'app/bench.js'; +const ENTRY_BASE = path.basename(ENTRY, '.js'); // e.g. 'bench', 'bench-viem' +const OUT = path.join(ROOT, `.auto/bench/${ENTRY_BASE === 'bench' ? 'bundle.js' : `bundle-${ENTRY_BASE}.js`}`); + +const modules = new Map(); // relative posix path (no ext) -> source + +function walk(dir, rel, stripPrefix = '') { + if (!fs.existsSync(dir)) { + return; + } + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const relPath = rel ? `${rel}/${entry.name}` : entry.name; + if (entry.isDirectory()) { + walk(path.join(dir, entry.name), relPath, stripPrefix); + } else if (entry.name.endsWith('.js')) { + // vendor files are pre-compiled JS; register verbatim with their + // vendor-relative key (viem/noble internal requires resolve against + // those keys). + const key = stripPrefix + ? relPath.startsWith(stripPrefix) + ? relPath.slice(stripPrefix.length) + : relPath + : relPath; + modules.set(key, fs.readFileSync(path.join(dir, entry.name), 'utf8')); + } + } +} +walk(DIST, ''); +walk(VENDOR, 'vendor', 'vendor/'); + +if (!modules.has(ENTRY)) { + throw new Error(`${ENTRY} missing — tsc emit failed?`); +} + +const parts = []; +for (const [modPath, src] of modules) { + parts.push( + `${JSON.stringify(modPath)}: function (module, exports, require) {\n${src}\n}`, + ); +} + +const ALIASES = JSON.parse( + fs.readFileSync(path.join(ROOT, '.auto/bench/tmp/aliases.json'), 'utf8'), +); + +const prelude = ` +var __aliases = ${JSON.stringify(ALIASES)}; +var __mods = { +${parts.join(',\n')} +}; +var __cache = {}; +function __norm(p) { + var segs = p.split('/'); + var out = []; + for (var i = 0; i < segs.length; i++) { + var s = segs[i]; + if (s === '' || s === '.') continue; + if (s === '..') { if (out.length) out.pop(); continue; } + out.push(s); + } + return out.join('/'); +} +function __try(path) { return __mods[path] !== undefined ? path : null; } +function __resolve(fromDir, spec) { + if (__aliases[spec]) return __aliases[spec]; + if (spec.slice(0, 2) === './' || spec.slice(0, 3) === '../') { + var joined = __norm(fromDir + '/' + spec); + return __try(joined) || __try(joined + '.js') || __try(joined + '/index.js'); + } + return __try(spec) || __try(spec + '.js') || __try(spec + '/index.js'); +} +function __requireFactory(dir) { + return function (spec) { + var key = __resolve(dir, spec); + if (key === null) throw new Error('Cannot find module "' + spec + '" from ' + dir); + var cached = __cache[key]; + if (cached) return cached.exports; + var mod = { exports: {} }; + __cache[key] = mod; + __mods[key](mod, mod.exports, __requireFactory(key.slice(0, key.lastIndexOf('/')))); + return mod.exports; + }; +} +var process = { env: {} }; +var global = globalThis; +// Minimal Buffer polyfill — @ethersproject/base64 decode runs Buffer.from(str, +// 'base64') at ens-normalize module load (pulled in by abi -> interface). +var __b64abc = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'; +function __b64lookup(c) { + if (c >= 65 && c <= 90) return c - 65; + if (c >= 97 && c <= 122) return c - 97 + 26; + if (c >= 48 && c <= 57) return c - 48 + 52; + if (c === 43) return 62; + if (c === 47) return 63; + return 255; // padding or invalid +} +var Buffer = { + from: function (data, enc) { + if (typeof data === 'string' && enc === 'base64') { + var out = []; + var bits = 0, acc = 0, count = 0; + for (var i = 0; i < data.length; i++) { + var v = __b64lookup(data.charCodeAt(i)); + if (v === 255) continue; + acc = (acc << 6) | v; + bits += 6; + if (bits >= 8) { + bits -= 8; + out.push((acc >> bits) & 0xff); + } + count++; + } + return new Uint8Array(out); + } + if (typeof data === 'string') { + var bytes = []; + for (var j = 0; j < data.length; j++) bytes.push(data.charCodeAt(j) & 0xff); + return new Uint8Array(bytes); + } + if (data && typeof data.length === 'number') return new Uint8Array(data); + return new Uint8Array(0); + }, + isBuffer: function () { return false; }, +}; +`; + +const entry = `${ + process.env.BENCH_BATCH_N ? `globalThis.BENCH_BATCH_N=${process.env.BENCH_BATCH_N};\n` : '' +}${ + process.env.BENCH_RET_BYTES ? `globalThis.BENCH_RET_BYTES=${process.env.BENCH_RET_BYTES};\n` : '' +}__requireFactory('app')('${ENTRY}');\n`; + +fs.writeFileSync(OUT, prelude + entry); +console.log(`bundle: ${modules.size} modules -> ${OUT}`); diff --git a/.auto/bench/median.mjs b/.auto/bench/median.mjs new file mode 100644 index 00000000000..e1e37348f5a --- /dev/null +++ b/.auto/bench/median.mjs @@ -0,0 +1,38 @@ +#!/usr/bin/env node +// Take per-metric medians across N Hermes run outputs and re-emit METRIC lines. +import fs from 'node:fs'; + +const files = process.argv.slice(2); +if (files.length === 0) { + throw new Error('usage: median.mjs [ ...]'); +} + +const order = []; +const perRun = files.map((file) => { + const metrics = {}; + for (const line of fs.readFileSync(file, 'utf8').split('\n')) { + const match = /^METRIC (\w+)=(.*)$/.exec(line); + if (match) { + const [, name, raw] = match; + if (!order.includes(name)) order.push(name); + const value = Number(raw); + if (!Number.isNaN(value)) { + metrics[name] = value; + } + } + } + return metrics; +}); + +for (const name of order) { + const values = perRun.map((m) => m[name]).filter((v) => v !== undefined); + if (values.length === 0) continue; + const sorted = [...values].sort((a, b) => a - b); + const median = sorted[(sorted.length - 1) >> 1]; + const out = + name === 'batch_n' || name.endsWith('_len') + ? String(median) + : String(Math.round(median * 1000) / 1000); + console.log(`METRIC ${name}=${out}`); +} +console.log('SELF_CHECK=OK'); diff --git a/.auto/bench/prepare.mjs b/.auto/bench/prepare.mjs new file mode 100644 index 00000000000..750befdd104 --- /dev/null +++ b/.auto/bench/prepare.mjs @@ -0,0 +1,389 @@ +#!/usr/bin/env node +// Playground build step 1: assemble the tmp TS tree for the Hermes bundle. +// +// - Copies the @ethersproject closure (TS sources shipped in src.ts/) into +// .auto/bench/tmp/src/@ethersproject// plus js-sha3. +// - Extracts the REAL ABI/encode/decode code from MulticallClient.ts into +// .auto/bench/tmp/src/app/multicall.ts (markers must stay intact). +// - Copies the stable templates (controller-abi.ts, bench.ts) into tmp/src/app. +// - Writes .auto/bench/tmp/tsconfig.json. +import fs from 'node:fs'; +import { createRequire } from 'node:module'; +import path from 'node:path'; + +const ROOT = path.resolve(process.argv[2] ?? process.cwd()); +const TMP = path.join(ROOT, '.auto/bench/tmp'); +const SRC = path.join(TMP, 'src'); +const MULTICALL_TS = path.join( + ROOT, + 'packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.ts', +); + +fs.rmSync(TMP, { recursive: true, force: true }); +fs.mkdirSync(path.join(SRC, 'app'), { recursive: true }); +// Mark the tmp tree as CommonJS so `module: node16` treats every file in it +// as CJS (the repo root package.json is "type": "module" and would otherwise +// win the nearest-package.json lookup) and emits require() calls. +fs.writeFileSync(path.join(TMP, 'package.json'), '{"type": "commonjs"}\n'); + +const req = createRequire( + path.join(ROOT, 'packages/assets-controller/package.json'), +); + +// --------------------------------------------------------------------------- +// 1. Ethers closure (BFS over package.json dependencies) +// --------------------------------------------------------------------------- + +const closure = new Map(); // pkg -> source dir (src.ts) +const queue = ['@ethersproject/abi']; +while (queue.length > 0) { + const pkg = queue.shift(); + if (closure.has(pkg)) { + continue; + } + const pkgDir = path.dirname(req.resolve(`${pkg}/package.json`)); + const pkgJson = JSON.parse( + fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'), + ); + if (pkg === 'js-sha3') { + closure.set(pkg, path.join(pkgDir, 'src')); + } else { + const srcTs = path.join(pkgDir, 'src.ts'); + if (!fs.existsSync(srcTs)) { + throw new Error(`${pkg} has no src.ts directory`); + } + const entry = path.join(srcTs, 'index.ts'); + if (!fs.existsSync(entry)) { + throw new Error(`${pkg} has no src.ts/index.ts entry`); + } + closure.set(pkg, srcTs); + } + for (const dep of Object.keys(pkgJson.dependencies ?? {})) { + if (dep.startsWith('@ethersproject/') || dep === 'js-sha3') { + queue.push(dep); + } + } +} + +function copyTree(from, to) { + fs.mkdirSync(to, { recursive: true }); + for (const entry of fs.readdirSync(from, { withFileTypes: true })) { + if (entry.isDirectory()) { + copyTree(path.join(from, entry.name), path.join(to, entry.name)); + } else if (/\.(ts|js)$/.test(entry.name)) { + fs.copyFileSync(path.join(from, entry.name), path.join(to, entry.name)); + } + } +} + +for (const [pkg, srcDir] of closure) { + copyTree(srcDir, path.join(SRC, pkg)); +} + +// --------------------------------------------------------------------------- +// 1b. Plain-JS vendor packages (bn.js, elliptic, hash.js, ...): copy the +// directory containing the package main and record a runtime alias +// (bare spec -> module key) for the bundler. TS `paths` are compile-time +// only, so emitted code still does require("bn.js") etc. +// --------------------------------------------------------------------------- + +const aliases = { 'js-sha3': 'js-sha3/sha3.js' }; +const vendored = new Set(); +const vendorQueue = []; +function enqueueDeps(pkgJson) { + for (const dep of Object.keys(pkgJson.dependencies ?? {})) { + if ( + closure.has(dep) || + vendored.has(dep) || + vendorQueue.includes(dep) || + dep === 'js-sha3' + ) { + continue; + } + vendorQueue.push(dep); + } +} +for (const [, srcDir] of closure) { + enqueueDeps( + JSON.parse( + fs.readFileSync(path.join(path.dirname(srcDir), 'package.json'), 'utf8'), + ), + ); +} +while (vendorQueue.length > 0) { + const pkg = vendorQueue.shift(); + if (vendored.has(pkg)) { + continue; + } + let pkgDir; + let pkgJson; + try { + pkgDir = path.dirname(req.resolve(`${pkg}/package.json`)); + pkgJson = JSON.parse( + fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf8'), + ); + } catch { + console.warn( + `vendor: skipping ${pkg} (unresolvable — fine if unreferenced at runtime)`, + ); + vendored.add(pkg); + continue; + } + const main = pkgJson.main || 'index.js'; + const mainFile = path.join(pkgDir, main); + if (!fs.existsSync(mainFile)) { + console.warn(`vendor: skipping ${pkg} (main ${main} missing)`); + vendored.add(pkg); + continue; + } + copyTree(path.dirname(mainFile), path.join(SRC, pkg)); + aliases[pkg] = `${pkg}/${path.basename(main)}`; + vendored.add(pkg); + enqueueDeps(pkgJson); +} + +fs.writeFileSync( + path.join(TMP, 'aliases.json'), + JSON.stringify(aliases, null, 2), +); + +// --------------------------------------------------------------------------- +// 1c. viem closure — pruned, compiled-JS vendoring (file-level BFS over the +// require() graph from viem's ABI utils; matches what a tree-shaken +// mobile bundle would actually include). Files go to tmp/vendor/ and are +// registered by the bundler verbatim (they are already CJS; tsc never +// sees them). +// --------------------------------------------------------------------------- + +const VENDOR = path.join(TMP, 'vendor'); +const rootReq = createRequire(path.join(ROOT, 'package.json')); +const viemMain = rootReq.resolve('viem'); // .../viem/_cjs/index.js +const viemRoot = path.dirname(path.dirname(viemMain)); // .../viem + +const viemFiles = new Map(); // vendor key -> absolute source file +const visitedFiles = new Set(); // absolute source files already visited +const REQUIRES_RE = /require\(["']([^"']+)["']\)/g; + +function pkgOf(spec) { + // '@noble/hashes/sha3' -> '@noble/hashes'; 'abitype' -> 'abitype' + return spec.startsWith('@') ? spec.split('/').slice(0, 2).join('/') : spec.split('/')[0]; +} + +function visitFile(absFile, key) { + if (visitedFiles.has(absFile)) { + return; + } + visitedFiles.add(absFile); + const src = fs.readFileSync(absFile, 'utf8'); + viemFiles.set(key, src); + REQUIRES_RE.lastIndex = 0; + let m; + while ((m = REQUIRES_RE.exec(src)) !== null) { + const spec = m[1]; + if (spec.startsWith('.')) { + for (const cand of [spec, `${spec}.js`, `${spec}/index.js`]) { + const p = path.resolve(path.dirname(absFile), cand); + if (fs.existsSync(p) && fs.statSync(p).isFile()) { + visitFile(p, path.posix.join(path.posix.dirname(key), cand)); + break; + } + } + } else { + try { + const resolved = rootReq.resolve(spec); + const pkgName = pkgOf(spec); + // Find the package root by walking up from the resolved file (some + // packages do not export ./package.json, e.g. @noble/hashes). + let pkgRoot = path.dirname(resolved); + for (;;) { + const pj = path.join(pkgRoot, 'package.json'); + if (fs.existsSync(pj)) { + const name = JSON.parse(fs.readFileSync(pj, 'utf8')).name; + if (name === pkgName) { + break; + } + } + const parent = path.dirname(pkgRoot); + if (parent === pkgRoot) { + throw new Error(`package root not found for ${spec}`); + } + pkgRoot = parent; + } + const subKey = path.posix.join( + pkgName, + path.relative(pkgRoot, resolved).split(path.sep).join('/'), + ); + aliases[spec] = subKey; + visitFile(resolved, subKey); + } catch (err) { + console.warn(`vendor-viem: skipping unresolvable ${spec}: ${err.message}`); + } + } + } +} + +for (const util of ['encodeFunctionData', 'decodeFunctionResult']) { + visitFile( + path.join(viemRoot, '_cjs/utils/abi', `${util}.js`), + `viem/_cjs/utils/abi/${util}.js`, + ); +} +// viem re-exports parseAbi from abitype (no parseAbi.js in viem's own tree). +{ + const abitypeMain = rootReq.resolve('abitype'); + const abitypeRoot = path.dirname(path.dirname(abitypeMain)); // .../abitype + aliases['abitype'] = path.posix.join( + 'abitype', + path.relative(abitypeRoot, abitypeMain).split(path.sep).join('/'), + ); + visitFile(abitypeMain, aliases['abitype']); +} + +for (const [key, src] of viemFiles) { + const dest = path.join(VENDOR, key); + fs.mkdirSync(path.dirname(dest), { recursive: true }); + fs.writeFileSync(dest, src); +} + +// viem shim: the only public surface the bench uses. A real app imports from +// 'viem' and the tree-shaker keeps exactly this closure. +fs.mkdirSync(path.join(VENDOR, 'viem'), { recursive: true }); +fs.writeFileSync( + path.join(VENDOR, 'viem/shim.js'), + `// AUTO-GENERATED by .auto/bench/prepare.mjs +// Pruned "viem" surface: exactly what a tree-shaken mobile bundle keeps. +// (parseAbi is re-exported by viem from abitype.) +const enc = require('./_cjs/utils/abi/encodeFunctionData.js'); +const dec = require('./_cjs/utils/abi/decodeFunctionResult.js'); +const parse = require('abitype'); +module.exports = { + encodeFunctionData: enc.encodeFunctionData, + decodeFunctionResult: dec.decodeFunctionResult, + parseAbi: parse.parseAbi, +}; +`, +); +aliases['viem'] = 'viem/shim.js'; + +// Stub node:crypto — pulled in by @noble/hashes' cryptoNode.js (old-Node +// fallback). The keccak/sha3 path is pure JS and never touches it; a stub +// matches what a mobile bundler does with the node builtin. +fs.mkdirSync(path.join(VENDOR, 'stub'), { recursive: true }); +fs.writeFileSync( + path.join(VENDOR, 'stub/node-crypto.js'), + '// AUTO-GENERATED stub: node:crypto does not exist on Hermes.\nmodule.exports = {};\n', +); +aliases['node:crypto'] = 'stub/node-crypto.js'; +fs.writeFileSync( + path.join(TMP, 'aliases.json'), + JSON.stringify(aliases, null, 2), +); + +// --------------------------------------------------------------------------- +// 2. Extract the real encode/decode code from MulticallClient.ts +// --------------------------------------------------------------------------- + +const source = fs.readFileSync(MULTICALL_TS, 'utf8'); +const lines = source.split('\n'); + +function findIndex(predicate, what) { + const i = lines.findIndex(predicate); + if (i === -1) { + throw new Error(`MulticallClient.ts marker not found: ${what}`); + } + return i; +} + +const startA = findIndex( + (l) => l.startsWith('const MULTICALL3_ABI'), + 'MULTICALL3_ABI', +); +const constantsHeader = findIndex((l) => l === '// CONSTANTS', '// CONSTANTS'); +const encodeHeader = findIndex( + (l) => l === '// ENCODING/DECODING UTILITIES (using @ethersproject/abi)', + '// ENCODING/DECODING UTILITIES', +); +const clientHeader = findIndex( + (l) => l === '// MULTICALL CLIENT', + '// MULTICALL CLIENT', +); + +const sliceA = lines.slice(startA, constantsHeader - 1); // up to === above CONSTANTS +const sliceB = lines.slice(encodeHeader - 1, clientHeader - 1); // === above header .. === above CLIENT + +const extracted = `// AUTO-GENERATED by .auto/bench/prepare.mjs — DO NOT EDIT +// Extracted (verbatim) from packages/assets-controller/.../MulticallClient.ts +import { Interface } from '@ethersproject/abi'; +import { encodeFunctionData } from './controller-abi'; + +export const ZERO_ADDRESS = '0x0000000000000000000000000000000000000000'; +export type Address = \`0x\${string}\`; +export type Hex = \`0x\${string}\`; +export type BalanceOfRequest = { tokenAddress: Address; accountAddress: Address }; + +${sliceA.join('\n')} + +${sliceB.join('\n')} + +export { + encodeBalanceOf, + encodeGetEthBalance, + decodeUint256, + encodeAggregate3, + decodeAggregate3Response, + buildAggregate3BalanceCalls, + multicall3Interface, + erc20Interface, +}; +`; + +fs.writeFileSync(path.join(SRC, 'app/multicall.ts'), extracted); + +// --------------------------------------------------------------------------- +// 3. Templates (stable, git-tracked) → tmp +// --------------------------------------------------------------------------- + +for (const template of ['controller-abi.ts', 'bench.ts', 'bench-viem.ts']) { + fs.copyFileSync( + path.join(ROOT, '.auto/bench/templates', template), + path.join(SRC, 'app', template), + ); +} + +// --------------------------------------------------------------------------- +// 4. tsconfig +// --------------------------------------------------------------------------- + +const tsconfig = { + compilerOptions: { + target: 'es2019', + module: 'node16', + paths: { + '@ethersproject/*': ['./src/@ethersproject/*/index.ts'], + 'js-sha3': ['./src/js-sha3/sha3.js'], + }, + allowJs: true, + checkJs: false, + outDir: 'dist', + rootDir: 'src', + strict: false, + noImplicitAny: false, + noEmitOnError: false, + skipLibCheck: true, + declaration: false, + sourceMap: false, + importHelpers: false, + esModuleInterop: true, + resolveJsonModule: true, + types: [], + }, + include: ['src/**/*.ts', 'src/**/*.js'], +}; + +fs.writeFileSync( + path.join(TMP, 'tsconfig.json'), + JSON.stringify(tsconfig, null, 2), +); + +const pkgs = [...closure.keys()].sort(); +console.log(`prepare: closure=${pkgs.length} (${pkgs.join(', ')})`); diff --git a/.auto/bench/templates/bench-viem.ts b/.auto/bench/templates/bench-viem.ts new file mode 100644 index 00000000000..c03b3608b19 --- /dev/null +++ b/.auto/bench/templates/bench-viem.ts @@ -0,0 +1,362 @@ +// Hermes benchmark runner — VIEM variant. +// +// Measures what MulticallClient's numbers would look like if the Ethers +// usage were replaced with viem (encodeFunctionData/decodeFunctionResult +// with a module-level parseAbi, the realistic equivalent of `new Interface()`). +// +// Same deterministic inputs, same stock-Ethers parity oracle, same timing +// loop as bench.ts; metrics are prefixed `viem_`. +declare function print(input: string): void; +declare function require(name: string): any; + +const viem: any = require('viem'); + +import { Interface, defaultAbiCoder } from '@ethersproject/abi'; + +import { buildAggregate3BalanceCalls, ZERO_ADDRESS } from './multicall'; + +// --------------------------------------------------------------------------- +// Candidate codec (viem) — mirrors the MulticallClient surface. +// --------------------------------------------------------------------------- + +const AGGREGATE3_ABI = + 'function aggregate3((address target, bool allowFailure, bytes callData)[] calls) payable returns ((bool success, bytes returnData)[])'; +const BALANCE_OF_ABI = + 'function balanceOf(address account) view returns (uint256)'; + +// Module-level parse — the viem equivalent of `new Interface(...)`. +const aggAbi = viem.parseAbi([AGGREGATE3_ABI]); +const balAbi = viem.parseAbi([BALANCE_OF_ABI]); + +function encodeAggregate3(calls: any[]): string { + return viem.encodeFunctionData({ + abi: aggAbi, + functionName: 'aggregate3', + args: [calls], + }); +} + +function decodeAggregate3Response( + data: string, + callCount: number, +): { success: boolean; returnData: string }[] { + const results = viem.decodeFunctionResult({ + abi: aggAbi, + functionName: 'aggregate3', + data, + }); + if (results.length !== callCount) { + throw new Error(`Expected ${callCount} results, got ${results.length}`); + } + return results.map((r: any) => ({ + success: r.success, + returnData: r.returnData, + })); +} + +function decodeUint256(data: string): string { + if (data === '0x' || data.length < 66) { + return '0'; + } + return String( + viem.decodeFunctionResult({ abi: balAbi, functionName: 'balanceOf', data }), + ); +} + +// --------------------------------------------------------------------------- +// Stock Ethers reference (the parity oracle) — identical to bench.ts. +// --------------------------------------------------------------------------- + +const refIface = new Interface([ + 'function aggregate3((address target, bool allowFailure, bytes callData)[] calls) payable returns ((bool success, bytes returnData)[])', + 'function balanceOf(address account) view returns (uint256)', +]); + +// --------------------------------------------------------------------------- +// Deterministic input generation (LCG) — same data every run as bench.ts. +// --------------------------------------------------------------------------- + +let seed = 0x2f6e2b1; +function rand(): number { + seed = (seed * 1103515245 + 12345) & 0x7fffffff; + return seed; +} +function hexOf(len: number): string { + let s = ''; + for (let i = 0; i < len; i++) { + s += (rand() % 16).toString(16); + } + return s; +} + +// Scalable knobs (injected by bundle.mjs from env) — used to verify the +// codec is size-general, not tuned to one batch shape. +const BATCH_N: number = (globalThis as any).BENCH_BATCH_N ?? 300; +const RET_BYTES: number = (globalThis as any).BENCH_RET_BYTES ?? 32; +const MULTICALL3_ADDRESS = '0xca11bde05977b3631167028862be2a173976ca11'; +const TOKEN_POOL = [ + '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', + '0xdac17f958d2ee523a2206206994597c13d831ec7', + '0x6b175474e89094c44da98b954eedeac495271d0f', + '0x2260fac5e5542a773aa44fbcfedf7c193bc2c599', + '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984', +]; + +const requests: { tokenAddress: string; accountAddress: string }[] = []; +for (let i = 0; i < BATCH_N; i++) { + const native = rand() % 5 === 0; + requests.push({ + tokenAddress: native + ? ZERO_ADDRESS + : TOKEN_POOL[rand() % TOKEN_POOL.length], + accountAddress: '0x' + hexOf(40), + }); +} +// Identical input construction to bench.ts (extracted real client code). +const calls = buildAggregate3BalanceCalls( + requests as any, + MULTICALL3_ADDRESS as any, +); + +// --------------------------------------------------------------------------- +// Synthetic aggregate3 responses (built once with the stock coder). +// --------------------------------------------------------------------------- + +function buildResponse(tuples: [boolean, string][]): string { + return defaultAbiCoder.encode( + ['(bool success, bytes returnData)[]'], + [tuples], + ) as string; +} + +const mainTuples: [boolean, string][] = requests.map((_, i) => { + const success = rand() % 20 !== 0; + if (!success) { + return [false, '0x']; + } + return [ + true, + '0x' + + BigInt(i * 999983 + 1) + .toString(16) + .padStart(RET_BYTES * 2, '0'), + ]; +}); +const respMain = buildResponse(mainTuples); + +const respEmpty = buildResponse([]); +const respEdge = buildResponse([ + [true, '0x' + 'ab'.repeat(32)], + [true, '0xab'], + [true, '0x' + 'cd'.repeat(31)], + [false, '0x'], + [true, '0x' + 'ef'.repeat(100)], + [true, '0x'], +]); + +// --------------------------------------------------------------------------- +// Parity self-checks +// --------------------------------------------------------------------------- + +function check(name: string, ok: boolean, detail: string): void { + if (!ok) { + print(`SELF_CHECK=FAIL ${name}: ${detail}`); + throw new Error(`self-check failed: ${name}`); + } +} + +function firstDiff(a: string, b: string): string { + const A = a.toLowerCase(); + const B = b.toLowerCase(); + if (A.length !== B.length) { + return `len ${A.length} vs ${B.length}; `; + } + for (let i = 0; i < A.length; i++) { + if (A[i] !== B[i]) { + return `diff@${i}: ours ${A.slice(Math.max(0, i - 8), i + 8)} vs ref ${B.slice(Math.max(0, i - 8), i + 8)}; `; + } + } + return 'no diff'; +} + +function refDecode(data: string): { success: boolean; returnData: string }[] { + const decoded = refIface.decodeFunctionResult('aggregate3', data); + const results = decoded[0] as { success: boolean; returnData: string }[]; + return results.map((r) => ({ + success: r.success, + returnData: r.returnData, + })); +} + +function checkDecode(name: string, data: string, count: number): void { + const ours = decodeAggregate3Response(data, count); + const ref = refDecode(data); + check( + name, + ours.length === ref.length, + `length ${ours.length} vs ${ref.length}`, + ); + for (let i = 0; i < ours.length; i++) { + check( + name, + ours[i].success === ref[i].success && + ours[i].returnData.toLowerCase() === ref[i].returnData.toLowerCase(), + `item ${i}: ours ${ours[i].success}/${ours[i].returnData.slice(0, 20)} ref ${ref[i].success}/${ref[i].returnData.slice(0, 20)}`, + ); + } +} + +function runSelfChecks(): void { + const encoded = encodeAggregate3(calls); + const expected = refIface.encodeFunctionData('aggregate3', [calls]); + check( + 'viem_encode_main', + encoded.toLowerCase() === expected.toLowerCase(), + `${firstDiff(encoded, expected)}${encoded.slice(0, 40)}... vs ${expected.slice(0, 40)}...`, + ); + + const edges: { + target: string; + allowFailure: boolean; + callData: string; + }[][] = [ + [], + [ + { + target: '0x1111111111111111111111111111111111111111', + allowFailure: true, + callData: '0x', + }, + ], + [ + { + target: '0x2222222222222222222222222222222222222222', + allowFailure: false, + callData: '0xab', + }, + { + target: '0x3333333333333333333333333333333333333333', + allowFailure: true, + callData: '0x' + 'ab'.repeat(33), + }, + ], + ]; + for (let i = 0; i < edges.length; i++) { + const ours = encodeAggregate3(edges[i]); + const ref = refIface.encodeFunctionData('aggregate3', [edges[i]]); + check( + 'viem_encode_edge_' + i, + ours.toLowerCase() === ref.toLowerCase(), + `${ours.slice(0, 40)}... vs ${ref.slice(0, 40)}...`, + ); + } + + checkDecode('viem_decode_main', respMain, BATCH_N); + checkDecode('viem_decode_empty', respEmpty, 0); + checkDecode('viem_decode_edge', respEdge, 6); + + let threw = false; + try { + decodeAggregate3Response(respMain, BATCH_N - 1); + } catch { + threw = true; + } + check('viem_decode_count_mismatch_throws', threw, 'expected throw'); + + const words = [ + '0x' + BigInt(0).toString(16).padStart(64, '0'), + '0x' + BigInt(123456789012345).toString(16).padStart(64, '0'), + '0x' + + BigInt( + '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff', + ) + .toString(16) + .padStart(64, '0'), + '0x' + hexOf(64), + ]; + for (const word of words) { + const ours = decodeUint256(word); + const ref = refIface + .decodeFunctionResult('balanceOf', word)[0] + .toString(); + check( + 'viem_decode_uint256', + ours === ref, + `${ours} vs ${ref} (${word.slice(0, 20)}...)`, + ); + } + const zero = decodeUint256('0x'); + check('viem_decode_uint256_empty', zero === '0', zero); +} + +// --------------------------------------------------------------------------- +// Timing (identical loop to bench.ts) +// --------------------------------------------------------------------------- + +function timeOp(fn: () => void, minMs: number, maxIters: number): number { + let iters = 0; + const t0 = Date.now(); + do { + fn(); + iters++; + } while (Date.now() - t0 < minMs && iters < maxIters); + return (Date.now() - t0) / iters; +} + +function median(values: number[]): number { + const sorted = [...values].sort((a, b) => a - b); + return sorted[(sorted.length - 1) >> 1]; +} + +function round3(value: number): number { + return Math.round(value * 1000) / 1000; +} + +// --------------------------------------------------------------------------- +// Run +// --------------------------------------------------------------------------- + +runSelfChecks(); + +encodeAggregate3(calls); +decodeAggregate3Response(respMain, BATCH_N); + +const REPS = 5; +const encMs: number[] = []; +const decMs: number[] = []; +const uintMs: number[] = []; + +for (let r = 0; r < REPS; r++) { + encMs.push(timeOp(() => encodeAggregate3(calls), 120, 40)); + decMs.push(timeOp(() => decodeAggregate3Response(respMain, BATCH_N), 120, 40)); + const decoded = decodeAggregate3Response(respMain, BATCH_N); + const datas = decoded + .filter((x) => x.success && x.returnData.length > 2) + .map((x) => x.returnData); + uintMs.push( + timeOp( + () => { + for (let i = 0; i < datas.length; i++) { + decodeUint256(datas[i]); + } + }, + 120, + 20, + ), + ); +} + +const calldata = encodeAggregate3(calls); + +print( + 'METRIC viem_encdec_full_ms=' + + round3(median(encMs) + median(decMs) + median(uintMs)), +); +print('METRIC viem_encdec_ms=' + round3(median(encMs) + median(decMs))); +print('METRIC viem_encode_ms=' + round3(median(encMs))); +print('METRIC viem_decode_ms=' + round3(median(decMs))); +print('METRIC viem_decode_uint256_ms=' + round3(median(uintMs))); +print('METRIC batch_n=' + BATCH_N); +print('METRIC calldata_hex_len=' + calldata.length); +print('METRIC resp_hex_len=' + respMain.length); +print('SELF_CHECK=OK'); diff --git a/.auto/bench/templates/bench.ts b/.auto/bench/templates/bench.ts new file mode 100644 index 00000000000..1fe2224d7d5 --- /dev/null +++ b/.auto/bench/templates/bench.ts @@ -0,0 +1,334 @@ +// Hermes benchmark runner — runs the REAL extracted MulticallClient +// encode/decode code under the Hermes CLI and emits `METRIC name=value` lines. +// Also performs parity self-checks against stock Ethers (byte-identical +// encode, identical decode) and fails the run on any mismatch. +declare function print(input: string): void; + +import { Interface, defaultAbiCoder } from '@ethersproject/abi'; + +import { + buildAggregate3BalanceCalls, + decodeAggregate3Response, + decodeUint256, + encodeAggregate3, + erc20Interface, + multicall3Interface, + ZERO_ADDRESS, +} from './multicall'; + +// Stock reference interface (default coder, checksum-validating address +// coder) — the parity oracle. +const refIface = new Interface([ + 'function aggregate3((address target, bool allowFailure, bytes callData)[] calls) payable returns ((bool success, bytes returnData)[])', +]); + +// --------------------------------------------------------------------------- +// Deterministic input generation (LCG) — same data every run. +// --------------------------------------------------------------------------- + +let seed = 0x2f6e2b1; +function rand(): number { + seed = (seed * 1103515245 + 12345) & 0x7fffffff; + return seed; +} +function hexOf(len: number): string { + let s = ''; + for (let i = 0; i < len; i++) { + s += (rand() % 16).toString(16); + } + return s; +} + +// Scalable knobs (injected by bundle.mjs from env) — used to verify the +// codec is size-general, not tuned to one batch shape. +const BATCH_N: number = (globalThis as any).BENCH_BATCH_N ?? 300; +const RET_BYTES: number = (globalThis as any).BENCH_RET_BYTES ?? 32; +const MULTICALL3_ADDRESS = '0xca11bde05977b3631167028862be2a173976ca11'; +const TOKEN_POOL = [ + '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', + '0xdac17f958d2ee523a2206206994597c13d831ec7', + '0x6b175474e89094c44da98b954eedeac495271d0f', + '0x2260fac5e5542a773aa44fbcfedf7c193bc2c599', + '0x1f9840a85d5af5bf1d1762f925bdaddc4201f984', +]; + +// 300 requests, ~20% native (zero-address token), lowercase addresses +// (accepted by both the stock checksum-validating coder and FastAddressCoder). +const requests: { + tokenAddress: `0x${string}`; + accountAddress: `0x${string}`; +}[] = []; +for (let i = 0; i < BATCH_N; i++) { + const native = rand() % 5 === 0; + requests.push({ + tokenAddress: (native + ? ZERO_ADDRESS + : TOKEN_POOL[rand() % TOKEN_POOL.length]) as `0x${string}`, + accountAddress: ('0x' + hexOf(40)) as `0x${string}`, + }); +} +const calls = buildAggregate3BalanceCalls( + requests, + MULTICALL3_ADDRESS as `0x${string}`, +); + +// --------------------------------------------------------------------------- +// Synthetic aggregate3 responses (built once with the stock coder). +// --------------------------------------------------------------------------- + +function buildResponse(tuples: [boolean, string][]): `0x${string}` { + return defaultAbiCoder.encode( + ['(bool success, bytes returnData)[]'], + [tuples], + ) as `0x${string}`; +} + +// Main response: realistic balances (32-byte uint256 per success), ~5% +// failures with '0x'. +const mainTuples: [boolean, string][] = requests.map((_, i) => { + const success = rand() % 20 !== 0; + if (!success) { + return [false, '0x']; + } + return [ + true, + '0x' + + BigInt(i * 999983 + 1) + .toString(16) + .padStart(RET_BYTES * 2, '0'), + ]; +}); +const respMain = buildResponse(mainTuples); + +// Edge responses. +const respEmpty = buildResponse([]); +const respEdge = buildResponse([ + [true, '0x' + 'ab'.repeat(32)], // exactly 32 bytes + [true, '0xab'], // 1 byte (odd word) + [true, '0x' + 'cd'.repeat(31)], // 31 bytes — padding edge + [false, '0x'], + [true, '0x' + 'ef'.repeat(100)], // long data + [true, '0x'], +]); + +// --------------------------------------------------------------------------- +// Parity self-checks +// --------------------------------------------------------------------------- + +function check(name: string, ok: boolean, detail: string): void { + if (!ok) { + print(`SELF_CHECK=FAIL ${name}: ${detail}`); + throw new Error(`self-check failed: ${name}`); + } +} + +function firstDiff(a: string, b: string): string { + const A = a.toLowerCase(); + const B = b.toLowerCase(); + if (A.length !== B.length) { + return `len ${A.length} vs ${B.length}; `; + } + for (let i = 0; i < A.length; i++) { + if (A[i] !== B[i]) { + return `diff@${i}: ours ${A.slice(Math.max(0, i - 8), i + 8)} vs ref ${B.slice(Math.max(0, i - 8), i + 8)}; `; + } + } + return 'no diff'; +} + +function refDecode(data: string): { success: boolean; returnData: string }[] { + const decoded = refIface.decodeFunctionResult('aggregate3', data); + const results = decoded[0] as { success: boolean; returnData: string }[]; + return results.map((r) => ({ + success: r.success, + returnData: r.returnData, + })); +} + +function checkDecode(name: string, data: string, count: number): void { + const ours = decodeAggregate3Response(data as `0x${string}`, count); + const ref = refDecode(data); + check( + name, + ours.length === ref.length, + `length ${ours.length} vs ${ref.length}`, + ); + for (let i = 0; i < ours.length; i++) { + check( + name, + ours[i].success === ref[i].success && + ours[i].returnData.toLowerCase() === ref[i].returnData.toLowerCase(), + `item ${i}: ours ${ours[i].success}/${ours[i].returnData.slice(0, 20)} ref ${ref[i].success}/${ref[i].returnData.slice(0, 20)}`, + ); + } +} + +function runSelfChecks(): void { + // Encode parity vs stock Ethers (case-insensitive; production guarantees + // identical bytes). + const encoded = encodeAggregate3(calls); + const expected = refIface.encodeFunctionData('aggregate3', [calls]); + check( + 'encode_main', + encoded.toLowerCase() === expected.toLowerCase(), + `${firstDiff(encoded, expected)}${encoded.slice(0, 40)}... vs ${expected.slice(0, 40)}...`, + ); + + // Encode edge cases. + const edges: { + target: `0x${string}`; + allowFailure: boolean; + callData: `0x${string}`; + }[][] = [ + [], + [ + { + target: '0x1111111111111111111111111111111111111111', + allowFailure: true, + callData: '0x', + }, + ], + [ + { + target: '0x2222222222222222222222222222222222222222', + allowFailure: false, + callData: '0xab', + }, + { + target: '0x3333333333333333333333333333333333333333', + allowFailure: true, + callData: '0x' + 'ab'.repeat(33), + }, + ], + ]; + for (let i = 0; i < edges.length; i++) { + const ours = encodeAggregate3(edges[i]); + const ref = refIface.encodeFunctionData('aggregate3', [edges[i]]); + check( + 'encode_edge_' + i, + ours.toLowerCase() === ref.toLowerCase(), + `${ours.slice(0, 40)}... vs ${ref.slice(0, 40)}...`, + ); + } + + // Decode parity. + checkDecode('decode_main', respMain, BATCH_N); + checkDecode('decode_empty', respEmpty, 0); + checkDecode('decode_edge', respEdge, 6); + + // Count-mismatch must throw. + let threw = false; + try { + decodeAggregate3Response(respMain as `0x${string}`, BATCH_N - 1); + } catch { + threw = true; + } + check('decode_count_mismatch_throws', threw, 'expected throw'); + + // decodeUint256 parity vs erc20Interface (stock). + const words = [ + '0x' + BigInt(0).toString(16).padStart(64, '0'), + '0x' + BigInt(123456789012345).toString(16).padStart(64, '0'), + '0x' + + BigInt( + '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff', + ) + .toString(16) + .padStart(64, '0'), + '0x' + hexOf(64), + ]; + for (const word of words) { + const ours = decodeUint256(word as `0x${string}`); + const ref = erc20Interface + .decodeFunctionResult('balanceOf', word)[0] + .toString(); + check( + 'decode_uint256', + ours === ref, + `${ours} vs ${ref} (${word.slice(0, 20)}...)`, + ); + } + const zero = decodeUint256('0x'); + check('decode_uint256_empty', zero === '0', zero); +} + +// --------------------------------------------------------------------------- +// Timing (adaptive loop, ms-resolution safe) +// --------------------------------------------------------------------------- + +function timeOp(fn: () => void, minMs: number, maxIters: number): number { + let iters = 0; + const t0 = Date.now(); + do { + fn(); + iters++; + } while (Date.now() - t0 < minMs && iters < maxIters); + return (Date.now() - t0) / iters; +} + +function median(values: number[]): number { + const sorted = [...values].sort((a, b) => a - b); + return sorted[(sorted.length - 1) >> 1]; +} + +function round3(value: number): number { + return Math.round(value * 1000) / 1000; +} + +// --------------------------------------------------------------------------- +// Run +// --------------------------------------------------------------------------- + +runSelfChecks(); + +// Warmup (module init, lazy paths). +encodeAggregate3(calls); +decodeAggregate3Response(respMain as `0x${string}`, BATCH_N); + +const REPS = 5; +const encMs: number[] = []; +const decMs: number[] = []; +const uintMs: number[] = []; + +for (let r = 0; r < REPS; r++) { + encMs.push(timeOp(() => encodeAggregate3(calls), 120, 40)); + decMs.push( + timeOp( + () => decodeAggregate3Response(respMain as `0x${string}`, BATCH_N), + 120, + 40, + ), + ); + const decoded = decodeAggregate3Response(respMain as `0x${string}`, BATCH_N); + const datas = decoded + .filter((x) => x.success && x.returnData.length > 2) + .map((x) => x.returnData); + uintMs.push( + timeOp( + () => { + for (let i = 0; i < datas.length; i++) { + decodeUint256(datas[i] as `0x${string}`); + } + }, + 120, + 20, + ), + ); +} + +const calldata = encodeAggregate3(calls); + +// encdec_full_ms is the primary metric: the full client path for one batch +// (encode aggregate3 -> decode response -> decodeUint256 per result). +print( + 'METRIC encdec_full_ms=' + + round3(median(encMs) + median(decMs) + median(uintMs)), +); +print('METRIC encdec_ms=' + round3(median(encMs) + median(decMs))); +print('METRIC encode_ms=' + round3(median(encMs))); +print('METRIC decode_ms=' + round3(median(decMs))); +print('METRIC decode_uint256_ms=' + round3(median(uintMs))); +print('METRIC batch_n=' + BATCH_N); +print('METRIC calldata_hex_len=' + calldata.length); +print('METRIC resp_hex_len=' + respMain.length); +print('SELF_CHECK=OK'); diff --git a/.auto/bench/templates/controller-abi.ts b/.auto/bench/templates/controller-abi.ts new file mode 100644 index 00000000000..084114d8d74 --- /dev/null +++ b/.auto/bench/templates/controller-abi.ts @@ -0,0 +1,144 @@ +// AUTO-GENERATED playground harness — vendored copy of +// packages/controller-utils/src/abi.ts (encodeFunctionData + FastAbiCoder), +// with the @metamask/utils byte helpers inlined so the Hermes bundle is +// self-contained. Semantics identical; only used off the final optimized path +// (baseline encode goes through this, matching production). +import { AbiCoder, Interface, ParamType } from '@ethersproject/abi'; +import { keccak256 } from '@ethersproject/keccak256'; + +// --- inlined @metamask/utils helpers (byte-identical semantics) --- + +function isHexString(value: unknown): value is string { + return ( + typeof value === 'string' && + value.startsWith('0x') && + value.length % 2 === 0 + ); +} + +function add0x(hex: string): string { + return hex.startsWith('0x') ? hex : `0x${hex}`; +} + +function utf8ToBytes(value: string): Uint8Array { + const bytes = new Uint8Array(value.length); + for (let i = 0; i < value.length; i++) { + bytes[i] = value.charCodeAt(i); + } + return bytes; +} + +function hexToBytes(hex: string): Uint8Array { + if (!isHexString(hex)) { + throw new Error(`Value must be a hexadecimal string, but received ${hex}`); + } + const stripped = hex.slice(2); + const bytes = new Uint8Array(stripped.length / 2); + for (let i = 0; i < bytes.length; i++) { + bytes[i] = parseInt(stripped.slice(i * 2, i * 2 + 2), 16); + } + return bytes; +} + +function bytesToHex(bytes: Uint8Array): string { + let hex = '0x'; + for (let i = 0; i < bytes.length; i++) { + hex += bytes[i].toString(16).padStart(2, '0'); + } + return hex; +} + +function concatBytes(arrays: Uint8Array[]): Uint8Array { + let total = 0; + for (const array of arrays) { + total += array.length; + } + const result = new Uint8Array(total); + let offset = 0; + for (const array of arrays) { + result.set(array, offset); + offset += array.length; + } + return result; +} + +function getChecksumAddress(address: string): string { + // EIP-55. Only used by FastAddressCoder#decode (address outputs) — not on + // the aggregate3 hot path, kept for fidelity. + const lower = address.toLowerCase(); + const nibbles = lower.slice(2); + const hash = keccak256(utf8ToBytes(nibbles)); + let out = '0x'; + for (let i = 0; i < nibbles.length; i++) { + const nibble = parseInt(hash[2 + i], 16); + const char = nibbles[i]; + out += nibble >= 8 ? char.toUpperCase() : char; + } + return out; +} + +// --- vendored from packages/controller-utils/src/abi.ts --- + +type Coder = ReturnType; +type Writer = Parameters[0]; +type Reader = Parameters[0]; + +// FastAddressCoder that skips checksumming addresses when encoding and uses the memoized `getChecksumAddress` for decoding. +class FastAddressCoder implements Coder { + name = 'address'; + + type = 'address'; + + dynamic = false; + + localName: string; + + constructor(localName: string) { + this.localName = localName; + } + + encode(writer: Writer, value: string): number { + return writer.writeValue(value); + } + + decode(reader: Reader): unknown { + const value = reader.readValue(); + const paddedHex = value.toHexString().slice(2).padStart(40); + return getChecksumAddress(add0x(paddedHex)); + } + + defaultValue(): string { + return '0x0000000000000000000000000000000000000000'; + } + + /* istanbul ignore next */ + _throwError(_message: string, _value: unknown): void { + throw new Error('Method not implemented.'); + } +} + +class FastAbiCoder extends AbiCoder { + _getCoder(param: ParamType): Coder { + if (param.type === 'address') { + return new FastAddressCoder(param.name); + } + return super._getCoder(param); + } +} + +const fastAbiCoder = new FastAbiCoder(); + +export function encodeFunctionData( + abi: Interface, + functionName: string, + values: unknown[], +): `0x${string}` { + const func = abi.getFunction(functionName); + const sigHash = hexToBytes(abi.getSighash(func)); + const encodedParams = fastAbiCoder.encode(func.inputs, values); + // @metamask/utils concatBytes implicitly runs valueToBytes on each element + // (hex string -> bytes); replicate that for the AbiCoder hex output. + return bytesToHex( + concatBytes([sigHash, hexToBytes(encodedParams)]), + ) as `0x${string}`; +} diff --git a/.auto/checks.sh b/.auto/checks.sh new file mode 100755 index 00000000000..c92576e819a --- /dev/null +++ b/.auto/checks.sh @@ -0,0 +1,9 @@ +#!/bin/bash +# Correctness checks (run on candidate keeps): MulticallClient jest suite, +# which includes the "identical calldata to regular Ethers" golden test. +set -euo pipefail +ROOT="$(git rev-parse --show-toplevel)" +cd "$ROOT" + +yarn workspace @metamask/assets-controller run jest --no-coverage \ + src/data-sources/evm-rpc-services/clients/MulticallClient.test.ts 2>&1 | tail -25 diff --git a/.auto/ideas.md b/.auto/ideas.md new file mode 100644 index 00000000000..6143827b8c6 --- /dev/null +++ b/.auto/ideas.md @@ -0,0 +1,92 @@ +# Ideas — Optimize MulticallClient aggregate3 encode/decode on Hermes + +Primary metric: `encdec_full_ms` (encode 300-call batch + decode response + +decodeUint256 per result), Hermes `-O`, median of 3 invocations. + +Engine for the numbers below: Hermes `hermes-v250829098.0.17` +(commit `3477757eb247`, HBC bytecode 98), the Hermes V1 build React Native +0.86.3 ships. macOS arm64 Release CLI, JIT off, debugger off. Parity +self-check passed on every run. Runs 1–10 in `.auto/log.jsonl` were an earlier +Static Hermes `static_h` checkout (bytecode 99); those ratios were within a +few percent of these. + +## Done (this session) + +| # | Idea | Verdict | Result | +| --- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------- | +| 1 | Hand-rolled `encodeAggregate3`: fixed-layout string assembly, hardcoded selector (asserted vs interface at load), zero Ethers on hot path | KEEP (run 2) | encode 25.4 → 0.675 ms (38×) | +| 2 | Hand-rolled `decodeAggregate3Response`: direct substring parsing following all offset words, no Result/BigNumber allocation | KEEP (run 3) | decode 18.1 → 0.30 ms (60×) | +| 3 | `decodeUint256` via native `BigInt(data.slice(0,66)).toString()` | KEEP (run 7) | uint256 5.5 → 0.2 ms (27×) | +| 4 | Rope-style `+=` encoder assembly vs array push+join | DISCARD (run 8) | tie on the earlier engine (1.125 vs 1.125); not remeasured | +| — | Metric fix | run 5 | primary metric now encdec_full_ms (was encode+decode only, missed uint256 stage) | + +Session: baseline `encdec_full_ms` = 49.0 → 1.175 (**42×**) on the React Native +0.86.3 engine. Loop converged after run 8 — micro-optimizations no longer +clear the 2% keep threshold. + +## Key learnings + +- The tuple `(address, bool, bytes)` is DYNAMIC (contains bytes), so the array + head needs one offset word PER CALL — cumulative over padded callData sizes. + Missing this was the only layout bug hit (caught by the bench parity + self-check vs stock Ethers, not by eyeballing). +- Ethers v5 `AbiCoder` cost on Hermes is dominated by: Writer numeric + conversions + hexlify per value (encode), Reader `Result` object + construction + per-word hexlify/arrayify + BN wrapping (decode). +- `@metamask/utils` v12 `concatBytes` silently converts hex strings via + `valueToBytes` — relevant when vendoring `encodeFunctionData`. +- TS7 (tsgo) removed `moduleResolution: node10` + `baseUrl`; paths patterns + must be relative; nearest `package.json` `"type"` decides ESM/CJS + (repo root is `"type": "module"` — needed a `"type": "commonjs"` marker in + the tmp bench tree). +- Metric definition matters: the first discard (run 4) was an artifact of the + primary metric not covering the uint256 stage; BigInt uint256 is 27× faster + in reality. + +## Backlog (untested — diminishing returns at ~1.1 ms total) + +- Encode: replace `parts.push` ×5 with pre-sized array index writes, or + `+=` string concat; measure (expected small). +- Decode: `parseInt` on sliced 64-char words → could scan last char for + success word; small. +- Hex LUT for byte→hex (16-entry table) instead of padStart/toString(16) + for length words; small. +- Hand-roll `encodeBalanceOf`/`encodeGetEthBalance` (per-account cache path, + not per-batch hot path in production — same account per batch): LOW value. +- Typed-array (Uint8Array) assembly instead of hex strings: would avoid + 2× char duplication but breaks the "hex passthrough" of callData and + needs bytesToHex at the end — expected NET LOSS on Hermes. +- Batch-level `buildAggregate3BalanceCalls`: skip per-call object allocation + via two parallel arrays — touches call sites; measurable? probably not vs + 0.65 ms encode. + +## Verdicts + +### viem instead of Ethers / hand-rolled codec (run 9 — measured, not adopted) + +Remeasured on Hermes V1 `hermes-v250829098.0.17` (`-O`, 300-call batch, median of 3, parity vs stock +ethers, SELF_CHECK=OK): a viem-based MulticallClient codec +(`encodeFunctionData`/`decodeFunctionResult`/module-level `parseAbi`, +pruned ABI closure = what a tree-shaken mobile bundle keeps, ~127 KB JS, +45 files): + +- viem full pipeline: **13.344 ms** (encode 3.211 / decode 8.333 / uint256 1.8) +- stock Ethers baseline: 49.043 ms → viem is **~3.7x faster than Ethers** +- hand-rolled codec (current PR): **1.175 ms** → viem is **~11x SLOWER** + +Verdict: viem is a legitimate Ethers replacement if maintainers reject +hand-rolled encoders (already in the monorepo via perps-controller, faithful +ABI semantics incl. address checksum validation), but it is NOT competitive +with the hand-rolled codec on the hot path. Keep the hand-rolled codec in +the PR; keep viem as a fallback option. Notes: needs a `node:crypto` stub +(noble hashes' old-Node adapter; the keccak/sha3 path itself is pure JS), +and it would be a NEW runtime dependency for assets-controller consumers. + +See `.auto/log.jsonl` (dashboard-compatible). Keep = committed, discard = +reverted, all decided by `.auto/run-exp.sh` against the working tree. + +## Run 10 — over-fit check (scaling sweep) + +- **Conclusion: NOT over-fit.** Correctness is generic (bounds-checked offset-following decoder, byte-parity vs Ethers for arbitrary inputs, error paths preserved). Performance is linear and flat per call across n=30→3000 (~3.3–4.0 µs/call) and nearly independent of returnData size (0.325 ms at 500 B/call vs 0.300 ms at 32 B/call). viem scales linearly in both n and bytes (n=3000 → 129 ms; 500 B → 22 ms decode). +- One honest caveat: bench addresses were all-lowercase, so Ethers/viem baselines skipped EIP-55 checksum keccak validation; with mixed-case (real-world) addresses the library baselines get *slower*, i.e. the reported 42× is a conservative lower bound. +- On-device A/B in the real mobile app closes the loop (see PR body harness instructions). diff --git a/.auto/log.jsonl b/.auto/log.jsonl new file mode 100644 index 00000000000..98548c70438 --- /dev/null +++ b/.auto/log.jsonl @@ -0,0 +1,12 @@ +{"type": "config", "name": "optimize-multicall-hermes", "metricName": "encdec_full_ms", "metricUnit": "ms", "bestDirection": "lower"} +{"run": 1, "commit": "de0e7d9fd5", "metric": 48.929, "metrics": {"encdec_ms": 43.429, "encode_ms": 25, "decode_ms": 18.429, "decode_uint256_ms": 5.5, "batch_n": 300, "encdec_full_ms": 48.929}, "status": "keep", "description": "baseline: current FastAbiCoder encode + Interface decodeFunctionResult (Hermes -O) [metric=encdec_full_ms (normalized from run-era metrics)]", "timestamp": 1792679857612, "segment": 1, "confidence": null, "asi": {}} +{"run": 2, "commit": "249a5168d1", "metric": 24.293, "metrics": {"encdec_ms": 18.793, "encode_ms": 0.65, "decode_ms": 18.143, "decode_uint256_ms": 5.5, "batch_n": 300, "calldata_hex_len": 134538, "resp_hex_len": 92738, "encdec_full_ms": 24.293}, "status": "keep", "description": "idea 1: hand-rolled aggregate3 encoder (fixed-layout string assembly, zero Ethers on encode path) [metric=encdec_full_ms (normalized from run-era metrics)]", "timestamp": 1792680253782, "segment": 1, "confidence": null, "asi": {"encoder": "string-join", "runtime": "hermes"}} +{"run": 3, "commit": "f8dd321eaa", "metric": 6.35, "metrics": {"encdec_ms": 0.9, "encode_ms": 0.65, "decode_ms": 0.25, "decode_uint256_ms": 5.45, "batch_n": 300, "calldata_hex_len": 134538, "resp_hex_len": 92738, "encdec_full_ms": 6.35}, "status": "keep", "description": "idea 2: hand-rolled aggregate3 response decoder (direct substring parsing, no Result/BigNumber allocation) [metric=encdec_full_ms (normalized from run-era metrics)]", "timestamp": 1792680372428, "segment": 1, "confidence": null, "asi": {"decoder": "substring", "runtime": "hermes"}} +{"run": 4, "commit": null, "metric": 1.15, "metrics": {"encdec_ms": 0.95, "encode_ms": 0.675, "decode_ms": 0.275, "decode_uint256_ms": 0.2, "batch_n": 300, "calldata_hex_len": 134538, "resp_hex_len": 92738, "encdec_full_ms": 1.15}, "status": "discard", "description": "idea 3: decodeUint256 via native BigInt (skip Interface/ParamType/coder lookup and BN wrapper) [metric=encdec_full_ms (normalized from run-era metrics)]", "timestamp": 1792680525305, "segment": 1, "confidence": null, "asi": {"uint256": "bigint", "runtime": "hermes"}} +{"run": 5, "commit": "caa8918735", "metric": 49.707, "metrics": {"encdec_full_ms": 49.707, "encdec_ms": 44.057, "encode_ms": 25.2, "decode_ms": 18.857, "decode_uint256_ms": 5.65, "batch_n": 300}, "status": "keep", "description": "metric fix: primary metric is now encdec_full_ms (encode+decode+decodeUint256 = full client batch path); re-measured original baseline under new metric", "timestamp": 1792680587032, "segment": 1, "confidence": null, "asi": {}} +{"run": 6, "commit": null, "metric": 1.15, "metrics": {"encdec_full_ms": 1.15, "encdec_ms": 0.95, "encode_ms": 0.675, "decode_ms": 0.275, "decode_uint256_ms": 0.2, "batch_n": 300, "calldata_hex_len": 134538, "resp_hex_len": 92738}, "status": "discard", "description": "idea 3 (retry on full-pipeline metric): decodeUint256 via native BigInt (skip Interface/ParamType/coder lookup and BN wrapper)", "timestamp": 1792680594963, "segment": 1, "confidence": null, "asi": {"uint256": "bigint", "runtime": "hermes"}} +{"run":7,"commit":"9388481802","metric":1.125,"metrics":{"encdec_full_ms":1.125,"encdec_ms":0.95,"encode_ms":0.675,"decode_ms":0.275,"decode_uint256_ms":0.2,"batch_n":300,"calldata_hex_len":134538,"resp_hex_len":92738},"status":"keep","description":"idea 3 (retry, normalized log): decodeUint256 via native BigInt (skip Interface/ParamType/coder lookup and BN wrapper)","timestamp":1792680626033,"segment":1,"confidence":null,"asi":{"uint256":"bigint","runtime":"hermes"}} +{"run":8,"commit":null,"metric":1.125,"metrics":{"encdec_full_ms":1.125,"encdec_ms":0.925,"encode_ms":0.65,"decode_ms":0.275,"decode_uint256_ms":0.2,"batch_n":300,"calldata_hex_len":134538,"resp_hex_len":92738},"status":"discard","description":"idea 4: rope-style += string assembly in encoder (Hermes string concat) vs array push+join","timestamp":1792680891065,"segment":1,"confidence":null,"asi":{"encoder":"rope-concat","runtime":"hermes"}} +{"run":9,"commit":null,"metric":11.853,"status":"measure","description":"feasibility: MulticallClient on viem instead of Ethers/hand-rolled (pruned viem ABI closure vendored pre-compiled, tree-shaken-equivalent; parity vs stock ethers SELF_CHECK=OK; measurement-only, no product change). Result: viem encdec_full 11.853 ms vs stock ethers 49.707 ms (~4.2x faster) but ~10.5x SLOWER than hand-rolled 1.125 ms. encode 2.9 / decode 7.353 / uint256 1.6. Closure: 45 files, ~127 KB JS; node:crypto stub needed (noble hashes old-Node adapter; keccak path pure JS). viem already in monorepo via perps-controller, but new runtime dep for assets-controller consumers.","metrics":{"encdec_full_ms":11.853,"encdec_ms":10.253,"encode_ms":2.9,"decode_ms":7.353,"decode_uint256_ms":1.6,"batch_n":300,"calldata_hex_len":134538,"resp_hex_len":92738},"timestamp":1792683743252,"segment":1,"confidence":null,"asi":{"codec":"viem","runtime":"hermes","variant":"bench-viem"}} +{"ts": "2026-10-22T16:23:49.933728+00:00", "run": 10, "status": "measure", "keep": false, "idea": "scaling sweep: verify hand-rolled codec is not over-fit to n=300 bench shape", "metrics": {"handrolled": {"n30_encdec_full_ms": 0.1, "n300_encdec_full_ms": 1.125, "n1500_encdec_full_ms": 5.686, "n3000_encdec_full_ms": 11.167, "n300_ret500B_decode_ms": 0.325}, "viem": {"n300_encdec_full_ms": 11.853, "n3000_encdec_full_ms": 116.075, "n300_ret500B_decode_ms": 20.0}, "stock_ethers": {"n300_encdec_full_ms": 49.707}}, "runtime": "hermes -O", "asi": {"purpose": "overfit-check", "variant": "batch_n and ret_bytes sweep"}, "verdict": "per-call cost flat ~3.3-3.8us across n=30..3000 (linear, not tuned to n=300); hand-rolled decode nearly content-independent (+18% for 15.6x returnData bytes) vs viem linear in bytes (2.7x). Not over-fit; device A/B pending."} +{"ts": "2026-10-23T10:12:00Z", "run": 11, "status": "measure", "keep": false, "idea": "remeasure on React Native 0.86.3 Hermes V1 (tag hermes-v250829098.0.17, commit 3477757eb247, HBC bytecode 98). macOS arm64 Release CLI, JIT off, debugger off, hermes -O. No product change. SELF_CHECK=OK on every run.", "metrics": {"handrolled": {"n30_encdec_full_ms": 0.1, "n300_encdec_full_ms": 1.175, "n300_encode_ms": 0.675, "n300_decode_ms": 0.3, "n300_decode_uint256_ms": 0.2, "n1500_encdec_full_ms": 5.886, "n3000_encdec_full_ms": 11.968, "n300_ret500B_decode_ms": 0.325}, "viem": {"n300_encdec_full_ms": 13.344, "n300_encode_ms": 3.211, "n300_decode_ms": 8.333, "n300_decode_uint256_ms": 1.8, "n3000_encdec_full_ms": 128.893, "n300_ret500B_decode_ms": 22.167}, "stock_ethers": {"n300_encdec_full_ms": 49.043, "n300_encode_ms": 25.4, "n300_decode_ms": 18.143, "n300_decode_uint256_ms": 5.5}}, "runtime": "hermes-v250829098.0.17 -O", "asi": {"purpose": "engine-match", "engine": "hermes-v250829098.0.17", "commit": "3477757eb2475555cf8d8df24bfb1deb0613880d", "bytecode": 98}, "verdict": "42x vs stock ethers (49.043/1.175). viem 13.344 ms is ~3.7x faster than ethers and ~11x slower than hand-rolled. Per-call cost flat ~3.3-4.0us across n=30..3000. Decode 0.300 ms at 32B vs 0.325 ms at 500B. Not over-fit. No impl change."} diff --git a/.auto/logrun.mjs b/.auto/logrun.mjs new file mode 100644 index 00000000000..f2c2ff164e4 --- /dev/null +++ b/.auto/logrun.mjs @@ -0,0 +1,87 @@ +#!/usr/bin/env node +// .auto/log.jsonl writer/reader — dashboard-compatible entries: +// {"run":N,"commit":sha|null,"metric":X,"metrics":{...},"status":"keep|discard|crash|checks_failed", +// "description":"...","timestamp":ms,"segment":1,"confidence":null,"asi":{...}} +import fs from 'node:fs'; +import path from 'node:path'; + +const ROOT = process.cwd(); +const LOG = path.join(ROOT, '.auto/log.jsonl'); + +function readEntries() { + if (!fs.existsSync(LOG)) return []; + return fs + .readFileSync(LOG, 'utf8') + .split('\n') + .filter(Boolean) + .map((line) => JSON.parse(line)); +} + +function writeEntry(entry) { + fs.appendFileSync(LOG, JSON.stringify(entry) + '\n'); +} + +const command = process.argv[2]; + +if (command === 'init') { + // name, metricName, metricUnit, bestDirection from argv + const [, , , name, metricName, metricUnit, bestDirection] = process.argv; + if (fs.existsSync(LOG)) { + throw new Error('.auto/log.jsonl already exists'); + } + writeEntry({ + type: 'config', + name, + metricName, + metricUnit, + bestDirection, + }); + console.log( + `init: ${name} / ${metricName} (${metricUnit}, ${bestDirection})`, + ); +} else if (command === 'best') { + const runs = readEntries().filter( + (e) => e.run !== undefined && e.status === 'keep', + ); + if (runs.length === 0) { + console.log('null'); + } else { + let best = runs[0]; + for (const r of runs) { + if (r.metric < best.metric) best = r; + } + console.log( + JSON.stringify({ + run: best.run, + metric: best.metric, + description: best.description, + }), + ); + } +} else if (command === 'append') { + const args = process.argv.slice(3); + const get = (flag) => { + const i = args.indexOf(flag); + return i === -1 ? undefined : args[i + 1]; + }; + const entry = { + run: Number(get('--run')), + commit: get('--commit') ?? null, + metric: Number(get('--metric')), + metrics: JSON.parse(get('--metrics') ?? '{}'), + status: get('--status'), + description: get('--desc') ?? '', + timestamp: Date.now(), + segment: 1, + confidence: null, + asi: JSON.parse(get('--asi') ?? '{}'), + }; + writeEntry(entry); + console.log( + `log: run ${entry.run} ${entry.status} metric=${entry.metric} (desc: ${entry.description})`, + ); +} else { + console.log( + 'usage: logrun.mjs init | best | append --run N --status S --desc D --metric M [--metrics JSON] [--asi JSON] [--commit SHA]', + ); +} diff --git a/.auto/measure-viem.sh b/.auto/measure-viem.sh new file mode 100755 index 00000000000..443908b10ca --- /dev/null +++ b/.auto/measure-viem.sh @@ -0,0 +1,36 @@ +#!/bin/bash +# Autoresearch benchmark — VIEM VARIANT: what would MulticallClient's numbers +# look like if the Ethers usage were replaced with viem? +# Same structure as measure.sh; builds the bundle-viem.js entry. +set -euo pipefail +ROOT="$(git rev-parse --show-toplevel)" +cd "$ROOT" + +HERMES="${HERMES_BIN:-/Users/prithpalsooriya/.kandev/quick-chat/c1b1839c-62b5-4776-9d7e-5eb1ae664862/hermes/build/bin/hermes}" + +# 1) Build (prepare vendors the pruned viem ABI closure into tmp/vendor). +node .auto/bench/prepare.mjs "$ROOT" +node_modules/.bin/tsc -p .auto/bench/tmp/tsconfig.json > .auto/bench/tsc.log 2>&1 || true +BENCH_ENTRY=app/bench-viem.js node .auto/bench/bundle.mjs "$ROOT" +node --check .auto/bench/bundle-bench-viem.js + +# 2) Run under Hermes (3 invocations) +RUNS=3 +HERMES_ARGS=('-O') +for i in $(seq 1 $RUNS); do + if ! "$HERMES" "${HERMES_ARGS[@]}" .auto/bench/bundle-bench-viem.js > ".auto/bench/viem_run_$i.out" 2>&1; then + echo "--- hermes crash (viem run $i) ---" >&2 + tail -15 ".auto/bench/viem_run_$i.out" >&2 + exit 1 + fi +done + +# 3) Parity self-check gate +if ! grep -q '^SELF_CHECK=OK$' .auto/bench/viem_run_*.out; then + echo "--- parity self-check failed (viem) ---" >&2 + grep -h '^SELF_CHECK=FAIL' .auto/bench/viem_run_*.out >&2 || tail -5 ".auto/bench/viem_run_1.out" >&2 + exit 1 +fi + +# 4) Median across invocations +node .auto/bench/median.mjs .auto/bench/viem_run_1.out .auto/bench/viem_run_2.out .auto/bench/viem_run_3.out diff --git a/.auto/measure.sh b/.auto/measure.sh new file mode 100755 index 00000000000..4463ec7c8b2 --- /dev/null +++ b/.auto/measure.sh @@ -0,0 +1,36 @@ +#!/bin/bash +# Autoresearch benchmark: builds the Hermes bundle from the CURRENT +# MulticallClient.ts source and measures encodeAggregate3 + +# decodeAggregate3Response. Emits `METRIC name=value` lines. +# Exit 0 only if build + parity self-checks + runs all succeed. +set -euo pipefail +ROOT="$(git rev-parse --show-toplevel)" +cd "$ROOT" + +HERMES="${HERMES_BIN:-/Users/prithpalsooriya/.kandev/quick-chat/c1b1839c-62b5-4776-9d7e-5eb1ae664862/hermes/build/bin/hermes}" + +# 1) Build (includes fast failure on syntax errors / marker drift) +.auto/bench/build.sh > /dev/null + +# 2) Run under Hermes (3 invocations; in-process adaptive timing + medians) +RUNS=3 +HERMES_ARGS=('-O') +for i in $(seq 1 $RUNS); do + if ! "$HERMES" "${HERMES_ARGS[@]}" .auto/bench/bundle.js > ".auto/bench/run_$i.out" 2>&1; then + echo "--- hermes crash (run $i) ---" >&2 + tail -5 ".auto/bench/run_$i.out" >&2 + echo "METRIC status=crash" + exit 1 + fi +done + +# 3) Parity self-check gate (all invocations must pass) +if ! grep -q '^SELF_CHECK=OK$' .auto/bench/run_*.out; then + echo "--- parity self-check failed ---" >&2 + grep -h '^SELF_CHECK=FAIL' .auto/bench/run_*.out || tail -5 .auto/bench/run_1.out >&2 + echo "METRIC status=self_check_failed" + exit 1 +fi + +# 4) Median across invocations +node .auto/bench/median.mjs .auto/bench/run_1.out .auto/bench/run_2.out .auto/bench/run_3.out diff --git a/.auto/prompt.md b/.auto/prompt.md new file mode 100644 index 00000000000..e421c5a6502 --- /dev/null +++ b/.auto/prompt.md @@ -0,0 +1,98 @@ +# Autoresearch: Optimize Multicall3 encodeAggregate3 / decodeAggregate3 on Hermes + +## Objective + +`encodeAggregate3` and `decodeAggregate3Response` in +`packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.ts` +are extremely slow on Hermes (MetaMask mobile / RN): on Android a single 300-call +batch takes ~4s to encode and ~4s to decode. Optimize them for Hermes while +keeping **byte-identical output** and all tests green. + +The benchmark extracts the REAL source (ABI constants, interface singletons, +encode/decode utilities) from `MulticallClient.ts` on every build, compiles it +with the vendored Ethers closure into a single self-contained JS bundle, and +runs it under `hermes/build/bin/hermes` (the local Static-Hermes-style CLI +binary, no `require`, single file only). + +## Metrics + +- **Primary**: `encdec_ms` (ms, lower is better) — per-op cost of one + `encodeAggregate3(calls)` + one `decodeAggregate3Response(resp, 300)` cycle on + a realistic 300-call batch (app default `maxCallsPerBatch`). Adaptive timing + loop (≥120ms per measurement), median of 5 in-process reps, median of 3 + Hermes process invocations. +- **Secondary**: `encode_ms`, `decode_ms`, `decode_uint256_ms` (300 items), + `calldata_hex_len`, `resp_hex_len`. + +## How to Run + +`./.auto/measure.sh` — builds the bundle (prepare → tsc → bundle) and runs it +under Hermes; outputs `METRIC name=value` lines. Exit non-zero on crash or +parity self-check failure (`SELF_CHECK=FAIL`). + +Experiment runner (mimics run_experiment + log_experiment + keep/discard): + +``` +.auto/run-exp.sh "" [asi key=value ...] +``` + +- improved → runs `.auto/checks.sh` (jest MulticallClient tests) → commit `keep` +- not improved / crash / checks_failed → reverts `MulticallClient.ts` +- appends a dashboard-compatible entry to `.auto/log.jsonl` + +Hermes binary: `/Users/prithpalsooriya/.kandev/quick-chat/c1b1839c-62b5-4776-9d7e-5eb1ae664862/hermes/build/bin/hermes` +(override with `HERMES_BIN`). + +## Files in Scope + +- `packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.ts` + — the ONLY production file that may be modified (encode/decode utilities + section; interface singletons; ABI constants). +- Everything under `.auto/` — benchmark harness, logs, ideas. + +## Off Limits + +- Any other production file in the monorepo. Do NOT add new package source + files (keeps the discard path safe: `git checkout -- MulticallClient.ts`). +- The jest test file may NOT be modified to make tests pass. +- Do not change exported behavior: `encodeAggregate3` output must stay + byte-identical to stock Ethers; `decodeAggregate3Response` / + `decodeUint256` results identical (self-check + jest golden tests enforce). + +## Constraints + +- `.auto/checks.sh` must pass for keeps: jest suite for MulticallClient + (includes the "identical calldata to regular Ethers" golden test). +- The in-bundle parity self-check must pass every run (encode vs stock + `Interface#encodeFunctionData`, decode vs stock `decodeFunctionResult`, + edge cases: empty calls, `'0x'` callData, odd/long returnData, count + mismatch throws). +- No new runtime dependencies in `MulticallClient.ts` (stdlib/ethers only — + prefer zero-dependency hand-rolled code for the hot paths). +- No Node-only APIs (this runs on Hermes). + +## Harness notes + +- `.auto/bench/prepare.mjs`: extracts from `MulticallClient.ts` between the + markers — slice A: `const MULTICALL3_ABI = [` up to the `// ===` above + `// CONSTANTS`; slice B: the `// ===` above + `// ENCODING/DECODING UTILITIES (using @ethersproject/abi)` up to the `// ===` + above `// MULTICall CLIENT`. **Keep those section headers intact** when + editing the source, or fix prepare.mjs. +- Ethers closure is compiled from `node_modules/@ethersproject/*/src.ts` (the + npm packages ship TS sources). `@metamask/controller-utils` + `encodeFunctionData` (FastAbiCoder) is vendored verbatim at + `.auto/bench/templates/controller-abi.ts` with inlined @metamask/utils byte + helpers. +- Baseline path: `encodeAggregate3` → `encodeFunctionData` (FastAbiCoder + + ethers `Writer`) and `decodeAggregate3Response` → ethers + `Interface#decodeFunctionResult` (generic `Reader`, per-word `hexlify`, + `arrayify`, object churn). + +## What's Been Tried + +(run 0) Baseline: untouched source. See `.auto/log.jsonl` for numbers. + +## Ideas backlog + +See `.auto/ideas.md`. diff --git a/.auto/run-exp.sh b/.auto/run-exp.sh new file mode 100755 index 00000000000..48d33170735 --- /dev/null +++ b/.auto/run-exp.sh @@ -0,0 +1,97 @@ +#!/bin/bash +# Autoresearch experiment runner (manual mimic of run_experiment + +# log_experiment keep/discard with auto-commit / auto-revert). +# +# Usage: .auto/run-exp.sh "" [asi key=value ...] +# +# - Runs .auto/measure.sh against the CURRENT working-tree MulticallClient.ts. +# - If the primary metric improves vs session best (and checks pass) -> keep: +# commit the source change. Otherwise -> discard: revert it. +# - Every run is logged to .auto/log.jsonl with verdict + metrics + asi. +set -euo pipefail +ROOT="$(git rev-parse --show-toplevel)" +cd "$ROOT" + +if [ $# -lt 1 ]; then + echo "usage: .auto/run-exp.sh \"\" [asi key=value ...]" >&2 + exit 2 +fi +DESC="$1"; shift || true +ASI_JSON=$(node -e " +const parts = process.argv.slice(1).filter(Boolean); +const o = {}; +for (const p of parts) { const i = p.indexOf('='); if (i > 0) o[p.slice(0, i)] = p.slice(i + 1); } +console.log(JSON.stringify(o)); +" "$@") + +SRCFILE=packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.ts + +# Scope guard: only MulticallClient.ts (plus untracked .auto/*) may be dirty. +DIRTY=$(git status --porcelain | grep -v '^??' | grep -v "$SRCFILE" || true) +if [ -n "$DIRTY" ]; then + echo "ABORT: unexpected dirty tracked files:" >&2 + echo "$DIRTY" >&2 + exit 2 +fi + +revert_source() { + git checkout -- "$SRCFILE" 2>/dev/null || true +} + +# Run the benchmark ----------------------------------------------------------- +if ! OUT=$(.auto/measure.sh 2>&1); then + echo "$OUT" | tail -10 >&2 + N=$(grep -c '"run":' .auto/log.jsonl 2>/dev/null || echo 0) + node .auto/logrun.mjs append --run "$((N + 1))" --status crash --desc "$DESC" --metric 0 \ + --metrics '{}' --asi "$ASI_JSON" + revert_source + echo "VERDICT=crash" + exit 1 +fi + +METRICS=$(echo "$OUT" | grep '^METRIC ' | sed 's/^METRIC //' | node -e " +const lines = require('fs').readFileSync(0, 'utf8').trim().split('\n'); +const o = {}; +for (const l of lines) { const i = l.indexOf('='); o[l.slice(0, i)] = Number(l.slice(i + 1)); } +console.log(JSON.stringify(o)); +") +ENCDEC=$(echo "$OUT" | awk -F= '/^METRIC encdec_full_ms=/{print $2}') +if [ -z "$ENCDEC" ] || [ "$ENCDEC" = "null" ]; then + echo "no encdec_full_ms in output:" >&2; echo "$OUT" >&2 + exit 1 +fi + +N=$(grep -c '"run":' .auto/log.jsonl 2>/dev/null || echo 0) +RUN_ID=$((N + 1)) +BEST=$(node .auto/logrun.mjs best) +BEST_METRIC=$(node -e "const j=JSON.parse(process.argv[1]); console.log(j === null ? '' : j.metric)" "$BEST") + +# Verdict: improved = strictly better by > 2% (noise guard) ------------------ +KEEP_THRESHOLD=$(node -e "console.log(($BEST_METRIC || 1e18) * 0.98)") +IMPROVED=no +if [ "$(node -e "console.log($ENCDEC < $KEEP_THRESHOLD ? 'yes' : 'no')")" = "yes" ]; then + IMPROVED=yes +fi + +if [ "$IMPROVED" = "yes" ]; then + if CHECKS_OUT=$(.auto/checks.sh 2>&1); then + git add "$SRCFILE" + git commit -q -m "autoresearch(exp $RUN_ID): $DESC — encdec_ms ${BEST_METRIC:-baseline} -> $ENCDEC" + SHA=$(git rev-parse --short HEAD) + node .auto/logrun.mjs append --run "$RUN_ID" --status keep --desc "$DESC" \ + --metric "$ENCDEC" --metrics "$METRICS" --asi "$ASI_JSON" --commit "$SHA" + echo "$CHECKS_OUT" | tail -3 + echo "VERDICT=keep exp=$RUN_ID encdec_ms=$ENCDEC (prev best ${BEST_METRIC:-none}) commit=$SHA" + else + echo "$CHECKS_OUT" | tail -20 >&2 + node .auto/logrun.mjs append --run "$RUN_ID" --status checks_failed --desc "$DESC" \ + --metric "$ENCDEC" --metrics "$METRICS" --asi "$ASI_JSON" + revert_source + echo "VERDICT=checks_failed exp=$RUN_ID encdec_ms=$ENCDEC (reverted)" + fi +else + node .auto/logrun.mjs append --run "$RUN_ID" --status discard --desc "$DESC" \ + --metric "$ENCDEC" --metrics "$METRICS" --asi "$ASI_JSON" + revert_source + echo "VERDICT=discard exp=$RUN_ID encdec_ms=$ENCDEC (best ${BEST_METRIC:-none})" +fi diff --git a/oxlint-suppressions.json b/oxlint-suppressions.json index c49310c43a8..fc31d403d58 100644 --- a/oxlint-suppressions.json +++ b/oxlint-suppressions.json @@ -657,12 +657,6 @@ } }, "packages/assets-controller/src/data-sources/evm-rpc-services/clients/MulticallClient.ts": { - "typescript/no-unsafe-call": { - "count": 1 - }, - "typescript/no-unsafe-member-access": { - "count": 1 - }, "typescript/no-unsafe-return": { "count": 1 } @@ -6127,4 +6121,4 @@ "count": 1 } } -} +} \ No newline at end of file diff --git a/oxlint.config.ts b/oxlint.config.ts index 3c6a1ad9df0..29d9d3f9a6c 100644 --- a/oxlint.config.ts +++ b/oxlint.config.ts @@ -28,6 +28,8 @@ export default createConfig({ '.skills-cache/**', '.yarn/**', 'merged-packages/**', + // Temporary autoresearch playground; removed before merge. + '.auto/**', 'packages/wallet-framework-docs/site/build/**', ], diff --git a/packages/assets-controller/CHANGELOG.md b/packages/assets-controller/CHANGELOG.md index 8b72702fd8e..720b5282eba 100644 --- a/packages/assets-controller/CHANGELOG.md +++ b/packages/assets-controller/CHANGELOG.md @@ -7,8 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added + +- Added an experimental aggregate3 codec selection API for `MulticallClient`: `setAggregate3CodecVariant`, `getAggregate3Codec`, and `getActiveAggregate3Codec` (exported from `@metamask/assets-controller`), plus an optional `aggregate3Codec` client option, allowing consumers to switch the Multicall3 batch codec between the hand-rolled default, viem, and stock Ethers implementations. Intended for on-device performance comparison; the default remains the hand-rolled codec ([#11010](https://github.com/MetaMask/core/pull/11010)) + ### Changed +- Replaced the generic Ethers ABI encoding/decoding used by `MulticallClient` for Multicall3 `aggregate3` batches with hand-rolled fixed-layout codecs: `encodeAggregate3` and `decodeAggregate3Response` now build and parse calldata/responses with direct string operations (and `decodeUint256` with native `BigInt`), producing byte-identical output to Ethers with matching error behavior for malformed data and result-count mismatches, while making 300-call multicall batches roughly 42× faster to encode/decode on the Hermes V1 engine shipped with React Native 0.86.3 (`hermes-v250829098.0.17`) ([#11010](https://github.com/MetaMask/core/pull/11010)) - 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/package.json b/packages/assets-controller/package.json index 1044c1cfbb4..6151878b79d 100644 --- a/packages/assets-controller/package.json +++ b/packages/assets-controller/package.json @@ -82,7 +82,8 @@ "@metamask/utils": "^12.0.0", "async-mutex": "^0.5.0", "bignumber.js": "^9.1.2", - "lodash-es": "^4.18.1" + "lodash-es": "^4.18.1", + "viem": "^2.56.8" }, "devDependencies": { "@metamask/auto-changelog": "^6.2.1", diff --git a/packages/assets-controller/src/data-sources/RpcDataSource.ts b/packages/assets-controller/src/data-sources/RpcDataSource.ts index baceaa24158..f84e10854a3 100644 --- a/packages/assets-controller/src/data-sources/RpcDataSource.ts +++ b/packages/assets-controller/src/data-sources/RpcDataSource.ts @@ -48,6 +48,7 @@ import type { } from './AbstractDataSource.js'; import { BalanceFetcher, + getActiveAggregate3Codec, isStakingContractAssetId, MulticallClient, TokenDetector, @@ -304,6 +305,7 @@ export class RpcDataSource extends AbstractDataSource< hexToNumber(hexChainId).toString(), ), )?.contracts?.multicall3, + aggregate3Codec: getActiveAggregate3Codec(), }); // Initialize BalanceFetcher with polling interval 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 5f8d345369d..0cb723e37fe 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 @@ -8,6 +8,12 @@ import type { ChainId, Provider, } from '../types/index.js'; +import { + getActiveAggregate3Codec, + getAggregate3Codec, + setAggregate3CodecVariant, +} from './aggregate3Codecs.js'; +import type { Aggregate3CodecVariant } from './aggregate3Codecs.js'; import { decodeAggregate3Response, encodeAggregate3, @@ -1011,6 +1017,87 @@ describe('encodeAggregate3', () => { expect(encodeAggregate3(calls)).toBe(expected); }); + + it('should throw for a target without a 0x prefix', () => { + const calls = [ + { + target: + '1234567890123456789012345678901234567890' as unknown as Address, + allowFailure: true, + callData: '0x' as Hex, + }, + ]; + + expect(() => encodeAggregate3(calls)).toThrow( + 'invalid address value: 1234567890123456789012345678901234567890', + ); + }); + + it('should throw for a non-hex target', () => { + const calls = [ + { + target: '0xnothex' as unknown as Address, + allowFailure: true, + callData: '0x' as Hex, + }, + ]; + + expect(() => encodeAggregate3(calls)).toThrow( + 'invalid address value: 0xnothex', + ); + }); + + it('should throw for an oversized target', () => { + const calls = [ + { + target: `0x${'12'.repeat(33)}` as unknown as Address, + allowFailure: true, + callData: '0x' as Hex, + }, + ]; + + expect(() => encodeAggregate3(calls)).toThrow( + `invalid address value: 0x${'12'.repeat(33)}`, + ); + }); + + it('should throw for callData without a 0x prefix', () => { + const calls = [ + { + target: TEST_ACCOUNT, + allowFailure: true, + callData: '70a08231' as string as Hex, + }, + ]; + + expect(() => encodeAggregate3(calls)).toThrow( + 'invalid bytes value: 70a08231', + ); + }); + + it('should throw for odd-length callData', () => { + const calls = [ + { + target: TEST_ACCOUNT, + allowFailure: true, + callData: '0xabc', + }, + ]; + + expect(() => encodeAggregate3(calls)).toThrow('invalid bytes value: 0xabc'); + }); + + it('should throw for non-hex callData', () => { + const calls = [ + { + target: TEST_ACCOUNT, + allowFailure: true, + callData: '0xzz', + }, + ]; + + expect(() => encodeAggregate3(calls)).toThrow('invalid bytes value: 0xzz'); + }); }); describe('decodeAggregate3Response', () => { @@ -1051,4 +1138,241 @@ describe('decodeAggregate3Response', () => { 'Expected 2 results, got 1', ); }); + + it('should throw for data without a 0x prefix', () => { + const mockResponse = buildMockAggregate3Response([ + { success: true, balance: '100' }, + ]); + + expect(() => + decodeAggregate3Response(mockResponse.slice(2) as Hex, 1), + ).toThrow(`invalid response data value: ${mockResponse.slice(2)}`); + }); + + it('should throw for a response with non-hex words', () => { + const garbage = `0x${'z'.repeat(64)}`; + + expect(() => decodeAggregate3Response(garbage as Hex, 0)).toThrow( + 'aggregate3 response contains a non-hex word', + ); + }); + + it('should throw for a truncated response', () => { + const mockResponse = buildMockAggregate3Response([ + { success: true, balance: '100' }, + ]); + // Cut off the final byte of the last returnData word. + const truncated = mockResponse.slice(0, -2) as Hex; + + expect(() => decodeAggregate3Response(truncated, 1)).toThrow( + 'aggregate3 response data length out-of-bounds', + ); + }); + + it('should return lowercased returnData for a mixed-case response', () => { + const mockResponse = buildMockAggregate3Response([ + { success: true, balance: '100' }, + ]); + + const result = decodeAggregate3Response( + `0x${mockResponse.slice(2).toUpperCase()}`, + 1, + ); + + expect(result).toHaveLength(1); + expect(result[0].success).toBe(true); + expect(result[0].returnData).toMatch(/^0x[0-9a-f]*$/u); + }); +}); + +describe('aggregate3 codec variants', () => { + const variants: Aggregate3CodecVariant[] = ['handrolled', 'viem', 'ethers']; + + const referenceInterface = new Interface([ + 'function aggregate3((address target, bool allowFailure, bytes callData)[] calls) payable returns ((bool success, bytes returnData)[])', + 'function balanceOf(address account) view returns (uint256)', + ]); + + const sampleCalls = [ + { + target: TEST_TOKEN_1, + allowFailure: false, + callData: + '0x70a082310000000000000000000000001234567890123456789012345678901234567890' as Hex, + }, + { + target: TEST_TOKEN_2, + allowFailure: true, + callData: '0x' as Hex, + }, + { + target: ZERO_ADDRESS, + allowFailure: false, + callData: '0x82ad56cb' as Hex, + }, + { + target: '0x1111111111111111111111111111111111111111' as Address, + allowFailure: true, + callData: `0x${'ab'.repeat(33)}`, + }, + ]; + + const edgeCallSets = [ + [], + [{ target: ZERO_ADDRESS, allowFailure: true, callData: '0x' as Hex }], + [ + { + target: '0x2222222222222222222222222222222222222222' as Address, + allowFailure: false, + callData: '0xab' as Hex, + }, + ], + ]; + + it.each(variants)( + '%s: encodes byte-identically to the Ethers reference', + (variant) => { + const codec = getAggregate3Codec(variant); + const expected = referenceInterface.encodeFunctionData('aggregate3', [ + sampleCalls, + ]); + expect(codec.encodeAggregate3(sampleCalls)).toBe(expected); + }, + ); + + it.each(variants)( + '%s: encodes edge shapes byte-identically to the Ethers reference', + (variant) => { + const codec = getAggregate3Codec(variant); + for (const calls of edgeCallSets) { + const expected = referenceInterface.encodeFunctionData('aggregate3', [ + calls, + ]); + expect(codec.encodeAggregate3(calls)).toBe(expected); + } + }, + ); + + it.each(variants)( + '%s: decodes responses identically to the Ethers reference', + (variant: Aggregate3CodecVariant): void => { + const codec = getAggregate3Codec(variant); + const tuples: [boolean, string][] = [ + [true, `0x${'ab'.repeat(32)}`], + [false, '0x'], + [true, `0x${'cd'.repeat(31)}`], + [true, `0x${'ef'.repeat(100)}`], + [true, `0x${'12'.repeat(64)}`], + ]; + const response = defaultAbiCoder.encode( + ['(bool success, bytes returnData)[]'], + [tuples], + ); + + const decoded = codec.decodeAggregate3Response(response as Hex, 5); + const reference = referenceInterface.decodeFunctionResult( + 'aggregate3', + response, + )[0] as { success: boolean; returnData: string }[]; + + expect(decoded).toHaveLength(reference.length); + for (let i = 0; i < decoded.length; i++) { + expect(decoded[i].success).toBe(reference[i].success); + expect(decoded[i].returnData.toLowerCase()).toBe( + reference[i].returnData.toLowerCase(), + ); + } + }, + ); + + it.each(variants)( + '%s: throws the count-mismatch error on wrong result count', + (variant) => { + const codec = getAggregate3Codec(variant); + const response = defaultAbiCoder.encode( + ['(bool success, bytes returnData)[]'], + [[[true, '0x']]], + ); + expect(() => codec.decodeAggregate3Response(response as Hex, 2)).toThrow( + 'Expected 2 results, got 1', + ); + }, + ); + + it.each(variants)( + '%s: decodes uint256 balances identically to the Ethers reference', + (variant: Aggregate3CodecVariant): void => { + const codec = getAggregate3Codec(variant); + const words = [ + `0x${'0'.repeat(64)}`, + `0x${BigInt(123456789012345).toString(16).padStart(64, '0')}`, + `0x${'f'.repeat(64)}`, + ]; + for (const word of words) { + const reference = ( + referenceInterface.decodeFunctionResult('balanceOf', word)[0] as { + toString(): string; + } + ).toString(); + expect(codec.decodeUint256(word as Hex)).toBe(reference); + } + // Empty and too-short inputs are treated as zero by every variant. + expect(codec.decodeUint256('0x')).toBe('0'); + expect(codec.decodeUint256('0x1234')).toBe('0'); + }, + ); + + it('setAggregate3CodecVariant switches the active codec', () => { + const initial = getActiveAggregate3Codec(); + setAggregate3CodecVariant('viem'); + try { + expect(getActiveAggregate3Codec()).toBe(getAggregate3Codec('viem')); + } finally { + setAggregate3CodecVariant('handrolled'); + expect(getActiveAggregate3Codec()).toBe(initial); + } + }); + + describe('MulticallClient codec injection', () => { + const buildRequests = (): BalanceOfRequest[] => [ + { tokenAddress: TEST_TOKEN_1, accountAddress: TEST_ACCOUNT }, + { tokenAddress: TEST_TOKEN_2, accountAddress: TEST_ACCOUNT }, + ]; + + it.each(variants)( + 'produces identical responses through the full client path with the %s codec', + async (variant: Aggregate3CodecVariant): Promise => { + const codec = getAggregate3Codec(variant); + + const mockResponse = buildMockAggregate3Response([ + { success: true, balance: '1000000000' }, + { success: true, balance: '2000000000' }, + ]); + + const provider = createMockProvider(); + provider.call.mockResolvedValue(mockResponse); + + const result = await new MulticallClient({ + getProvider: (): Provider => provider, + getMulticall3AddressForChain: (): undefined => undefined, + aggregate3Codec: codec, + }).batchBalanceOf(MAINNET_CHAIN_ID, buildRequests()); + + expect(result).toStrictEqual([ + { + tokenAddress: TEST_TOKEN_1, + accountAddress: TEST_ACCOUNT, + success: true, + balance: '1000000000', + }, + { + tokenAddress: TEST_TOKEN_2, + accountAddress: TEST_ACCOUNT, + success: true, + balance: '2000000000', + }, + ]); + }, + ); + }); }); 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..19c9b586167 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 @@ -470,28 +470,164 @@ function buildAggregate3BalanceCalls( }); } +/** Selector (sighash) of the Multicall3 `aggregate3` function, without `0x` prefix. */ +const AGGREGATE3_SELECTOR = '82ad56cb'; + +// 32-byte words (64 hex chars, no `0x` prefix) of the fixed aggregate3 +// calldata layout. The `calls` argument is the only (dynamic) argument, so +// its offset word is the constant 0x20; each (address, bool, bytes) tuple +// has exactly three static words, so each tuple's callData offset word is +// the constant 0x60. +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`; + +/** Hex string body (lowercase, no `0x` prefix). */ +const LOWERCASE_HEX_RE = /^[0-9a-f]*$/u; + +// Fail fast at module load if the vendored ABI ever disagrees with the +// selector this encoder hard-codes, instead of producing corrupt calldata. +if ( + multicall3Interface.getSighash( + multicall3Interface.getFunction('aggregate3'), + ) !== `0x${AGGREGATE3_SELECTOR}` +) { + throw new Error( + 'Multicall3 aggregate3 sighash changed; hand-rolled encoder is stale', + ); +} + /** * Encode a Multicall3 aggregate3 call. * + * Hand-rolled ABI encoding for the fixed `aggregate3` calldata layout + * (byte-identical to the generic @ethersproject/abi encoder for valid + * inputs, but far faster on Hermes, where the generic Writer path — with + * its per-value numeric conversions — dominates encode time): + * + * ```text + * selector 4 bytes + * offset to `calls` array data 32 bytes (constant 0x20) + * array length (call count) 32 bytes + * offset to tuple 0 32 bytes (\u2261 first tuple + * … one offset word per call starts right after the array + * head: 32 * n bytes) + * per call tuple body: + * target 32 bytes (left-padded) + * allowFailure 32 bytes (0 or 1) + * offset to callData within the tuple 32 bytes (constant 0x60) + * callData length in bytes 32 bytes + * callData right-padded to 32-byte words + * ``` + * + * Because every tuple contains dynamic `bytes`, tuples are dynamic types, so + * the array head carries one offset word per call; tuple offsets are + * cumulative over the padded callData sizes of preceding calls. + * * @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 }[], ): Hex { - return encodeFunctionData(multicall3Interface, 'aggregate3', [ - calls.map((call) => ({ - target: call.target, - allowFailure: call.allowFailure, - callData: call.callData, - })), - ]); + const callCount = calls.length; + + // Pass 1: validate + normalize each call, remember tuple bodies, and + // compute the cumulative array offsets while walking. + const headParts = new Array(callCount); + const bodyParts = new Array(callCount * 5); + let tupleOffset = 32 * callCount; // bytes; first tuple starts after the array head + + for (let i = 0; i < callCount; i++) { + const { target, allowFailure, callData } = calls[i]; + + 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}`); + } + + headParts[i] = tupleOffset.toString(16).padStart(64, '0'); + tupleOffset += + 128 + dataHex.length / 2 + ((64 - (dataHex.length % 64)) % 64) / 2; // static + len + padded data + + const j = i * 5; + bodyParts[j] = targetHex.padStart(64, '0'); + bodyParts[j + 1] = allowFailure ? WORD_ONE : WORD_ZERO; + bodyParts[j + 2] = WORD_CALLDATA_OFFSET; + bodyParts[j + 3] = (dataHex.length / 2).toString(16).padStart(64, '0'); + bodyParts[j + 4] = dataHex.padEnd( + dataHex.length + ((64 - (dataHex.length % 64)) % 64), + '0', + ); + } + + const parts: string[] = [ + `0x${AGGREGATE3_SELECTOR}`, + WORD_ARRAY_OFFSET, + callCount.toString(16).padStart(64, '0'), + ]; + for (let i = 0; i < callCount; i++) { + parts.push(headParts[i]); + } + for (let i = 0; i < callCount * 5; i++) { + parts.push(bodyParts[i]); + } + + return parts.join('') as Hex; +} + +/** + * Read one 32-byte word (64 hex chars) of a stripped response body at the + * given character index, as a number. + * + * @param body - The response body (lowercase hex, no `0x` prefix). + * @param charIndex - The character index at which the word starts. + * @returns The word's numeric value. + */ +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; } /** * Decode the response from aggregate3. * Returns array of (success, returnData) tuples. * + * Hand-rolled decoder for the fixed aggregate3 response layout — + * byte-for-byte equivalent to the generic @ethersproject/abi Reader (which + * allocates Result objects, BigNumbers and byte arrays per element and + * dominates decode time on Hermes), but as direct substring parsing: + * + * ```text + * offset to results array data 32 bytes (0x20) + * array length (result count) 32 bytes + * offset to tuple 0 32 bytes — one per result, + * … cumulative over returnData + * per result tuple body: + * success 32 bytes (0 or nonzero) + * offset to returnData within the tuple 32 bytes (0x40) + * returnData length in bytes 32 bytes + * returnData right-padded to 32-byte words + * ``` + * * @param data - The raw response data. * @param callCount - Number of calls made (used for validation). * @returns Array of success and return data. @@ -500,22 +636,37 @@ export function decodeAggregate3Response( data: Hex, callCount: number, ): { success: boolean; returnData: Hex }[] { - const decoded = multicall3Interface.decodeFunctionResult('aggregate3', data); - - // decoded[0] is the array of (success, returnData) tuples - const results = decoded[0] as readonly { - success: boolean; - returnData: string; - }[]; + if (!data.startsWith('0x')) { + throw new Error(`invalid response data value: ${data}`); + } + const body = data.slice(2); - if (results.length !== callCount) { - throw new Error(`Expected ${callCount} results, got ${results.length}`); + const headStart = readResponseWord(body, 0) * 2 + 64; + const results = readResponseWord(body, headStart - 64); + if (results !== callCount) { + throw new Error(`Expected ${callCount} results, got ${results}`); } - return results.map((result) => ({ - success: result.success, - returnData: result.returnData as Hex, - })); + const out = new Array(results); + for (let i = 0; i < results; i++) { + const tupleStart = + headStart + readResponseWord(body, headStart + i * 64) * 2; + const success = readResponseWord(body, tupleStart) !== 0; + const returnDataStart = + tupleStart + readResponseWord(body, tupleStart + 64) * 2; + const returnDataBytes = readResponseWord(body, returnDataStart); + const dataChars = returnDataStart + 64; + if (dataChars + returnDataBytes * 2 > body.length) { + throw new Error('aggregate3 response data length out-of-bounds'); + } + out[i] = { + success, + returnData: `0x${body + .slice(dataChars, dataChars + returnDataBytes * 2) + .toLowerCase()}`, + }; + } + return out; } /** @@ -524,13 +675,14 @@ export function decodeAggregate3Response( * @param data - The hex return data. * @returns The decoded balance as a string. */ -function decodeUint256(data: Hex): string { +export function decodeUint256(data: Hex): string { if (data === '0x' || data.length < 66) { // Empty or invalid data; treat as 0 return '0'; } - const decoded = erc20Interface.decodeFunctionResult('balanceOf', data); - return decoded[0].toString(); + // Decode the first 32-byte word directly (matching the generic decoder, + // which reads one word and ignores any trailing data). + return BigInt(data.slice(0, 66)).toString(); } // ============================================================================= @@ -540,6 +692,25 @@ function decodeUint256(data: Hex): string { /** Retries after the initial multicall attempt before returning failed responses. */ const MULTICALL_MAX_RETRIES = 2; +/** + * Pluggable codec for the aggregate3 hot path. The default is the + * hand-rolled implementation in this file. Alternative implementations + * (`viem`, `ethers`) live in `./aggregate3Codecs.js` and are exposed for + * on-device performance comparison; see the changelog for details. + */ +export type Aggregate3Codec = { + encodeAggregate3: typeof encodeAggregate3; + decodeAggregate3Response: typeof decodeAggregate3Response; + decodeUint256: typeof decodeUint256; +}; + +/** Default codec: the hand-rolled implementation in this file. */ +const DEFAULT_AGGREGATE3_CODEC: Aggregate3Codec = { + encodeAggregate3, + decodeAggregate3Response, + decodeUint256, +}; + export type MulticallClientConfig = { maxCallsPerBatch?: number; timeoutMs?: number; @@ -562,6 +733,12 @@ export type MulticallClientOptions = { getProvider: GetProviderFunction; getMulticall3AddressForChain: GetMulticall3AddressForChainFunction; config?: MulticallClientConfig; + /** + * Experimental: codec used for the aggregate3 hot path. Defaults to the + * hand-rolled implementation; alternatives are exposed for on-device + * performance comparison (see `./aggregate3Codecs.js`). + */ + aggregate3Codec?: Aggregate3Codec; }; /** @@ -575,10 +752,13 @@ export class MulticallClient { readonly #getMulticall3AddressForChain: GetMulticall3AddressForChainFunction; + readonly #codec: Aggregate3Codec; + constructor({ getProvider, getMulticall3AddressForChain, config, + aggregate3Codec, }: MulticallClientOptions) { this.#getProvider = getProvider; // Use default values for invalid (non-positive) batch sizes to prevent @@ -596,6 +776,7 @@ export class MulticallClient { timeoutMs, }; this.#getMulticall3AddressForChain = getMulticall3AddressForChain; + this.#codec = aggregate3Codec ?? DEFAULT_AGGREGATE3_CODEC; } /** @@ -668,14 +849,14 @@ export class MulticallClient { maxRetries: MULTICALL_MAX_RETRIES, }).execute(async () => { // Encode and send aggregate3 call - const callData = encodeAggregate3(calls); + const callData = this.#codec.encodeAggregate3(calls); const result = await provider.call({ to: multicallAddress, data: callData, }); // Decode response - const decoded = decodeAggregate3Response( + const decoded = this.#codec.decodeAggregate3Response( result as Hex, batch.length, ); @@ -690,7 +871,7 @@ export class MulticallClient { tokenAddress, accountAddress, success: true, - balance: decodeUint256(returnData), + balance: this.#codec.decodeUint256(returnData), }); } else { workingResult.push({ diff --git a/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codecs.ts b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codecs.ts new file mode 100644 index 00000000000..0d4151c108d --- /dev/null +++ b/packages/assets-controller/src/data-sources/evm-rpc-services/clients/aggregate3Codecs.ts @@ -0,0 +1,179 @@ +import { Interface } from '@ethersproject/abi'; +import { + decodeFunctionResult as viemDecodeFunctionResult, + encodeFunctionData as viemEncodeFunctionData, + parseAbi as viemParseAbi, +} from 'viem'; + +import { + decodeAggregate3Response as handrolledDecodeAggregate3Response, + decodeUint256 as handrolledDecodeUint256, + encodeAggregate3 as handrolledEncodeAggregate3, +} from './MulticallClient.js'; +import type { Aggregate3Codec } from './MulticallClient.js'; + +/** + * Available aggregate3 codec implementations: + * + * - `handrolled` — the optimized string codec in `MulticallClient.ts` + * (default; ~44x faster than the stock Ethers path on Hermes). + * - `viem` — the same surface implemented with viem's + * `encodeFunctionData`/`decodeFunctionResult` (maintained-library option). + * - `ethers` — the stock Ethers `Interface` implementation (the pre-optimization + * behavior), kept for A/B comparison. + * + * These exist so the three implementations can be compared on real devices + * with real workloads; see the changelog and PR for measurements. + */ +export type Aggregate3CodecVariant = 'handrolled' | 'viem' | 'ethers'; + +const AGGREGATE3_HUMAN_READABLE_ABI = [ + 'function aggregate3((address target, bool allowFailure, bytes callData)[] calls) payable returns ((bool success, bytes returnData)[])', +] as const; + +const BALANCE_OF_HUMAN_READABLE_ABI = [ + 'function balanceOf(address account) view returns (uint256)', +] as const; + +// viem: parse once at module level (the equivalent of `new Interface()`). +const aggregate3ViemAbi = viemParseAbi(AGGREGATE3_HUMAN_READABLE_ABI); +const balanceOfViemAbi = viemParseAbi(BALANCE_OF_HUMAN_READABLE_ABI); + +// Ethers: stateless interfaces with the same fragments as MulticallClient's. +const aggregate3EthersInterface = new Interface(AGGREGATE3_HUMAN_READABLE_ABI); +const balanceOfEthersInterface = new Interface(BALANCE_OF_HUMAN_READABLE_ABI); + +/** Hand-rolled codec from MulticallClient.ts (the default). */ +const handrolledCodec: Aggregate3Codec = { + encodeAggregate3: handrolledEncodeAggregate3, + decodeAggregate3Response: handrolledDecodeAggregate3Response, + decodeUint256: handrolledDecodeUint256, +}; + +/** viem codec. Preserves the count-mismatch contract of the default codec. */ +const viemCodec: Aggregate3Codec = { + encodeAggregate3: (calls) => + viemEncodeFunctionData({ + abi: aggregate3ViemAbi, + functionName: 'aggregate3', + args: [ + calls.map((call) => ({ + target: call.target, + allowFailure: call.allowFailure, + callData: call.callData, + })), + ], + }), + decodeAggregate3Response: (data, callCount) => { + const results = viemDecodeFunctionResult({ + abi: aggregate3ViemAbi, + functionName: 'aggregate3', + data, + }) as { success: boolean; returnData: `0x${string}` }[]; + + if (results.length !== callCount) { + throw new Error(`Expected ${callCount} results, got ${results.length}`); + } + + return results; + }, + decodeUint256: (data) => { + if (data === '0x' || data.length < 66) { + return '0'; + } + return String( + viemDecodeFunctionResult({ + abi: balanceOfViemAbi, + functionName: 'balanceOf', + data, + }), + ); + }, +}; + +/** Stock Ethers codec (the pre-optimization behavior). */ +const ethersCodec: Aggregate3Codec = { + encodeAggregate3: (calls) => + aggregate3EthersInterface.encodeFunctionData('aggregate3', [ + calls.map((call) => ({ + target: call.target, + allowFailure: call.allowFailure, + callData: call.callData, + })), + ]) as `0x${string}`, + decodeAggregate3Response: (data, callCount) => { + const decoded = aggregate3EthersInterface.decodeFunctionResult( + 'aggregate3', + data, + ); + const results = decoded[0] as readonly { + success: boolean; + returnData: `0x${string}`; + }[]; + + if (results.length !== callCount) { + throw new Error(`Expected ${callCount} results, got ${results.length}`); + } + + return results.map((result) => ({ + success: result.success, + returnData: result.returnData, + })); + }, + decodeUint256: (data) => { + if (data === '0x' || data.length < 66) { + return '0'; + } + const balance = balanceOfEthersInterface.decodeFunctionResult( + 'balanceOf', + data, + )[0] as bigint; + return balance.toString(); + }, +}; + +const CODECS: Record = { + handrolled: handrolledCodec, + viem: viemCodec, + ethers: ethersCodec, +}; + +/** + * Get an aggregate3 codec implementation by variant. + * + * @param variant - The codec variant. + * @returns The codec implementation. + */ +export function getAggregate3Codec( + variant: Aggregate3CodecVariant, +): Aggregate3Codec { + return CODECS[variant]; +} + +let activeVariant: Aggregate3CodecVariant = 'handrolled'; + +/** + * Select the aggregate3 codec variant used by subsequently constructed + * `MulticallClient` instances. + * + * Experimental: intended for on-device performance comparison of the codec + * implementations; may be removed once the default is settled. + * + * @param variant - The codec variant to activate. + */ +export function setAggregate3CodecVariant( + variant: Aggregate3CodecVariant, +): void { + activeVariant = variant; +} + +/** + * Get the currently active aggregate3 codec. + * + * @returns The active codec implementation. + */ +export function getActiveAggregate3Codec(): Aggregate3Codec { + return CODECS[activeVariant]; +} + +export type { Aggregate3Codec } from './MulticallClient.js'; 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..658f0cd135a 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 @@ -3,7 +3,14 @@ export { encodeAggregate3, MulticallClient, type MulticallClientConfig, + type Aggregate3Codec, } from './MulticallClient.js'; +export { + getAggregate3Codec, + getActiveAggregate3Codec, + setAggregate3CodecVariant, + type Aggregate3CodecVariant, +} from './aggregate3Codecs.js'; // Re-export provider types from types module export type { GetProviderFunction, Provider } from '../types/index.js'; diff --git a/packages/assets-controller/src/data-sources/evm-rpc-services/index.ts b/packages/assets-controller/src/data-sources/evm-rpc-services/index.ts index a17ad34d8e5..15f9fa15b0f 100644 --- a/packages/assets-controller/src/data-sources/evm-rpc-services/index.ts +++ b/packages/assets-controller/src/data-sources/evm-rpc-services/index.ts @@ -14,6 +14,11 @@ export type { export { MulticallClient, type MulticallClientConfig, + type Aggregate3Codec, + getAggregate3Codec, + getActiveAggregate3Codec, + setAggregate3CodecVariant, + type Aggregate3CodecVariant, } from './clients/index.js'; export { BalanceFetcher, diff --git a/packages/assets-controller/src/data-sources/index.ts b/packages/assets-controller/src/data-sources/index.ts index 04758c57281..e3faf005831 100644 --- a/packages/assets-controller/src/data-sources/index.ts +++ b/packages/assets-controller/src/data-sources/index.ts @@ -31,6 +31,14 @@ export { type ChainStatus, } from './RpcDataSource.js'; +export { + getAggregate3Codec, + getActiveAggregate3Codec, + setAggregate3CodecVariant, + type Aggregate3Codec, + type Aggregate3CodecVariant, +} from './evm-rpc-services/index.js'; + export { TokenDataSource, type TokenDataSourceOptions, diff --git a/packages/assets-controller/src/index.ts b/packages/assets-controller/src/index.ts index 3c328054c1c..84eb194a2b0 100644 --- a/packages/assets-controller/src/index.ts +++ b/packages/assets-controller/src/index.ts @@ -139,6 +139,20 @@ export type { ChainStatus, } from './data-sources/index.js'; +// Data sources - RPC MulticallClient codec selection +// Experimental: exposed for on-device performance comparison of the +// aggregate3 codec implementations; may be removed once the default is +// settled. +export { + getAggregate3Codec, + getActiveAggregate3Codec, + setAggregate3CodecVariant, +} from './data-sources/index.js'; +export type { + Aggregate3Codec, + Aggregate3CodecVariant, +} from './data-sources/index.js'; + // Data sources - Unified Snap Data Source (dynamically discovers keyring snaps) export { SnapDataSource, diff --git a/yarn.lock b/yarn.lock index c9a68561d97..23240a40b11 100644 --- a/yarn.lock +++ b/yarn.lock @@ -6074,6 +6074,7 @@ __metadata: typedoc: "npm:^0.28.20" typedoc-plugin-missing-exports: "npm:^4.1.4" typescript: "npm:@typescript/typescript6@^6.0.2" + viem: "npm:^2.56.8" languageName: unknown linkType: soft