Skip to content
Closed
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
12 changes: 6 additions & 6 deletions .github/workflows/ledger.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,11 @@ jobs:
- name: Validate ledger shape and published figures
run: |
python3 script/ledger_schema.py
python3 -B -m unittest discover -s script -p 'test_ledger_schema.py'
python3 -B -m unittest discover -s script -p 'test_*.py'
- name: Verify ledger against Base mainnet
env:
# Nonces and balances. mainnet.base.org serves these and refuses
# eth_getLogs, so the log reads go elsewhere. Both public, no key.
# Snapshot headers and state use the primary RPC; token logs use
# the logs RPC. Both endpoints must report the configured chain.
BASE_RPC_URL: https://mainnet.base.org
BASE_LOGS_RPC_URL: https://base.gateway.tenderly.co
# Shared runner egress gets throttled where a laptop does not.
Expand All @@ -49,9 +49,9 @@ jobs:
echo "Ledger verified against Base mainnet."
exit 0
elif [ "$code" -eq 2 ]; then
# An indexer outage is not an accounting finding. Each run re-checks
# the full transfer history, so a deferred check loses nothing.
echo "::warning title=Ledger not verified::Transfer data source unreachable; deferring to the next run."
# Incomplete coverage is not an accounting finding. Every run
# starts again from deployment and reports its actual coverage.
echo "::warning title=Ledger not verified::History or snapshot could not be verified within source/resource limits; deferring."
exit 0
else
echo "::error title=Accounting violation::A project-wallet movement is unaccounted for in rewards/ledger.json."
Expand Down
33 changes: 33 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,3 +55,36 @@ Deployment artifacts:
- Base Mainnet (8453): `0x914F6b6a0DaD39A3CB932dcf4D1af885C7c08EeB` (GA)
- Verified: https://basescan.org/address/0x914f6b6a0dad39a3cb932dcf4d1af885c7c08eeb#code
- Sepolia (11155111): `0x8c2B67EA395824Cc069F5e13b1d80E6016751a4A` (testnet)

## Ledger verification coverage

`python3 script/verify_ledger.py` scans this token's `Transfer` logs from its
configured deployment block through a fixed head. Both configured RPC endpoints
must report the ledger's chain ID and agree on that head. Balances and total
supply are read using its canonical block hash. This covers delegated
`transferFrom` movements even if balances later return to their original values
and allowances are revoked. Current allowances are not evidence of missing
historical transfers.

The verifier trusts complete RPC log responses; this is an accounting check,
not an independent cryptographic receipt proof. It keeps the existing scope:
mint events and transfers out of project wallets must match the ledger.

| Environment setting | Default | Purpose |
| --- | --- | --- |
| `BASE_HISTORY_BLOCK_SPAN` | `10000` | Maximum blocks per log request |
| `BASE_HISTORY_MAX_REQUESTS` | `2048` | Shared request budget, including wire retries and state reads |
| `BASE_HISTORY_TIMEOUT` | `300` | Deadline in seconds, checked around RPC operations and retry delays |
| `BASE_HISTORY_MAX_RESPONSE_BYTES` | `8388608` | Maximum response body per request |
| `BASE_HISTORY_MAX_LOGS_PER_PAGE` | `10000` | A page at this known/suspected result cap is incomplete |
| `BASE_HISTORY_MAX_LOGS` | `100000` | Maximum retained events across accepted pages |

Set the page span and result cap to the limits of your selected provider. A
failed, malformed, capped or unfinished range returns exit 2 when no accounting
violation has been established; it never falls back to nonce sampling or skips
the failed range. An already-observed canonical unledgered movement remains
exit 1 even if a later page fails. Exit 0 requires complete matching history and
successful snapshot state checks. Pending or post-snapshot ledger transactions
are inconclusive, rather than falsely reported absent. Larger histories may
need different explicit budgets; these defaults are not provider capacity or
runtime guarantees. Existing RPC pacing and retry settings still apply.
29 changes: 9 additions & 20 deletions script/chain_history.py
Original file line number Diff line number Diff line change
@@ -1,21 +1,11 @@
#!/usr/bin/env python3
"""Derive a project wallet's complete movement history from the chain.
"""Find blocks containing transactions signed by a wallet.

