Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions script/test_canonical_outage.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
"""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, block_hash, 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 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."""

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("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):
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_each_cause_is_named_and_they_differ(self):
_, outage = run(HeadOutage())
_, reorg = run(HeadReorg())
_, 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__":
unittest.main()
39 changes: 35 additions & 4 deletions script/verify_ledger.py
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,17 @@ 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
# 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

Expand Down Expand Up @@ -419,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)
Expand All @@ -429,6 +441,8 @@ 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
history.invalidated = True
raise SourceUnavailable("fixed-head hash changed during history scan")
history.canonical = True
except SourceUnavailable as exc:
Expand Down Expand Up @@ -700,10 +714,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()
Expand Down Expand Up @@ -749,6 +764,22 @@ def main() -> int:

print(f"history coverage: {DEPLOYMENT_BLOCK}..{history.covered_to} "
f"of fixed head {history.head} ({history.head_hash})")
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."
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 check that would have re-confirmed it "
"could not be completed, which is not a reason to withhold it.")
return 1
Comment on lines +777 to +782

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep contradictory history separate from head-read outages

If an earlier page contains an unledgered movement and a later page raises HistoryConflict, derive_transfers() returns immediately with canonical=False and head_changed=False, retaining the earlier transfers. This branch now reports an accounting violation even though the history was explicitly invalidated, rather than returning 2 as before. This includes a log at the fixed head having a different block hash, not just duplicate-record conflicts. I reproduced exit 1 using an unledgered transfer in the first page and conflicting copies of one log in a later page. Preserve a distinct invalid-history outcome and exclude it from the outage-only failure path.

Useful? React with 👍 / 👎.

if not history.complete:
print(f"history incomplete: {history.error}")
if unaccounted:
Expand Down
Loading