Architecturederived from the codestdlib onlyv1.0.1

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.

Shape of the thing

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.

Shelfware data flow Six CoinMarketCap endpoints feed client.py; client.py feeds join.py and lookup.py; join.py writes census.json, roster_snapshot.json, the snapshot series and the proof receipts; render_site.py turns the census into site/index.html; the page calls api/roster.js, api/status.js and api/health.js, which call CoinMarketCap on the browser's behalf. CoinMarketCap Pro API K /v1/key/infokeyed · 0 credits · the month's counter A /v5/real-world-assets/mapkeyed · 0 credits · has_tokens · rwa_rank C /v5/real-world-assets/issuers/listkeyed · 1 credit · num_tokens per issuer B /v5/real-world-assets/quotes/latestkeyed · 1 / 250 · tokens[] with price: null keyless · /public-api · the key is never sent D /public-api/v1/cryptocurrency/map0 credits · active · inactive · untracked E /public-api/v2/cryptocurrency/info0 credits · date_added for the shelf shelfware/ — stdlib Python client.py Client.get() · backoff 2, 4, 8, 16 s receipt per call · errors never raised rwa_map · rwa_quotes · issuers cmc_map · cmc_info · key_info join.py wrappers_from · resolve · enrich_info zero_tracked · scorecard · type_bars hero · census · recount delta.py · verify.py delta(before, after) · compare_counts lookup.py lookup(ticker) — roster leg + state leg cli.py TICKER · census · verify · delta committed data docs/proof/*.json live_run · ms · bench · spike the receipts data/snapshots/*.json one per day → data/delta.json by scripts/snapshot.py data/roster_snapshot.json the roster with a date — the keyless fallback data/census.json every wrapper, its state, the counts, the receipt Vercel — shelfware.edycu.dev api/roster.js keyed · 1 symbol · 1 credit snapshot fallback, labelled api/status.js keyless first · keyed repeat if refused · raw verbatim api/health.js census date · counts a boolean about the key site/index.html + /judge · /pitch · /architecture rendered from the census by scripts/render_site.py · --check fails on drift the ticker box fetches the three functions same-origin keyed keyless render_site.py quotes/latest · 1 credit map · info keyless first
6 endpoints · 6 modules · 5 committed artifacts · 3 functions · 1 static page amber outlines mark the path the product cannot exist without
One call

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.

the base is a boolean

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.

the receipt

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.

errors are data

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.

LedgerMethodEndpointCostWhat it carries
Arwa_map()/v5/real-world-assets/mapkeyed · 0Every underlying: has_tokens, rwa_rank, asset_type. Paged by has_more, 250 per page.
Brwa_quotes()/v5/real-world-assets/quotes/latestkeyed · 1 / 250tokens[] — 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.
Cissuers()/v5/real-world-assets/issuers/listkeyed · 1Each issuer's declared num_tokens.
Dcmc_map()/public-api/v1/cryptocurrency/mapkeyless · 0Listing 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.
Ecmc_info()/public-api/v2/cryptocurrency/infokeyless · 0date_added for the shelf, in batches of 200; ids named in a 400 are dropped and the batch retried.
Kkey_info()/v1/key/infokeyed · 0The month's credit counter, read before and after a census so the receipt's total can be checked against CMC's.
The census, stage by stage

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.

  1. Ledger A — the universe. rwa_map(); keep the rows with has_tokens.791 underlyings
  2. Ledger B — the roster. rwa_quotes(rwa_ids=…) for those ids; every tokens[] entry is a wrapper.1,435 wrappers, price: null rows kept
  3. Ledger C — the issuers. issuers(), for the declared-vs-attached column of the scorecard.
  4. Ledger D — the state. cmc_map() keyless, all of active,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 — so unresolved means CMC has no row, not that a page was skipped.
  5. Ledger E — the shelf's dates. cmc_info() keyless for every wrapper that is not active; date_added is the shelf's age.
  6. The join. join.census() — wrappers, resolution, the three rules, the scorecard, the type bars, the hero, the receipt and the counts — then key_info() again.
  7. Five artifacts. cli.write_census() writes data/census.json, data/roster_snapshot.json, docs/proof/live_run.json, today's data/snapshots/ file and, via write_delta(), data/delta.json.
The arithmetic, in full

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
The ticker question

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.

roster leg · which wrappers exist

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".

state leg · are they tracked

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.

The proxy — api/

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.

RouteSecretBehaviour
GET /api/roster?symbol=CMC_API_KEYRead 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=none1–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/healthnoneCensus 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.

Data files

Who writes what, who reads it.

FileWritten byRead by
data/census.jsonshelfware censusrender_site.py, shelfware verify, the tests, bench.py --replay
data/roster_snapshot.jsonshelfware censusshelfware TICKER (no key), api/roster.js
data/snapshots/*.json, data/delta.jsonshelfware census, scripts/snapshot.pyrender_site.py (the delta panel), shelfware delta
data/health.jsonrender_site.pyapi/health.js
data/seed/*.jsonscripts/seed.pyoffline tests, bench.py --replay — never the demo
docs/proof/*.jsonthe real runsDEMO.md, the page's hero card (docs/proof/ms.json)
scripts/ · proof

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.

scripts/ · series

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.

scripts/ · gates

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.

Failure handling

Every failure is labelled; none becomes a number.

ConditionBehaviour
429 / 5xx / droppedRetried with 2, 4, 8, 16 s backoff; then returned with throttled: true.
pool exhausted key exportedThe identical call, keyed; the row says so.
pool exhausted no keyThe committed state, labelled; the CLI exits 75 after answering.
400 from a batched callThe offending symbol / ids named in CMC's message are dropped and the call retried; the rest of the batch survives.
any other 4xxReturned immediately with CMC's own error code and message — never a raw body.
malformed JSONAn error, never a number.
driftcredits_used ≠ Σ keyed credit_count, or counts ≠ recount(): shelfware verify exits 1 and make check fails.
Repository

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
Deliberate non-architecture

What is not here, and why.

no database

A JSON file a judge can jq

The census is one file; the series is a directory of dated files.

no model, no LLM

Every number is a count

There is nothing to infer.

no framework

One screen, vanilla HTML/CSS/JS

Rendered from a template; a build step would add risk for no judge-visible gain.

no auth

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.

no runtime dependencies

python3 -m shelfware MS

Works on a clean machine with no install step. The only dependencies are the dev ones in pyproject.toml.

no server on the judged path

Static HTML from a committed file

The functions exist for the browser only; the CLI never touches them.

Read the code it describes

Every name on this page is a function.