Registry

The registry is the trust root for membership. It lists which addresses are nodes and which addresses are clients, now and before. It is a canister on the Internet Computer. Nodes and consumers verify what the canister publishes. They never trust the view of the registry that a node gives them.

Mainnet values

The SDK and the node have these values built in, in oracle_client::mainnet:

The governance address is the address of the threshold key that signs every registry version and every client list. Pin it in your consumer. Never read it from the document that you fetch.

What the canister holds

An address appears in this state at most once, ever.

One key per node. The address of the secp256k1 key of a node is the node id. The registry and the SDK key all per-node state by address. There is no separate identity key and no operator field.

The published document

The canister publishes one entry for each listed node:

{
  "version": 7,
  "effective_from": 1754582400,
  "nodes": [
    {
      "address": "0x19e7...ff2a",
      "endpoints": ["wss://eu1.oracle.example/v2/ws"],
      "weight": 1
    }
  ],
  "quorum": { "min_nodes": 3, "recommended": 5 },
  "governance_signature": "0x..."
}

The document does not name who runs each node. Governance checks operator diversity when it decides whom to list.

The client list

Nodes serve prices only to listed clients. Governance lists each client in a second document, the client list. The same threshold key signs it. The canister serves it at /clients.json.

{
  "version": 12,
  "effective_from": 1754582400,
  "epoch_secs": 60,
  "clients": [{ "address": "0x7f3a...", "expires_at": 1757174400 }],
  "governance_signature": "0x..."
}

• The address of the client API key is the client id. It names no customer.
• A removed client address never comes back.
• Nodes fetch the list every 30 s by default and check its certificate.
• A node refuses new sessions when no certified fetch has confirmed the list for 3 hours. It closes every session after 24 hours.
• Consumers never download the client list. A client change does not change the registry version.

Rules the canister enforces

• An address is used once. add_node, replace_node and add_client refuse an address that is, or ever was, a node or a client. A client key never becomes a price-signing key.
• Never below quorum. The canister refuses a removal that would leave fewer listed nodes than quorum.min_nodes. A replacement keeps the count.
• Versions only on change. The canister signs a new version only when governance changes something. A failed signing round changes nothing, and governance retries the same call.

Governance

Governance is the controller set of the canister, and it is the only caller of every update method but push. The canister rejects every other caller. Nodes call one update method, push, as the anonymous identity, and two queries, get_feeds and get_price_window. See Prices.

A node operator sends the node entry, or the two addresses that oracle-node rotate prints, to governance off-chain. Governance makes the call.

Prices

The nodes push their latest updates to the canister, each push as one signed batch, and the canister serves the median of the nodes for each priced feed. On-chain prices shows how to read them.

The canister runs the Rust SDK's checks on each frame: a listed signer, a sequence that rises, and the clock. inspect_message runs the cheap checks first and lets a push in only when one frame is new and valid, so a replay or junk costs the canister nothing.

The quorum is the registry's recommended. Each push costs the canister cycles, mostly for its one signature check: about 21M for a batch of 10 updates, against 103M for 10 single frames. At the 30 s heartbeat that is about 1.9T cycles a month for each node.

The network feed set

Every node serves the same feeds, so that a quorum can form on each one. Governance publishes them as a third signed document, the feed set, and the canister serves it as the certified /feeds.json. It holds each feed with its sources, as in a node config, the oldest node version that can serve it, and an optional push pace for every node.

A node takes each new version while it runs, in its own slot: two minutes after the publish, then 90 s for each node before it, so that two nodes never change at once. The web proxy follows when the slots have passed. Governance publishes from the repo's feed files with scripts/publish-feeds.sh, which runs every check a node runs before the call.

How a consumer trusts the registry

A consumer needs two proofs. The signature proves that a document is genuine. The IC certificate proves that it is current. A consumer needs no Internet Computer agent.

The signature

The consumer pins the governance address. It accepts a document only when:

• the governance signature recovers to the pinned address;
• the version is strictly newer than the version it holds.

Thus a node cannot vouch for its own registry, and an old version cannot reinstate a revoked key.

The certificate and freshness

A signature does not prove that a document is current, because a cache or a relay can replay an old version. The SDK and the nodes therefore check the IC certificate on every fetch of /registry.json and /clients.json:

• The certificate must chain to the root key of the network. The mainnet root key is built in.
• The certificate time must be within 5 minutes of the local clock. A replayed response fails like an outage.
• Mainnet sources fetch from the raw domain, which passes the response of the canister through unchanged.

The canister publishes only when something changes, so the age of a document says nothing. Each fetch that verifies confirms the version that it carries. The SDK fetches the registry on a jittered schedule, at most registry_poll_interval (60 s by default) apart. If no fetch confirms the registry for max_registry_age (48 hours by default), every feed reports degraded with the concern registry_stale. The prices are still verified, but the membership can be out of date.

Other networks

HttpRegistrySource::canister(id) fetches from the mainnet raw domain and checks against the mainnet root key. For another network, such as a local network, pass Certification::new(id, root_key) to HttpRegistrySource::new.

How a rotation reaches the consumer

A rotation is the replace_node call of governance. In one registry version, the new address takes the place of the old one, at the same endpoint. There is no overlap window. The consumer learns about it from the first frame that it cannot verify, or from a handshake challenge that names the new address.

1. An unknown signer, or a WrongNode challenge, triggers one fetch from the registry source. The SDK fetches at most once per refresh_interval (10 s by default), so a hostile relay cannot turn the client into a load generator.
2. refresh_registry adopts the document in place if it is strictly newer and signed by the pinned governance address. There is no reconnect and no loss of feed state. Nodes that the new version de-lists leave the quorum at adoption.
3. The SDK retries the frame. The quorum seat moves to the new address in the same adoption that drops the old one, so the node never counts twice. The new address starts a fresh replay floor.
4. The old key is now retired, not unknown. The SDK refuses its frames as RetiredKey and does not fetch again. A steady stream of such frames means that someone uses a stolen key.

Until the first frame under the new key, the node is out of the quorum of that consumer, as during a restart. Governance staggers rotations so that a consumer never loses two seats at the same time.

replace_node and remove_node

The SDK refuses a new registry version that would leave fewer nodes than its quorum. It keeps the registry that it has and returns an error.

After subscribe, the connections of the SDK follow the registry. When the SDK adopts a newer version, it connects to added nodes, disconnects removed nodes, and reconnects a node whose endpoint or address changed.

Stored frames

The live path verifies a frame only against a listed address. A stored frame, for an audit or a dispute, uses a separate path. verify_historical checks the frame against the listing of its signer from get_node_listing:

added_at ≤ publish_time_ns < removed_at

Without removed_at, a stolen key would verify backdated frames forever. The canister states these times. No signature covers them.

Keys have no expiry. A node key rotates on suspicion of compromise, not on a schedule. A stolen key that nobody notices keeps working until governance replaces or removes the node. Watch for divergence between nodes.