[mfw78]

Why

The first version of this pull request restored the operator docs, and in doing so it documented at length things that did not work: six shipped engine configs that could not boot, a soak harness that needed two local patch files before it started, and an EthFlow module that read Sepolia beside a venue on mainnet. A document that explains how to work round the repository is the wrong fix. This version repairs or removes those things, and the docs describe one path that was run for real.

Merge this after the re-pin in #698 (nexum-runtime 15e4a38): the soak runbook reads nexum_runtime_start_time_seconds and nexum_runtime_delivery_latency_seconds, which that runtime adds.

What changed

The shipped files form one consistent mainnet deployment.

• modules/ethflow-watcher/component.toml reads the production EthFlow contract on chain 1. The address is ETH_FLOW_PRODUCTION in the pinned cowprotocol crate, and it has code on mainnet. The module takes its chain from each log, so no module code changes.
• engine.docker.toml, docker-compose.yml and .env.example need one RPC endpoint (MAINNET_RPC_URL), not five.
• docker-compose.yml waits 180 seconds on a stop, longer than the engine's 150 second drain, where it waited 30. It also bounds the container log at 10 files of 100 MB.
• engine.example.toml no longer names the wrong binary or a positional argument that does not exist.

Removed, because they could not run. engine.m2.toml, engine.m3.toml, engine.e2e.toml, engine.load.toml, engine.soak.toml, engine.soak.docker.toml and docker-compose.soak.yml; the e2e-*, load-* and soak-snapshot scripts with lib.sh, env-template, the two Python helpers and scripts/README.md; and the run-m2, run-e2e, e2e, load and soak-snapshot recipes. The configs named modules this repository does not build or chains they did not declare, the e2e scripts targeted a different chain and registry from their config and checked metric names that no longer exist, and the load script needed a tool that nexum-runtime retired. The forked-mainnet engine test (anvil_fork_e2e.rs) covers what the e2e scripts were for. Everything removed is in the history and at the pre-carve tag.

Docs. Three files where there were four, and about 590 lines where there were about 1290.

• docs/deployment.md: the engine config reference, the two modules, and a "Multi-chain deployment" section that replaces the multi-chain guide. It names the two patterns (one engine process for each chain, which the CoW venue requires, and one process for many chains), lists the supported chains, gives a worked example that runs ethflow-watcher on Gnosis Chain, shows the chain tables for Ethereum Mainnet, Gnosis Chain, Base and Arbitrum One, and ends with what is tested and what is not.
• README.md gains a documentation map: the operator guides here, and the module tutorial, SDK guide, testing guide, manifest reference and operator handbook in nexum-runtime.
• docs/deployment/docker.md: build, run, verify, pin the digests, Prometheus, stop, upgrade, backup.
• docs/operations/soak-runbook.md: a soak is the Compose deployment with its Prometheus profile, plus a table of queries (uptime, engine restarts, module state, quarantine, faults, delivery latency, handler latency, memory, reconnects, RPC errors) and the steps that save the evidence. The queries apply to any Prometheus that scrapes the engine. It keeps the step that removes the RPC endpoint from a log before the log is published.

Tests.

• operator_configs.rs gains a test that holds engine.docker.toml to the shipped manifests: every chain a trigger reads is declared, and it is the venue's chain. Parsing alone let a config through that named the wrong chain.
• operator_configs.rs also holds the chain tables of the multi-chain section to the pinned parser, and makes sure that the venue accepts each of Ethereum Mainnet, Gnosis Chain, Base and Arbitrum One.
• module_manifests.rs no longer demands a start_block on the EthFlow trigger. It pins the registry's deployment block for ccow-monitor as before, and it pins the EthFlow trigger to chain 1, the production address, resume, and no start_block.

Worth a second look

• ethflow-watcher opens at head on its first boot. The earlier manifest backfilled from the contract's Sepolia deployment block. On mainnet that would read the contract's whole history and put every past order under watch, all long settled or expired. The module only observes, so the first boot starts at head and resume covers every later restart. An order that was open at the moment of the very first boot is not observed.
• The Compose soak harness is gone, with its hourly snapshot container. The runbook records the same evidence through Prometheus. Process memory still has no engine metric, so the runbook reads it from docker stats.
• Published image. The package is public now, so the Docker guide leads with docker compose pull shepherd and gives the local build as the alternative. An anonymous pull was run and it worked. The verification below used an image built from this branch: the latest image on the registry is the build of main before this pull request, and its EthFlow manifest still reads Sepolia, so the full pull-then-run path can be run only after this merges and main publishes.
• tools/baseline-latency is untouched. It targets Sepolia and was not run for this change.
• Multi-chain operation is documented and held to the config parser and the venue by a test, and the Gnosis Chain example was started once by hand. No run of many days was made on a chain other than Ethereum Mainnet, and the guide says so.

Verification

The image was built from this branch on top of the re-pin, and every command in the Docker guide and the soak runbook was run against it with a mainnet node:

• Boot: /readyz answered ready: true with both modules alive, the container went healthy, ccow-monitor finished its first-boot backfill of about 500,000 blocks in 35 seconds, and ethflow-watcher opened at head.
• All eleven runbook queries parse and answer on the live Prometheus. After a deliberate restart, changes(nexum_runtime_start_time_seconds[7d]) answered 1.
• Stop: the engine exited with code 0 and wrote graceful shutdown complete. After the start that followed, each event trigger opened at its cursor.
• Digest pinning: with both pins and without require_component_digest = false, the supervisor ready line had "verified":2 and no loading unverified warning.
• The log scrub left zero occurrences of the node's host, and the state backup command copied the store.
• The Gnosis Chain example of the multi-chain section was run from a source build against a public Gnosis endpoint: /readyz answered ready: true with ethflow-watcher: alive, the event trigger opened at the chain head, and the engine exited with code 0.

just ci with CI set passes on this branch: fmt, clippy at -D warnings, the orderbook-only gate, rustdoc, both module wasms, nextest and the doctests.

Breaking

The shipped ethflow-watcher manifest targets chain 1 where it targeted chain 11155111, and engine.docker.toml declares chain 1 only. A deployment that used the committed files with a Sepolia endpoint needs its own manifest and config.

AI Assistance: Claude Code used for the review, the changes, the tests and the documentation, and for the live Docker test of the documented steps.