> 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/smart-contracts.md). # Smart Contract Suite The YolkFi Soroban smart contract suite is engineered in Rust using the Soroban SDK. The suite enforces a lean, modular dependency chain: **Compliance & Batch State → Asset Issuance → Oracle Ingestion → Yield Accounting → Settlement**. *** ### Contract Architecture Overview (6-Contract Modular Suite) To minimize cross-contract execution overhead, reduce state storage rent, and present an optimized attack surface for security auditors, oracle signer authorization is directly integrated into the `YieldDistributor.rs` governance instance: | Contract | Primary Responsibility | Storage Tier | | ----------------------- | --------------------------------------------------------------------------- | --------------------- | | `InvestorRegistry.rs` | Investor verification, KYC status, and transfer eligibility | Persistent / Instance | | `ProductionRegistry.rs` | Farm profiles, production batch registration, and lifecycle status | Persistent / Instance | | `HenNFT.rs` | Asset-backed Hen NFT minting, ownership records, and permissioned transfers | Persistent / Instance | | `YieldDistributor.rs` | Oracle authorization & rotation, yield calculation, and claimable balances | Persistent / Instance | | `Treasury.rs` | Multi-signature vault, stablecoin custody, and DEX execution authorization | Instance | | `$YOLK` SAC | Stellar Asset Contract implementing SEP-41 token standard | Native Stellar Asset | *** ### Contract Dependency Graph ``` ┌───────────────────────┐ │ InvestorRegistry.rs │ ◄── (Layer-0 Compliance & Whitelisting) └──────────┬────────────┘ │ (cross-contract is_eligible check) ▼ ┌───────────────────────┐ ┌────────────────────────┐ │ HenNFT.rs │ ◄──── │ ProductionRegistry.rs │ └──────────┬────────────┘ └───────────┬────────────┘ │ (token ownership proof) │ (batch parameters) ▼ ▼ ┌────────────────────────────────────────────────────────┐ │ YieldDistributor.rs │ │ - Built-in Oracle Key Governance & Key Rotation │ │ - Ed25519 Cryptographic Verification │ │ - Deterministic 80/10/10 Split Accounting │ └───────────────────────────▲────────────────────────────┘ │ (funds & swaps) ┌───────────┴────────────┐ │ Treasury.rs │ └───────────┬────────────┘ │ (SEP-41 SAC mint/swap) ▼ ┌────────────────────────┐ │ $YOLK / USDC Assets │ └────────────────────────┘ ``` *** ### 1. `InvestorRegistry.rs` (Layer-0 Compliance) Enforces regulatory compliance by gating NFT minting and secondary transfers without storing sensitive PII on-chain. ```rust pub fn register_investor(env: Env, investor: Address, status: InvestorStatus); pub fn revoke_investor(env: Env, investor: Address); pub fn set_status(env: Env, investor: Address, status: InvestorStatus); pub fn is_eligible(env: Env, investor: Address) -> bool; pub fn get_status(env: Env, investor: Address) -> InvestorStatus; ``` *** ### 2. `ProductionRegistry.rs` (Batch Management) Maintains the cryptographic link between on-chain batches and real-world farm production contracts. ```rust pub fn register_farm(env: Env, farm_id: Bytes, metadata_hash: Bytes); pub fn register_batch(env: Env, batch_id: Bytes, farm_id: Bytes, hen_count: u32, agreement_hash: Bytes); pub fn activate_batch(env: Env, batch_id: Bytes); pub fn pause_batch(env: Env, batch_id: Bytes); pub fn close_batch(env: Env, batch_id: Bytes); pub fn get_batch(env: Env, batch_id: Bytes) -> ProductionBatch; ``` *** ### 3. `HenNFT.rs` (Asset-Backed Livestock NFT) Implements the 1:1 digital representation of physical laying hens. Gated by `InvestorRegistry`. ```rust pub fn mint(env: Env, recipient: Address, token_id: u128, batch_id: Bytes, metadata_hash: Bytes); pub fn transfer(env: Env, from: Address, to: Address, token_id: u128); pub fn owner_of(env: Env, token_id: u128) -> Address; pub fn metadata(env: Env, token_id: u128) -> HenMetadata; pub fn burn(env: Env, token_id: u128); ``` > **Why Soroban-Native NFTs & SEP-50 Standards Alignment:** Hen NFTs are built natively on Soroban rather than as Classic Assets because they require rich metadata binding (batch ID, farm hash), programmable permission checks on transfer (`InvestorRegistry.is_eligible`), and programmatic lifecycle management. The interface is engineered to track the emerging **SEP-50 Non-Fungible Token standard** draft on Soroban and leverage OpenZeppelin Soroban token architecture primitives. *** ### 4. `YieldDistributor.rs` (Oracle Ingestion & Yield Accounting) Combines authorized Oracle signer management with proportional earnings calculations, signature verifications, and claimable balance tracking: ```rust // Oracle Authorization & Key Rotation pub fn add_oracle(env: Env, oracle_pubkey: BytesN<32>); pub fn remove_oracle(env: Env, oracle_pubkey: BytesN<32>); pub fn is_oracle_authorized(env: Env, oracle_pubkey: BytesN<32>) -> bool; // Financial Execution & Claims pub fn submit_production_cycle(env: Env, report: ProductionCycleReport); pub fn claim_yield(env: Env, investor: Address, token_id: u128) -> i128; pub fn get_claimable_yield(env: Env, investor: Address) -> i128; pub fn get_distribution_cycle(env: Env, cycle_id: Bytes) -> DistributionCycle; ``` *** ### 5. `Treasury.rs` (Multisig Custody & Execution) Custodies protocol and stablecoin liquidity, executes token conversions via approved DEX routers, and separates administrative permissions from everyday operational claims. ```rust pub fn deposit(env: Env, from: Address, token: Address, amount: i128); pub fn withdraw(env: Env, recipient: Address, token: Address, amount: i128); pub fn execute_swap(env: Env, router: Address, token_in: Address, token_out: Address, amount_in: i128, min_amount_out: i128); pub fn set_admin_multisig(env: Env, multisig_address: Address); pub fn get_treasury_balance(env: Env, token: Address) -> i128; ``` *** ### 6. `$YOLK` Stellar Asset Contract (SAC) The protocol yield settlement token is issued as a Stellar Classic Asset and wrapped via the native **Stellar Asset Contract (SAC)**. This hybrid design grants `$YOLK` out-of-the-box compatibility with the Stellar DEX (SDEX), low base fee transaction throughput, and direct Soroban smart contract programmability via the **SEP-41 Token Standard**. --- # 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/smart-contracts.md?ask=&goal= ``` `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.