Architecture Overview

YieldShield's architecture is designed to provide a decentralized, capital-efficient insurance protocol for DeFi. The system consists of several key components that work together to create a robust insurance infrastructure.

System Components

The YieldShield protocol is built on a modular architecture with the following core components:

Split Risk Pool

The Split Risk Pool is the fundamental building block of YieldShield. Each pool manages risk allocation and capital distribution for a specific pair of insured and underwriter tokens. Pools handle deposits, withdrawals, yield distribution, and claims processing through a decentralized mechanism.

Split Risk Pool Factory

The Factory contract is responsible for creating and managing Split Risk Pool instances. It ensures proper initialization, maintains a registry of all active pools, and manages token whitelisting. All pools are deployed as upgradeable proxies, allowing for future improvements while maintaining state.

Yield Bearing Token Adapter

The Adapter system provides a standardized interface for integrating different types of yield-bearing tokens (ERC4626, Aave, and others) into the YieldShield ecosystem. This abstraction layer allows the protocol to work with various DeFi protocols seamlessly.

YS Governor

The Governance contract manages protocol-level parameters and upgrades through a decentralized voting mechanism. It uses OpenZeppelin's Governor pattern with timelock controls to ensure secure, transparent governance.

Pool Access Control

The Access Control system allows pool creators to optionally restrict who can deposit and withdraw from their pools. This mechanism provides flexibility for private pools (e.g. KYC requirements) while maintaining the open nature of public pools.

Protocol Flow

1. Token Whitelisting: Governance whitelists tokens that can be used in pools
2. Pool Creation: Users create insurance pools through the Factory contract, specifying insured and underwriter tokens
3. Capital Allocation: Underwriters deposit collateral, and insured users deposit assets to be protected
4. Yield Generation: Assets generate yield over time, which is shared between underwriters (commission) and protocol (fees)
5. Claims Processing: If an insured event occurs, users can withdraw their principal from the underwriter's collateral
6. Reward Distribution: Yield is distributed through a fee structure (commission, pool fee, protocol fee)

Component Interactions

The diagram above illustrates how the core components interact:

• Factory creates and manages Pool instances
• Pool uses Adapter for yield calculations
• Pool uses Access Control for optional restrictions
• Pool uses Price Oracle for token valuations
• Governance controls the Factory (token whitelisting, pool parameters)

Key Design Principles

• Upgradeability: Core contracts use UUPS proxy pattern for future improvements
• Modularity: Libraries and interfaces allow for flexible composition
• Security: Multiple layers of access control, rate limiting, and validation
• Capital Efficiency: Optimized storage layouts and gas-efficient operations
• Transparency: All operations are on-chain and verifiable

Documentation Structure

This architecture section provides detailed documentation for each component:

• Split Risk Pool: Core pool contract managing deposits, withdrawals, and yield distribution
• Split Risk Pool Factory: Factory contract for pool creation and token management
• Yield Bearing Token Adapter: Adapter library for yield-bearing token integration
• YS Governor: Governance contract for protocol parameter management
• Pool Access Control: Access control interface for pool-level restrictions