Skip to main content
A certified oracle report contains observations and a signature from the required number of validators. OracleReports verifies that signature against its configured validator keys and returns the report’s items. The consuming contract defines which items it accepts and its limits for age, confidence, flags, and repeated use. Use oracle data describes the value acceptance checks.

​
Deployment configuration

The network operator supplies the OracleReports deployment address and configuration for each validator set. The constructor permanently fixes that set and the network identity. A changed validator set requires a new deployment and retirement of the old verifier. A proof of possession demonstrates that the validator holds the private key for its public key. Its signature uses the domain separation tag BLS_POP_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_. The constructor checks the key encodings and possession proofs. A verifier accepts reports only through retireHeight. When the validator set changes, retire the old verifier so its keys cannot certify later reports. The configured retirer can call retire(newRetireHeight) to lower the bound. The new height must be strictly lower; it can never be extended. A successful call emits RetireHeightLowered(uint64 retireHeight).

​
Report numbering

MetalOracle at 0x00000000000000000000000000000000000000fd exposes the read function reportBaseMs() → uint64. It returns the starting Unix timestamp in milliseconds for certified report numbering. Report sequence numbers count one-second intervals from this timestamp. A return value of zero means certified report publication is disabled.

​
Report RPC

metal_getOracleReport returns the latest retained certified report when called with an empty parameter array. A single JSON integer parameter selects a report by its sequence number, named height. The result is null when no matching report is retained. Each node retains up to 64 certified reports. verifyReport takes a signer bitmap and an EIP-2537 signature. The RPC exposes signers and signature separately for that conversion. The certificate field contains the encoded certificate for clients that use its native format.

​
Report format

The report bytes are ABI-encoded as (uint64 round, ReportItem[] items). round is the report sequence number returned as height by the RPC. Each ReportItem has these fields in order: Item names, units, quote directions, and acceptance limits come from the feed configuration and oracle catalog. Report items use the same status flag masks as stored oracle observations:

​
Verifier interface

All functions except retire are reads. verifyReport checks the retirement bound, report number, signer bitmap, quorum, and signature. It returns the decoded items even when ok is false. A consuming contract must require ok before using them. Item selection, age, confidence, flags, and replay checks belong to that contract.

​
Signature encoding

The signer bitmap is exactly ceil(memberCount / 8) bytes. Validator index i is bit i % 8 of byte floor(i / 8), counting from the least significant bit. Unused bits in the last byte are zero. The verifier’s signature argument is a 256-byte EIP-2537 G2 point. Its four coordinates are x.c0 ∥ x.c1 ∥ y.c0 ∥ y.c1, each encoded as a 64-byte unsigned big-endian integer. The RPC uses the 96-byte compressed form of the same point. The signed message is varint(len(ns)) ∥ ns ∥ varint(height) ∥ keccak256(report), where ns is ackNamespace() and each varint is an unsigned LEB128 integer. The aggregate signature uses the domain separation tag BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_. In these encodings, ∥ means byte concatenation.