From 32d8b3f49c10be92de3559e5daacf602052e12ac Mon Sep 17 00:00:00 2001 From: rootfetch-bot Date: Mon, 16 Nov 2026 17:39:49 -0700 Subject: [PATCH 1/2] A head we could not re-read is not a head that changed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An unaccounted movement observed in a complete, successfully scanned history could be reported as a CI deferral — a green build over real evidence. main() returned 2 on `not history.canonical` before it had compared a single observed transfer against the ledger, and two unlike causes both cleared that flag: * the fixed head's hash CHANGED — positive proof the snapshot's basis is gone, so observations tied to it say nothing about the current chain * the head could NOT BE READ — an outage, which says nothing at all about what was already observed Collapsing them meant a budget running out at the final identity check buried a confirmed finding. That is issue #10 at a different gate: the run goes quiet about evidence it already has because a later read failed. It is also the defect @gjwang reported in the allowance handler, which this code fixed there and reintroduced here. The decision now happens after the observations exist and names the cause. A changed head still returns 2 and says the basis was replaced. An unreadable head with an observed violation returns 1 and says the re-read failed. An unreadable head with nothing observed stays inconclusive, as it must. Reproduced on ff43856 before the change; script/test_canonical_outage.py fails three ways without it. Verified live against Base mainnet: a real transfer removed from the ledger is still exit 1, the clean ledger still passes. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q --- script/test_canonical_outage.py | 81 +++++++++++++++++++++++++++++++++ script/verify_ledger.py | 29 ++++++++++-- 2 files changed, 106 insertions(+), 4 deletions(-) create mode 100644 script/test_canonical_outage.py 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: From 2f477d4bd2eca5292a9f2f227cd22726cb9ea62d Mon Sep 17 00:00:00 2001 From: rootfetch-bot Date: Mon, 16 Nov 2026 22:19:00 -0700 Subject: [PATCH 2/2] Never infer "outage" from the absence of a known cause MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous commit let an observed violation survive a head it could not re-read, and decided that by elimination: not a reorg, therefore an outage. HistoryConflict returns before the head re-check ever runs, so a source that CONTRADICTED itself was indistinguishable from one that was merely unreachable, and its discarded observations came back as a violation. That inverts the guarantee gjwang wrote into the conflict handler — "do not preserve a finding produced by the contradictory records" — which this commit had quietly overridden. Reproduced on 06b39f3: an unledgered movement committed by an early page, then a later page binding a block hash already bound to another number. exit code: 1 history not re-confirmed: conflicting block number/hash in history RESULT: FAIL — ...which is an outage and not a reason to withhold it. It was not an outage. The code said so because nothing had said otherwise. Every cause that makes observations untrustworthy now sets `invalidated` explicitly, and the verdict reads that flag instead of deducing it. A future cause that forgets to set it will be inconclusive at worst; before, anything unanticipated defaulted to "trust the observations and report a violation". The three outcomes are now distinct and tested as such: a replaced head and a self-contradictory source are both 2 with different reasons, an unreadable check with an observed violation stays 1. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q --- script/test_canonical_outage.py | 36 +++++++++++++++++++++++++++++---- script/verify_ledger.py | 28 ++++++++++++++++--------- 2 files changed, 51 insertions(+), 13 deletions(-) diff --git a/script/test_canonical_outage.py b/script/test_canonical_outage.py index 37e7440..5720d23 100644 --- a/script/test_canonical_outage.py +++ b/script/test_canonical_outage.py @@ -17,7 +17,7 @@ """ import unittest -from test_history_scan import ALICE, CHARLIE, Node, event, run +from test_history_scan import ALICE, CHARLIE, Node, block_hash, event, run import verify_ledger as v @@ -39,6 +39,19 @@ def __call__(self, payload, endpoint=None): return super().__call__(payload, endpoint) +class LateConflict(Node): + """An unledgered movement committed by an early page, then a later page + binds a block hash already bound to a different number: the source + contradicting itself after the finding is in hand.""" + + def __init__(self, **kw): + super().__init__(head=602, **kw) + self.events += [event(200, ALICE, CHARLIE, 40 * 10**18)] + clash = event(500, ALICE, CHARLIE, 1) + clash["blockHash"] = block_hash(200) + self.events.append(clash) + + class HeadReorg(Node): """The same observation, but the head genuinely changed under us.""" @@ -58,7 +71,17 @@ def test_unreadable_head_does_not_bury_an_observed_violation(self): 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.assertIn("replaced", output) + self.assertNotIn("RESULT: FAIL", output) + + def test_a_self_contradictory_source_is_not_an_outage(self): + """A conflict returns early and never reaches the head re-check, so it + looks exactly like an unreadable head. Inferring "outage" from the + absence of a known reorg turned contradictory records into a + violation. The cause has to be stated, never deduced.""" + code, output = run(LateConflict(), BASE_HISTORY_BLOCK_SPAN=100) + self.assertEqual(code, 2, output) + self.assertIn("contradict", output) self.assertNotIn("RESULT: FAIL", output) def test_an_unreadable_head_without_a_violation_stays_inconclusive(self): @@ -70,11 +93,16 @@ def __init__(self, **kw): self.assertEqual(code, 2, output) self.assertNotIn("RESULT: FAIL", output) - def test_the_cause_is_named_in_the_output(self): + def test_each_cause_is_named_and_they_differ(self): _, outage = run(HeadOutage()) _, reorg = run(HeadReorg()) - self.assertIn("outage", outage) + _, clash = run(LateConflict(), BASE_HISTORY_BLOCK_SPAN=100) + self.assertIn("could not be completed", outage) self.assertIn("replaced", reorg) + self.assertIn("contradict", clash) + # the three verdicts must not be interchangeable + self.assertNotIn("replaced", outage) + self.assertNotIn("contradict", outage) if __name__ == "__main__": diff --git a/script/verify_ledger.py b/script/verify_ledger.py index 23075c5..6171432 100644 --- a/script/verify_ledger.py +++ b/script/verify_ledger.py @@ -210,6 +210,13 @@ class TransferHistory: # 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 + # Set by every cause that makes this run's observations untrustworthy, as + # distinct from merely unconfirmed. A finding survives a source we could + # not READ; it must not survive a source that CONTRADICTED itself. Any + # future invalidating cause sets this rather than being inferred from the + # absence of the others -- inferring it is what let a self-contradictory + # provider be mistaken for an outage and produce a violation. + invalidated: bool = False error: str = "" budget: object = None @@ -423,6 +430,7 @@ def derive_transfers(token: str, wallets, chain_id=8453): # A self-contradictory provider invalidates this run's observations; # do not preserve a finding produced by the contradictory records. history.error = str(exc) + history.invalidated = True return history except SourceUnavailable as exc: history.error = str(exc) @@ -434,6 +442,7 @@ def derive_transfers(token: str, wallets, chain_id=8453): current = _header(budget, hex(head), endpoint) if current["hash"].lower() != history.head_hash: history.head_changed = True + history.invalidated = True raise SourceUnavailable("fixed-head hash changed during history scan") history.canonical = True except SourceUnavailable as exc: @@ -755,20 +764,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.") + if history.invalidated: + # Either the chain moved under the snapshot or the source contradicted + # itself. Both destroy the basis of what was observed, which an + # unreadable endpoint does not. + print("COULD NOT VERIFY: this run's observations are not evidence.") print(f" {history.error}") - print(" Observations are tied to a head the chain has replaced.") + print(" Observations are tied to a head the chain has replaced." + if history.head_changed else + " The source served records that contradict each other.") 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.") + "matching history; the check that would have re-confirmed it " + "could not be completed, which is not a reason to withhold it.") return 1 if not history.complete: print(f"history incomplete: {history.error}")