Skip to content
Open
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
81 changes: 81 additions & 0 deletions script/test_canonical_outage.py
Original file line number Diff line number Diff line change
@@ -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()
29 changes: 25 additions & 4 deletions script/verify_ledger.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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()
Expand Down Expand Up @@ -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
Comment on lines +767 to +772

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