// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/**
 * @title IReserveAggregator
 * @dev Interface for reserve aggregation from multiple custodians
 */
interface IReserveAggregator {
    struct CustodianInfo {
        string name;
        address oracle;
        uint256 lastUpdateTime;
        uint256 heartbeat; // maximum staleness in seconds
        bool isActive;
        uint8 custodianType; // 0=bank, 1=crypto, 2=fund_admin
    }

    struct ReserveAttestation {
        uint256 balance;
        uint256 timestamp;
        bytes32 documentHash;
        address attestor;
        bool isValid;
    }

    /**
     * @dev Get total reserve value across all active custodians
     * @return totalValue Total reserve value in token denomination
     * @return isValid Whether all required custodian data is current
     */
    function getTotalReserveValue() external view returns (uint256 totalValue, bool isValid);

    /**
     * @dev Get reserve value from specific custodian
     * @param custodianId Unique identifier for custodian
     * @return value Reserve value from this custodian
     * @return isValid Whether this custodian's data is current
     */
    function getCustodianReserveValue(bytes32 custodianId) external view returns (uint256 value, bool isValid);

    /**
     * @dev Get custodian information
     * @param custodianId Unique identifier for custodian
     */
    function getCustodianInfo(bytes32 custodianId) external view returns (CustodianInfo memory);

    /**
     * @dev Get latest attestation for a custodian
     * @param custodianId Unique identifier for custodian
     */
    function getLatestAttestation(bytes32 custodianId) external view returns (ReserveAttestation memory);

    /**
     * @dev Check if reserve data is stale for any custodian
     * @return isStale True if any custodian data exceeds heartbeat
     * @return staleCustodians Array of custodian IDs with stale data
     */
    function checkDataStaleness() external view returns (bool isStale, bytes32[] memory staleCustodians);

    // Events
    event CustodianAdded(bytes32 indexed custodianId, string name, address oracle);
    event CustodianUpdated(bytes32 indexed custodianId, address newOracle, uint256 newHeartbeat);
    event CustodianDeactivated(bytes32 indexed custodianId);
    event ReserveAttested(bytes32 indexed custodianId, uint256 balance, bytes32 documentHash);
    event StaleDataDetected(bytes32 indexed custodianId, uint256 lastUpdate, uint256 heartbeat);
}