The web client for bestiario — a window onto what is happening in the Mostro network.
bestiario indexes the public Nostr events Mostro instances publish and works out the figures: orders created and completed, volume by currency, disputes and how long they take, dev fees. It then publishes those figures as signed Nostr events. This repository is the site that reads them.
It is a static site. There is no server, no API and no build-time data fetch: the site ships code, and the data arrives at runtime over WebSocket from public relays, verified in the reader's browser.
A reader trusts one pubkey, not a host. The site is served from GitHub Pages, which is a convenience and not a trust anchor. Every figure on screen came from an event signed by the publisher key, and the signature was checked in the browser that drew it. A mirror of this site on another domain shows the same figures or shows nothing.
The site never invents a number. null is absence and renders as
absence, never as a zero. A figure the publisher inferred is marked as
inferred. A figure nothing published is neither of those and says so. A panel
whose proof failed shows the failure and no figure at all.
What a signature proves is that bestiario published these figures — nothing about whether they are right.
One screen today, over a window the reader picks (24 h, 7 d, 30 d, 90 d, or the whole archive):
- The map. Every currency the network traded in the window, placed in the country its ISO 4217 code names, sized by how many orders it carried.
- Orders: created, completed, canceled, completion and abandonment rates, and how many are open or in progress right now.
- Volume: total sats, ticket average and percentiles, the largest order, and a row per currency — thirteen of them on the current archive — with its own volume, order count and ticket distribution.
- Disputes: the rate, the resolution median, and the open book rebuilt from the indexed metric family, each with its id and its age.
- Dev fees: the total and its coverage, with the assumed percentage stated beside anything derived from it.
- The archive's real extent, so a period outside it reads as unindexed rather than as a quiet network.
The routes are illustrative, and the site says so on the map itself.
How many routes leave a currency is measured — its share of the busiest market. Where each one goes is not: bestiario publishes no document naming an instance, so nothing on the wire says which instance trades which currency. The far ends are anonymous anchors, drawn without a name so that nothing invites a reader to think a Mostro instance sits there.
The fix is upstream and is written: a window document for every report, so
instances reaches a relay. Until it does, the map draws movement and
refuses to draw a claim.
Stated plainly, because a number that is not there is easy to mistake for a number that is zero. Some of these are the daemon's limits and travel with the data; the rest are this repository's.
- Which instance trades which currency. No published document crosses the two. See the note above.
- Per-instance anything. Every document is published unscoped; there is
no
:i:<pubkey>view to build a bestiary from. - Unique users. Order keys are ephemeral; counting pubkeys counts orders, not people.
- What a dispute was about. The dispute event does not name its order.
- Why an order was canceled. The events record the change of state and never the cause.
- Volume in a reference currency. Computable in principle, and
missingon the current archive: no completed order had a rate snapshot close enough to price it. It renders as absence, not as a bug in this site.
The most delicate contract in this client, and worth knowing about before writing another one.
The publisher hashes a document's payload and the index names that hash;
a conformant client checks it before rendering. But the daemon computes the
hash over a different serialisation than the one it puts on the wire — the
struct in declaration order for the hash, an alphabetically sorted map for
the envelope. Hashing the bytes as received verifies 0 of 32 documents.
Re-serialised in declaration order, 32 of 32.
src/nostr/canonical.ts is that re-serialisation, it is the only module that
may produce those bytes, and its test runs over the real signed events and
asserts the whole set rather than "most". The rules that are not guessable
from the format alone are pinned there: ratio and a fiat amount are
f64 and always carry a decimal point, so 422550 on the wire is 422550.0
to the hash; a fiat metric is an {amount, code} object while a fiat row
cell is a bare float.
It is also the module that disappears the day the daemon serialises the
envelope from the typed struct — at which point it becomes JSON.stringify
of what was received, and the fixtures prove the collapse was safe.
$ npm install
$ npm run devThe dev server reads the live relays. There is no mock mode: the hardest bugs here are relay bugs.
| Command | What it does |
|---|---|
npm run dev |
Vite dev server, against the real relays |
npm run build |
Typecheck, then static output to dist/ |
npm run preview |
Serve dist/ for a last look |
npm test |
Unit and integration tests |
npm run test:coverage |
The same, with the thresholds enforced |
npm run lint |
ESLint |
npm run typecheck |
tsc --noEmit |
Nothing about the deployed page is configurable by whoever serves it. Two build-time variables, both baked into the bundle:
| Variable | Default | What it is |
|---|---|---|
VITE_PUBLISHER_PUBKEY |
the current publisher | The key whose signature every figure must carry |
VITE_BASE |
/ |
/ for a custom domain, /<repo>/ for a project page |
Changing the publisher is a commit and a deploy, which is the point. A publisher read at runtime from a query string would hand the trust anchor back to whoever serves the page.
The read relays are not a trust decision — a relay can withhold an event but
cannot forge one past verification — and live in src/config.ts.
bestiario-fe/
├── docs/SPEC.md # the specification this implements
├── public/
│ ├── geo/ # country geometry, served from this origin
│ ├── robots.txt # crawlers, and where the sitemap is
│ ├── sitemap.xml # one URL: hash routes are not addresses
│ └── og.png # the card an unfurler builds, 1200×630
├── assets/brand/ # Mostro's marks, as the share card draws them
├── scripts/
│ ├── fetch-fixtures.mjs # regenerates the fixtures from the relays
│ ├── gen-og-image.mjs # renders the share card and the touch icon
│ └── gen-iso-table.mjs # alpha-2 → ISO numeric, from the atlas
├── src/
│ ├── config.ts # publisher, relays, thresholds
│ ├── nostr/ # address grammar, canonicalisation, verification, pool
│ ├── store/ # index, documents, cache
│ ├── model/ # units, metric grouping, geography
│ ├── map/ # projection, scene, routes, labels
│ ├── components/ # map, tables, skeletons, trust rail
│ └── views/ # one file per route
└── tests/
├── fixtures/snapshot/ # the real signed events
└── ...
Files stay under 400 lines and modules are organised by domain, not by type.
Routing is by hash, so there is exactly one address a search engine holds:
https://mostro.world/. #/orders and #/volume are the same document to
it, which is why the sitemap names one URL and the canonical link names the
same one.
index.html carries a static description of the site inside #app —
prose, not figures. It is the page while the bundle downloads, the page a
reader without JavaScript keeps, and the page a crawler that runs none
indexes. main.tsx empties the container before Preact mounts, so the two
versions never overlap. No figure appears there: a number in that block
would be one nobody's browser verified, and this site publishes no such
number.
scripts/gen-og-image.mjs renders public/og.png and
public/apple-touch-icon.png with the Playwright Chromium the end-to-end
suite already installs. It is run by hand and its output is committed, so
what an unfurler fetches is a file somebody looked at. tests/e2e/seo.spec.ts
asserts every one of these against the built site over HTTP.
Tests first, and the two directories where a bug is silent — src/nostr and
src/model — are held at 100% on lines, branches and functions. The rest is
80%. npm run test:coverage enforces both.
The fixtures under tests/fixtures/snapshot/ are the real signed events,
byte for byte as they travel, pulled from the relays by
scripts/fetch-fixtures.mjs. Regenerating them is a commit a human reads:
stale fixtures are how a client and a publisher drift apart without either
noticing. The manifest records which publisher they came from, and a test
asserts it still matches the one the build trusts.
WCAG 2.2 AA. Semantic HTML, real tables with headers, and no meaning carried
by colour alone — which is why an inferred figure has a marker and not just a
hue. The map carries an accessible description of what it is showing,
including what it could not place. Loading is skeletons behind one live
region, so a screen reader hears what is loading once rather than a wall of
decorative boxes. prefers-reduced-motion stops every animation, the map's
travellers included.
Read docs/SPEC.md first — it is the source of truth for
what this site does and why, and it names the tests that cover each of its
requirements.
Everything written in this repository is in English: source, comments, commit messages, documentation, and everything on GitHub — issue titles and bodies, pull requests, review comments and the replies to them. Conversation with the maintainer may happen in Spanish; the artifacts do not.
Conventional commits (feat:, fix:, docs:, test:, chore:, …).
AGENTS.md is the working guide — conventions, commands, and the
places in this codebase where a careless change is silent. It is addressed to
coding agents and holds for everyone.
GNU General Public License v3.0, the same licence bestiario declares for the daemon.
