// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.24;

/// @notice Verifies CFB attestations against caller-supplied expectations and freshness policy.
/// @dev `maxAgeMillis` is inclusive. Zero accepts only an observation whose `timeMillis` equals
///      `block.timestamp * 1000`.
interface ICfbVerifier {
    /// @notice Exact fixed-18 value fields the caller expects the signed payload to contain.
    struct ExpectedValue {
        string feedId;
        uint64 timeMillis;
        bool negative;
        uint128 magnitude;
        bytes32 commitmentNonce;
    }

    /// @notice Fixed-18 value fields returned after successful verification.
    struct VerifiedValue {
        string feedId;
        uint64 timeMillis;
        bool negative;
        uint128 magnitude;
        uint8 version;
    }

    /// @notice Exact generic scheme and chain-specific encoding envelope the caller expects.
    struct ExpectedData {
        string feedId;
        uint64 timeMillis;
        string encodeType;
        bytes chainEncodingEnvelope;
        bytes32 commitmentNonce;
    }

    /// @notice Authenticated signed header fields returned without interpreting the data commitment.
    struct VerifiedPayload {
        bytes32 feedIdHash;
        uint64 timeMillis;
        bytes32 schemeId;
        bytes32 dataCommitment;
        address primarySigner;
        address operationalKey;
        uint8 version;
    }

    /// @notice Native data and derived chain-encoding hashes returned after successful verification.
    struct VerifiedData {
        string feedId;
        uint64 timeMillis;
        string encodeType;
        bytes nativeEncodedData;
        bytes32 encodingId;
        bytes32 schemeId;
        bytes32 chainEncodingLeaf;
        bytes32 rawChainEncodingRoot;
        bytes32 wrappedChainEncodingRoot;
        uint8 version;
    }

    /// @notice Authenticates the signed payload and returns its opaque header and signer identities.
    function verifyPayload(bytes calldata payload, bytes calldata signature, uint64 maxAgeMillis)
        external
        view
        returns (VerifiedPayload memory);

    /// @notice Verifies the delegated certificate, feed membership, payload signature, expected fields, and age.
    function verifyValue(
        ExpectedValue calldata expected,
        bytes calldata payload,
        bytes calldata signature,
        uint64 maxAgeMillis
    ) external view returns (VerifiedValue memory);

    /// @notice Verifies an opaque native encoding against its exact generic scheme and signed root commitment.
    function verifyData(
        ExpectedData calldata expected,
        bytes calldata payload,
        bytes calldata signature,
        uint64 maxAgeMillis
    ) external view returns (VerifiedData memory);

    /// @notice Returns whether the payload is fully authenticated without interpreting its data commitment.
    /// @dev Reverts with `EnforcedPause` while paused. Otherwise returns false for every unproven
    ///      outcome, including malformed or invalid payloads and failures in the gas-bounded inner call.
    function isValidPayload(bytes calldata payload, bytes calldata signature, uint64 maxAgeMillis)
        external
        view
        returns (bool);
}