cxyz oracle network7 nodes · Base Sepolia (84532) · read-only

How it works

A permissioned oracle network. Workflows are written in Rust and compiled to WASM; seven nodes run each one, agree on what it observed with a Tendermint-style consensus instance per call, sign a report, and deliver it to EVM chains through a Forwarder contract. Secrets are encrypted to a key only a threshold of nodes can use, and confidential handlers run inside an AWS Nitro Enclave. This page follows the repository's README and crate docs.

1. Architecture

The code is hexagonal. Core crates do no I/O, read no clock and hold no key; they talk to the outside only through traits (ports), and each adapter crate implements one port. crates/node is the composition root that wires them together. The consensus protocol is a pure state machine fed inputs and returning effects, which is what lets it run under a deterministic simulation with a hostile network and hostile peers (cxyz_testkit::consensus, one seed fixes a whole run).

One node: pure core, ports on its edge, adapters outside, wired by crates/node Workflow (WASM guest) written with crates/sdk, talks to the node only via crates/abi Application core no I/O, no clock, no keys domain abi engine network report consensus agreement attestation key-attestation enclave-protocol vault keygen confidential agreement, attestation and confidential are engine Capabilities; consensus is a pure state machine (Input → Effects) wasm wasmtime; fuel, memory, logs WorkflowRuntime trigger-cron + trigger-evm-log (final blocks) TriggerSource capability-http + capability-evm-read Capability store-jsonl executions.jsonl, append-only ExecutionStore SystemClock in crates/node Clock Transport transport-tcp sender authenticated Crypto crypto-ed25519 consensus signatures ReportSigner signer-local secp256k1 key in memory ChainWriter, NodeSetSource chain-evm deliver; follow node set EnclaveClient enclave-client vsock or TCP AttestationVerifier tee-nitro AWS root certificate evm-rpc: QuorumRpc the only way to a chain, for chain-evm, capability-evm-read and trigger-evm-log crates/node: composition root Node wires the engine, the agreement, attestation and confidential services and the transport. start() assembles a node from node.toml and its key file; the cxyz-node binary runs it and prints one line of JSON per event (started, node_set, execution, status).
Ports are traits defined by the core (engine, consensus, network, attestation, enclave-protocol, report); adapters are crates under crates/adapters. The workflow binary is a separate WASM guest.

2. The life of one report

A price feed as the example: a cron trigger fires on every node, each node runs the workflow, each fetches the price on its own, the network agrees on the median, every node signs the same report, and the nodes take turns delivering it until it is on chain.

Triggercron, on every nodeThis nodeengine + WASM6 other nodesdoing the sameData sourceHTTP APIForwarderon chainNodeRegistryon chainReceiverLatestValueReceiver1 Trigger: the same occurrence on every nodefires (scheduled_at)execution id = sha256(workflow, handler, trigger occurrence): the same onevery node, so their consensus instances for its calls find each other2 Run: a fresh WASM instance per run, always from the starthandler runs; inside observe(): http_getGET (each node on its own)answer: this node's observationA call whose result is not known yet ends the run. When the result arrives it goes into theexecution's journal and the workflow runs again from the start; calls already in the journalare answered from it at once. So a workflow must do the same thing given the same answers.3 Agree: call Agree { Median, observation }, one consensus instancesigned observationtheirsproposal (by proposer)prevoteprecommit5 precommits for one value decide it: the median of the decidedobservations. Late nodes are sent a decision certificate.4 Report: call WriteReport, every node signs the same reportReport { workflowId, executionId, reportIndex, configVersion, receiver, payload }EIP-712 signaturetheir signaturesEach node builds the report from the agreed value and signs itsdigest under the Forwarder's domain; signatures are resent every 2 s.5 Deliver: nodes take turns of 5 s, in an order taken from the report digestdeliver(report, f + 1 = 3 signatures)currentConfig, isSignerversion in force, f + 1 signers, order, newonReport(workflowId, executionId, payload)accepts only its Forwarderand allowed workflowsA node whose turn comes without f + 1 signatures only checks whether the reportis on chain. Everyone else sees it delivered and the call returns.6 FinishDelivered counts once the block of the transaction is final.The execution is recorded: a line in executions.jsonl.
Solid arrows are requests, dashed arrows answers. Only one of the six other nodes' paths is drawn; all of them do the same as this node.

Replay model

