Module http_oracle 

Deterministic HTTP oracle commit-reveal consensus.

Architecture - three-phase per-block oracle protocol:

PHASE 1 (fetch): Each validator independently fetches URLs that Axiom cells requested during the previous block’s execution. Requests are collected into OracleRequest records and written to pending_oracle_requests on State.

PHASE 2 (commit): Before proposing a block, each validator broadcasts SubmitOracleCommit transactions: commit_hash = blake3(validator_pk || request_id || response_body) These land on-chain as OracleCommit records.

PHASE 3 (reveal): Once >= ORACLE_QUORUM_PERCENT of stake has committed, validators broadcast SubmitOracleReveal transactions carrying the raw response_body. The chain verifies blake3(validator_pk || request_id || revealed_body) == commit_hash and adds the validator’s response to the tally. When quorum of IDENTICAL reveals is reached, the canonical response is written to OracleResult on State. Axiom cells can then read it synchronously in the next block.

Non-determinism is eliminated because:

• Axiom cells never call the network directly. http_call reads OracleResult.
• Every validator signs their reveal with their validator key.
• Divergent responses fail to reach quorum and produce no result.
• Results are content-addressed by request_id (blake3 of url+method+body).
• Results expire after gp::get_u64(gp::PARAM_ORACLE_CACHE_EXPIRY_BLOCKS) and are refetched.

URL governance - public cells:

• Anyone may propose a URL pattern with a bond via the oracle governance system cell.
• Validators vote; 2/3 stake approval passes.
• Owner may report malicious URL; 70% of bond slashed.
• Private cells (SetCellVisibility = Private) bypass governance.

Modules

return_codes

Return codes from the http_call host function.

storage_keys

Structs

OracleCommit

A validator’s commit to a specific oracle request response. Written to State by SubmitOracleCommit transaction.

OracleCommitPayload

Payload produced by validator_fetch_and_commit - passed as SubmitOracleCommit.

OracleRequest

An Axiom cell requested an HTTP fetch. Stored in State::pending_oracle_requests.

OracleResult

The finalized oracle result after quorum of identical reveals. Axiom cells read from this committed result, never from live HTTP.

OracleReveal

A validator’s reveal of their committed oracle response. Written to State by SubmitOracleReveal transaction.

OracleTally

Pending tally for a single oracle request - accumulates commits and reveals as validators submit them. Lives in State::oracle_pending.

Functions

check_url_permitted

Check if a URL is permitted for the given cell visibility. Private cells: any URL. Public cells: URL must match an approved pattern.

compute_commit_hash

Commit hash: validator commits to their response without revealing it. commit_hash = blake3(“oracle:commit:” || validator_pk || request_id || response_body)

queue_oracle_request

Queue an oracle request from an Axiom host call. Called by the http_call host function when no finalized result is available. The request is added to State::pending_oracle_requests so validators fetch it next block.

request_id

Canonical identifier for an oracle request. Derived deterministically from (url, method, body) - same request across validators yields the same request_id with no coordination needed.

url_matches_pattern

Check if URL matches an approved pattern (prefix match with wildcard).

url_response_format

Resolve a public URL’s response format from the approved proposal.

url_schema_id

validator_fetch_and_commit

Fetch all pending oracle requests and produce commit transactions. validators call this after the previous block finalizes.