Skip to content

refactor(clob): split the epoch-service god-object into focused modules (M4)#10

Merged
drewstone merged 2 commits into
mainfrom
refactor/m4-clob-modules
Jun 13, 2026
Merged

refactor(clob): split the epoch-service god-object into focused modules (M4)#10
drewstone merged 2 commits into
mainfrom
refactor/m4-clob-modules

Conversation

@drewstone

Copy link
Copy Markdown
Contributor

Closes the last reasoned-deferred audit item (M4). Pure structural refactor —
zero behavior change.

Why

operator/src/clob.rs had grown to ~1.4k lines holding, in one impl Clob:
config parsing, the transport trait + its HTTP impl, every wire type, all
pool/finality state, the proposer driver, the verifier, and the axum surface.
One file, seven unrelated concerns.

What

Split into a clob/ module, one cohesive concern per file:

file concern
config.rs ClobConfig + SURPLUS_CLOB_* parsing
net.rs the ClobNet transport trait + HTTP peer-list impl
wire.rs JSON wire types (order / cancel / proposal / attestation)
pool.rs admission, settled/cancelled finality sets + journal, snapshot, prune/evict
driver.rs proposer side: match → H3 pre-sim → quorum → submit, on-chain client, membership reconcile
peer.rs verifier side: attest + status
http.rs axum router, handlers, env boot, background loops
mod.rs Clob struct, constructors, shared accessors, re-exports

It's a move: the only non-mechanical change is bumping the handful of Clob
methods a sibling module now calls from private to pub(crate)/pub(super)
(snapshot, prune_filled, is_cancelled, load_finality, evict). The
public surface (crate::clob::{router, start_from_env, attest_deadline, Clob, ClobConfig, Wire*, ClobNet, HttpNet, cancel_digest, …}) is re-exported
unchanged, so mesh.rs and the integration tests didn't move a line.

A typed Attester newtype for the (Address, String) operator tuples was
deliberately left out — it ripples into mesh.rs and two test fixtures and
would bury this move-only diff. A follow-up if it earns its keep.

Verification

  • Builds clean on both feature sets (default, and chain,mesh).
  • Green: 13 operator unit + 4 clob_e2e + 1 mesh_clob + the matcher /
    settlement suites.
  • Both anvil e2e proofs pass byte-for-byte against the refactored binary:
    the happy-path batch settle, and the H3 pre-sim adversarial grief
    (bookNonce unchanged, doomed buy evicted, seller's order survives).

🤖 Generated with Claude Code

…es (M4)

`clob.rs` had grown to ~1.4k lines holding config parsing, the transport
trait + HTTP impl, every wire type, all pool/finality state, the proposer
driver, the verifier, and the axum surface in one `impl Clob`. Audit M4.

Split into a `clob/` module, one cohesive concern per file:
  - config.rs — `ClobConfig` + `SURPLUS_CLOB_*` parsing
  - net.rs    — the `ClobNet` transport trait + the HTTP peer-list impl
  - wire.rs   — the JSON wire types (order / cancel / proposal / attestation)
  - pool.rs   — admission, the settled/cancelled finality sets + journal,
                the epoch snapshot, prune/evict (all shared-state mutation)
  - driver.rs — proposer side: match → H3 pre-sim → quorum → submit, the
                on-chain client, and membership reconciliation
  - peer.rs   — verifier side: `attest` + `status`
  - http.rs   — the axum router, handlers, env boot, and background loops
  - mod.rs    — the `Clob` struct, constructors, shared accessors, re-exports

Pure move: zero behavior change. Cross-module `Clob` methods were bumped
from private to `pub(crate)`/`pub(super)` where a sibling now calls them
(snapshot, prune_filled, is_cancelled, load_finality, evict); nothing else
changed. The public surface (`crate::clob::{router, start_from_env,
attest_deadline, Clob, ClobConfig, Wire*, ClobNet, cancel_digest, …}`) is
re-exported unchanged, so mesh.rs and the integration tests are untouched.

A typed `Attester` newtype for the `(Address, String)` operator tuples was
deliberately left out: it ripples into mesh.rs and two test fixtures and
would obscure this move-only diff — a follow-up if it earns its keep.

Verified: builds clean (default + chain,mesh); 13 operator unit + 4
clob_e2e + 1 mesh_clob + matcher/settlement suites green; and both anvil
e2e proofs — happy-path batch settle and the H3 pre-sim adversarial grief —
pass byte-for-byte against the refactored binary.
H3 (PR #9, merged) and M4 (PR #10) were the last two reasoned deferrals.
Every CRITICAL/HIGH/MEDIUM/LOW from the 2026-06-12 audit is now closed; the
only open items are non-engineering (C2 Safe-signer live-close, PRODUCT P1–P3).
@drewstone drewstone merged commit d622666 into main Jun 13, 2026
2 of 5 checks passed
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.

1 participant