Crate degenbot_core

Expand description

Foundational utilities shared across all degenbot Rust crates.

This crate is the foundational leaf every other degenbot crate builds on. Its only non-ecosystem dependencies are degenbot-config (the typed BotConfig schema the CPU-budget sizing keys live in) and parking_lot. It has no pyo3 dependency under default features — the optional pyo3 feature enables From<Error> for PyErr conversions co-located with the error types (the orphan rule forbids putting those impls in a downstream crate, since both PyErr and the error types would be foreign there).

§Modules

errors — centralized error types (TickMathError, ClMathError, AbiDecodeError, AddressError, ProviderError, ContractError) with inter-error conversions. The From<Error> for PyErr impls are gated behind the pyo3 feature.
hex_utils — pure-Rust hex encoding/decoding.
address_utils — EIP-55 checksummed Ethereum addresses.
cpu_budget — cgroup-aware CPU budget detection and the two-runtime (solve bins / ambient I/O) sizing policy.
runtime — shared Tokio runtime singleton, sized by cpu_budget.
worker_census — boot-time registry of every execution resource (name/kind/count/thread-name/sizing) exported as the degenbot_worker_census gauge ; NEW SPAWN SITES MUST REGISTER — see the module docs.
eip_1559 — EIP-1559 next_base_fee (next-block base fee).
fee_percentiles — the shared priority-fee percentile pair the RPC oracle polls and the settlement-arbitrage strategy sizes against.
session_positions — the position seam: session-canonical position identity, the refusal vocabulary a read answers with, and the observer trait a lending integration implements. It sits here because the engine and the lending integrations already share this layer and no other one.

Modules§

address_utils: Address utility functions.
block_clock_pipe: BlockClockPipe — the shared block-clock channel (ADR-027 completion; architecture review 2026-08-20).
cpu_budget: Container-aware runtime CPU budget detection, shared by every consumer.
eip_1559: EIP-1559 base-fee math (relocated from the retired single-function crate degenbot-evm-math).
errors: Error types for degenbot Rust extensions.
fee_percentiles: The priority-fee market percentiles the fee-history oracle polls and the settlement-arbitrage strategy sizes against.
hex_utils: Pure-Rust hex encoding and decoding utilities.
libzip: Solady LibZip: FastLZ compress/decompress for EVM bytecode.
retry: Canonical retry-with-backoff policy for the workspace .
runtime: Shared Tokio runtime management.
session_positions: The position seam: session-canonical position identity, the refusal vocabulary a position read can answer with, and the trait a lending integration implements to serve one.
telemetry: The observability facade (ADR-043).
updater_telemetry: The updater→application telemetry port.
worker_census: Worker census registry (observability surface of the ADR-042 role-switching fleet, section 7).

Macros§

diag: A DEBUG diagnostic under a closed domain target, with the engine-span guard.
diag_trace: A TRACE forensic diagnostic under a closed domain target (full-field dumps: call traces, tick maps). Never on the console by default — the sink must enable degenbot=trace; the phase-4 forensic file sink captures it.
op_debug: A DEBUG lifecycle event under a closed domain target (the boot/census verdicts: process-wide sizing, runtime construction). Deliberately unguarded — unlike diag! these fire BEFORE any engine span exists, so the engine-span guard would only raise false alarms.
op_error: An ERROR event under a closed domain target.
op_info: An INFO lifecycle event under a closed domain target.
op_span: An INFO span named on the domain target (the engine-span namespace).
op_warn: A WARN event under a closed domain target.
telemetry_target: Map a domain token to its closed target, or fail the build.