A join over four ledgers, then counting.
Shelfware is one HTTP GET, one join on crypto_id, three counting rules and a receipt beside every number. No database, no model, no framework, no server on the judged path. Every function named on this page exists in shelfware/, scripts/ or api/. The long form, with every failure mode, is ARCHITECTURE.md (opens in a new tab) on GitHub.
Six endpoints in, one join, five files out.
Three keyed RWA ledgers and two keyless cryptocurrency ledgers reach client.py; join.py matches every wrapper's crypto_id to its listing state; the result is committed as JSON and rendered to a static page. Two dependency-free Vercel functions exist only because CoinMarketCap sends no CORS header.
Client.get() — one GET, a receipt, no exceptions.
Everything the engine knows about CoinMarketCap passes through one method in shelfware/client.py. It returns (json, meta); the meta is the receipt line that ends up beside every number on the page.
keyed=False → /public-api
Never sends the key, even when one is exported. keyed=True needs a key (NoKey otherwise) and goes to the Pro base. The judged CLI path is entirely keyless.
URL · HTTP · credit_count · bytes · sha256 · elapsed · UTC
credit_count is read from CoinMarketCap's own envelope. credits_used() sums it over keyed calls only — the keyless envelope also says 1, charged to nobody.
returned, never raised
429 / 5xx / dropped connections retry with 2, 4, 8, 16 s backoff, then come back as throttled: true. A rate limit can therefore never be reported as a fact about a token.
| Ledger | Method | Endpoint | Cost | What it carries |
|---|---|---|---|---|
| A | rwa_map() | /v5/real-world-assets/map | keyed · 0 | Every underlying: has_tokens, rwa_rank, asset_type. Paged by has_more, 250 per page. |
| B | rwa_quotes() | /v5/real-world-assets/quotes/latest | keyed · 1 / 250 | tokens[] — the wrapper roster, price: null rows included, with issuer_id and crypto_id per wrapper. Batches of 200 ids with skip_invalid=true, or one symbol= for the ticker question. The engine. |
| C | issuers() | /v5/real-world-assets/issuers/list | keyed · 1 | Each issuer's declared num_tokens. |
| D | cmc_map() | /public-api/v1/cryptocurrency/map | keyless · 0 | Listing status across active,inactive,untracked. Full map: 8 pages of 5,000. Per ticker: a symbol= filter — dotted symbols are never sent, an unknown symbol named in a 400 is dropped and the call retried. |
| E | cmc_info() | /public-api/v2/cryptocurrency/info | keyless · 0 | date_added for the shelf, in batches of 200; ids named in a 400 are dropped and the batch retried. |
| K | key_info() | /v1/key/info | keyed · 0 | The month's credit counter, read before and after a census so the receipt's total can be checked against CMC's. |
cli.run_census() — A, B, C, D, E, then the join.
The orchestration is one function. Each stage is a real call with its own receipt line; the whole run on 2026-09-18 was 54 calls, 5 credits and 40.9 s.
- Ledger A — the universe.
rwa_map(); keep the rows withhas_tokens.791 underlyings - Ledger B — the roster.
rwa_quotes(rwa_ids=…)for those ids; everytokens[]entry is a wrapper.1,435 wrappers, price: null rows kept - Ledger C — the issuers.
issuers(), for the declared-vs-attached column of the scorecard. - Ledger D — the state.
cmc_map()keyless, all ofactive,inactive,untracked. If the anonymous pool refuses the IP (429, error 1022), the identical paging runs keyed and the receipt says so. Whatever did not resolve is asked again by symbol — sounresolvedmeans CMC has no row, not that a page was skipped. - Ledger E — the shelf's dates.
cmc_info()keyless for every wrapper that is notactive;date_addedis the shelf's age. - The join.
join.census()— wrappers, resolution, the three rules, the scorecard, the type bars, the hero, the receipt and the counts — thenkey_info()again. - Five artifacts.
cli.write_census()writesdata/census.json,data/roster_snapshot.json,docs/proof/live_run.json, today'sdata/snapshots/file and, viawrite_delta(),data/delta.json.
join.py — every number is a count.
The whole product fits in one screen of definitions. Nothing is inferred; a p95 is a real observation (nearest-rank, pct_rank()).
# shelfware/join.py — the function that computes each line is named on the right
wrappers = flatten(tokens[] per underlying) wrappers_from()
status = D[crypto_id].status, else "unresolved" resolve()
date_added = E[crypto_id].date_added enrich_info()
shelf(w) = w.status == "untracked" is_shelf()
zero_tracked(underlying) = wrappers ≥ 1 and all shelf (strict) zero_tracked(strict=True)
= no wrapper active (loose) zero_tracked(strict=False)
scorecard[issuer] = declared (C.num_tokens) · attached · tracked · untracked
· inactive · unresolved · untracked/attached
· Σ market_cap over tracked scorecard()
type_bars[asset_type] = the same, over wrappers type_bars()
type_underlyings[type] = the headline split by type type_underlyings()
age_tracked = days since first_historical_data, active age_of_tracked()
age_shelf = days since date_added, untracked age_of_shelf()
hero = min rwa_rank over strict zero-tracked hero()
census(...) = all of the above + receipt + counts census()
recount(doc) = the counts again, from wrappers[] alone recount()
# the headline on 2026-09-18
zero_tracked / has_tokens = 476 / 791 → 60 %, recounted by shelfware verify on every make check
lookup(ticker) — two legs, each row labelled.
python3 -m shelfware MS runs lookup.lookup() from shelfware/lookup.py: it never raises for an API condition, and every leg records its source and, when it fell back, why.
keyed if a key is exported, else the snapshot
With a key: rwa_quotes(symbol=) for 1 credit. A 400 means the RWA universe has no such symbol — an answer, not a fallback. Without a key, or on any other error: data/roster_snapshot.json, with its date and the reason, source: "snapshot".
keyless, live, always first
cmc_map(symbols) on /public-api. Wrappers whose symbol the filter rejects take active from cmc_info, or the map's finer word from the snapshot when info says inactive. Each wrapper carries status_source ∈ {map, info, info+snapshot, snapshot}.
Pool exhausted and a key exported: the identical call keyed, status.base = "keyed". No key: the committed state, temporary_failure set — the CLI answers, then exits 75 (EX_TEMPFAIL).
The answer is one screen: every wrapper, its issuer, chain and listing state, then the receipt line. delta.delta() diffs two censuses by crypto_id — newly_tracked is strictly untracked → active, newly_shelved strictly the reverse, everything else other_flips. verify.compare_counts() recounts every headline from the rows; live_check() re-fetches ten states keyless and compares.
One hop, because CoinMarketCap sends no CORS header.
Three Node functions with no dependencies, sharing api/_lib.js. They never reshape CoinMarketCap's payload — raw passes through verbatim — and failures are never cached.
| Route | Secret | Behaviour |
|---|---|---|
GET /api/roster?symbol= | CMC_API_KEY | Read from the Vercel environment — the only place a secret exists. Exactly one symbol matching ^[A-Za-z0-9.$-]{1,16}$. Live quotes/latest?symbol= for 1 credit; a 400 is "no such symbol"; a missing key, 429, 403 or 5xx answers from data/roster_snapshot.json with source: "snapshot", its date and the reason. The snapshot tokens ride along on every answer. 60 s cache per symbol per instance. |
GET /api/status?symbols=&ids= | none | 1–20 alphanumeric symbols → /public-api/v1/cryptocurrency/map; 1–100 ids → /public-api/v2/cryptocurrency/info. Keyless first, always. If the anonymous pool refuses the host's shared IP (429 error 1022, seen on the first production deploy), the identical call is repeated on the keyed base for 1 credit with base: "keyed" and the keyless error kept beside it. |
GET /api/health | none | Census date, snapshot days, counts, hero, the deployed commit and roster_key_configured — a boolean is all that is ever said about the key. Reads data/health.json, written by render_site.py. |
vercel.json: outputDirectory: site, includeFiles: data/*.json for the functions, Cache-Control: no-store on /api/*. scripts/dev_server.mjs serves the same three routes and site/ locally on port 8103.
Who writes what, who reads it.
| File | Written by | Read by |
|---|---|---|
data/census.json | shelfware census | render_site.py, shelfware verify, the tests, bench.py --replay |
data/roster_snapshot.json | shelfware census | shelfware TICKER (no key), api/roster.js |
data/snapshots/*.json, data/delta.json | shelfware census, scripts/snapshot.py | render_site.py (the delta panel), shelfware delta |
data/health.json | render_site.py | api/health.js |
data/seed/*.json | scripts/seed.py | offline tests, bench.py --replay — never the demo |
docs/proof/*.json | the real runs | DEMO.md, the page's hero card (docs/proof/ms.json) |
spike.py · bench.py · verify.py
The day-1 question asked three ways with real calls; p50/p95 of the state leg, the ticker question and the join, separately; shelfware verify plus a check that README, DEMO, JUDGE and the page all state the pair the rows produce.
snapshot.py · seed.py
The daily census into data/snapshots/YYYY-MM-DD.json and data/delta.json — it never touches data/census.json. seed.py cuts four real responses with provenance and prints the hero rule; not the demo path.
render_site.py · check_submission_readiness.py
The pages and data/health.json from the census; an unfilled {{slot}} fails the render and --check fails on drift. The readiness gate refuses placeholders, TODOs, overclaims, key-shaped strings in any tracked file, and a census older than three days.
Every failure is labelled; none becomes a number.
| Condition | Behaviour |
|---|---|
| 429 / 5xx / dropped | Retried with 2, 4, 8, 16 s backoff; then returned with throttled: true. |
| pool exhausted key exported | The identical call, keyed; the row says so. |
| pool exhausted no key | The committed state, labelled; the CLI exits 75 after answering. |
| 400 from a batched call | The offending symbol / ids named in CMC's message are dropped and the call retried; the rest of the batch survives. |
| any other 4xx | Returned immediately with CMC's own error code and message — never a raw body. |
| malformed JSON | An error, never a number. |
| drift | credits_used ≠ Σ keyed credit_count, or counts ≠ recount(): shelfware verify exits 1 and make check fails. |
Where each part lives.
shelfware/
├── shelfware/ the engine — stdlib only
│ ├── client.py one GET, four ledgers, a receipt per call, backoff, no raising
│ ├── join.py the arithmetic: wrappers, resolve, three counting rules, scorecard, hero rule
│ ├── lookup.py the ticker question — roster leg + state leg, each row labelled
│ ├── delta.py · verify.py two snapshots diffed · every headline recounted from the rows
│ └── cli.py shelfware TICKER · census · verify · delta
├── api/ Vercel functions, no dependencies: roster (keyed) · status (keyless first) · health
├── site/ generated: the one screen (/), /judge, /pitch — and this page, /architecture
├── scripts/ snapshot · seed · bench · verify · render_site · md2html · readiness gate · spike
├── data/ census.json · roster_snapshot.json · snapshots/ · delta.json · seed/
├── docs/proof/ live_run.json · ms.json · bench.json · spike.json — the receipts
├── docs/ METHOD.md · COMPARISON.md · screenshots/ · assets/
├── tests/ 104 offline · 6 live · api.test.mjs
├── JUDGE.md · DEMO.md · ARCHITECTURE.md · FEEDBACK.md
└── README.md
What is not here, and why.
A JSON file a judge can jq
The census is one file; the series is a directory of dated files.
Every number is a count
There is nothing to infer.
One screen, vanilla HTML/CSS/JS
Rendered from a template; a build step would add risk for no judge-visible gain.
The judged path is keyless
The proxy's one secret lives in the deployment environment and is never in the repo, the browser, a log or a receipt.
python3 -m shelfware MS
Works on a clean machine with no install step. The only dependencies are the dev ones in pyproject.toml.
Static HTML from a committed file
The functions exist for the browser only; the CLI never touches them.