To the workflow, ctx.observe, ctx.write_report and the other calls simply return. Underneath, the node stops the workflow at the first call whose result is not known yet (the host ends the WASM instance instead of returning). When the result is known it is appended to the execution's journal and the workflow is run again from the start in a fresh instance; calls already in the journal are answered from it at once. The journal is the whole state of an execution. That is why a handler must be deterministic: no wall clock, no randomness, no floating point in results, and nothing from inside observe used afterwards except its return value.

Who decides what

3. Consensus

Each node observes something on its own; one consensus instance makes the honest nodes agree on a single set of signed observations and on the value an aggregator derives from it: the median of integers, or the value most nodes saw identically. The protocol is the Tendermint consensus algorithm (Buchman, Kwon and Milosevic, Algorithm 1) run once per instance instead of once per block height.

Observations Every node signs (Ed25519) and broadcasts what it observed. A node whose data source failed takes part without one. Everything said in the current round is sent again every 2 s; a node still in an earlier round is sent the votes of that round and of the sender's own. Propose (round r) proposer = (s + r) mod 7, with s taken from the instance id it proposes a quorum of signed observations, or the value it knows a quorum prevoted for, carrying those prevotes as proof Prevote for the proposal, or for nothing if it is invalid, late, or conflicts with the value the node is locked on 5 prevotes for a value: lock on it and precommit it Precommit for the value a quorum prevoted for, or for nothing after the prevote timeout 5 precommits for a value: decide Decided value = aggregator over the decided observations: Median, or Identical (the value most nodes saw) late nodes are answered with a decision certificate timeout 3 000 ms + r·500: prevote for nothing a quorum prevoted, no agreement: wait 1 000 ms + r·500, then precommit for nothing a quorum precommitted, no agreement: wait 1 000 ms + r·500, then go to round r + 1 round r + 1: next proposer, every timeout 500 ms longer; a round is never re-entered n = 7 nodes, f = 2 faults quorum = ⌈(n + f + 1) / 2⌉ = 5 two quorums share at least 2·5 − 7 = 3 > f nodes, so an honest one, which never votes for two values in one round the honest nodes alone are n − f = 5, a quorum a node follows peers into a later round once f + 1 = 3 of them are seen there a report needs exactly f + 1 = 3 signatures on chain: at least one is honest NodeRegistry refuses a node set with fewer than 3f + 1 = 7 signers vault key: 5 of 7 shares decrypt
One instance. The timeouts are those of Timeouts::default(), which cxyz-node start uses: propose 3 000 ms, prevote 1 000 ms, precommit 1 000 ms, each 500 ms longer per round; everything said in a round is sent again every 2 000 ms.

What makes it work on a network that loses, duplicates and reorders messages, with peers that tell different nodes different things:

None of these touches the voting rules, on which safety rests. A node whose data source is down still votes on what the others observed.

What the consensus crate does not do yet

  • Survive a restart. Safety assumes an honest node votes once per round. A restarted node keeps no state, so it must not rejoin a running instance.
  • End an instance. One that cannot decide, because too few nodes observed anything, keeps trying; giving up is the caller's decision.
  • Cope with nodes that disagree about each other's keys. If some nodes accept a node's votes and others cannot verify them, the two groups count different votes; a seven-node network split four to three can stall for good (it happened in a test). Safety is not affected. See the key replacement procedure below.

4. Talking to chains

No single RPC provider is trusted. A node is given several endpoints per chain and a quorum that must be a strict majority; QuorumRpc in crates/adapters/evm-rpc asks every endpoint at once and only returns what that many agree on: block hashes, call results pinned to a block hash, logs, receipts. Nothing else in the node talks to a chain, and this page reads the chain through the same type.

Endpoint A (provider 1) final height 1203 block 1201 = 0xab… eth_call @0xab… → 0x…64 Endpoint B (provider 2) final height 1201 block 1201 = 0xab… eth_call @0xab… → 0x…64 Endpoint C (provider 3) final height 1188 (behind) has no block 1201: does not count eth_call: error: does not count QuorumRpc: 3 endpoints, quorum 2 (a strict majority) 0. each endpoint counts only once it reported the configured chain id 1. final_block(finality) heights 1203, 1201, 1188: take the 2nd highest = 1201, so one endpoint claiming to be far ahead cannot pull the height up; then vote on the hash at 1201: A and B say 0xab… → BlockRef(1201, 0xab…) 2. call(to, data, block) eth_call pinned by block hash (EIP-1898), never by number; an answer counts once 2 endpoints gave exactly it 3. logs(filter, from, to) at most 1 000 blocks; an endpoint counts only if its block to.number is to.hash, and the whole list of logs must be identical errors, timeouts (10 s per endpoint), wrong chain, garbage: the endpoint simply does not count for that call Callers chain-evm: delivers reports, waits for receipts and finality, reads the node set from the registry the Forwarder names (latest block) capability-evm-read: workflow reads at blocks the node considers final trigger-evm-log: events once their block is final this page: final_block(Confirmations(0)), every call of one read pinned to it finality per chain: Finalized, Safe, or Confirmations(n); a report counts as delivered once the block of its transaction is final
An example with three endpoints, one of them behind. If fewer than quorum endpoints are faulty, every agreed answer was given by at least one honest endpoint.

