fialucci_oracle/lib.rs
1//! # fialucci-oracle
2//!
3//! Opinionated SDK for building external oracles on the [Fialucci](https://github.com/fialucci)
4//! chain. The SDK owns the network protocol; developers write only **business
5//! logic** by implementing the [`OracleHandler`] trait.
6//!
7//! ## The design constraint
8//!
9//! Three things must be byte-identical between every oracle in the wild and
10//! the chain node validating its submissions:
11//!
12//! 1. The proof body canonical JSON encoding.
13//! 2. The signing-bytes derivation (domain separator + body JSON).
14//! 3. The ed25519 signature over those bytes.
15//!
16//! Any drift breaks acceptance, silently — the oracle thinks it submitted,
17//! the chain rejects. Letting individual oracle authors re-implement any of
18//! these three things makes drift a question of when, not if. So the SDK
19//! does all three itself, and the dev cannot override them:
20//!
21//! - [`OracleIdentity`] holds the signing key; its byte-level signing entry
22//! point is crate-private. There is no public method that signs arbitrary
23//! bytes.
24//! - The runtime constructs the [`OracleDataSubmissionBody`] and signs it
25//! via `fialucci-types`'s authoritative `sign_oracle_data_submission` —
26//! the same call the chain's reference dev-tool binary uses, transitively
27//! bound to the same `fialucci-types` version the chain consumes.
28//! - HTTP submission goes through the SDK's [`ChainClient`], which posts
29//! exactly the [`SignedOracleDataSubmission`] the signing call returned —
30//! nothing in between.
31//!
32//! What devs **do** control is what the oracle observes and what claim it
33//! makes. That's the entire surface of [`OracleHandler::observe`]: given an
34//! [`ObservationRequest`], decide whether to respond and, if so, with what
35//! [`ProofClaim`] and what [`ProofEvidence`].
36//!
37//! ## Two submission paths
38//!
39//! 1. **Request-driven** (the default). [`Oracle::run`] polls
40//! `/oracle/observation-requests/matching` and calls
41//! [`OracleHandler::observe`] for each request the oracle is eligible to
42//! answer. Use this when your oracle should respond to upstream contract
43//! conditions.
44//! 2. **Proactive**. Call [`Oracle::submit_proactive`] yourself, on whatever
45//! cadence makes sense, with the `domain` / `subject` / `claim` /
46//! `evidence` you want to assert. Use this when your oracle observes
47//! the world on its own schedule (e.g. a GitHub poller that submits
48//! when a PR is merged). The signing + HTTP + nonce + chain-id seam is
49//! still SDK-owned — you just skip the observation-request hop.
50//!
51//! ## Quick start
52//!
53//! ```no_run
54//! use fialucci_oracle::{Oracle, OracleHandler, OracleIdentity, ObservationRequest, ProofClaimEvidence, HandlerError};
55//! use fialucci_oracle::types::{ProofClaim, ProofEvidence, hash_evidence_bytes};
56//! use async_trait::async_trait;
57//!
58//! struct MyOracle;
59//!
60//! #[async_trait]
61//! impl OracleHandler for MyOracle {
62//! async fn observe(&self, _request: &ObservationRequest) -> Result<Option<ProofClaimEvidence>, HandlerError> {
63//! // Decide based on whatever off-chain data source the oracle wraps.
64//! let evidence_bytes = b"my custom evidence payload";
65//! Ok(Some(ProofClaimEvidence {
66//! claim: ProofClaim::WorkCompleted,
67//! evidence: ProofEvidence {
68//! evidence_hash: hash_evidence_bytes(evidence_bytes),
69//! evidence_uri: None,
70//! content_type: Some("application/octet-stream".to_string()),
71//! metadata: None,
72//! },
73//! }))
74//! }
75//! }
76//!
77//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
78//! let identity = OracleIdentity::load_from_file("oracle_key.json")?;
79//! let oracle = Oracle::builder()
80//! .identity(identity)
81//! .node_url("http://127.0.0.1:8080")
82//! .handler(MyOracle)
83//! .build()
84//! .await?;
85//! oracle.run().await?;
86//! # Ok(()) }
87//! ```
88
89#![deny(missing_docs)]
90#![warn(rust_2018_idioms)]
91
92mod client;
93mod handler;
94mod identity;
95mod proof_body;
96mod runtime;
97
98#[cfg(feature = "allora")]
99mod allora_adapter;
100
101pub use client::{ChainClient, ClientError, SubmissionAck};
102pub use handler::{HandlerError, ObservationRequest, OracleHandler, ProofClaimEvidence};
103pub use identity::{IdentityError, OracleIdentity};
104pub use proof_body::{ProofBodyBuildError, ProofBodyBuilder};
105pub use runtime::{BuildError, Oracle, OracleBuilder, RuntimeError};
106
107/// Re-export of the canonical protocol types crate.
108///
109/// Use these types when constructing claims and evidence; the SDK and the
110/// chain depend on the same `fialucci-types` version, so wire shapes match
111/// by construction.
112pub mod types {
113 pub use fialucci_types::{
114 derive_oracle_id, hash_evidence_bytes, OracleId, OracleObservationRequestId,
115 OraclePublicKeyBytes, OracleSignatureBytes, ProofClaim, ProofDomain, ProofEvidence,
116 ProofSubject,
117 };
118}
119
120/// Allora-flavored EIP integration. Enabled by the `allora` feature
121/// (`fialucci-oracle = { version = "...", features = ["allora"] }`).
122///
123/// Re-exports the EIP Outbound Channel Adapter that drops into an Allora
124/// `service-activators:` block via `ref-name: fialucci_oracle_adapter`.
125/// See the module-level docs on [`FialucciOracleAdapter`] for the full
126/// Adapter-vs-Gateway design rationale.
127#[cfg(feature = "allora")]
128pub mod allora {
129 pub use crate::allora_adapter::{
130 AdapterAck, FialucciOracleAdapter, FialucciOracleSigner, OracleClaimPayload,
131 };
132}