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

/**
 * @title IRiscZeroVerifier
 * @notice Interface for RISC Zero STARK verifier integration
 * @dev This interface defines the standard RISC Zero verifier contract API
 *
 * **Production Deployment:**
 * Use RISC Zero's deployed verifier contract or deploy your own using
 * the RISC Zero SDK. This interface ensures compatibility with both options.
 *
 * **RISC Zero Resources:**
 * - Documentation: https://dev.risczero.com/
 * - Verifier Contracts: https://github.com/risc0/risc0/tree/main/bonsai/ethereum
 * - Bonsai Proving Service: https://dev.bonsai.xyz/
 */
interface IRiscZeroVerifier {
    /**
     * @notice Verify a RISC Zero STARK proof
     * @dev This is the main verification function called by belief attestation
     *
     * @param proof The STARK proof bytes generated by RISC Zero prover
     * @param imageId The image ID of the guest program (circuit identifier)
     * @param journalDigest The digest of the public outputs (public inputs hash)
     *
     * @return True if proof is valid, reverts if invalid
     *
     * **How This Works:**
     * 1. The guest program (ZK circuit) runs in RISC Zero zkVM
     * 2. Guest program produces a journal (public outputs)
     * 3. Prover generates STARK proof that program executed correctly
     * 4. This verifier checks the proof on-chain in ~61k gas
     *
     * **Image ID:**
     * The imageId uniquely identifies the guest program (ZK circuit).
     * It's the hash of the compiled RISC Zero program binary.
     * This ensures the proof was generated by the correct circuit.
     *
     * **Journal Digest:**
     * The journalDigest is keccak256(public_outputs).
     * For Vaultfire, this is: keccak256(abi.encode(beliefHash, proverAddress, epoch, moduleID))
     * The guest program must commit these exact values to its journal.
     */
    function verify(
        bytes calldata proof,
        bytes32 imageId,
        bytes32 journalDigest
    ) external view returns (bool);

    /**
     * @notice Get the verifier version
     * @return Version string of the RISC Zero verifier
     */
    function version() external view returns (string memory);
}