5. Secrets and confidential compute

The vault key

A confidential handler

relay: can stall, cannot read or forgethe only place secrets are decryptedEvery nodeworkflow + ConfidentialServiceFronting nodeparent instance, relaysEnclavecrates/enclave on NitroExternal APIHTTPS0 Before: the vault key and the secretThe nodes generated the key together (FROST DKG); each holds one share and KeyRegistry holds thepublic key every node signed. A secret is encrypted to it (TDH2) under a label made from the hashof the workflow's binary, so only that exact code can ever be given it.1 Requestctx.confidential(handler, input, ciphertexts)Every node derives the same RequestId (call, execution, code,handler, input, ciphertexts, vault key) and checks that everyciphertext is valid and bound to this workflow's code.execute this requestmakes a fresh key for this requestattestation: image, key, requestOffer (the attestation)2 Verify, then helpEach node verifies the attestation against AWS's root certificateand the images it was told to trust, and that it vouches for thisvery request. Only then does it compute its decryption parts.Shares: parts sealed to that keysealed parts, passed alongOpens the parts, decrypts each secretwith a threshold (5) of them, runs thehandler, which may use the secret:request carrying the secretanswer3 Resultresult + attestation of itResult (outcome, attestation)A node accepts a result only with an attestation from a trusted image of exactly thatresult for exactly this request. A faulty relay could show nodes different genuine runs,so the nodes then agree on what they saw (a consensus instance) before the workflow goes on.
Dashed red boxes are trust boundaries. The fronting node is one of the seven; as a relay it only passes sealed data along. The enclave's key is used once, so nothing learned later opens earlier requests.

6. Data schemas

Report and its EIP-712 signature

struct Report {
    bytes32 workflowId;     // the workflow that produced it (hash of binary + configuration)
    bytes32 executionId;    // identical on every node for the same trigger occurrence
    uint32  reportIndex;    // the number of the workflow call that produced it
    uint32  configVersion;  // version of the node set the signers belong to
    address receiver;       // the only contract it may be delivered to
    bytes   payload;        // for the receiver, e.g. abi.encode(int256 value, uint64 observedAt)
}

REPORT_TYPEHASH = keccak256("Report(bytes32 workflowId,bytes32 executionId,uint32 reportIndex,uint32 configVersion,address receiver,bytes payload)")
structHash      = keccak256(abi.encode(REPORT_TYPEHASH, workflowId, executionId, reportIndex,
                                       configVersion, receiver, keccak256(payload)))
domain          = EIP712Domain(name "CxyzForwarder", version "1", chainId, verifyingContract = Forwarder)
digest          = keccak256("\x19\x01" || domainSeparator || structHash)
signature       = 65 bytes r || s || v, secp256k1, by the node's report key
transmissionId  = keccak256(abi.encode(receiver, executionId, reportIndex))   // replay protection

Workflow ↔ host ABI

guest exports (module "cxyz", ABI_VERSION = 4)
  memory
  cxyz_abi_version()                    -> u32   must equal ABI_VERSION
  cxyz_alloc(len: u32)                  -> u32   room for the host to write into
  cxyz_describe(ptr, len)               -> u64   configuration in, encoded WorkflowManifest out
  cxyz_handle(handler: u32, ptr, len)   -> u64   HandleRequest { event, config } in, HandleResponse out
  cxyz_confidential(ptr, len)           -> u64   only ever called inside an enclave

guest imports from "cxyz"
  log(level: u32, ptr, len)
  call(ptr, len) -> u64    CallRequest in, CallResult out; if the result is not known yet
                           the host ends the instance instead of returning

buffers: (ptr, len) packed into one u64; messages encoded with postcard;
a fresh instance for every run, so the guest keeps no state between executions

