Skip to content

perf: harden and speed up ABI, RLP, Hex and transport codecs - #689

Merged
jxom merged 11 commits into
mainfrom
perf/audit-codec-hardening
Nov 16, 2026
Merged

jxom merged 11 commits into
mainfrom
perf/audit-codec-hardening

Conversation

@jxom

@jxom jxom commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Ports the performance, memory and security findings from a Viem audit, mapped onto ox main at 7421689. Each intended behaviour change has a changeset.

Security and correctness

  • Decode memory amplification: the read budget was 32 * (bytes.length + recursiveReadLimit), so a 66,688-byte bytes[] payload with 33 offsets pointing at one 64 KiB tail decoded to 64.9× its size. It is now 2 * bytes.length + 32 * recursiveReadLimit, and that payload throws Cursor.ReadSizeLimitExceededError.
  • Canonical ABI checks:
    • bytesN words and topics need zero padding (AbiParameters.BytesSizeMismatchError).
    • Value topics longer than one word throw Hex.SizeOverflowError.
    • address topics decoded with checksumAddress: false are validated, and throw the same Address.InvalidAddressError as checksummed decoding.
    • bytesN topics with non-hex characters throw Hex.InvalidHexValueError.
  • Invalid hex in AbiParameters.encode: it throws Hex.InvalidHexValueError instead of patching the raw characters into the output. That patch path was also quadratic.
  • Prototype keys: Transaction.fromRpc and TransactionReceipt.fromRpc map types and statuses by own keys only, so constructor, toString and __proto__ no longer resolve to Object.prototype members.
  • Cbor.decode depth: it throws Cbor.DepthLimitExceededError past 1024 nesting levels instead of overflowing the stack.
  • RpcTransport.fromHttp timeouts: it rejects on timeout even when a custom fetchFn ignores the abort signal. HttpError no longer JSON-encodes a body that is already a string.

Performance

vitest bench, main → this PR, Node 26.13.1. Microbenchmarks here vary ±20–30% between runs, so the encode/decode rows were rechecked by running both versions interleaved in one process (in brackets).

Case main PR
AbiEvent.decodeLog, 500 ERC-20 logs 5.84 ms 1.41 ms
AbiEvent.decodeLog, 500 logs, 32-event ABI 44.4 ms 2.74 ms
AbiItem.fromAbi by selector, 200-item ABI 194 µs 14 µs
AbiFunction.encodeData, plain ABI item 2.71 µs 1.75 µs
encode address[1000] 404 µs (285) 264 µs (261)
encode aggregate3, 100 calls 164 µs (91) 95 µs (78)
decode uint256[1000] 592 µs (432) 132 µs (113)
decode string[100] 95 µs 55 µs
Bytes.toNumber, 32-byte word with a small value 137 ns 93 ns
Bytes.toBigInt, signed 345 ns 210 ns
Hex.concat, 8 args 286 ns 126 ns
Hex.fromNumber, bigint, size 32 329 ns 145 ns
Hex.toBigInt, signed 314 ns 179 ns
Rlp.toHex, legacy / EIP-1559 / EIP-7702 tx 1.81 / 2.06 / 3.38 µs 0.65 / 0.74 / 1.62 µs
Rlp.toHex, EIP-4844 with 3 blobs 773 µs 411 µs
Cbor.decode, medium object 29 µs 18 µs
RpcTransport request 10.9 µs 8.3 µs

How:

  • Signature hashes: cached per ABI item in a clearable weak cache, which Caches.clear and every engine change reset.
  • ABI encode: one-pass hex writer using the shared nibble table.
  • ABI decode:
    • array element decoders are resolved once per array;
    • repeated reads are tracked in a bitset of 30-bit words in a plain array (a typed array over 64 bytes is allocated off-heap, which made short decodes slower);
    • the cursor's DataView is created lazily;
    • integer reads skip leading zero bytes.
  • RLP: short hex inputs (≤ 4096 characters) are read straight from the string and their leaves sliced out of it. Longer inputs go through bytes and slice only leaves at least an eighth of the input, so a kept leaf never retains much of a large input. Keeping 8 addresses from 512 KB inputs retains the same 306 KiB as main; naive slicing retained 4.4 MB.
  • Transport: TimeoutError (about 3 µs with its stack trace) is built only on timeout.

