diff --git a/script/test_canonical_outage.py b/script/test_canonical_outage.py new file mode 100644 index 0000000..37e7440 --- /dev/null +++ b/script/test_canonical_outage.py @@ -0,0 +1,81 @@ +"""Failing to RE-READ the head is not the same as the head having CHANGED. + +Both once left `canonical` false, and main() returned 2 on that before it had +even compared the observed transfers against the ledger. So a confirmed +unledgered movement could sit in a complete, successfully scanned history and +be reported as a CI deferral -- a green build over real evidence. That is +issue #10's defect at a different gate: the run goes quiet because a later +read failed. + +The two causes are now distinguished: + + * the head HASH CHANGED -- positive proof the snapshot's basis is gone, so + observations tied to it are not evidence about the current chain. Still 2. + * the head could NOT BE READ -- an outage, which says nothing about what was + already observed. An unaccounted movement survives it, as it survives a + failed page (test_history_scan) and a failed state read (test_allowance_outage). +""" +import unittest + +from test_history_scan import ALICE, CHARLIE, Node, event, run + +import verify_ledger as v + + +class HeadOutage(Node): + """A complete scan observes an unledgered transfer; the mandatory head + re-read then fails as an outage rather than a disagreement.""" + + def __init__(self, **kw): + super().__init__(**kw) + self.events += [event(200, ALICE, CHARLIE, 40 * 10**18)] + self.scanned = False + + def __call__(self, payload, endpoint=None): + if payload["method"] == "eth_getLogs": + self.scanned = True + if payload["method"] == "eth_getBlockByNumber" and self.scanned: + raise v.SourceUnavailable("RPC request budget exhausted") + return super().__call__(payload, endpoint) + + +class HeadReorg(Node): + """The same observation, but the head genuinely changed under us.""" + + def __init__(self, **kw): + super().__init__(**kw) + self.events += [event(200, ALICE, CHARLIE, 40 * 10**18)] + self.changed_head = True + + +class CanonicalOutage(unittest.TestCase): + def test_unreadable_head_does_not_bury_an_observed_violation(self): + code, output = run(HeadOutage()) + self.assertEqual(code, 1, output) + self.assertIn("UNACCOUNTED", output) + self.assertIn(CHARLIE, output) + + def test_a_changed_head_still_invalidates_the_observation(self): + code, output = run(HeadReorg()) + self.assertEqual(code, 2, output) + self.assertIn("no longer canonical", output) + self.assertNotIn("RESULT: FAIL", output) + + def test_an_unreadable_head_without_a_violation_stays_inconclusive(self): + class Clean(HeadOutage): + def __init__(self, **kw): + Node.__init__(self, **kw) + self.scanned = False + code, output = run(Clean()) + self.assertEqual(code, 2, output) + self.assertNotIn("RESULT: FAIL", output) + + def test_the_cause_is_named_in_the_output(self): + _, outage = run(HeadOutage()) + _, reorg = run(HeadReorg()) + self.assertIn("outage", outage) + self.assertIn("replaced", reorg) + + +if __name__ == "__main__": + unittest.main() diff --git a/script/verify_ledger.py b/script/verify_ledger.py index 80f278e..23075c5 100644 --- a/script/verify_ledger.py +++ b/script/verify_ledger.py @@ -206,6 +206,10 @@ class TransferHistory: covered_to: int complete: bool = False canonical: bool = False + # Positive evidence that the pinned head is no longer canonical, as + # opposed to simply not having been able to re-read it. A reorg + # invalidates observations tied to that head; an outage does not. + head_changed: bool = False error: str = "" budget: object = None @@ -429,6 +433,7 @@ def derive_transfers(token: str, wallets, chain_id=8453): for endpoint in (None, LOGS_RPC_URL): current = _header(budget, hex(head), endpoint) if current["hash"].lower() != history.head_hash: + history.head_changed = True raise SourceUnavailable("fixed-head hash changed during history scan") history.canonical = True except SourceUnavailable as exc: @@ -700,10 +705,11 @@ def main() -> int: print(" The next successful run re-checks the full history.") return 2 - if not history.canonical: - print("COULD NOT VERIFY: fixed-head history was not confirmed canonical.") - print(f" {history.error}") - return 2 + # A failure to re-confirm the head is NOT decided here. Returning early + # discards an unledgered movement that was already observed, which is the + # defect of issue #10 at a different gate: the run goes quiet about real + # evidence because a later read failed. The decision is made below, once + # the observations exist and the cause is known. for t in transfers: frm = t["from"]["hash"].lower() @@ -749,6 +755,21 @@ def main() -> int: print(f"history coverage: {DEPLOYMENT_BLOCK}..{history.covered_to} " f"of fixed head {history.head} ({history.head_hash})") + if history.head_changed: + # The chain moved under the snapshot. Observations are tied to a head + # that is no longer canonical, so they are not evidence about the + # current chain -- unlike an unreadable endpoint, this is positive + # proof the basis is gone. + print("COULD NOT VERIFY: the fixed head is no longer canonical.") + print(f" {history.error}") + print(" Observations are tied to a head the chain has replaced.") + return 2 + if not history.canonical and unaccounted: + print(f"history not re-confirmed: {history.error}") + print("\nRESULT: FAIL — unaccounted movement observed in complete, " + "matching history; the head could not be re-read, which is an " + "outage and not a reason to withhold it.") + return 1 if not history.complete: print(f"history incomplete: {history.error}") if unaccounted: