Architecture Decision Records

ADRs record the architecture-level decisions behind the Rust core once they are considered settled (accepted / implemented / proposed); the crate sources remain the last word on what the code actually does today. New ADRs are proposed and reviewed through ergo tasks and committed via their own review flow — a table row is added when the file lands.

Start here

The load-bearing decisions behind the two-consumer architecture:

• ADR-005: Polars-Inspired Three-Layer Architecture — why a Rust engine with a thin Python driver

• ADR-003: BotCore as the state layer, peer to ArbitrageEngine — where all pool/token state lives

• ADR-019: In-Process revm as the Sole Simulation Executor; Strategy-vs-Engine Separation — the sole simulation executor + strategy/engine separation

• ADR-008: Per-block state machine for the pump’s block clock — the pump’s block clock

• ADR-025: The ExecutionAdapter seam — a deep, user-owned execution layer over the thin engine — how user code plugs into execution

Index

ADR	Title	Status
001	I/O-Free Pool Architecture	accepted
002	Pool Type Registry as Module-Level Singleton	accepted
003	BotCore as the state layer, peer to ArbitrageEngine	accepted
004	Typed TickMap boundary for CL verifier + liquidity-apply seam	accepted
005	Polars-Inspired Three-Layer Architecture	accepted
006	Bot as the per-chain orchestrator	implemented
007	Pool unregister seam	accepted
008	Per-block state machine for the pump’s block clock	implemented
009	Single-Source-of-Truth Versioning	accepted
010	Alembic Retention Through 0.6.x and Rust Schema Cutover	accepted
011	Auto-healed Alembic Retirement (Dump-and-Restore Cutover)	proposed
012	Spec-Bound Pool Admission Contract	accepted
013	The _ffi Seam Is Private (Pydantic Barrier)	accepted
014	Pool-State Deepening — Where the Trait Seams Live	accepted
015	Solver-Seam Relocation — the Resolve→Solve Boundary	accepted
016	ReorgPoolState — Pool-Owned Reorg Rollback	accepted
017	Forward-Apply Pool-State Traits	accepted
018	Tracked Debt — bot_core↔solvers Fusion	accepted
019	In-Process revm as the Sole Simulation Executor	accepted
020	Tier-3 On-Chain Accuracy Oracle	accepted
021	Solver-state accuracy is a fail-fast tripwire	accepted
022	Registration verify-lifecycle is core-owned	accepted
023	PyBotIo end-state disposition	accepted
024	Net-profit order index (degenbot-order-index)	accepted
025	The ExecutionStrategy seam	accepted
026	Retire the “backrun” label — “settlement arbitrage”	accepted
027	The block-pump dispatch seam	accepted
028	The block-pump PumpDecision seam	accepted
029	The executor command grammar	accepted
030	The derivation outcome is a tri-state	accepted
031	The executor grammar as a facts-driven Plan walker	accepted; implemented
032	#[pyclass] Python naming convention	accepted
033	The encode funnel’s intake contract	accepted
034	ERC6909-vault profit capture wiring	accepted
035	Consolidate the AMM math family into degenbot-math	accepted
036	Do not re-land the V3/V4 window guards	accepted
037	Engine Mutex sharding (RAYPAR)	accepted
037	The swap-simulation gate	accepted
038	The CL event-routing FSM	accepted
039	State-lock — enumerated sim-anchor projection	pending status
040	Failure reactions are per-bucket	accepted
041	The block-epoch pipeline — one stage machine over a cheap-read data plane	implemented
042	One role-switching worker fleet — a bounded, budgeted host for every execution resource	proposed
043	The observability standard — four channels, a level rubric, one target taxonomy	proposed
044	Fleet intake liveness — BackstopTick + PostureEdge complete the host transition relation	accepted
045	The solve cycle as a deep module — ArbEngine regroups into registry + cycle + config	accepted
046	StageHandlers stays the pure product seam; PumpControl is the driver-facing control seam	accepted
047	Retire the ADR-006 D4 subscriber bus — compile is the guard for retired modules	accepted
048	Fleet boot registry — one keyed owner for the pooled roles’ boot facts	accepted
049	The engine’s interface is one stage seam — the engine recedes to composition machinery	accepted
050	A public EngineDriver is the Rust driver seam — the engine stays crate-private behind the one stage seam	accepted
051	The degenbot console is a Rust binary — one command model, an argv passthrough for Python	accepted
052	The database upgrades itself at open — Alembic retires in-tree ahead of 0.7	accepted
053	FFI Stub Generation — Retire the Hand-Maintained .pyi Set?	accepted
054	The strategy plumbing surface — ReplayOutcome, journal extractors, the planning workspace, and anchored discovery are the promoted seams	accepted
055	Pending-transaction strategy seams — MarketContext, PendingTxStrategy, SubmissionTarget, V4 substrate closure	accepted
056	Retire the gated serving seam — refuted premise, membership to the boot registry	accepted
057	The strategy host — one process, many drivers over one operator account	accepted
058	The strategy crate split — submission is mechanism, degenbot-strategy owns the plane	accepted
059	The pool family kernel — one taxonomy, capability tiers, species as data	accepted
060	Collapsing the V2 walk dispatch — representation vs interface	accepted
061	Pool-state provisioning is a plane capability — pool ingress, sealed seeds, the strategy kit	accepted
062	One operator file, four layers — node endpoints, chain id, and database path resolve through the typed config on every entry path	accepted
063	The file is portable, the secret is not — ${env:NAME} expansion for string-valued config keys	proposed
064	The session object registry is the cutover — identity is minted once, and the Python side is an adapter	accepted
065	The verdict is the single configuration authority — one load, one frozen projection, provenance in the authority	accepted
066	Deterministic Stub Generation — experimental-inspect and pyo3-introspection retire the hand-maintained .pyi set	accepted
067	The strategy substrate gets one home — ADR-061’s placement reopens	accepted

Numbering note: ADR-037 was assigned twice (engine mutex sharding; swap-simulation gate) — both kept as filed.