Build OpenHL Precompiles — connecting CLOB state to smart contracts

Question

Build openhl's precompile layer in Rust. Precompiles bridge the CLOB matching engine to the EVM — Solidity contracts read live orderbook state and submit orders via precompile calls. Pinned to openhl SHA e5ad29d.

Principle (minimum model)

• 12 lessons across 6 modules. Orientation → Custom EVM bootstrap → Read precompile (3 lessons, reaching live state) → Write precompile (2 lessons, order submission) → Bridge integration (2 lessons, fills flow back) → Capstone.
• Precompiles = Rust functions at magic addresses. Solidity calls address 0xCL...AB; Reth dispatches to your Rust function instead of executing bytecode.
• Three milestones. (1) read_best_bid hardcoded → wired through NodeBuilder. (2) read_best_bid reads live CLOB state. (3) place_order submits live + fills flow back via install_fill_sink.
• Pinned to SHA e5ad29d. Every example reproducible. Capstone answer-key at this SHA.
• Prerequisites. openhl CLOB (matching engine state machine) + Foundry course (Solidity testing).
• Architecture. OpenHlEvmFactory hooks into Reth's EVM creation; injects the precompiles + the install_clob / install_fill_sink bridges. Same OpenHlEvmFactory is reused for production sequencer + test harness.
• Production parallel. Hyperliquid HyperEVM uses this exact pattern (different code, same shape).

Worked example + steps

Build OpenHL Precompiles — connecting CLOB state to smart contracts

The previous course (building-openhl-clob) ended with the bridge owning a CLOB matching engine. Orders submit, fills flow into payloads, the integration test exercises the whole pipeline against a real Reth node. But the fills are still a parallel list. Smart contracts running inside that same Reth node can't see them. The CLOB state and the EVM state live in two different worlds.

This course closes that gap. You'll add custom EVM precompiles — EVM-native Rust functions registered at fixed addresses, callable from Solidity exactly like external contracts but executing native Rust (no EVM bytecode in between). Ethereum already reserves 0x01–0x0a for standard precompiles like ECDSA recovery and SHA-256; we'll register our CLOB precompiles in a parallel custom range starting at 0x0c00. After course 8:

• A smart contract can call 0x...0c1b (in our custom range) to read the current best bid.
• A smart contract can call 0x...0c1c (in the same range) to place an order that the matching engine processes.

Once these two paths exist, the CLOB stops being a parallel structure beside the EVM and starts being a state extension the EVM can interact with. That's what makes the chain "Hyperliquid-shape" — Hyperliquid's whole novelty is that the perp matching engine is callable from smart contracts running on the same chain.

By the end of this course, cargo test clob_precompile_round_trip passes — a smart contract call places an order via precompile, the order matches against existing book state, and the resulting fill flows back into the bridge.

1. What you'll have at the end

A new crates/evm/src/precompiles/ module containing:

• Two custom precompiles registered at well-known EVM addresses:
  • clob_read_best_bid (read): returns (price, qty) of the best bid as a 64-byte response.
  • clob_place_order (write): decodes an order from calldata, submits it to the CLOB, returns the fill summary.
• Custom EVM machinery (openhl_evm.rs) — an EvmFactory + ExecutorBuilder that wires the precompiles into Reth's executor.
• Bridge integration — LiveRethEvmBridge spawns its underlying Reth node with the custom EVM, so smart contract calls to the precompiles touch the same CLOB instance the bridge owns.

About 6 commits worth of work in openhl (~860 LOC), broken into 12 lessons (Lessons 0–11, with Lesson 11 as the capstone). The end-to-end test takes ~3 seconds: bootstrap Reth, deploy a thin solidity wrapper (or call directly via the engine), trigger the precompile, assert the fill.

2. What you won't have at the end

This course covers openhl Stage 9 (9a-9e) only. It does NOT cover:

• Encoding Fill → real EVM transaction in the block body. The fills are still a parallel list attached to payloads (the situation from course 7 Lesson 12). Course 8 makes them accessible from EVM execution, but doesn't make them part of the block body. That's a future course.
• Funding state machine. That's Stage 8b / course 9.
• Liquidations, oracles, perp-specific math. Not in Stage 9.
• Multi-market precompiles. Stage 9 has one CLOB; production would have one precompile per market or one with market-id calldata.

