IPoolAllocations

Interface for capital allocation tracking per syndicate.

The IPoolAllocations is the data contract that stores allocation state for underwriters. It tracks pledges, intent reservations, cooldowns, and coordinates with the reward system. This is the internal state contract, distinct from IPoolAllocationManager which is the user-facing entry point.

Interface

// SPDX-License-Identifier: BUSL-1.1
pragma solidity ^0.8.20;

import {Types} from "../libraries/helpers/Types.sol";
import {IYieldStrategyManager} from "./IYieldStrategyManager.sol";

/**
 * @title IPoolAllocations
 * @author LayerCover Protocol
 * @notice Interface for PoolAllocations - the internal state contract for underwriter pool allocations
 * @dev This is the DATA CONTRACT that stores allocation state (pledges, intents, cooldowns).
 *      NOT to be confused with IPoolAllocationManager, which is the USER-FACING contract
 *      that Syndicates call to deposit/allocate/deallocate (and delegates to this).
 * 
 * Relationship:
 * - IPoolAllocationManager: User-facing allocation actions (syndicates call this)
 * - IPoolAllocations: Internal state storage + validation (PoolAllocationManager calls this)
 */
interface IPoolAllocations {
    // ===== Structs for Bundled Views =====
    struct UnderwriterPoolView {
        uint256 pledge;
        uint256 intentAllocation;
        uint256 syndicateCap;
        uint64 lastCoverageExpiry;
        uint64 withdrawableAfter;
    }

    struct PoolAllocationView {
        uint256 totalCapitalPledged;
        uint256 capitalPendingWithdrawal;
        uint256 capitalAllocatedToIntents;
        uint256 underwriterCount;
        address[] activeAdapters;
        uint256[] capitalPerAdapter;
    }

    // ===== Initialization =====
    function initialize(
        address systemRegistry
    ) external;

    // ===== Configuration (Bundled) =====
    function configureAllocationLimits(Types.AllocationLimitsConfig memory config) external;
    function setPoolMutexGroup(uint256[] calldata poolIds, uint256 groupId) external;

    // ===== Coordination (PoolAllocationManager) =====
    function validatePoolAllocation(
        address underwriter,
        uint256[] calldata poolIds,
        uint256[] calldata amounts
    ) external view;

    function recordPoolAllocation(
        address underwriter,
        uint256 poolId,
        uint256 amount,
        address adapter
    ) external;

    function recordPoolDeallocation(
        address underwriter,
        uint256 poolId,
        uint256 deallocAmount,
        uint256 newPledge,
        address adapter
    ) external;

    function removeUnderwriterFromPool(address underwriter, uint256 poolId) external;
    function settleRewardsSingleCut(
        address user,
        uint256 poolId,
        uint256 basePledge,
        uint48 cutTime,
        uint256 postCutPledge
    ) external;
    function settleAllUserRewards(address user) external;

    // ===== Capital Hooks =====
    function onCapitalDeposited(address underwriter, uint256 amount) external;
    function onCapitalWithdrawn(address underwriter, uint256 principalComponentRemoved, bool isFullWithdrawal)
        external;
    function onLossRealized(address underwriter, uint256 principalComponentReduced) external;

    // ===== Intent Lifecycle (merged from IntentAllocations) =====
    function allocateIntentCapital(
        address underwriter,
        uint256 poolId,
        uint256 coverageAmount,
        uint32 coverageDuration,
        bytes32 reservationKey
    ) external returns (uint256 reservedShares);

    function releaseIntentCapital(
        address underwriter,
        uint256 poolId,
        uint256 coverageAmount,
        bytes32 reservationKey
    ) external;

    function transitionIntentToPolicy(
        address underwriter,
        uint256 poolId,
        uint256 coverageAmount
    ) external;

    function recordPolicyCoverageSettled(
        address underwriter,
        uint256 poolId,
        uint256 coverageAmount
    ) external;

    // ===== Bundled Views =====
    function getUnderwriterPoolDetailedView(address underwriter, uint256 poolId) external view returns (UnderwriterPoolView memory);
    function getPoolAllocationDetails(uint256 poolId) external view returns (PoolAllocationView memory);

    // ===== Helper Views =====
    function getUnderwriterAllocations(address user) external view returns (uint256[] memory);
    function getTotalCapitalPledgedToPool(uint256 poolId) external view returns (uint256);
    function getCapitalAllocatedToIntents(uint256 poolId) external view returns (uint256);
    function getCapitalPendingWithdrawal(uint256 poolId) external view returns (uint256);
    function getPledge(address user, uint256 poolId) external view returns (uint256);
    function isAllocatedToPool(address user, uint256 poolId) external view returns (bool);
    function getUnderwriterRiskPointsUsed(address user) external view returns (uint256);
    function getUnpledgedCapital(address user) external view returns (uint256 unpledgedCapital, uint256 totalPledged);
    function getAvailableCapital(address user, uint256 poolId) external view returns (uint256);
    
    function getSyndicatePoolCap(address syndicate, uint256 poolId) external view returns (uint256); // Often used in UI, maybe keep for ease? Or force use of detailed view? Plan says remove.
    function setSyndicatePoolCap(address syndicate, uint256 poolId, uint256 cap) external;

    // ===== Cooldown Helpers =====
    // getWithdrawableAfter -> bundled
    // getLastCoverageExpiry -> bundled
    function canWithdrawFromPool(address underwriter, uint256 poolId) external view returns (bool);

    // ===== Config Getters =====
    function getRewardDistributor() external view returns (address);
    function getPoolRegistry() external view returns (address);
    function getCapitalPool() external view returns (address);
    function getMaxAllocationsPerUnderwriter() external view returns (uint256);
    function getMaxLeverageRatio() external view returns (uint256);

    function cooldownPeriod() external view returns (uint64);
    function effectiveCooldown(address syndicate) external view returns (uint64);
    function setSyndicateCooldownOverride(address syndicate, uint64 cooldown) external;
    function maxExposurePerPoolBps() external view returns (uint16);

    function poolAllocationManager() external view returns (address);
    function getStrategyManager() external view returns (IYieldStrategyManager);
    function intentMatcher() external view returns (address);

    // ===== Governance Rebalance =====
    function forceRebalanceExposure(address underwriter) external;
    function forceResolveMutexConflict(address underwriter, uint256 poolIdToRemove) external;
}

Related Documentation

• ISyndicate - Uses allocations for underwriting
• IIntentMatcher - Creates intent reservations
• Syndicates - Capital allocation concept