Skip to content

fix(0.x): harden decoders and speed up hot paths (Viem audit) - #688

Merged
jxom merged 13 commits into
0.xfrom
perf/0.x-audit
Nov 16, 2026
Merged

jxom merged 13 commits into
0.xfrom
perf/0.x-audit

Conversation

@jxom

@jxom jxom commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Ports the findings of a Viem audit onto 0.x, the line Viem pins (0.14.x). Where main already had a fix, this PR backports it.

This branch is rebased onto #687, which landed several of the same perf items first: native Hex.fromBytes, the nibble-table Bytes.fromHex, the cursor read bitset, Hex.concat/trim/pad, Hex.validate, decodeAddress/getArrayComponents, and a global type-hash cache in TypedData. Those parts are #687's code, and the numbers below are measured against origin/0.x with #687 included.

Commits

Each commit typechecks and passes the tests it touches on its own.

  • fix(Rlp): strict decoding, plus a cursor-free decoder and a two-pass encoder.
  • fix(Hex): toNumber throws when the value is not a safe integer.
  • fix(AbiParameters, AbiEvent): canonical bytesN padding and topic size, plus a direct path for canonical topics.
  • fix(Siwe): random nonces.
  • fix: own-key lookups for untrusted type names.
  • fix(Cbor): depth limit.
  • fix(Json): marker strings that are not bigints, and skip the reviver when the text cannot contain the marker.
  • fix(Address): one-pass classifier, rejection of non-strings, lowercase-only checksum cache, and LruMap fixes.
  • fix(RpcTransport): HttpError body.
  • perf(core): Bytes.toNumber/toBigInt, bigint Hex.fromNumber, signed Hex.toBigInt, AbiParameters.encode joining and integer bounds, a lazy cursor DataView, and a lazy withTimeout error.
  • perf(tempo): formatters built without delete, and a single sender check in TxEnvelopeTempo.deserialize.

Behaviour changes

Each of these has a changeset.

  • RLP strict decoding (from main): Rlp.toBytes/Rlp.toHex, and so every TxEnvelope*.deserialize including Tempo, throw:

    • Rlp.TrailingBytesError for bytes after the item, such as Rlp.toHex('0x01ff') or deserialize(tx + 'ff').
    • Rlp.ListBoundaryExceededError when a child overruns its list, such as '0xc18180'.
    • Rlp.DepthLimitExceededError past 1024 levels of nesting, which used to overflow the stack.

    As a result, AccountSimulation.fromRpc with trailing config bytes now throws Rlp.TrailingBytesError, where it used to throw InvalidSimulationError: noncanonical config encoding. SignaturePreAuthorized.unwrap shows the RLP message in its details.

  • Hex.toNumber and Bytes.toNumber (from main) throw Hex.IntegerOutOfRangeError instead of returning a rounded number ('0x20000000000001') or NaN ('0x'). The ABI decoder reads offsets and lengths with a local lossy helper, so huge offsets still throw PositionOutOfBoundsError and AbiEvent's DataMismatchError mapping is unchanged.

  • Siwe.generateNonce draws each nonce from crypto.getRandomValues (Hex.random(48).slice(2)). Before, consecutive nonces shared 95 of 96 characters. internal/uid.ts had no other users and is removed.

  • Canonical ABI data:

    • AbiParameters.decode throws BytesSizeMismatchError when bytesN padding is not zero.
    • AbiEvent.decode throws the new AbiEvent.TopicSizeMismatchError when a topic for a statically typed indexed parameter is not exactly 32 bytes.
  • Untrusted type names such as "constructor" are looked up with Object.hasOwn in Transaction, TransactionReceipt and TransactionRequest (core and Tempo), and in TypedData. Before, an RPC type: "constructor" turned tx.type into the Object function, and a field type of "constructor" broke hashStruct.

  • Cbor.decode throws Cbor.DepthLimitExceededError past 1024 levels of nesting.

  • Json.parse keeps a string that ends in #__bigint but is not a bigint as a string, where it used to throw (Json.parse('{"a":"x#__bigint"}')).

  • Address.assert and Address.validate reject values that are not strings. Before, strict: false coerced them to strings, so Address.validate({ toString: () => address }, { strict: false }) returned true. In strict mode assert threw a TypeError. Both now reject such values with InvalidAddressError / false.

  • Address.checksum caches only the lowercase address. Every casing of an address shares one cache entry, where each casing used to take its own slot. LruMap.set now refreshes an existing key's recency, and an empty-string key can be evicted.

  • RpcTransport.HttpError shows a request body that is already a string as is, instead of encoding it twice.

