Visual Guide to Pool Interactions

This guide provides a visual and conceptual overview of how pools operate and interact within the Riskify platform. It is designed to help users, developers, and risk managers understand the structure, flows, and integration points of different pool types, risk transfer mechanisms, and monitoring systems.

Pool Architecture Overview

The following diagram illustrates the main types of pools in Riskify and how they are connected. Structured pools are divided into tranches, cross pools aggregate risk across pools, and passive pools provide liquidity and yield generation.

graph TD
    subgraph Structured Pools
        S1[Senior Tranche]
        S2[Mezzanine Tranche]
        S3[Junior Tranche]
    end
    
    subgraph Cross Pools
        C1[Cross Pool A]
        C2[Cross Pool B]
    end
    
    subgraph Passive Pools
        P1[Passive Structured]
        P2[Passive Cross]
    end
    
    S1 --> C1
    S2 --> C1
    S3 --> C2
    C1 --> P1
    C2 --> P2
    P1 --> P2

Diagram: Pool architecture in Riskify. Structured pools are split by risk tier, cross pools aggregate risk, and passive pools provide liquidity and yield.

Risk Transfer Mechanisms

Risk can be transferred between pools using direct or bundled flows. The following diagrams and code illustrate these mechanisms.

1. Direct Transfer Flow

This sequence diagram shows the step-by-step process of transferring risk from one pool to another, including validation, collateral locking, and confirmation.

sequenceDiagram
    participant Source Pool
    participant Risk Manager
    participant Target Pool
    
    Source Pool->>Risk Manager: Request Transfer
    Risk Manager->>Risk Manager: Validate Compatibility
    Risk Manager->>Target Pool: Check Capacity
    Target Pool-->>Risk Manager: Confirm Capacity
    Risk Manager->>Source Pool: Lock Collateral
    Risk Manager->>Target Pool: Transfer Risk
    Target Pool-->>Risk Manager: Confirm Transfer
    Risk Manager-->>Source Pool: Complete Transfer

Diagram: Direct risk transfer between pools, managed by a risk manager who validates and executes the transfer.

2. Bundle Transfer Example

This code example demonstrates how a bundle of risk positions can be transferred from a structured pool to a cross pool, with optimization and validation steps.

// Bundle configuration
const riskBundle = {
    sourcePool: {
        id: 1,
        type: PoolType.STRUCTURED,
        positions: [
            { trancheId: 1, amount: 100000, risk: 1500 }, // 15% risk
            { trancheId: 2, amount: 50000, risk: 2000 },  // 20% risk
            { trancheId: 3, amount: 25000, risk: 3000 }   // 30% risk
        ]
    },
    targetPool: {
        id: 2,
        type: PoolType.CROSS,
        capacity: 500000,
        currentUtilization: 300000
    },
    optimization: {
        maxRisk: 2500,        // 25% max risk
        minDiversification: 7000, // 70% min diversification
        targetYield: 1200     // 12% target yield
    }
};

// Bundle transfer execution
async function transferBundle(bundle) {
    // 1. Calculate optimal distribution
    const distribution = await calculateOptimalDistribution(bundle);
    
    // 2. Validate capacity and risk limits
    const validation = await validateTransfer(distribution);
    
    // 3. Execute transfer if valid
    if (validation.isValid) {
        return await executeTransfer(distribution);
    }
    
    return validation.errors;
}

Example: Transferring a bundle of risk positions between pools, with optimization and validation for risk and yield targets.

Pool State Transitions

Pools can change state based on risk events, emergencies, or operational triggers. The following state diagram shows the possible transitions for a pool.

stateDiagram-v2
    [*] --> Active
    Active --> UnderReview: Risk Threshold Breach
    Active --> Frozen: Emergency Trigger
    UnderReview --> Active: Risk Normalized
    UnderReview --> Frozen: Risk Escalation
    Frozen --> Active: Emergency Resolved
    Frozen --> Closed: Unrecoverable
    Closed --> [*]

Diagram: Pool lifecycle states, including active, under review, frozen, and closed, with transitions based on risk and emergency events.

Cross-Chain Risk Propagation

Riskify supports risk transfer and pool interactions across multiple blockchains. The diagram below shows how pools on different chains can be bridged for risk propagation.

graph LR
    subgraph Chain A
        A1[Pool A1]
        A2[Pool A2]
    end
    
    subgraph Chain B
        B1[Pool B1]
        B2[Pool B2]
    end
    
    subgraph Chain C
        C1[Pool C1]
        C2[Pool C2]
    end
    
    A1 -->|Bridge| B1
    B1 -->|Bridge| C1
    A2 -->|Bridge| C2
    
    style A1 fill:#f9f,stroke:#333,stroke-width:2px
    style B1 fill:#bbf,stroke:#333,stroke-width:2px
    style C1 fill:#bfb,stroke:#333,stroke-width:2px