Scanning every block since deployment is O(chain). This is O(our activity):

* A nonce is monotonic. Binary-searching `eth_getTransactionCount` over
block height finds every block in which a wallet sent a transaction.
Nothing can hide there — unlike a balance, a nonce never comes back down,
so a transfer out and straight back is still two nonce increments.
* Logs are then read for those blocks alone. Eleven blocks, not eleven
million.

What a nonce cannot see is a movement the wallet did not sign: a third party
spending an allowance via `transferFrom`. That case is the exact complement —
it changes the balance without touching the nonce — so `unexplained_balance`
below catches it with two reads. Together they leave nothing uncovered.

Stdlib only.
Nonce changes do not discover token movements initiated by third parties.
A transferFrom roundtrip can restore both balance and allowance, so these
helpers are not a complete token-history source. The verifier scans token
Transfer logs continuously instead. unexplained_balance compares state only;
a zero difference does not establish movement-history completeness.
"""


Expand Down Expand Up @@ -45,10 +35,9 @@ def walk(lo, hi, nonce_lo, nonce_hi):


def unexplained_balance(expected_wei, actual_wei):
"""What `transferFrom` would look like: a balance the ledger cannot explain.
"""Return the expected-minus-observed balance difference in wei.

A nonce search accounts for everything the wallet sent. If the balance is
still short, tokens left without the wallet signing — someone spent an
allowance. Returns the shortfall in wei; zero means fully explained.
A zero state difference cannot prove that no intermediate movements
occurred. Use continuous token logs when verifying transfer history.
"""
return expected_wei - actual_wei
61 changes: 61 additions & 0 deletions script/test_allowance_outage.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
"""Coverage and state outages must preserve confirmed accounting findings.

Supersedes the old allowance-read gate now that Transfer history is scanned.
"""
import contextlib
import io
import json
import unittest
from unittest.mock import patch

import verify_ledger as verifier
from test_allowances import ledger, transfers


class AccountingOutages(unittest.TestCase):
def run_verifier(self, observed=None, balance_error=None, complete=True):
history = verifier.TransferHistory(
transfers() if observed is None else observed,
verifier.DEPLOYMENT_BLOCK, "0x" + "ab" * 32,
verifier.DEPLOYMENT_BLOCK, complete=complete, canonical=True,
error="later page unavailable" if not complete else "")
output = io.StringIO()
with (patch.object(verifier, "LEDGER_PATH") as ledger_path,
patch.object(verifier, "fetch_transfers", return_value=history),
patch.object(verifier, "verify_balances_total_supply", side_effect=balance_error),
patch.object(verifier, "rpc_call", side_effect=lambda payload, endpoint=None: {
"jsonrpc": "2.0", "id": 1, "result": {
"number": payload["params"][0], "hash": "0x" + "ab" * 32}}),
contextlib.redirect_stdout(output)):
ledger_path.read_text.return_value = json.dumps(ledger())
code = verifier.main()
return code, output.getvalue()

def test_observed_unaccounted_transfer_survives_state_outage(self):
observed = transfers()
observed.append(dict(observed[-1], transaction_hash="0x" + "22" * 32))
code, output = self.run_verifier(observed,
verifier.SourceUnavailable("state unavailable"))
self.assertEqual(code, 1)
self.assertIn("UNACCOUNTED", output)

def test_observed_balance_mismatch_remains_a_violation(self):
code, output = self.run_verifier(
balance_error=verifier.AccountingViolation("balance mismatch"))
self.assertEqual(code, 1)
self.assertIn("BALANCE UNEXPLAINED", output)

def test_no_observed_violation_with_state_outage_is_inconclusive(self):
code, output = self.run_verifier(
balance_error=verifier.SourceUnavailable("state unavailable"))
self.assertEqual(code, 2)
self.assertIn("COULD NOT VERIFY", output)