CallRequest = HttpGet { url }
            | Agree { aggregation: Median | Identical, observation: Option<Value> }
            | WriteReport { chain_id, receiver: [u8; 20], payload }
            | EvmFinalizedBlock { chain_id }
            | EvmCall { chain_id, to, data, block_number }
            | Confidential { handler, input, secrets }
            | Secret { name }            (inside an enclave only)
            | Http { method, url, headers, body }   (inside an enclave only)

Node configuration (node.toml)

Every node gets the same peers in the same order, the same fault tolerance and the same workflows; paths are relative to the file. The node set is not configured: it is read from the registry the Forwarder names. The key file holds the three secrets and is readable by the node only.

node = 0                          # this node's position among the peers
listen = "0.0.0.0:7000"
keys = "node.keys"                # consensus (Ed25519), report and transmitter (secp256k1) secrets
fault_tolerance = 2               # seven nodes survive two faulty ones
executions = "executions.jsonl"   # optional: a record of every execution
delivery_turn_millis = 5000       # optional: each node's turn to deliver

[[peers]]                         # every node, this one included, in the same order everywhere
address = "node-0.example:7000"
consensus_key = "0x…"
also_accepts = ["0x…"]            # optional: while that peer's key is being replaced

[[chains]]
id = 84532
rpc = ["https://…", "https://…", "https://…"]
quorum = 2                        # a strict majority of the endpoints
finality = "finalized"            # or "safe", or { confirmations = 12 }
forwarder = "0x…"                 # without it the chain is only read

[[workflows]]
wasm = "price-feed.wasm"
config = "price-feed.conf"        # optional

Execution record (executions.jsonl)

{"execution":"<64 hex>","workflow":"<64 hex>","handler":0,
 "trigger":{"cron":{"scheduled_at":1700000000000}},
 "started_at":1700000000123,
 "outcome":"succeeded","value":4200,
 "logs":[{"level":"info","message":"agreed on 4200"}]}

failed:   "outcome":"failed","reason":"…" instead of "value"
evm log:  "trigger":{"evm_log":{"chain_id","block_number","block_hash","transaction_hash",
                                "log_index","address","topics","data"}}
times are milliseconds since 1970, bytes are 0x hex; one line per finished execution,
written with a single write to a file opened for appending; the node never reads it back

Status (status.json)

{"at": 1795057064040, "node": 0, "started_at": 1795050000000,
 "consensus_key": "0x…", "report_signer": "0x…", "transmitter": "0x…",
 "workflows": ["<64 hex>", …],
 "node_sets": [{"chain": 84532, "version": 1, "fault_tolerance": 2,
                "signers": ["0x…", …], "member": true}],
 "executions": 1,          // started, not finished
 "reports": 0,             // signed, not yet seen on chain
 "agreements": [{"execution": "<64 hex>", "call": 1, "round": 0,
                 "step": "propose" | "prevote" | "precommit", "observations": 6}]}

replaced about every 5 s; this page treats one older than 20 s as not reporting.
Agreements, executions or reports that stay for minutes are stuck.

Contracts

Owner (meant to be a multisig) root of trust: setConfig on NodeRegistry also owns EnclaveRegistry and each receiver (setWorkflowAllowed, setForwarder) ownership: two steps, cannot be renounced setConfig NodeRegistry version: uint32 (0 until first set) faultTolerance: uint8 signers: address[] (≤ 31, ≥ 3f + 1, strictly increasing) isSigner[version][signer] setConfig(signers, f) → version + 1 event ConfigSet(version, f, signers) currentConfig(), isSigner(), signers() EnclaveRegistry allowed[imageId], imageId = keccak256(pcr0, pcr1, pcr2), 48 bytes each allowImage(…, description), revokeImage holds the trusted images on chain; nothing reads it yet: nodes take the images they trust from their configuration Forwarder (no owner, immutable) registry: NodeRegistry (immutable) EIP-712 domain "CxyzForwarder", "1", chainId, verifyingContract = this delivered[transmissionId], where transmissionId = keccak256(abi.encode( receiver, executionId, reportIndex)) deliver(report, signatures): version is the one in force, exactly f + 1 signatures by signers of it, increasing order, not yet delivered; marks it, then calls onReport event ReportDelivered(receiver, workflowId, executionId, reportIndex) currentConfig(), isSigner() ReportReceiver (abstract) forwarder: the only accepted caller isWorkflowAllowed[workflowId] onReport(workflowId, executionId, payload) LatestValueReceiver is ReportReceiver payload = abi.encode(int256 value, uint64 observedAt); older observedAt refused latestValue, observedAt event ValueUpdated(executionId, value, observedAt) onReport KeyRegistry (no owner) nodeRegistry: NodeRegistry (immutable) EIP-712 domain "CxyzKeyRegistry", "1" epoch: uint32 (0 until the first key) configVersion: node set that signed it publicKey: bytes32 (Ristretto point) threshold: uint16 verificationKeys: bytes32[], one per share setKey(…, signatures): one signature from every node of the set in force, in the order of signers(), over VaultKey(epoch, configVersion, publicKey, threshold, verificationKeys) → epoch + 1 currentKey(), verificationKeys() reads signers(), currentConfig()
Arrows point at what a contract calls or reads. NodeRegistry's owner is the root of trust of the whole network; Forwarder and KeyRegistry have no owner.

