How the Oracle Works

Observing many signals. Resolving one truth.

This page explains how DNO makes its assessments, what data it uses, and what it can and cannot know. Everything described here is what the Oracle actually does — not aspirational, not approximate.

What the Oracle Is

The Demos Network Oracle (DNO) is a public observability layer for the Demos blockchain testnet. It watches the network's public validator nodes, measures whether they agree on the state of the chain, tracks specific problems, and publishes what it finds.

The Oracle is strictly watch-only. It observes, interprets, and summarizes. It does not command validators, does not advise operators, and does not make predictions about what will happen next. It publishes network state as neutral facts. What anyone does with those facts is their decision.

The Oracle is independent. It is not operated by the Demos core team. It does not control any downstream system. Any agent, builder, or person can consume its output and form their own conclusions.

What It Measures

Every Oracle assessment is built from seven independent concepts. Each answers exactly one question about the network. No two concepts overlap — if you can express something by combining two other concepts, it is not given its own field.

Status

Status describes current network operability — whether the chain is functioning right now. It is not a direct measure of network size or validator count.

stable — The network is operating normally. Public nodes are online, synced, and in agreement. No active incidents at warning or critical severity. At current network size, one offline node with strong agreement is still considered stable — this is normal testnet behavior, not impairment.

degraded — The network is working but impaired. Multiple nodes may be offline, agreement may be weakened, or warning-level incidents are active.

unstable — Serious impairment. Critical incidents are active, agreement is weak, or a majority of public nodes are unreachable.

unknown — The Oracle cannot determine the network's condition. This happens when fewer than two public nodes are reachable or when observation data is stale. This is not a health judgment — it is an explicit statement that the Oracle does not have enough information.

Trend

Trend tells you whether the situation is getting better, holding steady, or getting worse, based on comparing the current observation against recent history. It is purely backward-looking — it describes what has changed, never what will change.

Trend requires a minimum number of consecutive successful observations before it reports anything other than unknown. After a restart or data gap, trend resets to unknown until enough history accumulates.

Risk

Risk describes how dangerous the current observed state is. It is a snapshot — it characterizes the present moment, not a forecast.

low — No significant exposure. elevated — Caution warranted. This does not mean danger is confirmed — it means conditions are not fully clear or not fully healthy. high — The network is materially impaired.

When status is unknown, risk defaults to elevated. The Oracle treats the absence of information as a reason for caution — but not alarm. On a testnet where unknown is a normal occurrence, defaulting to high would desensitize consumers.

Data quality

Data quality measures whether the Oracle can see the network properly. It answers: did enough public nodes respond, recently enough, to form a credible assessment?

sufficient — At least two public nodes responded within the current cycle and data is fresh. insufficient — Too few nodes responded or data is stale beyond acceptable bounds. When data quality is insufficient, status is set to unknown.

Confidence

Confidence measures whether the observed signals agree with each other. The Oracle may have full visibility (data quality is sufficient) but see contradictory information — nodes reporting divergent block heights, mixed health signals. That is a confidence problem.

clear — Signals are consistent and unambiguous. uncertain — Signals conflict or are ambiguous. Status and risk are still published, but should be consumed with caution.

Agreement

Agreement measures whether the public validators are producing a coherent, shared chain. It is computed only from reachable public nodes with valid block observations. Offline or unreachable discovered nodes do not count as disagreement, because they cannot currently participate in observed consensus. Agreement is derived from block heights of reachable nodes — specifically, how many are within 25 blocks of the median.

strong — All or nearly all observed public nodes are aligned. moderate — Most agree, but some divergence exists. weak — Significant divergence. unknown — Fewer than two public nodes are reachable.

The Oracle publishes the underlying data alongside the label: aligned node count, total node count, median block height, and block spread. At current network size, calculated percentages would be misleadingly precise, so the Oracle publishes counts instead.

Incidents

Incidents are discrete, named events — a specific node going offline, a chain stall, a detected partition. They have a severity (info, warning, critical) and a lifecycle (opened → active → resolved).

General conditions like "the network is slow" are not incidents — they are captured by status, risk, and agreement. Incidents point to specific, identifiable problems.

Severity is assessed relative to current network size. One node going offline in a set of five is more significant than in a set of fifty.

How It Works

The Oracle runs a continuous observation cycle. Every 20 seconds, it:

1. Polls each known public validator node — checks reachability, block height, sync status, and peer count.
2. Computes network agreement from the observed block heights.
3. Checks for active incidents — new problems, resolved problems.
4. Runs the canonical state computation — derives all seven concepts from the raw observations.
5. Updates all API endpoints with the new state.

Every 20 minutes, the Oracle publishes an attested summary on-chain via SuperColony.

The canonical state computation is a single function that takes public node observations as input and produces all seven values as output. Fleet data never enters this function. The computation is deterministic — given the same observations, it always produces the same assessment.

Public vs Reference Separation

This is the most important structural rule in the Oracle. It governs everything.

Public network (primary truth)

All top-level assessments — status, trend, risk, data quality, confidence, agreement — are derived exclusively from public network observations. Public nodes are validator nodes operated by independent parties: Kynesys (the protocol team) and manually approved community validators.

Reference fleet (internal context)

The Oracle operator (XM33) also runs a fleet of seven validator nodes. These provide internal context and infrastructure health monitoring. Fleet data is published separately for transparency — but it never influences the public assessment.

The fleet is a reference layer because it is operated by a single entity, may be on a different chain state than the public network, and its health does not represent public network health.

How separation is enforced

In the API: fleet data appears only under a namespaced reference key in /health. The compact agent feed (/organism) contains zero fleet fields. Fleet incidents are tagged with scope "fleet" and excluded from the public incident count. The /incidents endpoint defaults to public scope only.