Diagram: Cross-chain risk propagation, where pools on different blockchains are connected via bridges for risk transfer and diversification.

Passive Pool Integration

Passive pools provide liquidity, absorb excess risk, and generate yield. The following diagrams and code show how passive pools interact with active pools and manage risk.

1. Passive Pool Structure

This diagram shows the flow of risk and yield between active and passive pools, and how risk buffers and yield generation are managed.

graph TD
    subgraph Passive Pool
        A[Liquidity Pool]
        B[Risk Buffer]
        C[Yield Generation]
    end
    
    subgraph Active Pools
        D[Structured Pool]
        E[Cross Pool]
    end
    
    D -->|Risk Transfer| A
    E -->|Risk Transfer| A
    A -->|Excess Risk| B
    A -->|Yield| C
    C -->|Returns| A

Diagram: Passive pool integration, showing how liquidity, risk, and yield flow between active and passive pools.

2. Passive Pool Example

This code example demonstrates how a passive pool is configured and how risk acceptance is validated for incoming transfers.

// Passive pool configuration
const passivePoolConfig = {
    pool: {
        id: 1,
        capacity: 1000000,
        utilizationTarget: 8000, // 80%
        riskLimit: 2000,        // 20%
        yieldTarget: 1000       // 10%
    },
    riskAcceptance: {
        maxPerTransfer: 100000,
        minCollateralization: 1200, // 120%
        cooldownPeriod: 86400,     // 1 day
        maxConcentration: 2000     // 20%
    },
    autoManagement: {
        rebalanceThreshold: 500,   // 5% deviation
        harvestThreshold: 1000,    // 10% yield
        reinvestThreshold: 500     // 5% excess liquidity
    }
};

// Risk acceptance validation
function validateRiskAcceptance(transfer) {
    const {
        amount,
        sourcePool,
        currentUtilization,
        riskScore
    } = transfer;
    
    return {
        isValid: 
            amount <= passivePoolConfig.riskAcceptance.maxPerTransfer &&
            currentUtilization <= passivePoolConfig.pool.utilizationTarget &&
            riskScore <= passivePoolConfig.pool.riskLimit,
        reason: 'Validation successful'
    };
}

Example: Passive pool configuration and risk acceptance logic for managing incoming risk transfers.

Risk Monitoring Dashboard

Riskify provides monitoring tools to track pool utilization, risk levels, and yield performance. The following diagram shows how data is collected, monitored, and used to generate alerts.

graph TD
    subgraph Monitoring System
        A[Risk Data Collector]
        B[Pool State Monitor]
        C[Alert Generator]
        
        subgraph Metrics
            D[Pool Utilization]
            E[Risk Levels]
            F[Yield Performance]
        end
        
        subgraph Alerts
            G[Capacity Alerts]
            H[Risk Alerts]
            I[Performance Alerts]
        end
        
        A --> B
        B --> D
        B --> E
        B --> F
        D --> G
        E --> H
        F --> I
    end

Diagram: Risk monitoring dashboard, showing how pool metrics are tracked and alerts are generated for capacity, risk, and performance.

Integration Example

This code example shows how to integrate a new pool into the Riskify system, including validation, risk transfer, and monitoring setup.

// Pool integration example
class PoolIntegration {
    constructor(config) {
        this.riskManager = new RiskManager(config);
        this.poolManager = new PoolManager(config);
        this.monitor = new PoolMonitor(config);
    }
    
    async integratePool(sourcePool, targetPool) {
        // 1. Validate compatibility
        const compatibility = await this.validateCompatibility(
            sourcePool,
            targetPool
        );
        
        if (!compatibility.isValid) {
            throw new Error(compatibility.reason);
        }
        
        // 2. Calculate optimal risk transfer
        const transfer = await this.calculateOptimalTransfer(
            sourcePool,
            targetPool
        );
        
        // 3. Execute integration
        const result = await this.executeIntegration(transfer);
        
        // 4. Set up monitoring
        await this.setupMonitoring(result.integrationId);
        
        return result;
    }
    
    async validateCompatibility(source, target) {
        // Implementation details
    }
    
    async calculateOptimalTransfer(source, target) {
        // Implementation details
    }
    
    async executeIntegration(transfer) {
        // Implementation details
    }
    
    async setupMonitoring(integrationId) {
        // Implementation details
    }
}

Example: Integrating a new pool, including validation, risk transfer, and monitoring setup for ongoing management.