Signing and the price payload

Each node signs every update with its own secp256k1 key. The consumer recovers the signer from the signature and looks it up in the registry.

A signature proves who signed an update. It does not prove that the price is correct. The median across independent nodes is the defence against a bad node. See Trust model.

Signature scheme

The scheme is secp256k1 ECDSA, recoverable, over a Keccak-256 digest.

The low-S rule removes signature malleability. The limit n/2 is:

0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0

The payload does not contain the signer. The consumer recovers the signer from the signature.

Domain separation

The digest is EIP-712-shaped:

DOMAIN_TYPEHASH  = keccak256("EIP712Domain(string name,string version,uint256 chainId)")
DOMAIN_SEPARATOR = keccak256(DOMAIN_TYPEHASH
                           ‖ keccak256("PriceOracle")
                           ‖ keccak256("1")
                           ‖ uint256(0))          // chainId 0: off-chain, chain-agnostic

digest = keccak256(0x19 ‖ 0x01 ‖ DOMAIN_SEPARATOR ‖ keccak256(payload_bytes))

• The digest is not EIP-712-compliant. It hashes the canonical payload bytes, not a structHash. Wallet eth_signTypedData does not produce these digests.
• chainId is 0 for off-chain use. An on-chain deployment uses the real chain id, and off-chain signatures do not verify there.
• A change to the domain version invalidates every signature.
• One digest function serves every payload type. The kind byte, byte 1 of every payload, keeps the types apart.

Payload kinds

Control-plane kinds have the high bit set, so a data payload never decodes as a control-plane payload. Venue reports, books and funding describes kinds 0x03, 0x04 and 0x05. Node WebSocket protocol describes kinds 0x83 and 0x84. The network feed set describes the feed set, kind 0x86.

The PriceUpdate v1 payload

The payload is exactly 96 bytes. All integers are big-endian. This byte layout is the contract. A JSON form of an update is only a view of these bytes.

Field notes:

• Staleness checks use observation_time_ns. Replay checks use publish_time_ns.
• The node seeds seq from its clock in milliseconds at startup. A restart thus continues above the previous run.
• num_sources and source_bitmap are claims. The decoder does not require that num_sources equals the number of bits in the bitmap.
• A HALTED update still carries the last good price.

Flags

A decoder rejects an update with a reserved bit set. It does not mask the bit. A future flag can be a new warning, and an old client must not conclude that there is no warning.

Source bitmap

Bit i of source_bitmap stands for the venue with wire index i:

The indexes are wire-stable. A new venue gets the next free index. An existing venue never changes its index. The bitmap has room for 32 venues.

The price frame

A node sends each signed update as a 182-byte frame:

Use the signer hint only to route work. Never compare it with the registry. Use the recovered address. On the node WebSocket, each frame arrives encrypted. See Data frames.

Verify an update

A consumer does these steps for each price frame. The Rust SDK does them in this order. See Rust SDK.

1. Check that the frame is exactly 182 bytes and that byte 0 is 1.
2. Parse the signature. Reject it if v is not 27 or 28, if r or s is zero, or if s > n/2.
3. Decode the payload. Reject a version other than 1, a kind other than 0x01, a reserved flag bit, or an unassigned venue bit.
4. Compute the digest over the payload bytes that you received. Do not hash bytes that you rebuilt from decoded fields.
5. Recover the signer address from the signature and the digest.
6. Look up the address in a registry that you verified against your pinned governance address. See Registry.
   • A retired address: reject the frame. Do not refresh the registry.
   • An unknown address: refresh the registry once, then try again. Limit the refreshes to one for each refresh_interval (default 10 s). Anyone who can inject a frame can cause a refresh.
7. Reject the update if observation_time_ns > publish_time_ns.
8. Reject the update if publish_time_ns is more than max_skew in the future (default 500 ms). Also reject it if it is older than max_age: 2 s by default, or 25 s for a funding or open interest feed.
9. Reject the update if seq is not greater than the last accepted seq for this (node, feed) pair. Then store the new seq.

Do the clock checks before step 9. A rejected frame must not raise the stored seq, or it can lock out the valid frame after it.

After these steps, the update is one that a listed node signed recently. The consumer then combines the latest update from each node: a quorum of distinct nodes and a median. See Aggregation.

Key all per-node state by address, not by registry index. The indexes change when the registry changes.

The price batch

A node signs each update on its own for its WebSocket subscribers. When it pushes to the registry canister, it signs its due updates as one batch, so the canister checks one signature for the push. See On-chain prices.

The frame is [0] frame_type = 5 ‖ [1..21] signer hint ‖ payload ‖ 65-byte signature. Verify it as a price frame, with one signature for the whole batch. Then check each update alone for steps 7 to 9: an update shares the seq of the node's single frames of its feed. The kind byte is inside the signed bytes, so a batch signature never passes as the signature of one of its updates.

Key management

A node has one secret seed. Two keys derive from it. Each key is HKDF-SHA256 of the seed under its own label. Neither key reveals the seed or the other key.

The secp256k1 address is the node's id. The registry lists nodes by address. Consumers key all per-node state by it. There is no separate identity key.

Keys stay local and encrypted

• oracle-node init and oracle-node rotate draw the seed from the operating system's CSPRNG.
• The key file is an age file, encrypted with a passphrase. The scrypt work factor is fixed at 2^18 (256 MiB, about one second). A key file can ask for at most 2^20.
• Inside the encryption, the file holds the seed as oracle-node-seed-v1:<hex>. Bare hex is an older secp256k1 key without an ed25519 key. Only a local test setup uses that form.
• The passphrase comes from a 0600 file or from a prompt at a terminal. It never comes from the config, an environment variable or a command-line argument. A node with an encrypted key and no passphrase source refuses to start.
• The node decrypts the key into memory at startup and erases it on drop. Run the node with core dumps off and swap encrypted or off.
• There is no KMS and no HSM. A cloud key service is a third party in the signing path.

The seeded keys in the examples and test helpers come from small integers. Never use them for a real node.

No expiry

Keys do not expire. An operator rotates a key on suspicion of compromise, not on a schedule. Each rotation is a governance call. The design accepts these costs:

• A stolen key that nobody notices stays valid until governance replaces or removes the node.
• An attacker can collect keys from several nodes over time. Watch the divergence between nodes.
• An abandoned node stays listed until governance removes it.

Rotation and retired keys

A rotation replaces one address with a new one through replace_node(old, new) on the registry canister. The canister keeps each retired address with its added_at and removed_at, and never lists it again. A live frame verifies only against a listed address. A stored frame verifies against the listing that covered its publish time. See Registry.