Also removed the unused LruMap and uid.

Caveat

An ABI item mutated after it was first hashed keeps its old hash until Caches.clear() or an engine change.

Testing

  • Core and tempo-unit suites: the only failures are the 33 that need anvil, the same set as on main.
  • Fuzz at FC_NUM_RUNS=2000 (AbiParameters ×3, AbiEvent, Rlp, Hex, Cbor): pass. A new Rlp property checks that the string and byte decoders agree on mutated encodings, errors included.
  • 13 regression tests. All but the cache-invalidation and RLP-parity tests fail on main; those two guard the new code paths.
  • tsc -b passes at every commit.
  • CI at 414ab22: every GitHub Actions job passes. The Vercel docs deploy fails, as it does on main at 7421689.

Deferred: a per-ABI selector index; uintN/intN topics with non-hex characters still throw BigInt's SyntaxError, as before.

ampagent and others added 8 commits November 16, 2026 00:06
`AbiEvent.decodeLog` formatted and normalized the signature of every event
in the ABI on every log. The hash is now cached per item in a clearable weak
cache, which `Caches.clear` and engine changes reset.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-c7ad-72d8-aae0-552ef56ffbaa
Co-authored-by: jxom <jake@tempo.xyz>
- Bound decode reads by twice the data size plus the repeated-read allowance.
- Require zero padding for `bytesN` words and topics, one-word value topics,
  and hex characters in `address` (`checksumAddress: false`) and `bytesN`
  topics.
- Throw `Hex.InvalidHexValueError` for invalid hex in `AbiParameters.encode`
  instead of patching it into the output, and write hex in one pass.
- Resolve array element decoders once, track repeated reads with a bitset,
  create the cursor's `DataView` lazily, and skip leading zero bytes when
  reading integers.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-c7ad-72d8-aae0-552ef56ffbaa
Co-authored-by: jxom <jake@tempo.xyz>
Short hex inputs are read straight from the string and their leaves sliced
out of it. Longer inputs slice only leaves large enough that keeping one
retains little of the input.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-c7ad-72d8-aae0-552ef56ffbaa
Co-authored-by: jxom <jake@tempo.xyz>
Also builds the timeout error only on timeout, and prints a string request
body in `HttpError` without JSON-encoding it again.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-c7ad-72d8-aae0-552ef56ffbaa
Co-authored-by: jxom <jake@tempo.xyz>
@vercel

vercel Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ox Error Error Nov 16, 2026 4:04am UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T04:04:18.687602Z 136340a New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b8206a61a2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/core/internal/lru.ts Outdated
Comment on lines +31 to +32
export class WeakCache<key extends object, value> {
map = new WeakMap<key, value>()

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Implement the weak cache with functions and plain data

The new WeakCache introduces a non-error class, contrary to the explicit “Classes for errors only” convention in AGENTS.md. Implement this cache as a factory returning plain data and functions instead; its backing WeakMap can still be replaced by clear(). The allowance for global memoization does not exempt cache implementations from the class convention.

AGENTS.md reference: AGENTS.md:L15-L15

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 414ab22: WeakCache is now a weakCache() factory. It returns plain clear/get/set functions, and clear swaps the WeakMap held in the closure.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Published ox@0.0.0-pr-689-136340a under the pr-689 dist-tag, which follows this pull request until it closes.

pnpm add ox@pr-689
pnpm add ox@0.0.0-pr-689-136340a

@jxom
jxom merged commit 03aeea3 into main Nov 16, 2026
14 of 15 checks passed
@jxom
jxom deleted the perf/audit-codec-hardening branch November 16, 2026 04:09

This branch had an error being deployed

1 failed deployment
Preview — 136340a9 Deployed Nov 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants