Split Risk Pool

The Split Risk Pool is the core component of YieldShield's insurance architecture. Each pool manages risk allocation and capital distribution for a specific pair of insured and underwriter tokens.

Overview

A Split Risk Pool creates an insurance relationship between two types of participants:

  • Insured Users: Deposit yield-bearing tokens to receive protection against value loss
  • Underwriters: Deposit collateral tokens to earn commission from the yield generated by insured assets

The pool manages deposits, withdrawals, yield distribution, and ensures that underwriter collateral is always sufficient to cover insured deposits.

Core Data Structures

InsuredDeposit

Tracks each insured user's deposit:

  • amount: Current insured token balance in the pool (reduces as fees are claimed)
  • poolTime: Timestamp when the deposit was made (used for yield calculations)
  • underwriterAddress: Address of the matched underwriter providing collateral
  • isWithdrawn: Flag indicating if the deposit has been withdrawn
  • assetsInVault: Base assets in the vault for yield calculation
  • valueOfDeposit: USD value of the deposit at time of deposit (for cross-asset withdrawals)

UnderwriterDeposit

Tracks each underwriter's collateral:

  • amount: Total underwriter tokens deposited
  • lockedAmount: Amount currently locked as collateral for insured deposits
  • lockedUntil: Timestamp when tokens will be unlocked (0 = unlocked, 1 = locked but unlock not started)
  • commissionAmount: Accumulated commission from yield (can be claimed via payCommission)

PoolConfig

Governance-controlled pool parameters:

  • minDepositAmount: Minimum deposit allowed
  • maxDepositAmount: Maximum single deposit
  • maxTotalValueLocked: Maximum total value locked in the pool
  • minimumPoolTime: Minimum time assets must stay before withdrawal (for underwriter token withdrawals)
  • unlockDuration: Duration of the unlock period for underwriter withdrawals
  • protocolFee: Protocol fee rate (basis points)
  • protocolFeeRecipient: Address receiving protocol fees
  • priceOracle: Oracle contract for token valuations

PoolState

Current pool balances:

  • insuredTokenBalance: Total insured tokens held in the pool
  • totalUnderwriteTokenBalance: Sum of all underwriter token balances

Main Operations

Deposits

depositUnderwriteAsset: Underwriters deposit collateral tokens

  • Validates deposit amount and TVL limits
  • Mints underwriter receipt tokens (1:1 ratio)
  • Tracks underwriter addresses for iteration

depositInsuredAsset: Insured users deposit assets to be protected

  • Requires an underwriter with sufficient unlocked collateral
  • Locks underwriter tokens as collateral (based on collateral ratio)
  • Calculates and stores USD value of deposit
  • Mints insured receipt tokens (1:1 ratio)
  • Enforces rate limiting (cooldown between deposits)

Withdrawals

insuredWithdraw: Insured users withdraw their deposits

  • Can choose to receive insured tokens (with yield minus fees) or underwriter tokens (principal only)
  • If withdrawing underwriter tokens, must wait for minimumPoolTime
  • Calculates and distributes fees (commission, pool fee, protocol fee)
  • Unlocks corresponding underwriter collateral
  • Burns receipt tokens

underwriterWithdraw: Underwriters withdraw their collateral

  • Can only withdraw unlocked tokens
  • Must start unlock process first (startUnlockProcess) if tokens are locked
  • Enforces rate limiting (cooldown between withdrawals)
  • Burns receipt tokens

startUnlockProcess: Initiates the unlock period for underwriter tokens

  • Sets lockedUntil timestamp based on unlockDuration
  • Required before withdrawing locked tokens

Yield and Fees

claimRewards: Claims accumulated yield and updates deposit state

  • Calculates yield earned since last claim
  • Distributes yield as: commission (to underwriter), pool fee (to pool creator), protocol fee (to protocol)
  • Updates valueOfDeposit with latest oracle price
  • Reduces deposit amount by fees
  • Can be called by anyone for any deposit

payPoolFee: Pool creator claims accumulated pool fees

  • Transfers accumulated pool fees to pool creator
  • Reduces pool's insured token balance

payProtocolFee: Protocol claims accumulated protocol fees

  • Transfers accumulated protocol fees to protocol recipient
  • Reduces pool's insured token balance

payCommission: Underwriter claims accumulated commission

  • Transfers accumulated commission to underwriter
  • Reduces pool's insured token balance

Rate Limiting

The pool implements per-address rate limiting using RateLimitLib:

  • Insured Deposit Cooldown: Prevents rapid successive deposits by the same user
  • Underwriter Withdraw Cooldown: Prevents rapid withdrawals by underwriters
  • Configurable intervals (can be set to 0 to disable)
  • Enforced per-address, allowing different users to operate independently

Access Control

Pools can optionally implement access control through the IPoolAccessControl interface:

  • Pool creator can set an access control contract
  • If set, all deposit/withdraw operations check permissions
  • If address(0), no restrictions (public pool)
  • Allows for private pools with custom access logic

Receipt Tokens

Each pool mints two types of receipt tokens using the Tranche contract:

  • INSURED_RECEIPT_TOKEN: Represents insured deposits (1:1 with deposited amount)
  • UNDERWRITER_RECEIPT_TOKEN: Represents underwriter collateral (1:1 with deposited amount)

Receipt tokens are ERC20 tokens with permit support, allowing for gasless approvals and integration with other DeFi protocols.

Supporting Components

Libraries

  • SlippageLib: Enforces minimum received amounts for slippage protection
  • ErrorsLib: Custom errors for gas-efficient error handling
  • EventsLib: Standardized events for off-chain indexing
  • ConstantsLib: Protocol-wide constants (basis point scale, limits, etc.)

Base Contract

  • ProtocolAccessControlUpgradeable: Provides governance controls, pausable functionality, and reentrancy protection

Interfaces

  • ISplitRiskPool: Defines the public interface for pool interactions
  • ITranche: Interface for receipt token minting/burning
  • IPriceOracle: Interface for token price and valuation queries

Upgradeability

Pools are deployed as UUPS (Universal Upgradeable Proxy Standard) proxies, allowing for:

  • Future improvements without losing state
  • Governance-controlled upgrades
  • Implementation contract updates

The pool implementation contract is immutable, while the proxy can be upgraded by governance.