Skip to main content

Crate fialucci_oracle

Crate fialucci_oracle 

Source
Expand description

§fialucci-oracle

Opinionated SDK for building external oracles on the Fialucci chain. The SDK owns the network protocol; developers write only business logic by implementing the OracleHandler trait.

§The design constraint

Three things must be byte-identical between every oracle in the wild and the chain node validating its submissions:

  1. The proof body canonical JSON encoding.
  2. The signing-bytes derivation (domain separator + body JSON).
  3. The ed25519 signature over those bytes.

Any drift breaks acceptance, silently — the oracle thinks it submitted, the chain rejects. Letting individual oracle authors re-implement any of these three things makes drift a question of when, not if. So the SDK does all three itself, and the dev cannot override them:

  • OracleIdentity holds the signing key; its byte-level signing entry point is crate-private. There is no public method that signs arbitrary bytes.
  • The runtime constructs the [OracleDataSubmissionBody] and signs it via fialucci-types’s authoritative sign_oracle_data_submission — the same call the chain’s reference dev-tool binary uses, transitively bound to the same fialucci-types version the chain consumes.
  • HTTP submission goes through the SDK’s ChainClient, which posts exactly the [SignedOracleDataSubmission] the signing call returned — nothing in between.

What devs do control is what the oracle observes and what claim it makes. That’s the entire surface of OracleHandler::observe: given an ObservationRequest, decide whether to respond and, if so, with what [ProofClaim] and what [ProofEvidence].

§Two submission paths

  1. Request-driven (the default). Oracle::run polls /oracle/observation-requests/matching and calls OracleHandler::observe for each request the oracle is eligible to answer. Use this when your oracle should respond to upstream contract conditions.
  2. Proactive. Call Oracle::submit_proactive yourself, on whatever cadence makes sense, with the domain / subject / claim / evidence you want to assert. Use this when your oracle observes the world on its own schedule (e.g. a GitHub poller that submits when a PR is merged). The signing + HTTP + nonce + chain-id seam is still SDK-owned — you just skip the observation-request hop.

§Quick start

use fialucci_oracle::{Oracle, OracleHandler, OracleIdentity, ObservationRequest, ProofClaimEvidence, HandlerError};
use fialucci_oracle::types::{ProofClaim, ProofEvidence, hash_evidence_bytes};
use async_trait::async_trait;

struct MyOracle;

#[async_trait]
impl OracleHandler for MyOracle {
    async fn observe(&self, _request: &ObservationRequest) -> Result<Option<ProofClaimEvidence>, HandlerError> {
        // Decide based on whatever off-chain data source the oracle wraps.
        let evidence_bytes = b"my custom evidence payload";
        Ok(Some(ProofClaimEvidence {
            claim: ProofClaim::WorkCompleted,
            evidence: ProofEvidence {
                evidence_hash: hash_evidence_bytes(evidence_bytes),
                evidence_uri: None,
                content_type: Some("application/octet-stream".to_string()),
                metadata: None,
            },
        }))
    }
}

let identity = OracleIdentity::load_from_file("oracle_key.json")?;
let oracle = Oracle::builder()
    .identity(identity)
    .node_url("http://127.0.0.1:8080")
    .handler(MyOracle)
    .build()
    .await?;
oracle.run().await?;

Modules§

types
Re-export of the canonical protocol types crate.

Structs§

ChainClient
HTTP client for a single Fialucci chain node.
Oracle
The configured, running oracle.
OracleBuilder
Fluent configurator for Oracle.
OracleIdentity
An oracle’s ed25519 keypair plus its derived OracleId.
ProofBodyBuilder
Fluent builder for OracleDataSubmissionBody.
ProofClaimEvidence
The pair an OracleHandler returns from observe.
SubmissionAck
Response shape of POST /oracle/submissions (and the observation-request variant).

Enums§

BuildError
Errors surfaced by OracleBuilder::build.
ClientError
Errors surfaced by ChainClient.
HandlerError
Generic error type for handler implementations.
IdentityError
Errors surfaced by OracleIdentity keystore operations.
ProofBodyBuildError
Errors surfaced by ProofBodyBuilder::build.
RuntimeError
Errors surfaced by Oracle::run / Oracle::tick / Oracle::submit.

Traits§

OracleHandler
The dev-facing extension point.

Type Aliases§

ObservationRequest
Re-export of the chain’s observation-request struct.