When you finish this course you have a chain where smart contracts can read and write the CLOB. That's a massive capability jump — it's the difference between "the chain has an orderbook somewhere" and "the chain is an orderbook + EVM." But fully closing the loop (fills back into block body as txs) is downstream work.

3. Prerequisites

You need:

• building-openhl-clob complete — or, equivalently, a workspace at the end-of-course-7 state. Your LiveRethEvmBridge<P> should have clob, pending_fills, submit_order, payload_fills, and pending_fill_count from Lessons 9–11 of that course. If yours doesn't, work through course 7 first.
• Rust 1.95+, same as before.
• Familiarity with REVM at the trait level. You don't need to have written precompiles before — Lesson 1 explains the pattern — but if you've never seen REVM's Precompile, PrecompileFn, or Precompiles types, skim the revm precompile docs first.
• Comfort with Arc<Mutex<T>> for shared state across thread boundaries. Precompiles need to read the CLOB from the EVM's execution context, which is a different async/sync boundary than the bridge's normal call sites.

You do not need:

• Any prior EvmFactory or ExecutorBuilder knowledge (Lessons 1–2 explain them).
• Any Solidity (we don't write Solidity — we just exercise the precompiles via raw calldata).
• Knowledge of Reth's internal block-execution pipeline beyond what course 6 covered.

4. Setup confirmation (do this now)

You should already have the two-directory workflow from courses 6 and 7:

• ~/code/my-openhl/ — your workspace
• ~/code/openhl-reference/ — read-only psyto/openhl clone

Bring the reference repo up to date in case Stage 9 commits are newer than your clone:

cd ~/code/openhl-reference
git fetch origin
git log --oneline | head -25
# You should see commits up to and including SHA d19ba1b (Stage 9c+).
# `git log` defaults to reverse-chronological order (newest first); the
# main Stage 9 commits appear like this:
#   2ba97c6 — Stage 9e
#   2f796c3 — Stage 9d
#   d19ba1b — Stage 9c+
#   a8823a1 — Stage 9c
#   b635ef7 — Stage 9b
#   1761d4d — Stage 9a

Then confirm your workspace is at the end-of-course-7 state:

cd ~/code/my-openhl
cargo test -p openhl-evm clob_fills_flow_into_payload --release 2>&1 | tail -5
# Expect: test passes (this is course 7's milestone test).

If that passes, you're at the right starting point.

5. The 12-lesson map

Lesson 10 is the milestone. Finishing Lesson 10, you have an EVM-callable CLOB on a live Reth node: smart contracts call precompiles, the matching engine runs, fills emerge through the bridge into payloads. Lesson 11 names what's still missing (the fills aren't yet EVM transactions — that's beyond Stage 9).

6. The answer-key discipline (same as before)

Each lesson from Lesson 1 to Lesson 10 cites one of the 6 Stage 9 commits:

After each lesson's test passes:

cd ~/code/openhl-reference
git checkout <SHA>
diff -u ~/code/my-openhl/crates/evm/src/precompiles/mod.rs ./crates/evm/src/precompiles/mod.rs

Match meaningfully — same types, same control flow. Whitespace and naming will differ.

7. Setup confirmation — the actual Lesson 0 exercise

Before Lesson 1, run all of these and confirm they pass:

# 1. Rust version
rustc --version    # expect: rustc 1.95.x or later

# 2. End-of-course-7 state
cd ~/code/my-openhl && cargo test -p openhl-evm clob_fills_flow_into_payload --release 2>&1 | tail -3
# Expect: 1 test passing

# 3. Reference repo has Stage 9 commits
cd ~/code/openhl-reference && git log --oneline | grep -E "(1761d4d|b635ef7|a8823a1)"
# Expect: all three SHAs appear

If all three pass, you're ready for Lesson 1.

Final check. In one sentence, what does this course add that course 7 didn't? If your answer doesn't mention "smart contracts can read and write the CLOB," re-read §1.

Summary (3 lines)

• Build openhl precompiles = read/write bridge between CLOB matching engine and EVM. 12 lessons / 6 modules.
• Three milestones: hardcoded read → live read → live write + fill sink. Pinned to SHA e5ad29d.
• Prerequisites: openhl CLOB + Foundry. Production parallel: Hyperliquid HyperEVM.