Accepted defaults

These were reviewed and accepted as they are:

  • Lowercase-only checksum cache: a checksummed input to Address.checksum or strict Address.validate misses the direct lookup, so it pays for a shape check and a lowercase lookup instead of one get. Lowercase and invalid input get faster. See the Address.validate rows below.
  • Address.validate rejects non-strings without coercing them (above).
  • The ABI decode read budget is unchanged (32 * (len + 8192)). main uses the same budget, and flat strings from native Hex.fromBytes (perf(0.x): hot-path speed and memory improvements, and Blobs.to multi-blob fix #687) already remove most of the memory amplification.
  • Json.stringify does not try plain JSON.stringify first: that is about 1.9× faster without bigints but 0.73× with them, and it would run getters and toJSON twice.
  • No per-call type-hash map in TypedData: perf(0.x): hot-path speed and memory improvements, and Blobs.to multi-blob fix #687's global type-hash cache already covers that item. A per-call map on top measured within noise (0.99–1.09×), so it was dropped.

Performance

These were measured on Node 26 / V8 in an orb, against origin/0.x (with #687). Each run interleaves 0.x and this branch seven times in one process, and each library builds its own fixtures. The table shows the median of three runs, with the range of their speedups. The orb's CPU speed varied between runs, so the absolute times move around, but the interleaved ratios are stable. The control rows, whose code this PR doesn't touch, stay within ±5% of 1.00×.

Benchmark 0.x This PR Speedup (3 runs)
Rlp.fromHex (EIP-1559 fields) 12.08 µs 11.07 µs 1.13× (1.09–1.13)
Rlp.toHex (EIP-1559 fields) 10.88 µs 8.92 µs 1.22× (1.11–1.45)
TxEnvelopeEip1559.serialize 15.82 µs 12.63 µs 1.06× (0.90–1.25)
TxEnvelopeEip1559.deserialize 11.03 µs 10.13 µs 1.05× (1.03–1.14)
TxEnvelopeTempo.serialize 15.95 µs 13.82 µs 1.15× (1.11–1.15)
TxEnvelopeTempo.deserialize 13.81 µs 12.82 µs 1.11× (1.08–1.15)
TxEnvelopeTempo.deserialize (fee payer sig) 42.60 µs 12.14 µs 3.63× (2.70–3.76)
Address.validate (reject) 52 ns 31 ns 1.68× (1.55–1.73)
Address.validate (valid lowercase) 196 ns 136 ns 1.44× (1.43–1.47)
Bytes.toNumber 32-byte word 452 ns 102 ns 4.64× (4.43–4.68)
Bytes.toBigInt full uint256 368 ns 400 ns 1.16× (0.92–1.37)
Cursor.create 173 ns 56 ns 3.60× (3.04–3.81)
AbiParameters.decode (bool,bytes)[50] 253.86 µs 180.51 µs 1.38× (1.32–1.41)
AbiParameters.decode uint256[1000] 1.07 ms 874.53 µs 1.39× (1.20–1.40)
AbiParameters.decode (address,uint256) 3.31 µs 2.99 µs 1.11× (1.10–1.15)
Json.parse (no bigint marker) 27.37 µs 7.04 µs 3.93× (3.64–4.35)
AbiParameters.encode uint256[1000] 1.51 ms 1.07 ms 1.46× (1.10–1.61)
AbiParameters.encode (address,uint256) 2.60 µs 2.65 µs 0.98× (0.98–1.00)
TypedData.getSignPayload (Permit2 batch of 5) 292.39 µs 313.05 µs 0.96× (0.93–0.99)
Hex.fromNumber bigint { size: 32 } 541 ns 205 ns 2.74× (2.64–2.84)
Hex.toBigInt signed 32 B 392 ns 268 ns 1.46× (1.19–1.52)
AbiEvent.decode Transfer (3 indexed) 9.53 µs 2.92 µs 3.38× (3.26–3.47)
tempo TransactionRequest.toRpc 801 ns 478 ns 1.76× (1.66–1.78)
Address.checksum (cached) 181 ns 162 ns 1.09× (0.98–1.12)
Address.validate (checksummed) 324 ns 550 ns 0.59× (0.55–0.62)
Controls: paths that use #687's code unchanged (expected ≈1.00×)
Benchmark 0.x This PR Speedup (3 runs)
Hex.fromBytes 20 B 126 ns 128 ns 1.02× (0.95–1.05)
Hex.fromBytes 32 B 143 ns 148 ns 0.97× (0.97–1.00)
Hex.fromBytes 1 KB 2.06 µs 2.04 µs 1.02× (0.97–1.13)
Hex.fromBytes 128 KB 447.11 µs 287.16 µs 1.01× (1.00–1.56)
Hex.validate (reject) 32 ns 32 ns 1.00× (0.97–1.03)
Bytes.fromHex 32 B 239 ns 253 ns 0.94× (0.92–1.10)
Bytes.fromHex 20 B { size: 32 } 208 ns 205 ns 1.01× (1.01–1.07)
Bytes.fromHex 1 KB 12.57 µs 11.96 µs 1.00× (0.95–1.05)
Bytes.toBigInt small value in word 158 ns 161 ns 0.99× (0.98–1.00)
Hex.fromNumber number 122 ns 127 ns 0.98× (0.96–1.05)
Hex.concat 8 × 32 B 283 ns 287 ns 0.99× (0.98–1.00)
Bytes.padLeft 20 → 32 B 108 ns 108 ns 1.00× (1.00–1.05)
Hex.trimLeft 32 B 316 ns 326 ns 1.03× (0.95–1.04)
Hex.toString 1.88 µs 1.77 µs 1.06× (0.99–1.07)

Notes:

Verification

  • vitest --project core --project tempo-unit: 3384 passed and 2 failed. Both failures are behavior: network envelope tests, which fail on untouched 0.x too and passed in CI on the previous push.
  • tsc --noEmit, biome and the tsdoc lint are clean, and every commit typechecks on its own.
  • A differential harness against origin/0.x ran 316,657 checks with random and edge-case inputs across Hex, Bytes, Rlp, ABI encode/decode, AbiEvent, TypedData, Json, the envelopes and the Tempo formatters. It found no differences beyond the intended changes above.

@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 Ready Ready Preview Nov 16, 2026 4:10am 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:05.042121Z 024b0ed 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.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Published ox@0.0.0-pr-688-024b0ed under the pr-688 dist-tag, which follows this pull request until it closes.

pnpm add ox@pr-688
pnpm add ox@0.0.0-pr-688-024b0ed

ampagent and others added 9 commits November 16, 2026 02:06
Backports main's strict decoding. `Rlp.toBytes`/`Rlp.toHex`, and so every
`TxEnvelope*.deserialize`, now throw `TrailingBytesError` when bytes follow
the item, `ListBoundaryExceededError` when a child overruns its list, and
`DepthLimitExceededError` past 1024 levels of nesting instead of
overflowing the stack.

The decoder now reads from a plain position over the bytes instead of a
cursor, and the encoder measures then writes in two passes without
closures.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
Backports main's check. `Hex.toNumber` and `Bytes.toNumber` throw
`Hex.IntegerOutOfRangeError` instead of returning a rounded number (for
example for `0x20000000000001`) or `NaN` (for `0x`).

The ABI decoder reads offsets and lengths with its own lossy helper, so
huge offsets still throw `PositionOutOfBoundsError` and AbiEvent still
maps them to `DataMismatchError`.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
…pic size

`AbiParameters.decode` throws `BytesSizeMismatchError` when the padding of
a `bytesN` word is not zero, and `AbiEvent.decode` throws the new
`TopicSizeMismatchError` when a topic for a statically typed indexed
parameter is not 32 bytes.

With topics known to be one word, canonical `address`, `uint256` and
`bytes32` topics are read directly instead of through
`AbiParameters.decode`.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
`Siwe.generateNonce` used `uid(96)`, which read a `Math.random` buffer
through a window that slid one character per call, so consecutive nonces
shared 95 of 96 characters. It now returns `Hex.random(48)` without the
prefix. `internal/uid.ts` had no other users and is removed.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
`Transaction`, `TransactionReceipt` and `TransactionRequest` (core and
Tempo) map RPC `type` strings through plain objects, so a type of
`"constructor"` resolved to the `Object` function. `TypedData` did the
same with struct and field type names, which broke `hashStruct`. These
lookups now check `Object.hasOwn` first.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
`Cbor.decode`, which parses WebAuthn attestations, recursed without a
limit. It now throws `Cbor.DepthLimitExceededError` when arrays, maps or
tags nest deeper than 1024 instead of overflowing the stack.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
`Json.parse` threw on untrusted text such as `{"a":"x#__bigint"}`. A
string that ends in the bigint marker but is not a bigint is now kept as
a string.

Without a reviver, text that cannot contain the marker (literally or
through a `\u` escape) now parses without the reviver wrapper.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
…ase key

Backports main's `internal/address.ts` classifier. `Address.assert` and
`Address.validate` now check the shape and casing in one pass without
building and catching errors, and reject values that are not strings,
which `strict: false` used to coerce.

`Address.checksum` caches only the lowercase address, so every casing of
an address shares one entry instead of each taking a slot. `LruMap.set`
now refreshes an existing key's recency, and an empty-string key can be
evicted.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
`HttpError` passed the request body, which is usually already JSON,
through `JSON.stringify` again, so the error showed it escaped and
quoted.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
ampagent and others added 2 commits November 16, 2026 02:49
- `Bytes.toBigInt` reads a full 32-byte word as four 64-bit halves, and
  `Bytes.toNumber` builds values of up to 6 significant bytes as numbers.
- `Hex.fromNumber` encodes non-negative bigints that fit `size` without
  the range check, and keeps that check in a separate function so that
  `fromNumber` stays small enough to inline. Signed `Hex.toBigInt` uses
  `BigInt.asIntN`.
- `AbiParameters.encode` joins parts once instead of spreading them into
  `Hex.concat`, which overflowed the stack for a `uint256[]` of 200k
  elements, and caches integer bounds per type.
- Cursors create their `DataView` on first use.
- `withTimeout` builds its `TimeoutError` only once a request times out.

Co-authored-by: jxom <jake@tempo.xyz>
…ders once

`TransactionRequest.toRpc` leaves out `data`, `input`, `to` and `value`
for Tempo requests instead of deleting them afterwards, and
`Transaction.fromRpc` leaves out `aaAuthorizationList` the same way.

`TxEnvelopeTempo.deserialize` checks that the fee payer field is a string
before validating it as an address, once, so a fee payer signature tuple
no longer goes through `Address.validate` twice.

Amp-Thread-ID: https://ampcode.com/threads/T-01a1e175-cf94-74ff-8a7c-572b7cb2b7d2
Co-authored-by: jxom <jake@tempo.xyz>
@jxom jxom changed the title fix(0.x): harden decoders and speed up hot paths fix(0.x): harden decoders and speed up hot paths (Viem audit) Nov 16, 2026
@jxom
jxom merged commit af9a628 into 0.x Nov 16, 2026
13 of 14 checks passed
@jxom
jxom deleted the perf/0.x-audit branch November 16, 2026 04:10

This branch was successfully deployed

1 active deployment
Preview — 024b0ed7 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