Three kinds of citation, for three different problems: the bytes of a
dataset, one value inside a transaction, and a number computed over a query.
Citing a series
“Cite this data” on a chart page canonicalises the series: fixed orientation,
no overlays, one period, one range. It writes the series to CSV and hashes
those exact bytes with SHA-256.
You get a hash and a public URL at /citations/<hash>. Anyone, signed in or
not, can resolve it. If the underlying data changes later, the same request
produces a different hash: the old citation still describes what you used.
Put the hash in the paper. It is shorter than a URL and it is checkable.
Citing any dataset query
The same works for every dataset in Data Downloads:
liquidations, health factors, absorptions, vaults, price bars, the event
registry, and a bounded slice of the raw log table. Build the query as you
would for an export (the protocols, the dates or blocks, the columns), and on
the request’s page choose Cite this query. The export does not have to
run: the citation is of the query, not of a file.
What gets hashed is the canonical CSV of that query, and canonical means the
same bytes on any two days the data has not changed:
- the columns you chose, in the catalogue’s order, whatever order you ticked
them in; - the rows in the dataset’s natural-key order (block and log index for a log
table, pool and hour for bars, date and id for the registry), never the
order the warehouse happened to return; - one spelling per number (no exponents, no locale), the empty field for a
null, LF line endings, UTF-8, and nothing that changes between runs (no
timestamp, no header comment); - the block range the rows covered, pinned into the record. “Every
liquidation since March” would grow as the chain grows and could never be
checked again, so the citation stores the first and last block it saw and
re-derives inside them. Datasets without a block column pin the last date
they reached instead.
The record shows the spec in words (dataset, filters, block range, columns,
sort order), so anyone with an export of the same rows can rebuild the file
and compare hashes. Subscribers can also download the cited bytes from the
record itself; the download is served only while the bytes still hash to the
citation.
Naming your organization
When you cite, you can tick Name my organization as a creator. The record
then lists your organization beside the platform in every format below. A
citation never names a person; it names the platform and, if you chose it,
your institution or team.
Versions: dataset releases
On the first of each month the platform cuts a release of every dataset:
its block range (or last date), its row count, and the SHA-256 of the full
canonical export. Releases are labelled YYYY.MM and listed on the
Data Downloads page and on each dataset’s page.
A citation whose block range falls inside a release names that version
(2026.09); one that does not yet is marked unreleased. The version is what
a library or a reference manager expects to see, and it is what lets two
papers say whether they used the same edition of a dataset. Citing the whole
dataset over a release’s block range, with every column, reproduces the
release’s own hash.
What the record gives a library
The landing page at /citations/<hash> carries a schema.org Dataset
record in its head (name, description, identifier, creators, dates, version,
distribution), so search engines and data catalogues can index a cited hash.
The same record is available as:
/citations/<hash>.json: DataCite-shaped metadata (creators, titles,
publisher, publication year, resource type, version, dates, identifiers);/citations/<hash>.bib: a BibTeX entry, with the full hash in its note;/citations/<hash>.cff: a Citation File Format file, theCITATION.cff
convention software repositories use.
No DOI is minted. The hash and the URL are the identifiers, and the DataCite
record carries every field a registration would need, so a DOI can be added
later without changing what a paper cited. Whether to join DataCite is an
open decision for the platform’s owner.
Checked nightly, never rewritten
Every dataset citation is re-derived each night from its stored spec and its
hash compared. If the bytes still match, the record says when it was last
checked. If they no longer match (a backfill, a corrected token decimal, a
repaired reorg), the record is flagged in place with the new digest beside the
cited one. The cited hash is never changed: a dataset that moved is itself a
finding, and a paper’s footnote has to keep resolving to what the paper used.
A warehouse that cannot answer marks the record “unresolved”, never “wrong”.
Citing one value
A sentence like “wallet X repaid Y USDC” doesn’t want a link to a whole
transaction. On any transaction page, Cite a value lists every decoded field
of that transaction’s logs. Citing one gives you a {{cite:N}} token to paste
into any research note.
In the note it renders as the value itself, with the source transaction, log
index and field on hover.
Why it stays honest
A citation stores where the value came from and how it was decoded, not a
URL. Every night we go back to the warehouse, decode the source log again, and
compare:
- unchanged → marked verified, with the date;
- changed → flagged in place, showing both figures. We do not rewrite the
cited value, because a value that moved is itself a finding: a decoding fix, a
corrected token decimal, a reorg repair; - unreadable → marked unresolved, never silently re-confirmed.
Citing a number no transaction contains
A point citation names one field of one log. But most claims in a paper are
aggregates — “wallet X transferred Y in total over the window”, “there were N
liquidations above $1m” — and no single transaction holds that number.
A derived citation cites the query instead. It stores the dataset, the
filters, the aggregate and the answer, hashes all of it, and resolves publicly
like any other citation.
Paste {{derived:N}} into a block and the figure renders with its provenance,
beside {{cite:N}} for point citations.
It uses the same query as an export
The dataset and filters are exactly what Data Downloads uses. That is
deliberate: a derived citation and a CSV of the underlying rows describe the
same query in the same words, so a reader can pull the rows the number came
from rather than taking it on trust.
It is re-derived nightly, and never rewritten
The nightly verifier re-runs the query. If the answer has moved — a backfill,
a decoding fix, a repaired reorg — the citation is flagged in place with
both figures. The cited value is never silently updated, because a number
that changed is itself a finding.
An unreachable warehouse marks the citation “unresolved” rather than “wrong”.
Assistants cite rather than assert
The CiteQuery tool computes an aggregate and hands back a token to paste.
Any specific on-chain number in a written-up note should be a citation and
never a bare literal: a literal cannot be checked by anyone, and a citation
carries its own query and its own hash.