Statistics for the Mostro network, computed from the public Nostr events its instances publish.
Every Mostro instance announces its orders, dev fees, disputes and its own configuration as signed Nostr events on public relays. bestiario reads those events, keeps every version of every one of them in a local SQLite database, and turns them into figures: how many orders were created and completed, in which currencies, by which instance, how long disputes take, how much each instance forwards to the development fund. Network-wide, and one instance against the rest — the bestiary.
It is a command-line tool. Every report prints as a table by default and as
JSON with --json.
Stated first, because a number that is not there is easy to mistake for a number that is zero. The events carry no more than they carry:
- Unique users, repeat traders, retention. Orders and disputes are published by the instance, not by the people trading. No user pubkey is anywhere in the data.
- Which order a dispute is about. A dispute event (kind 38386) does not name its order. Disputes are counted by status, initiator and instance, and the dispute rate is a ratio of two counts — disputes opened over orders that found a taker — never a pairing.
- Why an order was canceled. Expired, canceled by an admin, canceled
cooperatively: all arrive as
canceled. - The intermediate states.
fiat-sentanddisputeare published asin-progress; onlypending,in-progress,successandcanceledreach the wire. - Anything that needs a price, exactly. Volume in a reference currency
rests on the rate an instance published minutes before a trade, and the
volume implied by dev fees rests on an assumed fee share. Those are
inferred figures: marked
(inf)in every table and"kind": "inferred"in every JSON record, with what qualifies them in anerrorcolumn beside them. Everything else below is a count of published events.
A Rust toolchain (stable, edition 2024) is the only requirement; SQLite is bundled.
git clone https://github.com/MostroP2P/bestiario
cd bestiario
cargo install --path .Or cargo build --release and run target/release/bestiario.
cp settings.toml.example settings.tomlsettings.toml.example documents every key. The ones that matter first:
| Key | What it does |
|---|---|
[nostr].relays |
Relays to read from. wss://relay.mostro.network carries every instance. |
[nostr].discover_relays |
true to also dial the relays the instances say they publish to (NIP-65, kind 10002). Off by default. |
[indexer].instances |
Pubkeys to follow, as hex or npub1…. |
[indexer].accept_unknown_instances |
true to index every pubkey that publishes Mostro events, whether listed or not. Events from other platforms on the same relays (they exist) are turned away either way. |
[indexer].networks |
Which networks count: mainnet alone by default. |
[indexer].backfill_from |
How far back the first backfill reaches, as a unix timestamp. |
[database].url |
Where the archive lives: sqlite://bestiario.db. |
bestiario reads settings.toml from the current directory; --config
points it elsewhere. Every value is validated at startup, and a bad one is
an error naming the key rather than a report with a hole in it.
Each instance publishes a NIP-65 relay list saying where it reads and where
it writes. bestiario records the relays it writes to — an instance's
events are only fetchable where it publishes them, and a relay it merely
reads from holds nothing of its own — and, with discover_relays = true,
dials them alongside the configured ones.
Discovery is additive and never subtractive: the configured relays always
come first and are never dropped, since they are the operator's decision
while a discovered relay is a third party's claim. Only the relays an
instance says it writes to are taken, which NIP-65 spells as an r tag
with no marker or with write; an entry marked anything else carries no
such claim and is dropped, like a URL that cannot be dialled. With the flag
off the connection set is exactly what settings.toml lists, whatever the
instances have advertised. A relay list carries no y tag, so bestiario
takes one only from a pubkey it already knows as an instance — the same
rule that guards rate snapshots — and it asks only about those pubkeys
too, even with accept_unknown_instances = true. Kind 10002 is the kind
every Nostr user publishes: requesting it of no author in particular would
download the network's whole NIP-65 index to throw all but a handful of it
away. Until something has vouched for a publisher, the two untagged kinds
are not requested at all.
The connection set is not fixed at startup. A relay list read during a
backfill is followed by that same invocation — the run walks the relays it
discovers rather than leaving them for a second one — and a sync that
stores one rebuilds its subscription over the wider set there and then, so a
process meant to run for months does not go on dialling only the relays it
happened to know about on the day it started.
Every key can also be set from the environment, which is how the container
image is configured: BESTIARIO__DATABASE__URL overrides [database].url,
and a list is one comma-separated variable. See docs/DEPLOY.md.
$ bestiario backfill
backfill: 21 stored, 5 already known, 0 unchanged, 3 rejectedbackfill walks each relay's history backwards, from now down to
backfill_from, one kind at a time, and stores what it finds. It prints a
summary of what was stored, what it had already seen and what it turned
away, and it is safe to run again: nothing is written twice. Relays keep
dev fees for about a year and orders for about a fortnight, so on a fresh
archive expect fees for orders you will never see; the reports call those
orphans.
Every report needs this step: over a database that holds no events yet,
a report refuses to run and says so, rather than printing a table of
zeros that reads like an answer. The database path in settings.toml is
relative to the directory you run from, so a backfill and a report have
to be run from the same place.
To keep the archive current afterwards:
bestiario syncsync subscribes to the relays and stores events as they arrive, until
interrupted. It resumes from where it left off.
Every windowed report below — all of them except orders <ORDER_ID>,
which shows one order whole — accepts the same window and scope flags:
--fromand--until, as a unix timestamp orYYYY-MM-DD(UTC). The window is half-open —--untilis excluded — so consecutive windows tile. The default is the last thirty days, and a window wider than a century is refused: further back than any relay's history and further forward than any question about it, so it is a typo rather than a request.--instance <PUBKEY|NAME>: one instance, by pubkey, by a unique prefix of it, or by name.--network <NETWORK>: one network, overriding the configured list. Dispute events carry no network tag, so disputes cannot be narrowed this way:stats disputesrefuses the flag, and the views that include a dispute figure (summary,instance,compare) report it as—under it rather than as a network-wide number beneath a network-scoped heading.--json.
The examples are real output, captured by the test suite from the corpus of
signed events under tests/fixtures/ — every event there is one an instance
actually published. That corpus was chosen to cover the shapes a parser has
to survive, not to look like a month of trading: eight orders and five
disputes from unrelated instances make for a dispute rate nobody should
read as a market figure. The shape of each report is what to look at.
Every command shown is executed by tests/e2e.rs against that corpus, on
a frozen clock, and the output shown under it has to be what the binary
printed — byte for byte — so an example that has drifted fails the build.
Two things follow from how that suite works. The relay it seeds refuses
expired events, as any relay does, so the corpus is re-signed for it with
keys derived from each instance's real pubkey: the pubkeys in the examples
are those test keys, not the instances' own. And the clock is frozen at
2026-08-27T03:06:40Z, which is why five orders are still "open now".
Every figure in every report is one of three things, and the difference is
the difference between a measurement and an estimate. It is marked, not
explained in a footnote: an inferred figure carries (inf) after its name
in a table and "kind": "inferred" in JSON, with what qualifies it in the
error column beside it.
| What it is | How to read it | |
|---|---|---|
| Observed | A count or a sum of published events. orders.created, volume.sats, dev_fees.total_sats, disputes.opened. |
A fact about what the instances published. If it is wrong, either an event was missed or the parser is. |
| Derived | Arithmetic over observed figures: a rate, a share, a percentile. orders.completion_rate, market.buy_orders_share, timing.time_to_fill_p50, disputes.rate. |
As solid as the two numbers under it, and no more. Read the definition before the value — disputes.rate divides disputes by orders that found a taker, and pairs no dispute to any order, because a dispute event does not name one. |
| Inferred | Rests on something nobody published, so it cannot be checked against the wire. Marked (inf). |
Never quote it as a measurement. The error column states the assumption and the margin; if you disagree with the assumption, the figure is yours to recompute. |
Only two families are inferred, and both say why:
- Volume in a reference currency (
stats volume --in USD) multiplies each completed order by the rate its instance had published by the moment it settled. The assumption is that the rate a few minutes old still held when the trade closed; theerrorcolumn gives the age of the oldest quote used, how many orders were priced on another instance's snapshot, and how many could not be priced and are excluded from the sum. - Volume implied by dev fees (
stats dev-fees) inverts each fee byfee_in_force × dev_fee_percentage. That percentage is not published by any instance — it is the[assumptions]key ofsettings.toml,0.30by default — and one satoshi of rounding on a fee is1 ÷ (fee × pct)satoshis of volume. Both are in theerrorcolumn, andimplied_vs_observedsets the figure against the observed volume of the orders that are still known, which is the measure of how far the assumed share is from the real one.
Everything else in this README is observed or derived. Where a figure
cannot be computed at all, it reads — in a table and null in JSON —
never zero: zero is an answer, and the absence of one is not.
$ bestiario summary --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌──────────────────────────┬───────────────────────────────────────────┐
│ metric ┆ value │
╞══════════════════════════╪═══════════════════════════════════════════╡
│ summary.created ┆ 8 │
│ summary.completed ┆ 1 │
│ summary.completion_rate ┆ 50.0% │
│ summary.volume_sats ┆ 1361 sats │
│ summary.active_instances ┆ 4 │
│ summary.top_fiat ┆ ARS (2), BRL (2), EUR (2) │
│ summary.top_methods ┆ CBU (2), CVU (2), BBVA Efectivo Móvil (1) │
│ summary.open_disputes ┆ 1 │
└──────────────────────────┴───────────────────────────────────────────┘$ bestiario stats orders --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌─────────────────────────┬───────┐
│ metric ┆ value │
╞═════════════════════════╪═══════╡
│ orders.created ┆ 8 │
│ orders.completed ┆ 1 │
│ orders.canceled ┆ 1 │
│ orders.completion_rate ┆ 50.0% │
│ orders.abandonment_rate ┆ 12.5% │
│ orders.created_delta ┆ — │
│ orders.completed_delta ┆ — │
│ orders.open_now ┆ 4 │
│ orders.in_progress_now ┆ 1 │
└─────────────────────────┴───────┘--by slices the same figures by status, kind, fiat, method,
instance, period (calendar months), hour or weekday (histograms):
$ bestiario stats orders --by fiat --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌─────────────────────────────┬────────┐
│ metric ┆ value │
╞═════════════════════════════╪════════╡
│ orders.ARS.created ┆ 2 │
│ orders.ARS.completed ┆ 0 │
│ orders.ARS.canceled ┆ 0 │
│ orders.ARS.completion_rate ┆ — │
│ orders.ARS.abandonment_rate ┆ 0.0% │
│ orders.ARS.created_delta ┆ — │
│ orders.ARS.completed_delta ┆ — │
│ orders.ARS.open_now ┆ 1 │
│ orders.ARS.in_progress_now ┆ 1 │
│ orders.BRL.created ┆ 2 │
│ orders.BRL.completed ┆ 0 │
│ orders.BRL.canceled ┆ 1 │
│ orders.BRL.completion_rate ┆ 0.0% │
│ orders.BRL.abandonment_rate ┆ 50.0% │
│ orders.BRL.created_delta ┆ — │
│ orders.BRL.completed_delta ┆ — │
│ orders.BRL.open_now ┆ 1 │
│ orders.BRL.in_progress_now ┆ 0 │
│ orders.CUP.created ┆ 1 │
│ orders.CUP.completed ┆ 1 │
│ orders.CUP.canceled ┆ 0 │
│ orders.CUP.completion_rate ┆ 100.0% │
│ orders.CUP.abandonment_rate ┆ 0.0% │
│ orders.CUP.created_delta ┆ — │
│ orders.CUP.completed_delta ┆ — │
│ orders.CUP.open_now ┆ 0 │
│ orders.CUP.in_progress_now ┆ 0 │
│ orders.EUR.created ┆ 2 │
│ orders.EUR.completed ┆ 0 │
│ orders.EUR.canceled ┆ 0 │
│ orders.EUR.completion_rate ┆ — │
│ orders.EUR.abandonment_rate ┆ 0.0% │
│ orders.EUR.created_delta ┆ — │
│ orders.EUR.completed_delta ┆ — │
│ orders.EUR.open_now ┆ 2 │
│ orders.EUR.in_progress_now ┆ 0 │
│ orders.USD.created ┆ 1 │
│ orders.USD.completed ┆ 0 │
│ orders.USD.canceled ┆ 0 │
│ orders.USD.completion_rate ┆ — │
│ orders.USD.abandonment_rate ┆ 0.0% │
│ orders.USD.created_delta ┆ — │
│ orders.USD.completed_delta ┆ — │
│ orders.USD.open_now ┆ 0 │
│ orders.USD.in_progress_now ┆ 0 │
└─────────────────────────────┴────────┘A rate over nothing — no order completed or canceled, no previous month to
grow from — is reported as — in a table and null in JSON, never as
zero: zero is an answer, and this is the absence of one.
--by day cuts the window into UTC calendar days instead, one block per
day and a Δ against the day before:
$ bestiario stats orders --by day --from 2026-08-25 --until 2026-08-28
2026-08-25T00:00:00+00:00 — 2026-08-28T00:00:00+00:00
┌────────────────────────────────────┬─────────┐
│ metric ┆ value │
╞════════════════════════════════════╪═════════╡
│ orders.2026-08-25.created ┆ — │
│ orders.2026-08-25.completed ┆ — │
│ orders.2026-08-25.canceled ┆ — │
│ orders.2026-08-25.completion_rate ┆ — │
│ orders.2026-08-25.abandonment_rate ┆ — │
│ orders.2026-08-25.created_delta ┆ — │
│ orders.2026-08-25.completed_delta ┆ — │
│ orders.2026-08-26.created ┆ 8 │
│ orders.2026-08-26.completed ┆ 1 │
│ orders.2026-08-26.canceled ┆ 1 │
│ orders.2026-08-26.completion_rate ┆ 50.0% │
│ orders.2026-08-26.abandonment_rate ┆ 12.5% │
│ orders.2026-08-26.created_delta ┆ — │
│ orders.2026-08-26.completed_delta ┆ — │
│ orders.2026-08-27.created ┆ 0 │
│ orders.2026-08-27.completed ┆ 0 │
│ orders.2026-08-27.canceled ┆ 0 │
│ orders.2026-08-27.completion_rate ┆ — │
│ orders.2026-08-27.abandonment_rate ┆ — │
│ orders.2026-08-27.created_delta ┆ -100.0% │
│ orders.2026-08-27.completed_delta ┆ -100.0% │
└────────────────────────────────────┴─────────┘Every day of the window is there, quiet ones included, so a chart cannot
draw a line across a gap that was never published. A day the archive
predates is the one thing that is not zero: nobody indexed it, and saying
zero would claim the network published nothing when the truth is that
bestiario was not there. Those days keep their rows and report —, and a Δ
against one of them is — too. Relays hold orders for about a fortnight,
so any window reaching back past your first backfill will show them.
The same applies to a kind nothing ever asked for. backfill --kind 38383
indexes orders and leaves disputes untouched; a later stats disputes --by day then has no dispute history to speak from, and reports — throughout
rather than a month of confident zeros. Run backfill without --kind, or
sync, and the days it covered become answerable — zeros included, because
a day nobody disputed anything is a fact. A report combining families needs
all of them: the dispute rate divides disputes by orders, so a day is
answerable only when both reach it.
$ bestiario stats volume --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌────────────────────────────┬────────────┐
│ metric ┆ value │
╞════════════════════════════╪════════════╡
│ volume.sats ┆ 1361 sats │
│ volume.completed ┆ 1 │
│ volume.ticket_avg ┆ 1361 sats │
│ volume.ticket_p50 ┆ 1361 sats │
│ volume.ticket_p90 ┆ 1361 sats │
│ volume.largest ┆ 1361 sats │
│ volume.size.lt_10k ┆ 1 │
│ volume.size.10k_50k ┆ 0 │
│ volume.size.50k_200k ┆ 0 │
│ volume.size.200k_1m ┆ 0 │
│ volume.size.gt_1m ┆ 0 │
│ volume.buy_sats ┆ 0 sats │
│ volume.sell_sats ┆ 1361 sats │
│ volume.fiat.CUP.total ┆ 800.00 CUP │
│ volume.fiat.CUP.orders ┆ 1 │
│ volume.fiat.CUP.sats ┆ 1361 sats │
│ volume.fiat.CUP.completed ┆ 1 │
│ volume.fiat.CUP.ticket_avg ┆ 800.00 CUP │
│ volume.fiat.CUP.ticket_p50 ┆ 800.00 CUP │
│ volume.fiat.CUP.ticket_p90 ┆ 800.00 CUP │
└────────────────────────────┴────────────┘Sats and fiat traded by the orders that reached success in the window,
dated by the moment they did: total, average and p50/p90 ticket, the
largest order, the size buckets and the maker's side. Fiat figures are per
currency and cover fixed-amount orders only — a range order names no single
amount, so it has sats to add and no fiat to add. --by slices by kind,
fiat, instance or period, one block per slice that completed
something in the window — only completed orders are read, so the cost of
a week's report is a week's orders, not the history:
$ bestiario stats volume --by kind --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌─────────────────────────────────┬────────────┐
│ metric ┆ value │
╞═════════════════════════════════╪════════════╡
│ volume.sell.sats ┆ 1361 sats │
│ volume.sell.completed ┆ 1 │
│ volume.sell.ticket_avg ┆ 1361 sats │
│ volume.sell.ticket_p50 ┆ 1361 sats │
│ volume.sell.ticket_p90 ┆ 1361 sats │
│ volume.sell.largest ┆ 1361 sats │
│ volume.sell.size.lt_10k ┆ 1 │
│ volume.sell.size.10k_50k ┆ 0 │
│ volume.sell.size.50k_200k ┆ 0 │
│ volume.sell.size.200k_1m ┆ 0 │
│ volume.sell.size.gt_1m ┆ 0 │
│ volume.sell.buy_sats ┆ 0 sats │
│ volume.sell.sell_sats ┆ 1361 sats │
│ volume.sell.fiat.CUP.total ┆ 800.00 CUP │
│ volume.sell.fiat.CUP.orders ┆ 1 │
│ volume.sell.fiat.CUP.sats ┆ 1361 sats │
│ volume.sell.fiat.CUP.completed ┆ 1 │
│ volume.sell.fiat.CUP.ticket_avg ┆ 800.00 CUP │
│ volume.sell.fiat.CUP.ticket_p50 ┆ 800.00 CUP │
│ volume.sell.fiat.CUP.ticket_p90 ┆ 800.00 CUP │
└─────────────────────────────────┴────────────┘--in <CURRENCY> adds the conversion into a reference currency: each
completed order at the rate its instance had published by the moment it
settled, summed. The figure is inferred — the rate is one instance's
snapshot, minutes old — and every row of it says so, with what qualifies it
in the error column: the age of the oldest rate used, how many orders were
priced on another instance's snapshot, and how many had no rate at all and
are left out of the sum:
$ bestiario stats volume --in USD --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌───────────────────────────────────┬────────────┬────────────────────────────────────────────────────────────────────────┐
│ metric ┆ value ┆ error │
╞═══════════════════════════════════╪════════════╪════════════════════════════════════════════════════════════════════════╡
│ volume.sats ┆ 1361 sats ┆ │
│ volume.completed ┆ 1 ┆ │
│ volume.ticket_avg ┆ 1361 sats ┆ │
│ volume.ticket_p50 ┆ 1361 sats ┆ │
│ volume.ticket_p90 ┆ 1361 sats ┆ │
│ volume.largest ┆ 1361 sats ┆ │
│ volume.size.lt_10k ┆ 1 ┆ │
│ volume.size.10k_50k ┆ 0 ┆ │
│ volume.size.50k_200k ┆ 0 ┆ │
│ volume.size.200k_1m ┆ 0 ┆ │
│ volume.size.gt_1m ┆ 0 ┆ │
│ volume.buy_sats ┆ 0 sats ┆ │
│ volume.sell_sats ┆ 1361 sats ┆ │
│ volume.fiat.CUP.total ┆ 800.00 CUP ┆ │
│ volume.fiat.CUP.orders ┆ 1 ┆ │
│ volume.fiat.CUP.sats ┆ 1361 sats ┆ │
│ volume.fiat.CUP.completed ┆ 1 ┆ │
│ volume.fiat.CUP.ticket_avg ┆ 800.00 CUP ┆ │
│ volume.fiat.CUP.ticket_p50 ┆ 800.00 CUP ┆ │
│ volume.fiat.CUP.ticket_p90 ┆ 800.00 CUP ┆ │
│ volume.in.USD.total (inf) ┆ — ┆ no rate used; 1 with no usable rate within 300s (1361 sats excluded) │
│ volume.in.USD.orders (inf) ┆ 0 ┆ orders with a rate published at or before success_at │
│ volume.in.USD.unpriced_sats (inf) ┆ 1361 sats ┆ sats of the orders with no usable rate at success_at; not in the total │
│ volume.in.USD.rate_age_max (inf) ┆ — ┆ age of the oldest snapshot used │
└───────────────────────────────────┴────────────┴────────────────────────────────────────────────────────────────────────┘Here the one completed order settled hours before the first rate snapshot
was captured, so there is nothing to price it with: the total is —, not
0.00 USD, and the excluded sats are counted.
$ bestiario stats timing --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌──────────────────────────────────────┬───────┐
│ metric ┆ value │
╞══════════════════════════════════════╪═══════╡
│ timing.time_to_fill_samples ┆ 0 │
│ timing.time_to_fill_p50 ┆ — │
│ timing.time_to_fill_p90 ┆ — │
│ timing.time_to_complete_samples ┆ 0 │
│ timing.time_to_complete_p50 ┆ — │
│ timing.time_to_complete_p90 ┆ — │
│ timing.full_cycle_samples ┆ 0 │
│ timing.full_cycle_p50 ┆ — │
│ timing.full_cycle_p90 ┆ — │
│ timing.time_to_cancel_samples ┆ 0 │
│ timing.time_to_cancel_p50 ┆ — │
│ timing.time_to_cancel_p90 ┆ — │
│ timing.book_size ┆ 4 │
│ timing.book_age_avg ┆ 16.9h │
│ timing.funnel.created ┆ 5 │
│ timing.funnel.taken ┆ 0 │
│ timing.funnel.taken_share ┆ 0.0% │
│ timing.funnel.completed ┆ 0 │
│ timing.funnel.canceled_taken ┆ 0 │
│ timing.funnel.canceled_untaken ┆ 0 │
│ timing.funnel.canceled_untaken_share ┆ 0.0% │
│ timing.funnel.expired_untaken ┆ 1 │
│ timing.funnel.open ┆ 4 │
│ timing.unknown_origin ┆ 3 │
│ timing.regressed ┆ 0 │
└──────────────────────────────────────┴───────┘Every duration is the gap between two observed versions of the same
order: time to fill (in-progress − pending), time to complete
(success − in-progress), the full cycle (success − pending) and time
to cancel (canceled − pending), as nearest-rank p50/p90 over the orders
whose gap ended in the window, each with the number of samples it is
taken over — the populations differ, since each gap needs its own two
versions. book_size and book_age_avg are about now: the pending
orders seen from their book entry, not taken, not ended, not expired.
The funnel is over the orders whose pending version was seen in the
window: how many found a taker (an in-progress version, or a success,
which the protocol cannot reach without one), how many completed, how many
were canceled after a taker or with none seen, how many sat past their
expiry with no ending seen (expired_untaken), and how many are still
open. unknown_origin counts the orders first seen at a later stage —
usual in a backfill, since a relay keeps only an order's latest version —
which belong to no cohort and anchor no duration; regressed counts
orders carrying both a success and a cancellation, of which only the
earlier is counted. Slices — --by fiat, --by method, --by kind,
--by instance — go by the order's first version seen, so a later
republication cannot move an entry to another slice.
In this corpus every order was captured in a single version: the five seen
at pending form the cohort, the three seen already in progress or ended
are of unknown origin, and no duration can be measured.
$ bestiario stats market --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌───────────────────────────────┬──────────────────────────────────────────────────────────────────────────────┐
│ metric ┆ value │
╞═══════════════════════════════╪══════════════════════════════════════════════════════════════════════════════╡
│ market.orders ┆ 8 │
│ market.buy_orders_share ┆ 50.0% │
│ market.buy_volume_share ┆ 0.0% │
│ market.premium_avg ┆ 10.0% │
│ market.premium_p50 ┆ 10.0% │
│ market.premium_p50_buy ┆ — │
│ market.premium_p50_sell ┆ 10.0% │
│ market.premium_spread ┆ — │
│ market.market_price_share ┆ 50.0% │
│ market.range_share ┆ 50.0% │
│ market.range_width_avg ┆ 82.8% │
│ market.fiat_top3_by_orders ┆ ARS 2, BRL 2, EUR 2 │
│ market.fiat_top3_orders_share ┆ 75.0% │
│ market.fiat_hhi_orders ┆ 21.9% │
│ market.fiat_top3_by_volume ┆ CUP 1361 sats │
│ market.fiat_top3_volume_share ┆ 100.0% │
│ market.fiat_hhi_volume ┆ 100.0% │
│ market.method_top3_by_orders ┆ CBU 2, CVU 2, BBVA Efectivo Móvil 1 │
│ market.method_top3_by_volume ┆ Efectivo 1361 sats, EnZona 1361 sats │
│ market.new_fiats ┆ ARS, BRL, CUP, EUR, USD │
│ market.new_methods ┆ BBVA Efectivo Móvil, Belo, CBU, CVU, DePix, Efectivo, EnZona, Lemon, +7 more │
└───────────────────────────────┴──────────────────────────────────────────────────────────────────────────────┘Which way the book leans and at what price. Pressure is the buy share of
the orders created in the window and of the sats completed in it; the
premiums are those of the completed orders — an open order's premium is
only an ask — as average, median, median by side and the spread between
the sides. market_price_share is the share of orders born with amt = 0,
priced when taken; range_share the share published as [min, max], with
the mean relative width (max − min) ÷ max — a block that holds ARS
beside EUR cannot average their widths, and the relative form compares.
Currencies and payment methods are ranked by orders created and by sats
completed, and new_fiats / new_methods list what was seen for the
first time in the window — the first eight, and a count of the rest; —
on those two rows means none were, not that none could be counted. The
methods counted are those of an order's first version, what the maker put
on the book: a pm amended days later was not on offer at creation, and
dated by that order it would hide a genuine first sighting.
An order names one currency and may name several payment methods, and it
is credited in full to each method it names — above, one completed order
of 1 361 sats offered over two methods shows 1 361 against each, so the
method rows add up to more than the volume traded. The sats are
attributed to a method, not divided between them; dividing them would
invent a figure nobody published. That is why only the currencies carry
the concentration rows: the top-three share, and the
Herfindahl–Hirschman index — an index between 1/n and 1 rather than a
share of anything, shown as a percentage for the column it sits in.
--by fiat, --by kind and --by instance slice it. A fiat slice drops
the currency ranking, which says nothing about one currency, and gains
range_width_fiat_avg: the mean max − min in that currency, which only
a single-currency block can state — relative width alone would call
[10, 100] wider than [900, 1000]. Every row of a slice is that
slice's own, the first sightings included: market.buy.new_methods names
the methods whose first buy order fell in the window, so a method a
seller has offered for a year is new to the buy block the day a buyer
first names it, and market.<instance>.new_fiats names what is new to
that instance.
$ bestiario stats rates --fiat USD --instance Mostro
2026-07-28T03:06:40+00:00 — 2026-08-27T03:06:40+00:00
┌────────────────────────────────────┬──────────────┐
│ metric ┆ value │
╞════════════════════════════════════╪══════════════╡
│ rates.feeds ┆ 1 │
│ rates.fresh ┆ 0 │
│ rates.stale ┆ 0 │
│ rates.dead ┆ 1 │
│ rates.silent ┆ 0 │
│ rates.skewed ┆ 0 │
│ rates.currencies ┆ 141 │
│ rates.USD.quoted_by ┆ 1 │
│ rates.USD.comparable ┆ 0 │
│ rates.USD.low ┆ — │
│ rates.USD.high ┆ — │
│ rates.USD.disparity ┆ — │
│ rates.USD.Mostro (6320ee5e) ┆ 78614.25 USD │
│ rates.Mostro (6320ee5e).age ┆ 16.5h │
│ rates.Mostro (6320ee5e).status ┆ dead │
│ rates.Mostro (6320ee5e).currencies ┆ 141 │
└────────────────────────────────────┴──────────────┘What each instance quotes right now, and how alive its feed is. These are the only figures in the tool that are not taken over the window: a feed is a live thing, and §6.8 asks what it says now — the window still heads the report, as everywhere.
A feed is fresh while its latest snapshot is under five minutes old, the
bound a rate has to price a trade; stale past that but within the ten
minutes a kind 30078 event declares itself valid for through its NIP-40
expiration; dead past that expiry, with nothing since; silent when
the instance has published no rate at all; and skewed when its latest
snapshot is dated in the future, which is a clock nobody shares rather than
an age. Every instance falls in exactly one of the five, and the counts add
up to the statuses listed below them. Rate snapshots carry no y tag, so
bestiario stores one only from a pubkey it has already seen publishing as
an instance — an unvouched feed is not a feed, and a stored snapshot whose
publisher is missing from the bestiary fails the report rather than being
quietly readmitted to it.
--fiat <CURRENCY> adds the currency's block: who quotes it, the cheapest
and dearest quote, and the disparity between them. The disparity is about
now: only the quotes that are still fresh set low, high and the
ratio, because two prices an hour apart differ by the market moving — which
is not a disagreement between instances — and a price whose own event has
expired is not what the feed quotes today. Everyone quoting the currency is
still counted under quoted_by, so a currency nobody quotes live says —
rather than reporting the disagreement of two dead snapshots; one
comparable quote disagrees with nobody, and that row says — too. Without
--instance the report covers every instance in the bestiary, one block
each.
$ bestiario series orders.created --by day --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌─────────────────────────────────┬───────┐
│ metric ┆ value │
╞═════════════════════════════════╪═══════╡
│ orders.created.2026-08-23 ┆ 0 │
│ orders.created.2026-08-23.delta ┆ — │
│ orders.created.2026-08-24 ┆ 0 │
│ orders.created.2026-08-24.delta ┆ — │
│ orders.created.2026-08-25 ┆ 0 │
│ orders.created.2026-08-25.delta ┆ — │
│ orders.created.2026-08-26 ┆ 8 │
│ orders.created.2026-08-26.delta ┆ — │
└─────────────────────────────────┴───────┘Any metric of the families above, once per bucket, with the change against
the bucket before it. --by takes day, week, month or year;
--split instance|kind|fiat plots one line per slice:
$ bestiario series volume.sats --by day --split kind --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌───────────────────────────────────┬───────────┐
│ metric ┆ value │
╞═══════════════════════════════════╪═══════════╡
│ volume.sats.buy.2026-08-23 ┆ 0 sats │
│ volume.sats.buy.2026-08-23.delta ┆ — │
│ volume.sats.buy.2026-08-24 ┆ 0 sats │
│ volume.sats.buy.2026-08-24.delta ┆ — │
│ volume.sats.buy.2026-08-25 ┆ 0 sats │
│ volume.sats.buy.2026-08-25.delta ┆ — │
│ volume.sats.buy.2026-08-26 ┆ 0 sats │
│ volume.sats.buy.2026-08-26.delta ┆ — │
│ volume.sats.sell.2026-08-23 ┆ 0 sats │
│ volume.sats.sell.2026-08-23.delta ┆ — │
│ volume.sats.sell.2026-08-24 ┆ 0 sats │
│ volume.sats.sell.2026-08-24.delta ┆ — │
│ volume.sats.sell.2026-08-25 ┆ 0 sats │
│ volume.sats.sell.2026-08-25.delta ┆ — │
│ volume.sats.sell.2026-08-26 ┆ 1361 sats │
│ volume.sats.sell.2026-08-26.delta ┆ — │
└───────────────────────────────────┴───────────┘The Δ is a relative change for a magnitude — a count, a sum, a duration —
since that is what "grew by a third" means, and the arithmetic difference
for a figure that is already a proportion: a completion rate going from 20%
to 30% rose by ten points, not by half. The first bucket has nothing to
have changed from, and a change from zero is not a proportion of anything;
both read — — which, over a corpus this sparse, is every bucket of the
examples above.
The metric name is whatever the reports call it, and nothing keeps a
separate list: a metric a family gains is one series can plot the day it
lands. That includes the names the data gives rather than the code —
volume.fiat.ARS.total exists because an ARS order completed — so which
names are plottable depends on the window, and a name that does not exist
in it is answered with the ones that do. A converted figure names its own
currency and is priced from the snapshots exactly as stats volume --in USD is: series volume.in.USD.total needs no flag of its own.
An inferred figure stays inferred once it is a bucket: (inf) in the
table, "kind": "inferred" in the JSON, with the qualification the report
gives it — and so does a Δ between two of them, since a change between two
estimates is an estimate.
Two kinds of figure are refused rather than plotted: those about now
(orders.open_now), which would be the same number in every bucket, and
those that are already a change against a previous period
(orders.created_delta), since a Δ of a Δ answers nothing. So is a range
with more buckets than a table anybody reads — before the buckets are
built, not after.
$ bestiario stats dev-fees --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌────────────────────────────────────┬──────────┬──────────────────────────────────────────────┐
│ metric ┆ value ┆ error │
╞════════════════════════════════════╪══════════╪══════════════════════════════════════════════╡
│ dev_fees.total_sats ┆ 117 sats ┆ │
│ dev_fees.paid ┆ 2 ┆ │
│ dev_fees.coverage ┆ — ┆ │
│ dev_fees.latency_p50 ┆ — ┆ │
│ dev_fees.latency_p90 ┆ — ┆ │
│ dev_fees.duplicates ┆ 0 ┆ │
│ dev_fees.orphans ┆ 2 ┆ │
│ dev_fees.implied_volume (inf) ┆ — ┆ no fee inverted; 2 fees with no fee in force │
│ dev_fees.with_fee_volume ┆ — ┆ │
│ dev_fees.implied_vs_observed (inf) ┆ — ┆ no fee names a settled order │
└────────────────────────────────────┴──────────┴──────────────────────────────────────────────┘An order paid for twice — a known daemon bug — counts once towards the
total and once under duplicates. coverage is the share of completed
orders that produced a fee, over the instances known to charge one.
--by instance and --by period slice it.
The last three rows are the comparison of SPEC §6.6. A dev fee is
round(fee × amount × pct), so each fee implies an order of about
fee ÷ (fee_in_force × pct) sats — including the fees whose order has
already expired off the relays, which is what makes the figure worth
having. It is inferred twice over, and the error column says how: one
sat of rounding on a fee is 1 ÷ (fee × pct) sats of volume, and pct —
the share of its fee an instance forwards — is not published by anyone, so
it is the [assumptions] of settings.toml (0.30, the daemon default,
unless overridden per instance).
A third qualification outweighs both in a backfill: a fee whose instance
never published a fee the projection still has cannot be inverted at
all. Those fees are not in the sum and no rounding bound covers them, so
whenever there is one the error column says lower bound: n of m fees inverted and the figure is to be read as the floor it is.
with_fee_volume is the observed side: ∑ amount_sats of the orders that
a fee names and that reached success — a fee paid against an order
the relays no longer have, or one that was later canceled, has no observed
volume to show, and the row is — rather than 0 when none of them does.
It is observed in the strict sense: it does not move with what could be
inverted. implied_vs_observed is implied ÷ observed − 1 over the
intersection — the fees that were inverted and name a settled order of a
positive amount — so a positive figure means the instance forwards more
than assumed. Orders still known at amt = 0 (market price, never
amended: SPEC §3) are out of the ratio, which would otherwise divide by
nothing, and the column says how many.
The two sides are dated differently on purpose: a fee counts in the window
its own event falls in, while the order it names may have settled in the
previous one. with_fee_volume for a month is therefore not the same set
as volume.total for that month, and the two are not meant to reconcile.
Here every fee names an order the relays no longer have and the instance's fee at the time is unknown, so nothing can be inverted and the rows say so.
$ bestiario stats disputes --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌─────────────────────────────────────────┬──────────────────────────────────────┐
│ metric ┆ value │
╞═════════════════════════════════════════╪══════════════════════════════════════╡
│ disputes.opened ┆ 5 │
│ disputes.status.initiated ┆ 1 │
│ disputes.status.in_progress ┆ 1 │
│ disputes.status.seller_refunded ┆ 2 │
│ disputes.status.settled ┆ 1 │
│ disputes.status.released ┆ 0 │
│ disputes.status.cooperatively_canceled ┆ 0 │
│ disputes.initiator.buyer ┆ 60.0% │
│ disputes.initiator.seller ┆ 40.0% │
│ disputes.rate ┆ 250.0% │
│ disputes.resolved ┆ 3 │
│ disputes.outcome.seller_refunded ┆ 66.7% │
│ disputes.outcome.settled ┆ 33.3% │
│ disputes.outcome.released ┆ 0.0% │
│ disputes.outcome.cooperatively_canceled ┆ 0.0% │
│ disputes.resolution_p50 ┆ 1.4h │
│ disputes.resolution_p90 ┆ 2.0h │
│ disputes.open_now ┆ 1 │
│ disputes.open.1.id ┆ c6ebce7e-e521-4df3-a8c5-24301145eb66 │
│ disputes.open.1.age ┆ 3.1d │
└─────────────────────────────────────────┴──────────────────────────────────────┘--by status and --by initiator print the histograms alone; --by instance and --by period one block per slice.
$ bestiario instances --instance "Mostro Brasil" --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌─────────────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────┐
│ metric ┆ value │
╞═════════════════════════════════════════════════════╪══════════════════════════════════════════════════════════════════╡
│ instances.Mostro Brasil (ec3c3e00).pubkey ┆ ec3c3e00a04aa9e0c040fcef2dc7767d66c6c93d5dd2b39ba937b820ddf23610 │
│ instances.Mostro Brasil (ec3c3e00).name ┆ Mostro Brasil │
│ instances.Mostro Brasil (ec3c3e00).mostro_version ┆ — │
│ instances.Mostro Brasil (ec3c3e00).protocol_version ┆ — │
│ instances.Mostro Brasil (ec3c3e00).fee ┆ — │
│ instances.Mostro Brasil (ec3c3e00).min_order ┆ — │
│ instances.Mostro Brasil (ec3c3e00).max_order ┆ — │
│ instances.Mostro Brasil (ec3c3e00).fiat ┆ — │
│ instances.Mostro Brasil (ec3c3e00).ln_networks ┆ — │
│ instances.Mostro Brasil (ec3c3e00).bond ┆ — │
│ instances.Mostro Brasil (ec3c3e00).first_seen ┆ 2026-08-26T10:03:46+00:00 │
│ instances.Mostro Brasil (ec3c3e00).last_seen ┆ 2026-08-26T10:36:53+00:00 │
│ instances.Mostro Brasil (ec3c3e00).silent_for ┆ 16.5h │
│ instances.Mostro Brasil (ec3c3e00).silent ┆ no │
│ instances.Mostro Brasil (ec3c3e00).created ┆ 2 │
└─────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────┘Without --instance, one block per known instance. An instance is silent
after a week without any event. What an instance never published — a third
of the network publishes no name — is —, not blank.
One instance, with its own figures and its share of the network:
$ bestiario instance Mostro --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌─────────────────────────────────────────┬──────────────────────────────────────────────────────────────────┐
│ metric ┆ value │
╞═════════════════════════════════════════╪══════════════════════════════════════════════════════════════════╡
│ instance.pubkey ┆ 6320ee5edbaeb9a00d7c4768e472e277539aa993007c43d75ce00a38dff4d425 │
│ instance.name ┆ Mostro │
│ instance.mostro_version ┆ — │
│ instance.protocol_version ┆ — │
│ instance.fee ┆ — │
│ instance.min_order ┆ — │
│ instance.max_order ┆ — │
│ instance.fiat ┆ — │
│ instance.ln_networks ┆ — │
│ instance.bond ┆ — │
│ instance.first_seen ┆ 2026-08-25T01:24:38+00:00 │
│ instance.last_seen ┆ 2026-08-26T10:39:33+00:00 │
│ instance.silent_for ┆ 16.5h │
│ instance.silent ┆ no │
│ orders.created ┆ 4 │
│ orders.completed ┆ 0 │
│ orders.canceled ┆ 0 │
│ orders.completion_rate ┆ — │
│ orders.abandonment_rate ┆ 0.0% │
│ orders.created_delta ┆ — │
│ orders.completed_delta ┆ — │
│ orders.open_now ┆ 2 │
│ orders.in_progress_now ┆ 1 │
│ volume.sats ┆ 0 sats │
│ dev_fees.total_sats ┆ 116 sats │
│ dev_fees.paid ┆ 1 │
│ dev_fees.coverage ┆ — │
│ dev_fees.latency_p50 ┆ — │
│ dev_fees.latency_p90 ┆ — │
│ dev_fees.duplicates ┆ 0 │
│ dev_fees.orphans ┆ 1 │
│ disputes.opened ┆ 1 │
│ disputes.status.initiated ┆ 0 │
│ disputes.status.in_progress ┆ 1 │
│ disputes.status.seller_refunded ┆ 0 │
│ disputes.status.settled ┆ 0 │
│ disputes.status.released ┆ 0 │
│ disputes.status.cooperatively_canceled ┆ 0 │
│ disputes.initiator.buyer ┆ 100.0% │
│ disputes.initiator.seller ┆ 0.0% │
│ disputes.rate ┆ 100.0% │
│ disputes.resolved ┆ 0 │
│ disputes.outcome.seller_refunded ┆ — │
│ disputes.outcome.settled ┆ — │
│ disputes.outcome.released ┆ — │
│ disputes.outcome.cooperatively_canceled ┆ — │
│ disputes.resolution_p50 ┆ — │
│ disputes.resolution_p90 ┆ — │
│ disputes.open_now ┆ 0 │
│ share.orders ┆ 50.0% │
│ share.volume ┆ 0.0% │
└─────────────────────────────────────────┴──────────────────────────────────────────────────────────────────┘$ bestiario market ARS --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌─────────────────────────────────────┬───────────────────────────────────────────┐
│ metric ┆ value │
╞═════════════════════════════════════╪═══════════════════════════════════════════╡
│ market.ARS.orders ┆ 2 │
│ market.ARS.buy_orders_share ┆ 50.0% │
│ market.ARS.buy_volume_share ┆ — │
│ market.ARS.premium_avg ┆ — │
│ market.ARS.premium_p50 ┆ — │
│ market.ARS.premium_p50_buy ┆ — │
│ market.ARS.premium_p50_sell ┆ — │
│ market.ARS.premium_spread ┆ — │
│ market.ARS.market_price_share ┆ 50.0% │
│ market.ARS.range_share ┆ 50.0% │
│ market.ARS.range_width_avg ┆ 66.7% │
│ market.ARS.range_width_fiat_avg ┆ 50000.00 ARS │
│ market.ARS.method_top3_by_orders ┆ CBU 2, CVU 2, Belo 1 │
│ market.ARS.method_top3_by_volume ┆ — │
│ market.ARS.new_methods ┆ Belo, CBU, CVU, Lemon, MODO, Mercado Pago │
│ market.ARS.time_to_fill_samples ┆ 0 │
│ market.ARS.time_to_fill_p50 ┆ — │
│ market.ARS.time_to_fill_p90 ┆ — │
│ market.ARS.book_size ┆ 1 │
│ market.ARS.instances ┆ 1 │
│ market.ARS.instances_top3_by_orders ┆ Mostro (6320ee5e) 2 │
│ market.ARS.instances_top3_by_volume ┆ — │
└─────────────────────────────────────┴───────────────────────────────────────────┘Everything the reports know about one currency, in one place: which way its
book leans and at what premium, how it is priced, which payment methods it
is offered over, how long an order takes to find a taker, and which
instances trade it at all. The figures are the ones stats market and
stats timing report, each over the cohort its own family uses, so nothing
here can drift from where it is quoted from: the structure rows count the
orders standing in the currency — a currency is what an order's latest
version says it is — and the timing rows count the orders that entered the
book in it, because a time-to-fill is measured from the book entry and an
order amended from ARS to USD waited in ARS. The two differ only for an
order amended into another currency. Ranking currencies inside a single
currency would say nothing, so those rows are absent.
$ bestiario compare --network regtest --from 2026-08-23 --until 2026-08-27
2026-08-23T00:00:00+00:00 — 2026-08-27T00:00:00+00:00
┌───────────────────────────┬───────────┬─────────────┬─────────────────┬─────┬───────────────┬──────────────┬─────────┐
│ instance ┆ completed ┆ volume_sats ┆ completion_rate ┆ fee ┆ dev_fees_sats ┆ dispute_rate ┆ version │
╞═══════════════════════════╪═══════════╪═════════════╪═════════════════╪═════╪═══════════════╪══════════════╪═════════╡
│ Fostro testing (8c6a4452) ┆ 1 ┆ 1361 sats ┆ 100.0% ┆ — ┆ 0 sats ┆ — ┆ — │
└───────────────────────────┴───────────┴─────────────┴─────────────────┴─────┴───────────────┴──────────────┴─────────┘One row per instance: completed orders, sats volume, completion rate, fee,
dev fees sent, dispute rate, version. Under --network only the instances
that traded on that network are compared — here one — and the dispute rate
is —, since disputes cannot be narrowed to a network.
$ bestiario orders aac4b221-bcd0-47e2-bea8-b0251fc5bb89
2026-08-26T10:39:05+00:00 — 2026-08-26T10:39:06+00:00
┌────────────────────┬──────────────────────────────────────┐
│ metric ┆ value │
╞════════════════════╪══════════════════════════════════════╡
│ order.id ┆ aac4b221-bcd0-47e2-bea8-b0251fc5bb89 │
│ order.versions ┆ 1 │
│ order.1.at ┆ 2026-08-26T10:39:05+00:00 │
│ order.1.status ┆ in-progress │
│ order.1.kind ┆ buy │
│ order.1.amount ┆ 101446 sats │
│ order.1.fiat ┆ 75000.00 ARS │
│ order.1.premium ┆ 0.0% │
│ order.1.expires_at ┆ 2026-08-26T23:09:21+00:00 │
└────────────────────┴──────────────────────────────────────┘Every version the instance published, oldest first, then every dev fee that names the order. This is the one report that shows events rather than counts.
$ bestiario summary --json --from 2026-08-23 --until 2026-08-27
{
"generated_at": "2026-08-27T03:06:40+00:00",
"range": {
"from": "2026-08-23T00:00:00+00:00",
"until": "2026-08-27T00:00:00+00:00"
},
"metrics": [
{
"name": "summary.created",
"kind": "observed",
"unit": "count",
"value": 8
},
{
"name": "summary.completed",
"kind": "observed",
"unit": "count",
"value": 1
},
{
"name": "summary.completion_rate",
"kind": "observed",
"unit": "ratio",
"value": 0.5
},
{
"name": "summary.volume_sats",
"kind": "observed",
"unit": "sats",
"value": 1361
},
{
"name": "summary.active_instances",
"kind": "observed",
"unit": "count",
"value": 4
},
{
"name": "summary.top_fiat",
"kind": "observed",
"unit": "text",
"value": "ARS (2), BRL (2), EUR (2)"
},
{
"name": "summary.top_methods",
"kind": "observed",
"unit": "text",
"value": "CBU (2), CVU (2), BBVA Efectivo Móvil (1)"
},
{
"name": "summary.open_disputes",
"kind": "observed",
"unit": "count",
"value": 1
}
]
}The envelope is the same for every report: generated_at, range, and
metrics, one flat record per figure with its name, its kind
(observed or inferred), its unit and its value — null for a
figure with nothing to report. Names are dotted paths, with the slice as a
segment (orders.ARS.created), so a consumer can split on the dot.
$ bestiario rebuild
rebuild: 21 events replayed (0 unreadable), 8 orders and 5 disputes projectedEvery table except the raw event archive is derived from it. rebuild
recomputes them; rebuild --from-raw replays the archive from scratch.
Neither talks to a relay.
The figures are worth computing because somebody reads them, and this is how
they leave the machine that computed them: as signed Nostr events, so a
reader trusts a pubkey rather than a host. The format is specified in full in
docs/NOSTR-PUBLICATION.md — addressable events
of kind 30666, one document per report and per series partition, one
orders document per instance, and an index document naming what exists,
what changed and what is current.
If you are writing the client rather than the publisher,
docs/NOSTR-CLIENT.md is the catalogue: every
address that exists, every metric inside it with its unit and meaning, the
rules a conformant client follows, and worked examples — including how to
render each instance's orders broken down by currency.
Where to publish, and how large a document may be, are configured separately from the relays the indexer reads:
[publish]
# Defaults to [nostr].relays. Kept apart on purpose: reading a relay and
# writing to it are different trust decisions.
relays = ["wss://relay.mostro.network"]
# The publisher's own ceiling on a document. A relay that advertises a
# smaller limitation.max_content_length in its NIP-11 document lowers it;
# none raises it.
max_content_bytes = 65536
# Where the signing key lives: the NAME of an environment variable, never
# the key itself. `nsec = "nsec1…"` is refused.
nsec = "env:BESTIARIO_PUBLISH_NSEC"export BESTIARIO_PUBLISH_NSEC=nsec1…
bestiario publishThe key is never written into this file and never passed as a flag. A flag
is readable in ps by every user on the machine and lands in the shell
history of whoever typed it; a configuration file is copied between
machines, committed, and pasted into issues. So settings.toml holds the
name of the variable, and a literal key in that field is a configuration
error rather than a setup that works and quietly leaks — the type the field
parses into cannot hold a secret at all.
The variable is read only by a run that is going to sign. bestiario stats orders on a machine that publishes nothing neither needs the key nor fails
without it, and neither does publish --dry-run, whose whole purpose is to
review a snapshot without a key being involved. A run that will publish
resolves it before reading a single row, so an unexported variable fails in
the first second and says which variable to export.
The pubkey that key belongs to is the whole of what a reader trusts. A client verifies a signature, not a hostname, so moving the daemon to another machine changes nothing anybody has to be told — and losing the key is the one thing that cannot be undone, because a new one publishes a different bestiario.
publish --dry-run computes the whole snapshot from one reading of the
archive and prints it — every document, the bytes it would carry and the
hash of its figures — without writing or signing anything:
$ bestiario publish --dry-run
snapshot 20260827T030640Z generated at 2026-08-27T03:06:40+00:00
archive 2026-08-26T05:56:56+00:00 to 2026-08-26T10:39:33+00:00
ceiling 65536 bytes ([publish].max_content_bytes), 1 relay(s) asked
summary:24h 879 ad3958ae1baa7f16…
summary:7d 879 177dc358f14087ba…
summary:30d 879 76cf8677efd78923…
summary:90d 879 c3440188430c6a09…
summary:all 879 c20db9b53d9cc8f5…
orders:24h 3378 d0127167035c32ee…
orders:7d 3378 c6d029a781d24f2b…
orders:30d 3378 213a84869830ac38…
orders:90d 3378 ba9fbbf3163494b4…
orders:all 3378 404f8cac1cac9f60…
series:orders:daily:2026-08 1786 d1f43f5adda5f389…
series:orders:weekly:2026-08 737 d3e9fddf33c6755f…
series:orders:monthly:2026 992 89f38aca2c281f54…
volume:24h 2406 54c684fb3130ea96…
volume:7d 2406 f786a9f3d4aff119…
volume:30d 2406 1f040cc37515dd5f…
volume:90d 2406 01ebd787eadaad25…
volume:all 2406 666fd3085d067a01…
series:volume:daily:2026-08 6076 381a43910ec4de79…
series:volume:weekly:2026-08 2557 f89ec535ae70a211…
series:volume:monthly:2026 3477 ba53ff8913c5556f…
market:24h 2096 1070c45b3b441396…
market:7d 2096 9424ca34bece60d6…
market:30d 2096 b820d8dba13bf434…
market:90d 2096 9617eb9cb4e6efd1…
market:all 2096 523d89ee5498d5db…
disputes:24h 1862 72783941379ee595…
disputes:7d 1893 125ecf7a8d6476fb…
disputes:30d 1893 66ee8ef140b193b1…
disputes:90d 1893 2bd127d29fc824e0…
disputes:all 1881 564bf43cc1502948…
series:disputes:daily:2026-08 4386 d5e50de14205386b…
series:disputes:weekly:2026-08 1780 0c37f4429b6dca87…
series:disputes:monthly:2026 2484 4d9c46f1302bf3b0…
dev-fees:24h 1088 f80e0c51ec30a0a4…
dev-fees:7d 1088 707f2487088cda84…
dev-fees:30d 1088 4fd471b4034b0410…
dev-fees:90d 1088 54fcc515b8caa011…
dev-fees:all 1051 c7260c97a12e3f98…
series:dev-fees:daily:2026-08 2944 dcb5f44a0170c293…
series:dev-fees:weekly:2026-08 1245 853bffa25ad87daf…
series:dev-fees:monthly:2026 1675 a35138e16cb36269…
instances:24h 22959 54a897458a3eaf22…
instances:7d 22959 28bb6894136b3d5b…
instances:30d 22959 e349a68af965d3e3…
instances:90d 22959 d8fdd1ee6fe42a37…
instances:all 22959 ed95a4d81ba418a9…
compare:24h 10028 3b2a7d72ba021955…
compare:7d 10028 3585cda31273fbc2…
compare:30d 10028 81d88ac8fab57fb5…
compare:90d 10028 507e5498465a522e…
compare:all 10026 347f5da2adea40a6…
orders:24h:i:807fdded0e6c21acbd19103e6ddc503bbef45078feaaa6c749fae7e7c00ef88f 898 add27590945b07b2…
orders:7d:i:807fdded0e6c21acbd19103e6ddc503bbef45078feaaa6c749fae7e7c00ef88f 898 c93461dcbabf4bae…
orders:30d:i:807fdded0e6c21acbd19103e6ddc503bbef45078feaaa6c749fae7e7c00ef88f 898 a11481cb24add1c7…
orders:90d:i:807fdded0e6c21acbd19103e6ddc503bbef45078feaaa6c749fae7e7c00ef88f 898 544796a5e148b338…
orders:all:i:807fdded0e6c21acbd19103e6ddc503bbef45078feaaa6c749fae7e7c00ef88f 898 7e8c8943a236dde7…
orders:24h:i:b9899686ebd14f88023e382ed75c20c47509122cadcd4d42272087809b07ef0c 898 add27590945b07b2…
orders:7d:i:b9899686ebd14f88023e382ed75c20c47509122cadcd4d42272087809b07ef0c 898 c93461dcbabf4bae…
orders:30d:i:b9899686ebd14f88023e382ed75c20c47509122cadcd4d42272087809b07ef0c 898 a11481cb24add1c7…
orders:90d:i:b9899686ebd14f88023e382ed75c20c47509122cadcd4d42272087809b07ef0c 898 544796a5e148b338…
orders:all:i:b9899686ebd14f88023e382ed75c20c47509122cadcd4d42272087809b07ef0c 898 7e8c8943a236dde7…
orders:24h:i:6320ee5edbaeb9a00d7c4768e472e277539aa993007c43d75ce00a38dff4d425 3046 a61a0d7410afa4f5…
orders:7d:i:6320ee5edbaeb9a00d7c4768e472e277539aa993007c43d75ce00a38dff4d425 3046 a16a9748efc6f162…
orders:30d:i:6320ee5edbaeb9a00d7c4768e472e277539aa993007c43d75ce00a38dff4d425 3046 9a13d93b59c9c90a…
orders:90d:i:6320ee5edbaeb9a00d7c4768e472e277539aa993007c43d75ce00a38dff4d425 3046 74384b89f6d6501f…
orders:all:i:6320ee5edbaeb9a00d7c4768e472e277539aa993007c43d75ce00a38dff4d425 3046 5c7eaf596d44d39a…
orders:24h:i:2be7ca274d2df0abc141bc3e8472b953bb54090aae5c24a74de69b45f57e89a4 898 add27590945b07b2…
orders:7d:i:2be7ca274d2df0abc141bc3e8472b953bb54090aae5c24a74de69b45f57e89a4 898 c93461dcbabf4bae…
orders:30d:i:2be7ca274d2df0abc141bc3e8472b953bb54090aae5c24a74de69b45f57e89a4 898 a11481cb24add1c7…
orders:90d:i:2be7ca274d2df0abc141bc3e8472b953bb54090aae5c24a74de69b45f57e89a4 898 544796a5e148b338…
orders:all:i:2be7ca274d2df0abc141bc3e8472b953bb54090aae5c24a74de69b45f57e89a4 898 7e8c8943a236dde7…
orders:24h:i:d49048f3d6c88dc5d74d7749644fd2527eaefac7b3c6eab4a2c6b38c77792d3e 898 add27590945b07b2…
orders:7d:i:d49048f3d6c88dc5d74d7749644fd2527eaefac7b3c6eab4a2c6b38c77792d3e 898 c93461dcbabf4bae…
orders:30d:i:d49048f3d6c88dc5d74d7749644fd2527eaefac7b3c6eab4a2c6b38c77792d3e 898 a11481cb24add1c7…
orders:90d:i:d49048f3d6c88dc5d74d7749644fd2527eaefac7b3c6eab4a2c6b38c77792d3e 898 544796a5e148b338…
orders:all:i:d49048f3d6c88dc5d74d7749644fd2527eaefac7b3c6eab4a2c6b38c77792d3e 898 7e8c8943a236dde7…
orders:24h:i:8c6a44526180955a7efe7211f254a56ed60c81bf2880b901f4b8e0218a954250 1606 de8d93b617d6a5c1…
orders:7d:i:8c6a44526180955a7efe7211f254a56ed60c81bf2880b901f4b8e0218a954250 1606 29f8c691cae8e9c0…
orders:30d:i:8c6a44526180955a7efe7211f254a56ed60c81bf2880b901f4b8e0218a954250 1606 b516fa89ed1ba97a…
orders:90d:i:8c6a44526180955a7efe7211f254a56ed60c81bf2880b901f4b8e0218a954250 1606 4d604bcc4ed0a426…
orders:all:i:8c6a44526180955a7efe7211f254a56ed60c81bf2880b901f4b8e0218a954250 1606 34a4fea51d400d6e…
orders:24h:i:38f26971886ded77cb56e66f09b7cffdbad36a057afcd902a9aca3e926b3404b 1612 e323fc864c501bad…
orders:7d:i:38f26971886ded77cb56e66f09b7cffdbad36a057afcd902a9aca3e926b3404b 1612 3e1a7e4ddebc2686…
orders:30d:i:38f26971886ded77cb56e66f09b7cffdbad36a057afcd902a9aca3e926b3404b 1612 445e7f8017054caf…
orders:90d:i:38f26971886ded77cb56e66f09b7cffdbad36a057afcd902a9aca3e926b3404b 1612 54a34f63d83e77e2…
orders:all:i:38f26971886ded77cb56e66f09b7cffdbad36a057afcd902a9aca3e926b3404b 1612 a466af0f100b51b9…
orders:24h:i:ec3c3e00a04aa9e0c040fcef2dc7767d66c6c93d5dd2b39ba937b820ddf23610 1606 9056667bb80adb75…
orders:7d:i:ec3c3e00a04aa9e0c040fcef2dc7767d66c6c93d5dd2b39ba937b820ddf23610 1606 866adcf9848f882c…
orders:30d:i:ec3c3e00a04aa9e0c040fcef2dc7767d66c6c93d5dd2b39ba937b820ddf23610 1606 8ae984280559f9e9…
orders:90d:i:ec3c3e00a04aa9e0c040fcef2dc7767d66c6c93d5dd2b39ba937b820ddf23610 1606 da80705befd1a123…
orders:all:i:ec3c3e00a04aa9e0c040fcef2dc7767d66c6c93d5dd2b39ba937b820ddf23610 1606 e670617be5bbc21d…
orders:24h:i:72947bb3c55ad11d48ec65af98394a312b563dad0d49768833965d625088e402 898 add27590945b07b2…
orders:7d:i:72947bb3c55ad11d48ec65af98394a312b563dad0d49768833965d625088e402 898 c93461dcbabf4bae…
orders:30d:i:72947bb3c55ad11d48ec65af98394a312b563dad0d49768833965d625088e402 898 a11481cb24add1c7…
orders:90d:i:72947bb3c55ad11d48ec65af98394a312b563dad0d49768833965d625088e402 898 544796a5e148b338…
orders:all:i:72947bb3c55ad11d48ec65af98394a312b563dad0d49768833965d625088e402 898 7e8c8943a236dde7…
orders:24h:i:31899277a5c6f0567f0c64faa3acb24d306ad6f7ad006ab06ff159eceb9f0cac 898 add27590945b07b2…
orders:7d:i:31899277a5c6f0567f0c64faa3acb24d306ad6f7ad006ab06ff159eceb9f0cac 898 c93461dcbabf4bae…
orders:30d:i:31899277a5c6f0567f0c64faa3acb24d306ad6f7ad006ab06ff159eceb9f0cac 898 a11481cb24add1c7…
orders:90d:i:31899277a5c6f0567f0c64faa3acb24d306ad6f7ad006ab06ff159eceb9f0cac 898 544796a5e148b338…
orders:all:i:31899277a5c6f0567f0c64faa3acb24d306ad6f7ad006ab06ff159eceb9f0cac 898 7e8c8943a236dde7…
orders:24h:i:64ff477adab60bd22444c584439470fffa626df882a012d66aa34d1efda51f14 898 add27590945b07b2…
orders:7d:i:64ff477adab60bd22444c584439470fffa626df882a012d66aa34d1efda51f14 898 c93461dcbabf4bae…
orders:30d:i:64ff477adab60bd22444c584439470fffa626df882a012d66aa34d1efda51f14 898 a11481cb24add1c7…
orders:90d:i:64ff477adab60bd22444c584439470fffa626df882a012d66aa34d1efda51f14 898 544796a5e148b338…
orders:all:i:64ff477adab60bd22444c584439470fffa626df882a012d66aa34d1efda51f14 898 7e8c8943a236dde7…
orders:24h:i:765b0beaaeaa6e3fdb983c4c518ec5a2e35dcefad01d41326b82fd1b96c9abe6 898 add27590945b07b2…
orders:7d:i:765b0beaaeaa6e3fdb983c4c518ec5a2e35dcefad01d41326b82fd1b96c9abe6 898 c93461dcbabf4bae…
orders:30d:i:765b0beaaeaa6e3fdb983c4c518ec5a2e35dcefad01d41326b82fd1b96c9abe6 898 a11481cb24add1c7…
orders:90d:i:765b0beaaeaa6e3fdb983c4c518ec5a2e35dcefad01d41326b82fd1b96c9abe6 898 544796a5e148b338…
orders:all:i:765b0beaaeaa6e3fdb983c4c518ec5a2e35dcefad01d41326b82fd1b96c9abe6 898 7e8c8943a236dde7…
index 21136 —
113 documents, 350098 bytesThe first three lines are what a review is for. snapshot is the run's
identity, carried by every document as the s tag of §7. archive is the
extent the figures rest on, and the reason a client must not read a period
outside it as zero: a relay keeps orders for about a fortnight, so a chart
reaching back further would draw a flat line at zero across a period the
network was trading. ceiling is the limit every document was weighed
against — the configured one, or a smaller one a relay advertises — and a
document over it is an error naming the document rather than a rejection
discovered halfway through publishing.
The hash is over the document's payload alone, never over the envelope
around it: snapshot_id and the clock change on every run, so a hash over
them would make every unchanged document look new. That is what lets a
client cache what it already has, and what makes the index's answer to
"what changed" worth reading.
The index itself carries a dash where the others carry a digest. It is the one document with no envelope and no hash — it is what the hashes are in, and it is republished on every run by definition. Its size still counts against the ceiling, which is why §5.1 shards it by year once it grows close to one.
--out <dir> writes the same documents as <d>.json files — the static
snapshot a site can serve before its relay connection is live:
bestiario publish --out ./snapshotWith a key configured, publish on its own signs every document and sends
it to [publish].relays:
bestiario publishThe index goes last, and that ordering is the whole of §7. An index names every document with the hash of the payload that belongs to it, so an index on a relay is a promise that the documents it names are already there. A document no relay accepted breaks that promise, so the run stops before the index and says which document was missing — a snapshot that is half on the relay is recoverable by running again, while an index that points at documents nobody holds sends every reader to fetch nothing until the next run.
A relay that refuses a document is reported and not fatal. Publication goes to several relays for the same reason indexing reads from several: a snapshot that reached four of five relays is a snapshot people can read, and aborting on the fifth would throw away the four. Only a document that reached none of them stops the run.
--dry-run signs nothing even when a key is configured — it is the
invocation an operator reaches for precisely when they do not yet trust
what the next one would send. A run with no key, no --dry-run and no
--out is refused rather than quietly doing nothing: it is the invocation
of somebody who believes they have configured a publisher and has not.
A document whose figures did not move is not re-signed and not sent. Every
document carries a revision that starts at 1 and increments only when its
payload changes; a new run is not a new revision, which is what makes
the hash worth caching against. A run over an archive that has not moved
re-sends no document at all — only the index, which is the stated exception:
nothing hashes it, naming the current snapshot is its whole job, and it goes
out every run.
Unchanged documents stay in the index, with the hash, revision and
updated_at they already had. "Unchanged" is one of the things the index
exists to say: dropping one would read as "no longer published".
A revision above the first says when it was restated and why, in one of
four words — backfill, rebuild, schema, correction — so a client
that had cached the figure can say the number changed rather than
silently swapping it. The reason is read off the archive rather than off a
flag: publish is not told whether a backfill or a rebuild ran before it,
but the archive records what it published under and what it held, so a
schema bump, an archive that reaches further back or holds more events, and
a run over the same events are three states it can tell apart. correction
is never inferred — nothing in the archive distinguishes it from a rebuild.
That history lives in the archive, in published_documents and
publication_runs, for the same reason everything else does: reading the
last index back off a relay would work until the day a relay pruned it, and
then every revision would silently reset to 1.
bestiario publish --republish
bestiario publish --republish --from 2026-01-01 --until 2026-06-30--republish regenerates and sends every document from the archive alone,
whatever any relay holds. It is the recovery path for a pruned relay, a new
relay or a schema migration, and it is what makes "the relay is not the
archive" true rather than aspirational.
It overrides the skip above, which would otherwise defeat it: the documents
a pruned relay is missing are overwhelmingly the ones whose figures have
not changed in months, so a run honouring the skip would send it nothing.
With --from / --until it recovers the series partitions that range
touches — plus whatever an ordinary run would have sent anyway, because an
index naming a changed document that was withheld would point every reader
at something no relay holds.
Everything is signed afresh rather than replayed from stored events. A cache of signed events would be state that can disagree with the archive it came from, and re-signing an unchanged payload is not a restatement: no revision moves, and no client is told a figure changed when it did not.
cargo test --workspace # unit, integration and the end-to-end suite
cargo clippy --workspace --all-targets -- -D warnings
./scripts/coverage.sh # the two coverage gates of SPEC §12scripts/coverage.sh measures the workspace once and applies both gates of
docs/SPEC.md §12: 95% of lines overall, and every line of crates/stats
and src/ingest/parse executed. Those two layers are plain functions over
plain data, so a line no test reaches there is a case nobody thought about;
the rest is I/O failure handling, where the test costs more than the line is
worth. --open shows the annotated report, --clean discards profiles from
an earlier build.
docs/RELEASE.md is the release procedure: cargo release <level> --execute
bumps the version — or cargo release --execute, which ships the version the
manifest already carries — writes the CHANGELOG.md section from the commit
log and pushes a vX.Y.Z tag, and the tag makes GitHub Actions build the Linux
x86_64 binary and publish the release with those notes.
docs/SPEC.md is the source of truth for event formats, the data model,
the metrics and the CLI; docs/ROADMAP.md is the plan, one row per pull
request. docs/NOSTR-PUBLICATION.md specifies one planned feature in full —
publishing the figures as signed Nostr events, so a reader trusts a pubkey
rather than a host — and is scheduled as phase 6 of the roadmap;
docs/NOSTR-CLIENT.md is the catalogue of what that publishes, for whoever
consumes it. The
aggregation layer is a separate crate, crates/stats, with no I/O
dependencies — a compile error, not a convention — so that the same figures
can be signed onto a relay without touching them.
