Liquidity Pool

Piron Pools - Technical Architecture

System Architecture Overview

Piron Pools is built on a modular, enterprise-grade smart contract architecture designed for security, scalability, and regulatory compliance. The system separates concerns across multiple specialized contracts while maintaining seamless integration.

Core Contract System

┌─────────────────────────────────────────────────────────────────┐
│                    PIRON POOLS ECOSYSTEM                        │
└─────────────────────────────────────────────────────────────────┘

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  Frontend    │    │   Backend    │    │  Monitoring  │
│  Dashboard   │    │   Services   │    │   & Alerts   │
└──────┬───────┘    └──────┬───────┘    └──────┬───────┘
       │                   │                   │
       └─────────────────┬─┴─────────────────────┘
                         │
┌─────────────────────────▼─────────────────────────┐
│                SMART CONTRACT LAYER                │
├────────────────┬────────────────┬──────────────────┤
│  Access        │  Pool          │  Fund            │
│  Management    │  Management    │  Custody         │
│                │                │                  │
│ AccessManager  │ PoolFactory    │ PoolEscrow       │
│ FeeManager     │ PoolRegistry   │ Manager          │
│ PoolOracle     │ LiquidityPool  │                  │
└────────────────┴────────────────┴──────────────────┘
                         │
┌─────────────────────────▼─────────────────────────┐
│              INFRASTRUCTURE LAYER                  │
├────────────────┬────────────────┬──────────────────┤
│  Blockchain    │  Data Storage  │  External APIs   │
│                │                │                  │
│ Ethereum/L2    │ IPFS/Arweave   │ Price Feeds     │
│ EVM Compatible │ Event Indexing │ Compliance APIs │
└────────────────┴────────────────┴──────────────────┘

Smart Contract Specifications

Core Contracts

Contract
Purpose
Key Responsibilities
Status

Manager

Core business logic

Pool lifecycle, investment processing, returns calculation

✅ Active

LiquidityPool

ERC-4626 vault

User deposits/withdrawals, DeFi composability

✅ Active

PoolEscrow

Fund custody

Secure fund holding, manager-controlled releases

✅ Active

AccessManager

Role-based control

Time-delayed roles, emergency controls, hierarchical perms

✅ Active

PoolRegistry

Pool discovery

Asset approval, pool categorization, status tracking

✅ Active

PoolFactory

Pool creation

Standardized deployment, configuration validation

✅ Active

FeeManager

Fee handling

Fee calculation, manual collection, treasury management

⚠️ Standalone

PoolOracle

Data verification

Investment proof validation, external data feeds

🚧 Planned

Contract Relationships

┌─────────────┐    creates     ┌─────────────┐    registers    ┌─────────────┐
│PoolFactory  │──────────────▶│LiquidityPool│───────────────▶│PoolRegistry │
└─────────────┘                └─────────────┘                └─────────────┘
       │                              │                              │
       │ creates                      │ delegates                    │ validates
       ▼                              ▼                              ▼
┌─────────────┐    controls    ┌─────────────┐    queries      ┌─────────────┐
│ PoolEscrow  │◄──────────────│   Manager   │───────────────▶│AccessManager│
└─────────────┘                └─────────────┘                └─────────────┘
       ▲                                                              │
       │ releases funds                                               │ enforces
       └──────────────────────────────────────────────────────────────┘

Detailed Contract Architecture

1. Manager Contract - Core Business Logic

Purpose: Orchestrates all pool operations and enforces business rules

Key Components:

struct PoolData {
    PoolConfig config;           // Pool configuration
    PoolStatus status;          // Current pool state
    uint256 totalRaised;        // Total user deposits
    uint256 actualInvested;     // Amount actually invested by SPV
    uint256 totalDiscountEarned; // Discount earned (for discounted instruments)
    uint256 totalCouponsReceived; // Coupons received from SPV
    uint256 totalCouponsDistributed; // Coupons marked for distribution
    uint256 fundsWithdrawnBySPV; // Funds withdrawn by SPV for investment
    uint256 fundsReturnedBySPV;  // Funds returned by SPV at maturity
}

struct UserPoolData {
    uint256 depositTime;        // When user first deposited
    uint256 couponsClaimed;     // Coupons already claimed by user
}

State Management:

enum PoolStatus {
    FUNDING,           // Accepting deposits
    PENDING_INVESTMENT,// Awaiting SPV investment
    INVESTED,          // SPV has invested, earning returns
    MATURED,           // Investment matured, users can withdraw
    EMERGENCY          // Emergency state, refunds available
}

Critical Functions:

  • initializePool() - Initialize new pool configuration

  • handleDeposit() - Process user deposits with validation

  • handleWithdraw() - Route withdrawals based on pool status

  • closeEpoch() - Transition from FUNDING to PENDING_INVESTMENT

  • processInvestment() - Confirm SPV investment with slippage protection

  • processMaturity() - Handle instrument maturity and return distribution

2. LiquidityPool Contract - ERC-4626 Vault

Purpose: Standard vault interface for user interactions and DeFi composability

ERC-4626 Implementation:

contract LiquidityPool is ERC4626, ILiquidityPool, Pausable {
    IPoolManager public immutable manager;
    address public immutable escrow;

    // Core ERC-4626 functions
    function deposit(uint256 assets, address receiver) external returns (uint256 shares);
    function withdraw(uint256 assets, address receiver, address owner) external returns (uint256 shares);
    function totalAssets() external view returns (uint256);

    // Pool-specific functions
    function getUserReturn(address user) external view returns (uint256);
    function isInFundingPeriod() external view returns (bool);
    function getTimeToMaturity() external view returns (uint256);
}

Key Features:

  • Standard Compliance: Full ERC-4626 implementation for DeFi integration

  • Manager Delegation: All business logic delegated to Manager contract

  • Pausable: Emergency pause functionality for security

  • View Functions: Rich interface for frontend integration

3. PoolEscrow Contract - Secure Fund Custody

Purpose: Hold user funds securely and release them based on Manager instructions

Architecture:

contract PoolEscrow is IPoolEscrow, ReentrancyGuard, AccessControl {
    IERC20 public immutable asset;
    address public immutable manager;
    address public immutable spvAddress;

    // Fund tracking
    mapping(address => uint256) public deposits;
    uint256 public totalDeposits;
    uint256 public totalCouponPool;
    uint256 public totalMaturityReturns;

    // Large transfer detection
    uint256 public constant LARGE_TRANSFER_THRESHOLD = 100000e6; // $100K
}

Security Features:

  • Single Manager Control: Only Manager can authorize fund releases

  • Large Transfer Detection: Alerts for transfers > $100K

  • Comprehensive Tracking: Full audit trail of all fund movements

  • Emergency Mode: Lockdown capability for security incidents

4. AccessManager Contract - Role-Based Security

Purpose: Implement hierarchical role-based access control with time delays

Role Hierarchy:

bytes32 public constant DEFAULT_ADMIN_ROLE = 0x00;             // System administration
bytes32 public constant SPV_ROLE = keccak256("SPV_ROLE");      // Investment operations
bytes32 public constant OPERATOR_ROLE = keccak256("OPERATOR_ROLE"); // Pool operations
bytes32 public constant EMERGENCY_ROLE = keccak256("EMERGENCY_ROLE"); // Emergency controls
bytes32 public constant POOL_CREATOR_ROLE = keccak256("POOL_CREATOR_ROLE"); // Pool creation

Security Features:

  • Time Delays: 24-hour delay on critical role changes

  • Emergency Bypass: Immediate execution for emergency roles

  • Role Tracking: Complete audit log of role grants/revocations

  • Pausable System: Global pause capability

5. PoolRegistry Contract - Pool Discovery & Validation

Purpose: Centralized registry for pool discovery and asset validation

Core Data:

struct PoolInfo {
    address manager;           // Manager contract address
    address asset;            // Base asset (USDC)
    address escrow;           // Escrow contract address
    string instrumentType;    // "DISCOUNTED" or "INTEREST_BEARING"
    address creator;          // Pool creator address
    uint256 createdAt;       // Creation timestamp
    bool isActive;           // Active status
}

Functions:

  • registerPool() - Register new pools (Factory only)

  • approveAsset() - Approve assets for pool creation (Admin only)

  • updatePoolStatus() - Update pool active status (Operator only)

  • getPoolInfo() - Query pool information

  • isRegisteredPool() - Validate pool registration

6. PoolFactory Contract - Standardized Pool Creation

Purpose: Create pools with standardized configuration and validation

Creation Flow:

function createPool(PoolConfig memory config) external returns (address pool, address escrow) {
    // 1. Validate configuration
    require(config.targetRaise > 0 && config.targetRaise <= 100_000_000e6, "Invalid target");
    require(config.epochEndTime > block.timestamp, "Invalid epoch");
    require(config.maturityDate > config.epochEndTime, "Invalid maturity");

    // 2. Deploy contracts
    escrow = address(new PoolEscrow(config.asset, address(manager), config.spvAddress));
    pool = address(new LiquidityPool(IERC20(config.asset), name, symbol, address(manager), escrow));

    // 3. Register and initialize
    registry.registerPool(pool, poolInfo);
    manager.initializePool(pool, poolConfig);

    return (pool, escrow);
}

Validation Rules:

  • Target raise: $1K - $100M

  • Epoch duration: 1-30 days

  • Maturity: 30-365 days after epoch

  • Asset must be approved

  • SPV address must be valid

Security Architecture

Multi-Layer Security Model

