Repository navigation
feat: add settlement detection and recovery tools - #304
Open
stephenctw wants to merge 2 commits into
Open
stephenctw wants to merge 2 commits into
stephenctw wants to merge 2 commits into
Conversation
Detect stalled staging and acceptance independently of the sender. Add verified recovery preparation and an interactive operator wrapper, with chain-backed outage drills, refusal tests and an incident runbook. Run the provider-free tool tests in fast checks and CI.
Advance protocol clocks by block number without pushing a freshly built devnet head into the observers future. Keep production timestamp freshness checks intact so the outage drill also runs on the canonical two-level fixture.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
When the settlement sender disappears, a finished Dave tournament can remain unstaged or an eligible staged result can remain unaccepted. Inputs can keep reaching L1 while outputs from the blocked epoch remain unavailable. This PR adds independent detection and operator-driven recovery for that specific F4 scenario.
Related fear: F4 — the app stops settling and nobody notices, from Mugen-Builders/qa-redteam-v0#9, specifically the won epoch that nobody stages or accepts. This addresses the sender-outage case, not every cause of F4.
Solution
settlement-watch.pyreads contract state independently of Sling, pins views to one block, and reports the current settlement phase. An unchanged unstaged winner or eligible acceptance becomes stalled after an operator-configured block allowance. Normal tournament/staging waits, failed roots, foreclosure, and observation errors remain distinct.settlement-recover.pyexports settlement material from a replay directory or verifies independently supplied evidence against chain state and simulates an unsigned staging/acceptance transaction. Exporting stored material does not itself establish correctness.settlement-operator.pycombines the tools. On a detected stall it asks whether to prepare recovery, verifies and simulates the action, then asks separately before submitting through a configured signer. It rechecks and simulates again after operator review. The default response and EOF decline; without a signer it prepares only.A winner is not automatically safe to settle: a correct terminal application can win but have no acceptable machine-validity proof. Recovery therefore requires checked replay material and a successful simulation rather than blindly progressing whichever result won.
Reproduction and evidence
Run
just test-settlement-livenessin the configured development environment afterjust doctorpasses.Four deterministic Anvil scenarios exercise real Sling workers, Machine execution, and deployed contracts:
The worker stoppage is deterministic harness fault injection, not a process-signal test. The fresh runner shares Sling's implementation and emulator; this is not independent implementation assurance. The fixture establishes output-root eligibility, not an ERC-20 payout.
Validation and CI
Local checks passed:
cargo check --locked.cargo clippy --locked --workspace --all-targets -- -D warnings.cargo fmt --all --checkandgit diff --check.just test-settlement-toolsis included injust checkand the existing CI test job. Chain-backed scenarios run through the existingjust test-node-harnessCI step; they are not duplicated in the Python test step. Remote CI has not run yet at PR creation.Compatibility and deployment limits
No contract, consensus, wire-format, or storage-schema changes. The tools target this checkout's contract ABI and stored proof layout. Block allowances are deployment settings; the four-block test value is not a mainnet recommendation.
This is operational hardening of an existing liveness dependency, not a demonstrated consensus-safety defect. Production keystore integration, paging/response latency, a running Sequencer during the outage, and actual ERC-20 withdrawal execution remain deployment checks. External supervision must detect observer absence and persistent observation failures. Transaction submission is reported separately from confirmation; operators must verify receipts and the expected epoch transition.
Red-team reproduction record
The primary incident and triage entry is now RT-16 / qa-redteam-v0#16. It contains pinned reproduction steps, a test-only single-sentry variant, and logs from canonical two-level and CI three-level fixtures. That incident PR is reproduction-first; the detector and recovery implementation here remains an optional solution resource for maintainers to prioritize.
The fixture-clock correction in this PR keeps synthetic block timestamps from moving ahead of real wall time when newly generated devnets fast-forward protocol clocks. Production timestamp freshness checks are unchanged. The extra single-sentry test is supplied in the red-team reproduction kit rather than added as new production logic here.