In the dashboard: public data is presented first. Fleet data is in a collapsed "Reference Layer" section, clearly labeled.

Interpretation Model

The Oracle separates operability from resilience:

• Status describes whether the chain is functioning now.
• Risk describes how fragile that observed state is.
• Agreement measures alignment among currently reachable public nodes.
• Discovered but offline nodes reduce redundancy and coverage, but do not count as disagreement.

This prevents low public node reachability from being misread as immediate chain instability. A network can be stable with elevated risk — meaning: the chain works, but resilience is reduced.

Explanation Layer

The Oracle provides explanatory fields alongside its categorical assessments. These fields are intended to improve interpretability for human readers and machine consumers.

status_reason

Explains the primary observed basis for the current status. Example: Blocks advancing; reachable nodes aligned

risk_factors

Lists active observed contributors to current network fragility or reduced resilience. This array may be empty when no material risk factors are currently detected.

agreement_reason

Describes the current reachable-node alignment basis used in the agreement assessment. Example: 3 of 3 reachable nodes within ±25 blocks of median (spread: 0 blocks)

confidence_reason

Explains why confidence is clear or uncertain. Typical values: Observed public signals agree (clear), Insufficient reachable public nodes to cross-check (uncertain, single-node case), or Reachable public nodes report widely different block heights (uncertain, divergent signals).

These explanatory fields summarize current observed conditions. They do not constitute guarantees, certification, or operational advice.

Historical Metrics

The Oracle displays rolling historical metrics derived from its own observation cycles over the current history window.

uptime_7d — percentage of observed cycles in which the node was reachable.

avg_latency_7d — average response latency across successful observed cycles.

These historical metrics are observational summaries only. They do not constitute endorsement, certification, or recommendation of any validator or operator. Early values should be interpreted cautiously until sufficient history has accumulated. Historical metrics do not change the canonical truth model unless explicitly stated.

Scope and Limits

The Oracle is a watch-only observability system. It summarizes observed network conditions and historical measurements but does not provide financial, operational, legal, or governance advice.

Inclusion of a validator in Oracle outputs does not imply endorsement, approval, or certification.

Oracle outputs are based on externally observable signals available during each measurement cycle. Public endpoint availability, temporary network conditions, or incomplete visibility may affect results. Outputs should be interpreted as structured observed assessments, not guarantees of present or future validator behavior.

Understanding Uncertainty

The Oracle treats uncertainty as a first-class output. On a young testnet with small, evolving node coverage, partial visibility is a normal operating condition — not an error.

The Oracle starts from caution and earns stronger claims through sustained observation. It prefers honest uncertainty over artificial precision.

Three kinds of uncertainty

Insufficient data. The Oracle does not have enough information to form an assessment. Too few public nodes responded, or the Oracle just started and hasn't completed a full cycle yet. Effect: data quality → insufficient, status → unknown, risk → elevated.

Stale data. The Oracle has data, but it may be too old to reflect current reality. Observation failures, network timeouts, or process interruptions can cause staleness. The Oracle always publishes how many seconds ago it last observed the network (staleness_seconds) so consumers can apply their own freshness judgment.

Contradictory data. The Oracle has fresh, sufficient data, but the signals conflict — nodes report different block heights, mixed health signals. This is often the most informative kind of uncertainty, because it frequently signals a real network event. A related variant: when only one public node is reachable, confidence is also uncertain — not because signals conflict, but because there is no second source to cross-check against. Effect: confidence → uncertain, but data quality remains sufficient. The problem is in the network or in coverage, not in the Oracle's ability to observe.

The unknown contract

When the Oracle reports unknown, insufficient, or uncertain for any field:

1. The value is explicitly stated — never omitted, never null.
2. No guess, default, or cached value is substituted.
3. Consumers can rely on these states as stable, intentional signals — not bugs.

Known Limitations

DEMOS is a young testnet. The Oracle is designed for this reality and makes no claims beyond what it can observe.

Small public node set. The Oracle currently monitors five public nodes (two Kynesys, three community). Assessments use coarse-grained categories that match this resolution. As the network grows, finer granularity will be added without structural changes.

Discovered but unmonitored validators. The Oracle discovers new validators via peer list crawling. Some may be online but not yet added to formal monitoring. The Network Growth panel on the dashboard shows their sync progress. They are added to monitoring manually after reaching the network head.

Observable coverage only. The Oracle can only assess what it can reach. Nodes that are firewalled, on private networks, or not yet discovered are invisible. The Oracle is honest about this — unknown and insufficient are always explicitly stated.

No prediction. The Oracle describes what is, not what will be. Even trend is backward-looking. Predictive signals may be added as a separate, clearly labeled layer in the future — never merged into the core truth model.

How to Use the Data

For builders and operators

The dashboard at /dashboard provides a visual overview. The banner shows current status with risk and confidence context. The Network Agreement panel shows whether validators agree. The Network Growth panel tracks validator discovery and sync progress.

The /health endpoint provides full diagnostic data — canonical fields at the top level, derived data for detail, fleet data under reference, and deprecated fields under legacy.

For agents and automated consumers

The /organism endpoint is the primary agent feed. It returns 14 flat fields with no nested objects and no fleet data. Every field is always present and never null.

The simplest consumption pattern is the minimal triple: read status + risk + confidence. These three fields give you the complete network picture in three values. Your agent decides what to do with them — the Oracle never tells you.

For trust calibration: check data_quality before relying on the assessment. Check staleness_seconds to know how fresh the data is. If data quality is insufficient, treat all other values with skepticism.

For incident awareness: active_incidents gives the count, max_incident_severity tells you the worst active problem without needing to fetch the full incident list.