def test_missing_entry_in_partial_history_is_not_a_finding(self):
code, output = self.run_verifier(observed=transfers()[:1], complete=False)
self.assertEqual(code, 2)
self.assertIn("COULD NOT VERIFY", output)


if __name__ == "__main__":
unittest.main()
40 changes: 18 additions & 22 deletions script/test_allowances.py
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
"""An outstanding allowance means the history cannot be called complete.
"""Complete Transfer history covers delegated transfers independently of allowance.

A spender holding an allowance can move tokens via `transferFrom`. That bumps
no nonce on our side and lands in a block the derivation never reads, so it is
invisible to every other check here. The verifier must not print "every
movement is accounted for" while one is live.
These state fixtures retain nonzero and revoked allowances to ensure that
future spending authority does not become a false historical violation.
"""
import contextlib
import io
Expand Down Expand Up @@ -48,17 +46,21 @@ def run(allowance):
def rpc(payload, endpoint=None):
if payload["method"] == "eth_blockNumber":
return {"jsonrpc": "2.0", "id": 1, "result": "0x1"}
if payload["method"] == "eth_getBlockByNumber":
return {"jsonrpc": "2.0", "id": 1, "result": {
"number": payload["params"][0], "hash": "0x" + "ab" * 32}}
data = payload["params"][0]["data"]
if data.startswith(verifier.ALLOWANCE_SELECTOR):
value = allowance
raise AssertionError("complete history must not query current allowance")
elif data.startswith("0x18160ddd"):
value = state[1]
else:
value = state[0].get("0x" + data[-40:], 0)
return {"jsonrpc": "2.0", "id": 1, "result": "0x%064x" % value}

verifier.LIVE_SPENDERS[:] = [PERMIT2]
with (patch.object(verifier, "fetch_transfers", return_value=transfers()),
with (patch.object(verifier, "fetch_transfers", return_value=verifier.TransferHistory(
transfers(), verifier.DEPLOYMENT_BLOCK, "0x" + "ab" * 32,
verifier.DEPLOYMENT_BLOCK, complete=True, canonical=True)),
patch.object(verifier, "rpc_call", side_effect=rpc),
patch.object(Path, "read_text", return_value=json.dumps(led))):
buf = io.StringIO()
Expand All @@ -68,28 +70,22 @@ def rpc(payload, endpoint=None):


class Allowances(unittest.TestCase):
def tearDown(self):
verifier.LIVE_SPENDERS.clear()

def test_a_live_allowance_prevents_claiming_completeness(self):
def test_a_live_allowance_does_not_invalidate_complete_history(self):
code, out = run(UNLIMITED)
self.assertEqual(code, 1, "cannot claim completeness while tokens can leave unseen")
self.assertIn("OUTSTANDING ALLOWANCES", out)
self.assertIn("RESULT: FAIL", out)
self.assertEqual(code, 0)
self.assertNotIn("OUTSTANDING ALLOWANCES", out)

def test_an_unlimited_allowance_is_named_as_such(self):
self.assertIn("unlimited", run(UNLIMITED)[1])
def test_an_unlimited_allowance_does_not_require_an_extra_history_gate(self):
self.assertIn("RESULT: OK", run(UNLIMITED)[1])

def test_a_small_allowance_still_counts(self):
code, out = run(5 * 10**18)
self.assertEqual(code, 1)
self.assertIn("5 SRCMNT", out)
def test_a_small_allowance_is_not_a_missing_transfer(self):
self.assertEqual(run(5 * 10**18)[0], 0)

def test_a_revoked_allowance_does_not_block_the_verdict(self):
code, out = run(0)
self.assertEqual(code, 0)
self.assertNotIn("OUTSTANDING", out)
self.assertIn("accounted for", out)
self.assertIn("RESULT: OK", out)


if __name__ == "__main__":
Expand Down
Loading