> 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/overview.md).

# Architecture Overview

### Protocol Summary

* **Network:** Stellar Mainnet
* **Execution Environment:** Soroban Smart Contracts
* **Smart Contract Language:** Rust (Soroban SDK)
* **Primary Digital Asset:** Asset-Backed Hen NFTs (`HenNFT.rs`)
* **Settlement Assets:** USDC, EURC (Circle), EURCV (SG-FORGE), $YOLK
* **Initial Operational Partner:** AT Grup (Capacity: up to 30,000 laying hens for Season 1)

***

### Core Data & Value Flow

```
Investor
   │
   ▼
YolkFi Web Application (Next.js)
   │
   ├── Stellar Wallets Kit (Freighter, Lobstr, xBull, Ledger)
   └── Privy (Embedded Web2 Wallets + Ed25519 rawSign)
   │
   ▼
Hen NFT (Soroban Native)
   │  (1:1 digital representation)
   ▼
Physical Laying Hen
   │  (Contracted agricultural batch)
   ▼
Egg Production & Commercial Sales
   │
   ├── Big Dutchman IoT Telemetry (Production metrics)
   └── AT Grup Commercial ERP (Invoiced revenue)
   │
   ▼
YolkFi Oracle Worker Node
   │
   ├── Ingest & Normalize
   ├── Multi-Rule Sanity & Staleness Validation
   ├── Farm Operator Authorization
   └── Ed25519 Cryptographic Signing
   │
   ▼
Soroban Smart Contract Layer
   │
   ├── InvestorRegistry.rs (Layer-0 Compliance & Eligibility)
   ├── ProductionRegistry.rs (Batch Lifecycle Management)
   ├── YieldDistributor.rs (Oracle Signer Whitelisting & Yield Accounting)
   └── Treasury.rs (Multi-Sig Vault & Settlement)
   │
   ▼
$YOLK Settlement & Investor Claims
```

***

### Core Design Principles

1. **Physical Assets First:** Every Hen NFT digitally references a specific physical laying hen operating within an active, monitored commercial production batch.
2. **Real Production is the Source of Yield:** Yield originates strictly from verified commercial egg sales—not inflationary or speculative token minting.
3. **Deterministic On-Chain Accounting:** Once validated production and revenue parameters land on-chain, Soroban contract execution is fully deterministic.
4. **Off-Chain Telemetry, On-Chain Settlement:** Massive operational IoT sensor streams remain off-chain; Soroban maintains lean, auditable state proofs and financial settlement logic.
5. **Layer-0 Compliance:** Investor permissioning and eligibility checks occur before asset issuance or secondary transfers.

***

### Data Trust Model

The YolkFi architecture strictly isolates trust across three verifiable boundaries:

| Trust Domain                       | Entity / Layer                 | Responsibilities & Guarantees                                                                                                                                   |
| ---------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Domain 1: Physical World**       | AT Grup & Big Dutchman Systems | Maintains physical flock health, automated feeding, environmental climate control, commercial supermarket packaging, and invoiced sales records.                |
| **Domain 2: Cryptographic Oracle** | YolkFi Oracle Worker Node      | Ingests raw telemetry and ERP records, executes schema & anomaly checks, acquires farm operator authorization, and signs canonical reports via Ed25519.         |
| **Domain 3: Soroban Ledger**       | Stellar Smart Contracts        | Enforces Layer-0 investor eligibility, validates Ed25519 oracle signatures, executes deterministic revenue distribution math, and custodies claimable balances. |

> **The Honest Trust Boundary:** Soroban does not independently monitor physical hens; it cryptographically guarantees that only authenticated, authorized, and non-stale production reports from registered operational authorities can trigger financial distributions.

***

### Complete 17-Step Mainnet Data & Settlement Flow

```
 1. Big Dutchman automated climate & egg gathering telemetry collected
       ↓
 2. Production telemetry exported (egg counts, flock mortality, feed index)
       ↓
 3. AT Grup commercial accounting records invoiced sales & realized wholesale price
       ↓
 4. YolkFi Oracle Worker ingests and aggregates both datasets
       ↓
 5. Schema validation & mathematical range checks executed
       ↓
 6. Production reconciliation against historical cycle variance bounds
       ↓
 7. Farm operator signs off on the finalized reporting cycle
       ↓
 8. Canonical payload hashed (SHA-256) and signed with Oracle Ed25519 private key
       ↓
 9. Signed payload submitted to Soroban RPC via YieldDistributor transaction
       ↓
10. Contract verifies Oracle signature via env.crypto().ed25519_verify()
       ↓
11. Production cycle finalized on-chain and replay protection flag committed
       ↓
12. Deterministic 80/10/10 investor & protocol revenue splits calculated
       ↓
13. Treasury allocates settlement stablecoins (USDC/EURC) and routes $YOLK via Soroswap
       ↓
14. Per-hen claimable balances credited to verified Hen NFT holders
       ↓
15. DistributionFinalized contract events emitted to the Stellar ledger
       ↓
16. YolkFi indexer ingests contract events into PostgreSQL read replicas
       ↓
17. Real-time yield balances and production telemetry updated on investor web app
```


---

# 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/overview.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.