feat(benchmark): Add CodSpeed benchmark suite (#219)

## Summary
- add CodSpeed benchmarks and shared data/helpers
- add CodSpeed workflow for sharded benchmark runs
- add codspeed/pytest requirements files

## Testing
- `PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -p pytest_codspeed.plugin
benchmarks/ --codspeed`

Author: BobTheBuidler

.github/workflows/benchmark.yaml

@@ -0,0 +1,56 @@
+name: Benchmark Suite
+
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - ".github/workflows/benchmark.yaml"
+      - "evmspec/**"
+      - "benchmarks/**"
+      - "setup.py"
+      - "pyproject.toml"
+      - "requirements-codspeed.txt"
+      - "requirements-pytest.txt"
+  push:
+    branches: [master]
+    paths:
+      - ".github/workflows/benchmark.yaml"
+      - "evmspec/**"
+      - "benchmarks/**"
+      - "setup.py"
+      - "pyproject.toml"
+      - "requirements-codspeed.txt"
+      - "requirements-pytest.txt"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  codspeed:
+    name: Run CodSpeed Benchmarks
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            setup.py
+            poetry.lock
+
+      - name: Install evmspec
+        run: python -m pip install --upgrade pip && python -m pip install . -r requirements-codspeed.txt
+
+      - name: Run CodSpeed
+        uses: CodSpeedHQ/action@v4
+        with:
+          mode: instrumentation
+          run: pytest --codspeed benchmarks/

.github/workflows/pytest.yaml

@@ -68,5 +68,4 @@ jobs:
         env:
           PYTEST_NETWORK: mainnet
           ETHERSCAN_TOKEN: ${{ secrets.ETHERSCAN_TOKEN  }}
-        run: |
-          poetry run pytest
+        run: poetry run pytest tests

benchmarks/README.md

@@ -0,0 +1,29 @@
+# Benchmarks for evmspec
+
+This directory contains CodSpeed-friendly benchmarks for key hot paths in `evmspec`:
+
+- `test_address_benchmarks.py`: Address checksum and construction.
+- `test_hexbytes_benchmarks.py`: `HexBytes32` construction.
+- `test_numeric_benchmarks.py`: `uint` hex parsing.
+- `test_decoding_benchmarks.py`: Transaction, receipt, and log decoding.
+- `test_block_benchmarks.py`: `TinyBlock.transactions` decoding.
+
+## Running Benchmarks
+
+Install the benchmark dependencies:
+
+```
+pip install -r requirements-codspeed.txt
+```
+
+Run the suite with CodSpeed:
+
+```
+pytest benchmarks/ --codspeed
+```
+
+## Contributing
+
+- Add benchmarks for new public APIs or hot decode paths.
+- Keep inputs representative of real RPC payloads.
+- Each benchmark should stand alone (no paired reference/optimized variant).

benchmarks/__init__.py

@@ -0,0 +1,6 @@
+from typing import Any, Callable
+
+
+def batch(iterations: int, func: Callable[..., Any], *args: Any, **kwargs: Any) -> None:
+    for _ in range(iterations):
+        func(*args, **kwargs)

benchmarks/batch.py

@@ -0,0 +1,139 @@
+import json
+
+ADDRESS_CHECKSUM = "0x52908400098527886E0F7030069857D2E4169EE7"
+ADDRESS_LOWER = "0xde709f2102306220921060314715629080e2fb77"
+ADDRESS_ZERO = "0x0000000000000000000000000000000000000000"
+
+ADDRESS_CASES = [
+    ADDRESS_CHECKSUM,
+    ADDRESS_LOWER,
+    ADDRESS_ZERO,
+]
+ADDRESS_CASE_IDS = [
+    "checksummed",
+    "lower",
+    "zero",
+]
+
+HASH_1 = "0x" + "11" * 32
+HASH_2 = "0x" + "22" * 32
+HASH_3 = "0x" + "33" * 32
+HASH_4 = "0x" + "44" * 32
+
+TOPIC_0 = "0x" + "aa" * 32
+TOPIC_1 = "0x" + "bb" * 32
+DATA_32 = "0x" + "00" * 32
+
+HEXBYTES32_CASES = [
+    HASH_1,
+    bytes.fromhex("11" * 32),
+]
+HEXBYTES32_CASE_IDS = [
+    "hexstr",
+    "bytes",
+]
+
+UINT_HEX_CASES = [
+    "0x0",
+    "0x1",
+    "0xff",
+    "0x7fffffffffffffff",
+]
+UINT_HEX_CASE_IDS = [
+    "0",
+    "1",
+    "ff",
+    "int64-max",
+]
+
+LEGACY_TX = {
+    "type": "0x0",
+    "hash": HASH_1,
+    "nonce": "0x1",
+    "blockHash": HASH_2,
+    "blockNumber": "0x10",
+    "transactionIndex": "0x0",
+    "from": ADDRESS_CHECKSUM,
+    "to": ADDRESS_LOWER,
+    "value": "0x0",
+    "gas": "0x5208",
+    "gasPrice": "0x3b9aca00",
+    "input": "0x",
+    "v": "0x1b",
+    "r": HASH_3,
+    "s": HASH_4,
+}
+
+EIP1559_TX = {
+    "type": "0x2",
+    "hash": HASH_2,
+    "nonce": "0x2",
+    "blockHash": HASH_3,
+    "blockNumber": "0x10",
+    "transactionIndex": "0x1",
+    "from": ADDRESS_LOWER,
+    "to": ADDRESS_CHECKSUM,
+    "value": "0x1",
+    "gas": "0x5208",
+    "gasPrice": "0x3b9aca00",
+    "maxFeePerGas": "0x77359400",
+    "maxPriorityFeePerGas": "0x3b9aca00",
+    "input": "0x",
+    "v": "0x0",
+    "r": HASH_1,
+    "s": HASH_2,
+    "yParity": "0x1",
+    "accessList": [],
+}
+
+TX_LIST = [
+    LEGACY_TX,
+    EIP1559_TX,
+]
+
+BLOCK_WITH_TXS = {
+    "timestamp": "0x65f2",
+    "transactions": TX_LIST,
+}
+
+BLOCK_WITH_HASHES = {
+    "timestamp": "0x65f2",
+    "transactions": [HASH_1, HASH_2],
+}
+
+LOG = {
+    "address": ADDRESS_CHECKSUM,
+    "topics": [TOPIC_0, TOPIC_1],
+    "data": DATA_32,
+    "removed": False,
+    "blockNumber": "0x10",
+    "transactionHash": HASH_1,
+    "logIndex": "0x1",
+    "transactionIndex": "0x0",
+}
+
+RECEIPT = {
+    "transactionHash": HASH_1,
+    "blockNumber": "0x10",
+    "contractAddress": None,
+    "transactionIndex": "0x0",
+    "status": "0x1",
+    "gasUsed": "0x5208",
+    "cumulativeGasUsed": "0x5208",
+    "logs": [LOG],
+    "effectiveGasPrice": "0x3b9aca00",
+    "type": "0x2",
+}
+
+
+def _dump(obj: object) -> bytes:
+    return json.dumps(obj, separators=(",", ":")).encode()
+
+
+RAW_LEGACY_TX = _dump(LEGACY_TX)
+RAW_EIP1559_TX = _dump(EIP1559_TX)
+RAW_TX_LIST = _dump(TX_LIST)
+RAW_BLOCK_WITH_TXS = _dump(BLOCK_WITH_TXS)
+RAW_BLOCK_WITH_HASHES = _dump(BLOCK_WITH_HASHES)
+RAW_LOG = _dump(LOG)
+RAW_RECEIPT = _dump(RECEIPT)

benchmarks/data.py

@@ -0,0 +1,19 @@
+# mypy: disable-error-code=misc
+import pytest
+from pytest_codspeed import BenchmarkFixture
+
+from benchmarks.batch import batch
+from benchmarks.data import ADDRESS_CASES, ADDRESS_CASE_IDS
+from evmspec.data import Address
+
+
+@pytest.mark.benchmark(group="address_checksum")
+@pytest.mark.parametrize("address", ADDRESS_CASES, ids=ADDRESS_CASE_IDS)
+def test_address_checksum(benchmark: BenchmarkFixture, address: str) -> None:
+    benchmark(batch, 100, Address.checksum, address)
+
+
+@pytest.mark.benchmark(group="address_construct")
+@pytest.mark.parametrize("address", ADDRESS_CASES, ids=ADDRESS_CASE_IDS)
+def test_address_construct(benchmark: BenchmarkFixture, address: str) -> None:
+    benchmark(batch, 100, Address, address)

benchmarks/test_address_benchmarks.py

@@ -0,0 +1,26 @@
+# mypy: disable-error-code=misc
+import pytest
+from msgspec.json import Decoder
+from pytest_codspeed import BenchmarkFixture
+
+from benchmarks.batch import batch
+from benchmarks.data import RAW_BLOCK_WITH_HASHES, RAW_BLOCK_WITH_TXS
+from evmspec.data import _decode_hook
+from evmspec.structs.block import TinyBlock
+
+_decode_tinyblock = Decoder(type=TinyBlock, dec_hook=_decode_hook).decode
+
+
+def _decode_block_transactions(raw: bytes) -> None:
+    block = _decode_tinyblock(raw)
+    block.transactions
+
+
+@pytest.mark.benchmark(group="tinyblock_transactions")
+@pytest.mark.parametrize(
+    "raw",
+    [RAW_BLOCK_WITH_TXS, RAW_BLOCK_WITH_HASHES],
+    ids=["full-transactions", "hashes-only"],
+)
+def test_tinyblock_transactions(benchmark: BenchmarkFixture, raw: bytes) -> None:
+    benchmark(batch, 20, _decode_block_transactions, raw)

benchmarks/test_block_benchmarks.py

@@ -0,0 +1,63 @@
+# mypy: disable-error-code=misc
+import pytest
+from msgspec.json import Decoder
+from pytest_codspeed import BenchmarkFixture
+
+from benchmarks.batch import batch
+from benchmarks.data import (
+    RAW_EIP1559_TX,
+    RAW_LEGACY_TX,
+    RAW_LOG,
+    RAW_RECEIPT,
+    RAW_TX_LIST,
+)
+from evmspec.data import _decode_hook
+from evmspec.structs.log import Log
+from evmspec.structs.receipt import TransactionReceipt
+from evmspec.structs.transaction import Transaction, Transaction1559, TransactionLegacy
+
+_decode_legacy_tx = Decoder(type=TransactionLegacy, dec_hook=_decode_hook).decode
+_decode_1559_tx = Decoder(type=Transaction1559, dec_hook=_decode_hook).decode
+_decode_transactions = Decoder(type=tuple[Transaction, ...], dec_hook=_decode_hook).decode
+_decode_receipt = Decoder(type=TransactionReceipt, dec_hook=_decode_hook).decode
+_decode_log = Decoder(type=Log, dec_hook=_decode_hook).decode
+
+
+def _decode_1559_access_list(raw: bytes) -> None:
+    tx = _decode_1559_tx(raw)
+    tx.accessList
+
+
+def _decode_receipt_logs(raw: bytes) -> None:
+    receipt = _decode_receipt(raw)
+    receipt.logs
+
+
+@pytest.mark.benchmark(group="decode_tx_legacy")
+def test_decode_tx_legacy(benchmark: BenchmarkFixture) -> None:
+    benchmark(batch, 100, _decode_legacy_tx, RAW_LEGACY_TX)
+
+
+@pytest.mark.benchmark(group="decode_tx_1559")
+def test_decode_tx_1559(benchmark: BenchmarkFixture) -> None:
+    benchmark(batch, 100, _decode_1559_tx, RAW_EIP1559_TX)
+
+
+@pytest.mark.benchmark(group="decode_tx_list")
+def test_decode_tx_list(benchmark: BenchmarkFixture) -> None:
+    benchmark(batch, 50, _decode_transactions, RAW_TX_LIST)
+
+
+@pytest.mark.benchmark(group="decode_tx_access_list")
+def test_decode_tx_access_list(benchmark: BenchmarkFixture) -> None:
+    benchmark(batch, 50, _decode_1559_access_list, RAW_EIP1559_TX)
+
+
+@pytest.mark.benchmark(group="decode_log")
+def test_decode_log(benchmark: BenchmarkFixture) -> None:
+    benchmark(batch, 200, _decode_log, RAW_LOG)
+
+
+@pytest.mark.benchmark(group="decode_receipt_logs")
+def test_decode_receipt_logs(benchmark: BenchmarkFixture) -> None:
+    benchmark(batch, 50, _decode_receipt_logs, RAW_RECEIPT)

benchmarks/test_decoding_benchmarks.py

@@ -0,0 +1,13 @@
+# mypy: disable-error-code=misc
+import pytest
+from pytest_codspeed import BenchmarkFixture
+
+from benchmarks.batch import batch
+from benchmarks.data import HEXBYTES32_CASES, HEXBYTES32_CASE_IDS
+from evmspec.data import HexBytes32
+
+
+@pytest.mark.benchmark(group="hexbytes32_construct")
+@pytest.mark.parametrize("value", HEXBYTES32_CASES, ids=HEXBYTES32_CASE_IDS)
+def test_hexbytes32_construct(benchmark: BenchmarkFixture, value: bytes | str) -> None:
+    benchmark(batch, 100, HexBytes32, value)