> For the complete documentation index, see [llms.txt](https://docs.yolkfi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yolkfi.com/02.-technical-architecture/oracle-bridge.md).

# Oracle & Real-World Data Bridge

The YolkFi Oracle acts as the secure, deterministic data bridge between industrial farm automation and Soroban.

***

### Data Ingestion Architecture

* **Big Dutchman Telemetry:** Daily active hen population, egg collection counts, environmental telemetry, feed consumption, and mortality logs.
* **Commercial ERP (AT Grup):** Invoiced egg sales volume, average realized wholesale price per egg, and batch operating deductions.

***

### Strongly Typed Soroban Report Struct

```rust
/// Submitted by the Oracle Worker to Soroban
#[contracttype]
pub struct ProductionCycleReport {
    pub cycle_id: Bytes,              // e.g., "S1-2026-11-20"
    pub batch_id: Bytes,              // e.g., "YOLK-S1"
    pub farm_id: Bytes,               // e.g., "AT-GRUP-01"
    pub period_start: u64,            // Unix timestamp
    pub period_end: u64,              // Unix timestamp
    pub eligible_egg_volume: u64,     // Total eggs gathered in period
    pub flock_count: u64,             // Active laying hens count
    pub eligible_sales_volume: u64,   // Commercial eggs sold
    pub eligible_revenue: i128,       // Revenue in stroops (1 USDC = 10^7 stroops)
    pub data_hash: BytesN<32>,        // SHA-256 hash of raw ERP/telemetry data
    pub oracle_signature: BytesN<64>, // Ed25519 cryptographic signature
    pub oracle_pubkey: BytesN<32>,    // Registered Oracle public key
}
```

***

### Validation Rules & Sanity Bounds

Before submission or finalization on-chain, the report must satisfy deterministic constraints:

| Validation Rule           | Threshold / Condition                               | Action on Failure           |
| ------------------------- | --------------------------------------------------- | --------------------------- |
| **Data Staleness**        | Timestamp age > 36 hours                            | Immediate Rejection         |
| **Consistency Check**     | `eligible_sales_volume` > `eligible_egg_volume`     | Immediate Rejection         |
| **Flock Size Deviation**  | Flock count deviates > 10% from previous cycle      | Flagged for Manual Review   |
| **Revenue Inconsistency** | Revenue = 0 when sales volume > 0                   | Immediate Rejection         |
| **Replay Protection**     | `cycle_id` already finalized on-chain               | Immediate Rejection         |
| **Signature Check**       | Ed25519 verification against authorized oracle keys | Transaction Panics & Aborts |

***

### On-Chain Cryptographic Verification

```rust
// Native Soroban Ed25519 signature verification
env.crypto().ed25519_verify(
    &report.oracle_pubkey,   // BytesN<32>
    &serialized_payload,     // Bytes (SHA-256 payload preimage)
    &report.oracle_signature // BytesN<64>
);
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.yolkfi.com/02.-technical-architecture/oracle-bridge.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.