ADR-026: Retire the “backrun” label — “settlement arbitrage” (strategy) and “arbitrage” (umbrella layer)

Status: accepted. Supersedes the “backrun” naming used by ADR-019, ADR-025, and the degenbot-settlement-strategy crate / eth_backrun_* example for all forward-looking writing. It does not rewrite those historical records — they keep “backrun” as it read at the time; this ADR is the canonical reference the codebase moves toward (tracked by ergo epic R2BXPV).

Context

The repository’s strategy has been named “backrun” since ADR-019 (the crate degenbot-settlement-strategy, the example examples/eth_backrun_v2_v3_v4_rust.py, and the ADR-019/025 bodies). That label is architecturally misleading and kept requiring re-explanation across sessions:

  • “Backrun” (classic MEV) means positioning a transaction/bundle immediately after a specific, identified victim transaction (mempool-ordered), profiting from that victim’s price impact — a named victim and ordering relative to it are essential.

  • This bot’s strategy reads the settled block’s resulting pool state, solves cross-pool price discrepancies (V2/V3/V4 paths) with no labeled victim, and dispatches a single transaction at the head of the next block. It has no victim-tx targeting and no tx-to-tx ordering.

Because “backrun” is an overloaded MEV term that does not describe this mechanism, every session’s implicit reading had to be corrected by hand. The decision below gives the codebase a durable, unambiguous vocabulary.

A secondary driver: reviewers repeatedly had to decode the abbreviation “arb”. “arbitrage” is a real, look-up-able word; the repo standardizes on the verbose, unabbreviated form.

Decision

D1 — Canonical terms (supersede “backrun” everywhere forward-looking)

  • “settlement arbitrage” — the bot’s current strategy: arbitrage the cross-pool price discrepancies a settled block leaves in pool state, executing one transaction at the next-block head. The defining properties are (1) the opportunity source is a settled pool-state discrepancy (not a victim’s flow) and (2) execution is a single tx at the next-block head (not ordered against a specific tx).

  • “arbitrage” — the umbrella strategy layer. Users may run any arbitrage strategy (liquidation, sandwich, frontrun, backrun, multi-market, statistical, CEX/DEX, …); the layer is deliberately neutral (Q6).

  • No “arb” abbreviation anywhere — “arbitrage” spelled out.

D2 — Identifier mapping (crunch/epic R2BXPV)

Layer

Old

New

crate

degenbot-settlement-strategy

degenbot-arbitrage

logger

degenbot_settlement_strategy

degenbot_arbitrage

example

examples/eth_backrun_v2_v3_v4_rust.py

examples/eth_settlement_arbitrage_v2_v3_v4_rust.py

public CLI fn

build_backrun_arg_parser

build_arbitrage_arg_parser

internal fn

_make_backrun_config

_make_arbitrage_config

tests

test_backrun_* / test_eth_backrun_*

test_arbitrage_* / test_eth_arbitrage_*

CLI/config prose

“backrun chain/session”

“arbitrage chain/session”

mechanism prose

“backrun bot/strategy”

“settlement arbitrage” / “arbitrage”

  • Consistent naming across all layers so the decision is durable.

  • No backwards-compat stub/alias for any renamed symbol (internal features; no public callers — AGENTS.md standalone-feature rule).

D3 — History is frozen (this ADR supersedes, it does not rewrite)

  • ADR-019, ADR-025 titles + bodies keep “backrun” as they read historically.

  • docs/investigations/*, docs/plans/*, docs/results/*, docs/migration-guides/*, and other dated extraction records keep the label.

  • Future work uses the canonical terms via this ADR.

Consequences

  • Forward-looking code and living docs (README, CONTEXT.md, living docs/architecture/*) move to the canonical terms; done under ergo epic R2BXPV, staged non-breaking prose first (B1–B3), then breaking identifier renames (A1–A5).

  • Historical records intentionally retain the old label and become the proof of what was named at the time; a stale identifier reference in a frozen record to a renamed crate/symbol is expected and not corrected.

  • Search tooling/rg are the source of truth for any residual hit; the final audit gate (task A5) asserts the only remaining “backrun” hits are frozen.