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
4 changes: 4 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,11 @@ on:
pull_request:

jobs:
# Named for the status check main's branch protection requires. The
# duplicate workflow deleted in c11b779 carried this job name; removing it
# took the required context with it and nothing could merge afterwards.
test:
name: Foundry project
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
Expand Down
5 changes: 2 additions & 3 deletions .github/workflows/ledger-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ jobs:
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Test receipt, balance, and supply verification
# Every Python suite lives in script/; test/ holds Solidity only.
- name: Python tests
run: python3 -B -m unittest discover -s script -p 'test_*.py' -v
- name: Test verifier integration
run: python3 -B -m unittest discover -s test -p 'test_*.py' -v
23 changes: 17 additions & 6 deletions .github/workflows/ledger.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ on:
jobs:
verify:
name: Verify on-chain accounting
timeout-minutes: 150
runs-on: ubuntu-latest
permissions:
contents: read
Expand All @@ -31,15 +32,25 @@ 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'
# Proving nothing is MISSING means reading all ~16.3M blocks since
# deployment: over an hour against free endpoints, and growing. That is
# not a per-pull-request cost, so a PR confirms every entry is real and
# the balances add up (about a second), and the full scan runs on main
# and on the weekly schedule. The fast mode prints what it did not check.
- 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.
BASE_VERIFY_SCOPE: ${{ github.event_name == 'pull_request' && 'entries' || 'full' }}
# 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.
BASE_RPC_MIN_INTERVAL: "0.25"
# A complete pass is ~16,300 pages since deployment, so at the pace
# above it needs well over an hour and grows with the chain. Give it
# room rather than let every run defer without verifying anything.
BASE_HISTORY_TIMEOUT: "7200"
run: |
set +e
python3 script/verify_ledger.py
Expand All @@ -49,9 +60,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
1 change: 0 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ fmt:
test:
forge test -vvv
python3 -B -m unittest discover -s script -p 'test_*.py'
python3 -B -m unittest discover -s test -p 'test_*.py'

verify:
python3 -B script/ledger_schema.py
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.
97 changes: 45 additions & 52 deletions docs/verification.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,73 +6,66 @@ reason. `script/verify_ledger.py` makes that claim falsifiable.

## The chain is the source

History is derived from the chain itself, needing **no API key, no account and
History is read from the chain itself, needing **no API key, no account and
nobody's permission**. Any public Base RPC endpoint will serve it.

Reading every block since deployment would be O(chain) — eleven million blocks
to find eleven transactions. Instead it is O(our own activity):
Every block from the token's deployment (41988939) to a fixed head is read in
order, in `eth_getLogs` pages, with nothing skipped. The head is pinned at the
start and re-checked at the end so a reorg cannot turn a later fork's state
into a finding.

1. A nonce is monotonic, so binary-searching `eth_getTransactionCount` over
block height finds every block in which a project wallet sent a
transaction. Nothing hides there: unlike a balance, a nonce never comes
back down, so tokens sent out and returned are still two increments.
2. Logs are read for those blocks only, plus the deployment block for the
mint, which no wallet signed.
That is deliberately the expensive option. It was not always.

Measured against Base mainnet: **about 180 requests, under twenty seconds**,
for the token's entire history. That cost grows with our activity, not with
the chain's.
## Why not a cheaper method

## What a nonce cannot see
Between 2026-10-29 and 2026-11-16 this script used wallet nonces as an index:
a nonce is monotonic, so binary-searching `eth_getTransactionCount` finds every
block in which a project wallet *signed* a transaction, and only those blocks
need their logs read. About 180 requests instead of sixteen thousand.

A third party spending an allowance via `transferFrom` moves tokens without
our wallet signing anything. No nonce increments, and the transfer sits in a
block this derivation never reads.
It was wrong, and [#10](https://github.com/khalidsaidi/sourcemint/issues/10)
is why. A nonce only moves when our wallet signs. A spender using an allowance
moves tokens by `transferFrom` without touching it, so those blocks were never
read. An allowance check was supposed to cover that case, but an allowance is
only evidence while it is live: send tokens out, send them back, revoke the
approval, and the balance nets to zero, the nonce never moved, the allowance
reads zero, and the verifier reported success for history it had never seen.

Two things address it.
Reported by @Chandain, reproduced independently by @gjwang, fixed by @gjwang
in [#11](https://github.com/khalidsaidi/sourcemint/pull/11). Both cases are
permanent offline regressions in `script/test_history_scan.py`.

`balanceOf` and `totalSupply` are reconciled against what the ledger implies,
so an unexplained balance reveals a movement nobody here signed. That catches
the ordinary case but not a round trip, where tokens leave and the same amount
returns and the balance is unchanged.
The lesson is narrower than "nonces are bad": the method sampled, and a sample
cannot support a claim of completeness. Anything cheaper than reading every
block has to prove it is not sampling.

So the verifier also refuses to claim completeness while any allowance is
outstanding. Granting an allowance is itself a transaction a project wallet
signed, so it appears in a block already being read: the same single request
per block returns `Approval` logs alongside `Transfer` logs, at no extra cost.
Every spender ever approved is then checked with `allowance`, and a non-zero
result fails the run with the spender named.
## Three states, not two

That is deliberately strict. A live allowance does not mean anything has gone
wrong — it means this check cannot prove that nothing has, and saying so is
the point.
A single pass/fail flag conflates things that are not the same, which is how
an outage used to downgrade an already-observed violation to "could not
verify". They are now distinct:

## There is no indexer
- An unledgered movement that was actually observed is a **finding**. It stays
a finding whatever happens afterwards — a later page failing, a state read
timing out, the budget running out.
- Coverage that did not complete is **inconclusive**. No verdict is available
about blocks that were not read.
- A ledger entry simply absent from an incomplete range is **neither**. It may
be in a block not yet reached.

There was one, and it is gone. `base.blockscout.com` returns HTTP 403 to
programmatic requests, and no free keyless indexer for Base serves this —
Routescan does not support the chain, BaseScan's v1 API is deprecated,
Etherscan's v2 requires a paid plan for 8453, and Blockscout's MCP server runs
on a shared credit allowance that is routinely exhausted.
## What this costs, and for how long

It was briefly kept as a shortcut. That was a mistake: approvals are only
collected while reading the chain, so a run that took the shortcut skipped the
completeness guard and said nothing about it. A faster path that quietly
checks less is worse than no faster path.
At 1,000 blocks per page — the largest range free keyless endpoints serve —
the token's history is about 16,300 requests and an hour.

If a free keyless indexer reappears it belongs here only if it supplies the
`Approval` logs too.
Base produces roughly 317,000 blocks a day, so that grows by about eight
minutes of scanning every week. Extrapolated, a complete pass passes GitHub
Actions' six-hour job limit within about a year of 2026-11-16.

## Configuration

| Variable | Default | Used for |
|---|---|---|
| `BASE_RPC_URL` | — | nonces, balances, block height |
| `BASE_LOGS_RPC_URL` | `base.gateway.tenderly.co` | the handful of single-block log reads |

Two endpoints because no single free one serves both: `mainnet.base.org`
answers nonces and balances but refuses `eth_getLogs` entirely. Both are
public and need no key.
This is a known limit, not a solved problem. When it binds, the options are a
keyed endpoint with larger ranges, or a committed checkpoint of the last
verified block and its hash — which trades "every run re-derives everything"
for "every run trusts the last one", and should not be done quietly.

## Verdicts

Expand Down
Loading
Loading