Overview
Introduction
Markout Labs Oracle is a network of independent nodes that sign crypto prices. The consumer takes the median across several nodes.
Markout Labs Oracle publishes crypto prices as signed updates. A network of independent nodes produces them. Each node is a Rust process that one operator runs.
Each node does five things:
- It keeps WebSocket connections open to the venues (the exchanges it reads): Binance, Bybit, OKX, Coinbase, Kraken and Deribit.
- It converts the quotes of each venue into one common form.
- It computes one price and one confidence interval for each feed.
- It signs each update with its own secp256k1 key.
- It sends the signed updates to the clients that governance lists.
The nodes do not talk to each other. There is no consensus round and no leader. The consumer collects updates from several nodes and takes the median. The Rust SDK does this work for you.
The one thing to understand
A signature proves authorship, not truth. It tells you that node X stated this price at this time. It does not tell you that the price is correct. It does not even tell you that the node connected to a venue. The update contains num_sources, but nothing binds that number to what the node really did.
The defence against a node that lies or fails is not cryptographic. The defence is the median across N nodes with independent keys, plus monitoring of the divergence between nodes. One bad node cannot move the median. Its disagreement makes the confidence interval wider, so a consumer that acts on conf reacts correctly.
Important
If you verify the signatures of one node only, you know who sends the data. You know nothing about whether the data is correct. For this reason the SDK refuses a quorum below three nodes unless you explicitly accept the risk. See Trust model.
What you get
| Item | What it is |
|---|---|
| Price | The median across the nodes, for one feed such as CRYPTO.BTC/USD. |
conf |
A symmetric ± band around the price. It is the main signal of how much to trust the price. |
| Status | ok, degraded or halted. A halted price is not safe for settlement or liquidation. |
| Concerns | The reasons for a status that is not ok, for example insufficient_nodes or node_divergence. |
| Venue reports | Optional. What one node saw on each venue of a feed: best bid and ask, sizes, mark, index, funding, and how each venue counted. |
| Books | Optional. The top 50 levels of each venue book that a node keeps. |
Read Feeds and symbols for the feed names and the number format. Read Aggregation for how a node computes a price.
The components at a glance
| Component | Who runs it | What it does |
|---|---|---|
Node (oracle-node) |
A node operator | Reads the venues, computes and signs prices, and serves them on /v2/ws to listed clients only, encrypted. |
| Registry canister | Governance, on the Internet Computer | The trust root. It lists the node addresses and the client addresses, and it signs both lists. |
Rust SDK (oracle-client) |
The consumer | Connects to every listed node, verifies each frame, and resolves one price from the quorum. |
Web proxy (oracle-proxy) |
An operator for web apps | Runs the SDK as one listed client and serves the result as plain JSON on /v1/ws. |
Architecture shows how these parts connect.
Where to start
App developer
You have two options:
- Rust SDK. Use Rust SDK. The SDK verifies every signature and applies the quorum in your process. You need a client key that governance lists. Client access tells you how to get one.
- Web proxy JSON API. Use Web proxy for a browser or another client that cannot keep a secret key. The proxy does the verification for you. You then trust the operator of the proxy.
Then read Trust model. It tells you what the price does and does not guarantee.
Node operator
- Read Run a node. It covers the init wizard, the encrypted key, the config file and systemd.
- Read Key rotation before you need it.
- Read Latency to measure your node.
- Read Run the proxy if you also serve web clients.
Registry explains how governance lists your node.
Protocol implementer
Read these pages if you write your own verifier or client: