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:
- The proof body canonical JSON encoding.
- The signing-bytes derivation (domain separator + body JSON).
- 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:
OracleIdentityholds 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 viafialucci-types’s authoritativesign_oracle_data_submission— the same call the chain’s reference dev-tool binary uses, transitively bound to the samefialucci-typesversion 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
- Request-driven (the default).
Oracle::runpolls/oracle/observation-requests/matchingand callsOracleHandler::observefor each request the oracle is eligible to answer. Use this when your oracle should respond to upstream contract conditions. - Proactive. Call
Oracle::submit_proactiveyourself, on whatever cadence makes sense, with thedomain/subject/claim/evidenceyou 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§
- Chain
Client - HTTP client for a single Fialucci chain node.
- Oracle
- The configured, running oracle.
- Oracle
Builder - Fluent configurator for
Oracle. - Oracle
Identity - An oracle’s ed25519 keypair plus its derived
OracleId. - Proof
Body Builder - Fluent builder for
OracleDataSubmissionBody. - Proof
Claim Evidence - The pair an
OracleHandlerreturns fromobserve. - Submission
Ack - Response shape of
POST /oracle/submissions(and the observation-request variant).
Enums§
- Build
Error - Errors surfaced by
OracleBuilder::build. - Client
Error - Errors surfaced by
ChainClient. - Handler
Error - Generic error type for handler implementations.
- Identity
Error - Errors surfaced by
OracleIdentitykeystore operations. - Proof
Body Build Error - Errors surfaced by
ProofBodyBuilder::build. - Runtime
Error - Errors surfaced by
Oracle::run/Oracle::tick/Oracle::submit.
Traits§
- Oracle
Handler - The dev-facing extension point.
Type Aliases§
- Observation
Request - Re-export of the chain’s observation-request struct.