Reading the numbers
Most mistakes people make with chain data come from one confusion: treating a figure that was not measured as a figure that was measured and came back zero. Core separates those on every screen. Learning the four states takes two minutes and it is the single most useful thing on this site.
The four states
Section titled “The four states”Loading never contains a figure. Ready and Empty are facts about the world. Unavailable and Degraded are facts about the read.
| State | What Core shows | What you may conclude |
|---|---|---|
| Loading | A placeholder shaped like the content that will replace it. Never a number. | Nothing yet. Wait. |
| Ready | Results, with the period each figure covers. | What is shown was measured. |
| Empty | An explicit sentence such as “no tokens found”, naming what was checked. | The reader answered and there is genuinely nothing. This is a fact about the market. |
| Unavailable | The market or panel named, a plain-language statement that the read failed, and a retry. | Nothing. The quantity is unknown. Do not read it as zero. |
| Degraded | Results plus a notice that only part of the picture loaded. | What you see is real and incomplete. A missing row is not evidence of absence. |
A dash is not a zero
Section titled “A dash is not a zero”A single figure that Core could not measure is shown as a dash. Floor prices, volumes, holder counts, listing counts, and any score derived from them all follow this rule.
- A dash means the figure was not read.
- A number means it was.
Core never fills a gap with a sample row, a last-known value with no age, or a figure written into the application. A market can legitimately show a name and a dash in every column, and that state is honest about what is known. Do not read a ranking into a table whose sorted column is entirely dashes.
Where the distinction is enforced
Section titled “Where the distinction is enforced”This is not a style guideline. It is implemented in the interface layer and tested.
- A data surface carries one of the five states above, and the empty state and the error state are different components with different text.
- A component that is handed a state it does not understand fails to the unavailable state rather than to an empty one. Failing closed means an outage cannot be silently rendered as “nothing here”.
- The one exception is deliberate: a read that succeeds and returns nothing is the empty state, always, even where a caller would have preferred a retry prompt.
The same rule at the API
Section titled “The same rule at the API”The public health contract applies the identical distinction to itself. In
/indexer-health, each protocol carries:
tipandnodeTip, so a lag of zero is distinguishable from two tips that were never read;lastSuccess, which isnullwhen there has never been a successful read;freshness.staleandfreshness.disagreeingas separate booleans, because an observation being old and two authorities disagreeing are different problems;statusand areasonCode, so an error names its cause.
A protocol reporting tip: 0 with lastSuccess: null has not been read. It is
not a chain at height zero.
What this costs you, and why it is worth it
Section titled “What this costs you, and why it is worth it”Sometimes a page will tell you it does not know something rather than showing a plausible number. That is the intended outcome. A plausible number you cannot distinguish from a measured one is worse than no number, because you will act on it.
- Where each number comes from, for which reader answered.
- Indexer freshness, for how far behind that reader was.
- Market and reader states, for what to do about each one.