7. Operating a network

Restarting a node

Safe at any moment, including by killing it. It comes back knowing nothing of what it was doing: executions in progress are lost on that node, and it only takes part in what is triggered after it is up again. The rest finish without it. Restart one node at a time and wait for an execution line with "outcome":"succeeded" before the next: each node that is down or freshly restarted uses up one of the faults the network tolerates. Chain events that happen while a node is down are not handled by that node, and a node's clock must not be set back across a restart to before an occurrence it already took part in: it would vote on it a second time.

Changing the node set

The owner of NodeRegistry calls setConfig; nothing is restarted. Each node reads the node set from the registry its Forwarder names and, when it changes, signs every report still on its way again for the new set. A node whose signing key is not in the set keeps running and agreeing; its signature just does not count there (member: false). Each chain is followed on its own. Only who signs can change this way: the number of nodes is fixed for the life of a network.

Replacing a node

New operatorposition kOther 6 operatorstheir nodesPosition kold node → new nodeRegistry ownermultisigChainNodeRegistry, KeyRegistry1 new keyscxyz-node keys generatethree public values2 everyone accepts the new consensus key tooalso_accepts = [new key]; restart one by one3 swap the nodestop old; start new with the new key4 the chainsetConfig: new report signerEvery node reads the new node set from the registry its Forwarder names and signs reportsstill on their way again for it. From here on the old signing key is worthless.5 drop the old keyconsensus_key = new; drop also_accepts; restart one by one6–8 the vault share (every node involved must be online)6 KeyRepair: five other nodes give the new node the share of itsposition; none learns it; it only accepts a share matching the key7 KeyGeneration::refresh by all seven: same key, every share changes;each node signs the result and KeyRegistry records the next epoch8 each node switches to its new share once the registry shows the new epoch,and erases the old one: what the protection against old shares rests on
Steps 1–5 change who the node is; steps 6–8 give the new operator the vault share and leave the previous one with nothing of use. Steps 6–8 are run by a program of one's own for now, not by cxyz-node.

Why the order matters. A node must never sign with a consensus key some of its peers do not accept yet: those peers and the rest would count different votes, and agreement can stall until the configurations are in step again. An earlier version of the test, which started the new node before its peers knew its key, lost one price in eleven that way. Accepting both keys for a while (step 2) avoids it; while both are accepted, whoever holds either key speaks as that node, so step 5 must not be skipped. On the vault side, five old shares still open everything, refresh or not; a refresh only makes old shares useless together with new ones. The protection rests on step 8: honest nodes really erasing their old shares.

8. Limits of what exists

  • The cryptography written here is new and unreviewed: TDH2 in crates/vault, and the ceremony, refresh and repair logic in crates/keygen (around FROST's own functions, which are used unchanged). All of it needs an external audit before it protects anything of value.
  • Nothing is durable across a restart except a node's keys and configuration; a restarted node must not rejoin a running consensus instance.
  • Confidential compute: one enclave, fronted by one node, with no pool and no reassignment if that node is down. The trusted images come from each node's configuration; EnclaveRegistry holds the same list on chain but nothing reads it yet. Decrypted secrets are not yet erased from the WASM runtime's memory after use.
  • cxyz-node generates the vault key with the other nodes and runs confidential handlers against an enclave, but does not run a refresh or a repair of the key; those are driven from a program of one's own, as in the tests. The network shown on the Live page is seven node processes and one enclave on one machine, run by one operator: it shows the protocol working, not the independence the fault tolerance assumes.
  • A consensus instance that cannot decide keeps trying; nodes that disagree about each other's keys can stall agreement.
  • The number of nodes is fixed for the life of a network, and the node set and threshold for the life of a vault key.
  • This page: it holds no keys and changes nothing. It shows what the nodes' files say and what a quorum of RPC endpoints say; it verifies no signature and no attestation itself.