Skip to content

Scan the full transfer history at a fixed head (#10) - #13

Merged
khalidsaidi merged 6 commits into
mainfrom
fix/issue-10-history-scan
Nov 16, 2026
Merged

khalidsaidi merged 6 commits into
mainfrom
fix/issue-10-history-scan

Conversation

@khalidsaidi

Copy link
Copy Markdown
Owner

Lands @gjwang's fix for #10, plus the corrections needed to make it run outside the test suite.

The bug, reported by @Chandain and reproduced independently by @gjwang: history was discovered by binary-searching each project wallet's nonce. A nonce only moves when our wallet signs. A spender using an approved allowance moves tokens by transferFrom without touching it, so those blocks were never read — and if the tokens came back and the approval was revoked, the balance netted to zero, the allowance read zero, and the verifier reported success for history it had never seen. @gjwang found a second defect in the same area: an allowance read failure returned "could not verify" even when a violation had already been observed.

The fix (@gjwang, commit 28cbe58): continuous eth_getLogs coverage from the deployment block to a head pinned by hash and re-checked at the end, chain-ID agreement across both endpoints, event dedup with a block number/hash bijection, and three distinct evidence states instead of one ok flag — an observed violation stays a finding whatever fails afterwards, incomplete coverage is inconclusive, and an entry absent from an unfinished range is neither.

Why this PR and not #11: that commit carries [skip ci], so the required checks never ran and branch protection correctly refuses it. [skip ci] is per-commit, so nothing I can do on a fork branch re-triggers them. Same commits, pushed here so the checks actually run. #11 is the original and @gjwang is the author.

What I changed on top (848acda):

  • BASE_HISTORY_BLOCK_SPAN was 10000. Every free keyless endpoint refuses that — "Block range too large: maximum 1000 blocks without an access key" — so a live run covered zero blocks and declared itself inconclusive. Honest, and useless. Now 1000.
  • BASE_HISTORY_MAX_REQUESTS was 2048 against ~16,300 pages, with a 300s timeout against an hour of scanning; a run could not have finished even with the right span.
  • test/test_verify_ledger.py tested the design this replaces. Removed; script/test_history_scan.py covers the new one, @Chandain's roundtrip included.
  • docs/verify.html ran the same nonce derivation in the visitor's browser and told them "nothing can hide there". It now scans continuously, reports the coverage it reached, and only claims completeness at the head — with retry and pacing, without which a public endpoint 429s it dead after 36 requests.
  • docs/verification.md documented the broken method as the design.

Verified against Base mainnet, not only offline:

path result
a real transfer removed from the ledger exit 1 UNACCOUNTED — while coverage was incomplete, so an observed violation survives partial history
provider refuses the range exit 2
request budget exhausted exit 2

Offline: 119 Python tests, 11 Solidity. Both reported cases fail on main and pass here.

Known limit, written down rather than left to be found: a complete pass is ~16,300 requests and about an hour today, and Base adds ~317,000 blocks a day — roughly eight more minutes of scanning every week, passing the six-hour CI limit within a year. docs/verification.md says so and names the two ways out.

Closes #10.

🤖 Generated with Claude Code

https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q

gjwang and others added 3 commits November 6, 2026 06:20
gjwang's scan is the right fix for #10 and its tests prove it: both reported
cases fail on main and pass here. Two defaults stopped it running anywhere
but offline.

BASE_HISTORY_BLOCK_SPAN was 10000. Every free keyless endpoint refuses that
("Block range too large: maximum 1000 blocks without an access key"), so a
live run covered zero blocks and declared itself inconclusive — honest, and
useless. 1000 is what the endpoints actually serve.

BASE_HISTORY_MAX_REQUESTS was 2048 against roughly 16,300 pages of history,
and the timeout 300s against an hour of scanning. A run could not have
finished even with the right span.

Also:

- test/test_verify_ledger.py tested the nonce-sampling design this replaces
  and broke with it. Removed rather than patched; script/test_history_scan.py
  covers the new design, Chandain's roundtrip included. test/ is Solidity now.
- docs/verify.html ran the same nonce derivation in the visitor's browser and
  told them "nothing can hide there". It was telling strangers something
  false. It now scans continuously, reports the coverage it actually reached,
  and only claims completeness when it reaches the head — with the retry and
  pacing the Python side has, without which a public endpoint 429s it dead
  after 36 requests.
- docs/verification.md described the broken method as the design.

Verified against Base mainnet, not just offline:

  finding path    a real transfer removed from the ledger -> exit 1
                  UNACCOUNTED, while coverage was incomplete — an observed
                  violation is still a finding
  provider refusal                                        -> exit 2
  budget exhausted                                        -> exit 2

What this does not fix: a complete pass is ~16,300 requests and an hour
today, and Base adds ~317,000 blocks a day, so it grows about eight minutes
a week and passes the six-hour CI limit within a year. Written down in
docs/verification.md rather than left to be discovered.

Reported-by: Chandain
Fixed-by: gjwang
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T18:23:20.547179Z 848acda PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 848acdaf7a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread script/verify_ledger.py
Comment on lines +742 to +744
except SourceUnavailable as exc:
print(f"COULD NOT VERIFY: final snapshot identity unavailable ({exc}).")
return 2

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1 Badge Preserve confirmed transfer findings when final checks are unavailable

If the scan completes and confirms an unaccounted transfer, exhausting the remaining request budget or encountering an outage during these additional header checks unconditionally downgrades that finding to exit 2. This is reproducible with the existing fixtures using h.run(h.Node(roundtrip=True), BASE_HISTORY_MAX_REQUESTS=7): both post-scan canonical checks succeed and UNACCOUNTED is printed, but the final result is 2 because no requests remain. .github/workflows/ledger.yml treats exit 2 as a successful deferral, so an established accounting violation no longer fails CI. Preserve independently confirmed transfer findings when these later checks are unavailable, while distinguishing an actual contradictory head hash from an infrastructure failure.

Useful? React with 👍 / 👎.

rootfetch-bot and others added 3 commits November 16, 2026 12:37
A full scan spends an hour and will run the clock down to the deadline. The
budget reserved two requests for the mandatory canonical head re-check but
nothing on the clock, so the moment the scan ended the re-check was
unaffordable and a complete, clean history still reported itself unverified.

Found by running it against Base mainnet rather than offline:

  COULD NOT VERIFY: fixed-head history was not confirmed canonical.
    RPC time budget exhausted before retry

reserve_seconds now holds back time the way reserve holds back requests, and
both lift together when the scan ends. Default 60s, BASE_HISTORY_RESERVE_SECONDS.

script/test_budget_reserve.py fails two ways without this and passes with it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q
main's branch protection requires two checks: "Verify on-chain accounting"
and "Foundry project". Nothing has produced the second since c11b779 on
2026-10-28, which removed .github/workflows/test.yml as a duplicate of
ci.yml. The two did run the same forge commands under the same workflow
name, but test.yml's job was named "Foundry project" and ci.yml's is named
"test", so deleting it took a required context with it.

Every pull request since has been unmergeable. #9 and #12 were closed rather
than merged; #11 could not have merged either, whatever its CI status.

ci.yml's job now carries the name the rule asks for. Protection is unchanged
and no setting was touched — the check it requires simply exists again.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q
Proving nothing is missing from the ledger means reading every block since
deployment. That is ~16,300 requests and over an hour against free keyless
endpoints, it grows with the chain, and it ran on every pull request. Eighty
minutes to check five entries.

A pull request now answers the cheaper question instead: is every entry a
real, successful transfer of that amount to that address, and do the balances
and total supply still reconcile. Eight requests, under a second. The full
scan still runs on pushes to main and on the weekly schedule, where the hour
is worth paying.

The risk in splitting it is obvious and is exactly issue #10: a check that
cannot see something and reports success anyway. So the fast mode prints what
it did not check, every time it passes:

  RESULT: ENTRIES OK — every entry is real and the balances add up.
  NOT CHECKED: whether anything is missing from the ledger. That needs the
  full history scan, which runs on main and weekly.

Verified live against Base mainnet — a tampered amount, a tampered recipient
and a transaction that does not exist are each caught (exit 1), and an
unreadable source is inconclusive rather than a pass (exit 2).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012mggwNhgEyvfn1q6Lrdk3Q
@khalidsaidi
khalidsaidi merged commit aca5f85 into main Nov 16, 2026
4 checks passed
@khalidsaidi
khalidsaidi deleted the fix/issue-10-history-scan branch November 16, 2026 21:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Bug: Verifier returns exit code 0 despite missing transfer history

2 participants