┌─────────────────────────────────────────────────────────────┐
│                    SECURITY LAYERS                          │
├─────────────────────────────────────────────────────────────┤
│ Layer 1: Access Control & Role Management                  │
│ • Time-delayed role changes (24h)                          │
│ • Hierarchical permissions (Admin > SPV > Operator)        │
│ • Emergency pause mechanisms                               │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: Fund Custody & Segregation                        │
│ • Dedicated escrow contracts per pool                      │
│ • Manager-controlled fund releases                         │
│ • Automated fund tracking and reconciliation               │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: Economic Attack Prevention                        │
│ • Slippage protection (5% tolerance)                       │
│ • Minimum funding thresholds (50% of target)               │
│ • Large transfer detection ($100K threshold)               │
├─────────────────────────────────────────────────────────────┤
│ Layer 4: Smart Contract Security                           │
│ • Reentrancy protection on all external calls              │
│ • SafeERC20 for token interactions                         │
│ • Custom errors for gas efficiency                         │
├─────────────────────────────────────────────────────────────┤
│ Layer 5: Operational Security                              │
│ • Circuit breakers for unusual activity                    │
│ • Comprehensive event logging                              │
│ • Emergency mode activation                                │
└─────────────────────────────────────────────────────────────┘

Access Control Matrix

Role
Pool Creation
Investment Ops
Pool Management
Emergency Ops
System Config

Admin

✅

❌

✅

✅

✅

SPV

❌

✅

❌

❌

❌

Operator

❌

❌

✅

❌

❌

Emergency

❌

❌

✅

✅

❌

Creator

✅

❌

❌

❌

❌

Economic Security Measures

Slippage Protection:

// Fixed 5% tolerance on all investment amounts
uint256 minAmount = (expectedAmount * 9500) / 10000; // 5% below
uint256 maxAmount = (expectedAmount * 10500) / 10000; // 5% above
require(actualAmount >= minAmount && actualAmount <= maxAmount, "SlippageProtectionTriggered");

Minimum Funding Threshold:

// Pools must reach 50% of target to proceed to investment
uint256 minimumRaise = targetRaise * 50 / 100;
if (amountRaised >= minimumRaise) {
    status = PENDING_INVESTMENT;
} else {
    status = EMERGENCY; // Trigger refunds
}

Data Flow Architecture

Pool Lifecycle Data Flow

FUNDING PHASE
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    User     │───▶│LiquidityPool│───▶│   Manager   │
│  Deposits   │    │   (ERC4626) │    │ (Validation)│
└─────────────┘    └─────────────┘    └─────────────┘
                          │                   │
                          ▼                   ▼
                   ┌─────────────┐    ┌─────────────┐
                   │   Escrow    │    │Pool Registry│
                   │ (Custody)   │    │(Tracking)   │
                   └─────────────┘    └─────────────┘

INVESTMENT PHASE
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│     SPV     │───▶│   Manager   │───▶│   Escrow    │
│ (Investment)│    │(Processing) │    │(Release)    │
└─────────────┘    └─────────────┘    └─────────────┘
                          │
                          ▼
                   ┌─────────────┐
                   │Real-World   │
                   │ Investment  │
                   └─────────────┘

MATURITY PHASE
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│     SPV     │───▶│   Manager   │───▶│   Escrow    │
│ (Returns)   │    │(Distribution)│   │ (Release)   │
└─────────────┘    └─────────────┘    └─────────────┘
                          │
                          ▼
                   ┌─────────────┐
                   │    Users    │
                   │ (Withdraw)  │
                   └─────────────┘

Technical Implementation Details

Event Architecture

Comprehensive Logging:

// Pool lifecycle events
event PoolCreated(address indexed pool, string instrumentName, uint256 targetRaise);
event StatusChanged(PoolStatus oldStatus, PoolStatus newStatus);
event Deposit(address indexed pool, address indexed user, uint256 amount, uint256 shares);
event Withdraw(address indexed pool, address indexed user, uint256 amount, uint256 shares);

// Investment events
event SPVFundsWithdrawn(address indexed pool, uint256 amount, bytes32 transferId);
event InvestmentConfirmed(uint256 actualAmount, string proofHash);
event MaturityProcessed(uint256 finalAmount);

// Security events
event EmergencyExit(address indexed pool, uint256 timestamp);
event LargeTransferDetected(bytes32 indexed transferId, uint256 amount, uint256 threshold);
event SlippageProtectionActivated(address indexed pool, uint256 expected, uint256 actual);

Deployment Architecture

Contract Deployment Order

  1. AccessManager - Foundation for all access control

  2. PoolRegistry - Central registry for pool discovery

  3. Manager - Core business logic (depends on Registry + Access)

  4. PoolFactory - Pool creation (depends on Registry + Manager)

  5. FeeManager - Fee calculation (standalone, optional)

Configuration Dependencies

AccessManager
    ├── PoolRegistry (requires AccessManager)
    ├── Manager (requires Registry + AccessManager)
    ├── PoolFactory (requires Registry + Manager + AccessManager)
    └── FeeManager (requires AccessManager)
PreviousHow-To Guides

Last updated