@enclave-e3/contracts 0.1.11 → 0.1.13

package/contracts/interfaces/IBondingRegistry.sol

@@ -173,6 +173,12 @@ interface IBondingRegistry {
      */
     function isActive(address operator) external view returns (bool);
 
+    /**
+     * @notice Get the number of currently active operators
+     * @return Number of active operators
+     */
+    function numActiveOperators() external view returns (uint256);
+
     /**
      * @notice Check if operator has deregistration in progress
      * @param operator Address of the operator

package/contracts/interfaces/ICiphernodeRegistry.sol

@@ -5,6 +5,9 @@
 // or FITNESS FOR A PARTICULAR PURPOSE.
 pragma solidity >=0.8.27;
 
+import { IEnclave } from "./IEnclave.sol";
+import { IBondingRegistry } from "./IBondingRegistry.sol";
+
 /**
  * @title ICiphernodeRegistry
  * @notice Interface for managing ciphernode registration and committee selection
@@ -16,7 +19,7 @@ interface ICiphernodeRegistry {
     /// @param initialized Whether the round has been initialized.
     /// @param finalized Whether the round has been finalized.
     /// @param requestBlock The block number when the committee was requested.
-    /// @param submissionDeadline The deadline for submitting tickets.
+    /// @param committeeDeadline The deadline for committee formation (ticket submission).
     /// @param threshold The M/N threshold for the committee ([M, N]).
     /// @param publicKey Hash of the committee's public key.
     /// @param seed The seed for the round.
@@ -24,12 +27,14 @@ interface ICiphernodeRegistry {
     /// @param committee The committee for the round.
     /// @param submitted Mapping of nodes to their submission status.
     /// @param scoreOf Mapping of nodes to their scores.
+    /// @param failed True if committee formation failed (threshold not met).
     struct Committee {
         bool initialized;
         bool finalized;
+        bool failed;
         uint256 seed;
         uint256 requestBlock;
-        uint256 submissionDeadline;
+        uint256 committeeDeadline;
         bytes32 publicKey;
         uint32[2] threshold;
         address[] topNodes;
@@ -43,13 +48,13 @@ interface ICiphernodeRegistry {
     /// @param seed Random seed for score computation.
     /// @param threshold The M/N threshold for the committee.
     /// @param requestBlock Block number for snapshot validation.
-    /// @param submissionDeadline Deadline for submitting tickets.
+    /// @param committeeDeadline Deadline for committee formation (ticket submission).
     event CommitteeRequested(
         uint256 indexed e3Id,
         uint256 seed,
         uint32[2] threshold,
         uint256 requestBlock,
-        uint256 submissionDeadline
+        uint256 committeeDeadline
     );
 
     /// @notice This event MUST be emitted when a ticket is submitted for sortition
@@ -69,6 +74,16 @@ interface ICiphernodeRegistry {
     /// @param committee Array of selected ciphernode addresses
     event CommitteeFinalized(uint256 indexed e3Id, address[] committee);
 
+    /// @notice This event MUST be emitted when committee formation fails (threshold not met)
+    /// @param e3Id ID of the E3 computation
+    /// @param nodesSubmitted Number of nodes that submitted tickets
+    /// @param thresholdRequired Minimum number of nodes required
+    event CommitteeFormationFailed(
+        uint256 indexed e3Id,
+        uint256 nodesSubmitted,
+        uint256 thresholdRequired
+    );
+
     /// @notice This event MUST be emitted when a committee is selected for an E3.
     /// @param e3Id ID of the E3 for which the committee was selected.
     /// @param publicKey Public key of the committee.
@@ -200,12 +215,12 @@ interface ICiphernodeRegistry {
     /// @notice Sets the Enclave contract address
     /// @dev Only callable by owner
     /// @param _enclave Address of the Enclave contract
-    function setEnclave(address _enclave) external;
+    function setEnclave(IEnclave _enclave) external;
 
     /// @notice Sets the bonding registry contract address
     /// @dev Only callable by owner
     /// @param _bondingRegistry Address of the bonding registry contract
-    function setBondingRegistry(address _bondingRegistry) external;
+    function setBondingRegistry(IBondingRegistry _bondingRegistry) external;
 
     /// @notice This function should be called to set the submission window for the E3 sortition.
     /// @param _sortitionSubmissionWindow The submission window for the E3 sortition in seconds.
@@ -220,11 +235,18 @@ interface ICiphernodeRegistry {
     function submitTicket(uint256 e3Id, uint256 ticketNumber) external;
 
     /// @notice Finalize the committee after submission window closes
+    /// @dev If threshold not met, marks E3 as failed and returns false
     /// @param e3Id ID of the E3 computation
-    function finalizeCommittee(uint256 e3Id) external;
+    /// @return success True if committee formed successfully, false if threshold not met
+    function finalizeCommittee(uint256 e3Id) external returns (bool success);
 
     /// @notice Check if submission window is still open for an E3
     /// @param e3Id ID of the E3 computation
     /// @return Whether the submission window is open
     function isOpen(uint256 e3Id) external view returns (bool);
+
+    /// @notice Get the committee deadline for an E3
+    /// @param e3Id ID of the E3 computation
+    /// @return committeeDeadline The committee deadline timestamp
+    function getCommitteeDeadline(uint256 e3Id) external view returns (uint256);
 }

package/contracts/interfaces/IE3.sol

@@ -16,9 +16,7 @@ import { IDecryptionVerifier } from "./IDecryptionVerifier.sol";
  * @param seed Random seed for committee selection and computation initialization
  * @param threshold M/N threshold for the committee (M required out of N total members)
  * @param requestBlock Block number when the E3 computation was requested
- * @param startWindow Start window for the computation: index 0 is minimum block, index 1 is the maximum block
- * @param duration Duration of the E3 computation in blocks or time units
- * @param expiration Timestamp when committee duties expire and computation is considered failed
+ * @param inputWindow When to start and stop accepting inputs from data providers
  * @param encryptionSchemeId Identifier for the encryption scheme used in this computation
  * @param e3Program Address of the E3 Program contract that validates and verifies the computation
  * @param e3ProgramParams ABI encoded computation parameters specific to the E3 program
@@ -33,9 +31,7 @@ struct E3 {
     uint256 seed;
     uint32[2] threshold;
     uint256 requestBlock;
-    uint256[2] startWindow;
-    uint256 duration;
-    uint256 expiration;
+    uint256[2] inputWindow;
     bytes32 encryptionSchemeId;
     IE3Program e3Program;
     bytes e3ProgramParams;

package/contracts/interfaces/IE3Program.sol

@@ -40,13 +40,9 @@ interface IE3Program {
     ) external returns (bool success);
 
     /// @notice Validate and process input data for a computation
-    /// @dev This function is called by the Enclave contract when input is published
+    /// @dev This function is called by data providers when they want to submit their
+    /// encrypted data
     /// @param e3Id ID of the E3 computation
-    /// @param sender The account that is submitting the input
     /// @param data The input data to be validated
-    function validateInput(
-        uint256 e3Id,
-        address sender,
-        bytes memory data
-    ) external;
+    function publishInput(uint256 e3Id, bytes memory data) external;
 }

package/contracts/interfaces/IE3RefundManager.sol

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+//
+// This file is provided WITHOUT ANY WARRANTY;
+// without even the implied warranty of MERCHANTABILITY
+// or FITNESS FOR A PARTICULAR PURPOSE.
+pragma solidity >=0.8.27;
+import { IEnclave } from "./IEnclave.sol";
+
+/**
+ * @title IE3RefundManager
+ * @notice Interface for E3 refund distribution mechanism
+ * @dev Handles refund calculation and claiming for failed E3s
+ */
+interface IE3RefundManager {
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                        Structs                         //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+    /// @notice Work value allocation in basis points (10000 = 100%)
+    struct WorkValueAllocation {
+        uint16 committeeFormationBps;
+        uint16 dkgBps;
+        uint16 decryptionBps;
+        uint16 protocolBps;
+    }
+    /// @notice Refund distribution for a failed E3
+    struct RefundDistribution {
+        uint256 requesterAmount; // Amount for requester
+        uint256 honestNodeAmount; // Total amount for honest nodes
+        uint256 protocolAmount; // Amount for protocol treasury
+        uint256 totalSlashed; // Slashed funds added
+        uint256 honestNodeCount; // Number of honest nodes
+        bool calculated; // Whether distribution is calculated
+    }
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                        Events                          //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+    /// @notice Emitted when refund distribution is calculated
+    event RefundDistributionCalculated(
+        uint256 indexed e3Id,
+        uint256 requesterAmount,
+        uint256 honestNodeAmount,
+        uint256 protocolAmount,
+        uint256 totalSlashed
+    );
+    /// @notice Emitted when a refund is claimed
+    event RefundClaimed(
+        uint256 indexed e3Id,
+        address indexed claimant,
+        uint256 amount,
+        bytes32 claimType
+    );
+    /// @notice Emitted when slashed funds are routed to E3
+    event SlashedFundsRouted(uint256 indexed e3Id, uint256 amount);
+    /// @notice Emitted when work allocation is updated
+    event WorkAllocationUpdated(WorkValueAllocation allocation);
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                        Errors                          //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+    /// @notice E3 is not in failed state
+    error E3NotFailed(uint256 e3Id);
+    /// @notice Refund already claimed
+    error AlreadyClaimed(uint256 e3Id, address claimant);
+    /// @notice Not the requester
+    error NotRequester(uint256 e3Id, address caller);
+    /// @notice Not an honest node
+    error NotHonestNode(uint256 e3Id, address caller);
+    /// @notice Refund not calculated yet
+    error RefundNotCalculated(uint256 e3Id);
+    /// @notice No refund available
+    error NoRefundAvailable(uint256 e3Id);
+    /// @notice Caller not authorized
+    error Unauthorized();
+
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                      Functions                         //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+    /// @notice Calculate refund distribution for a failed E3
+    /// @param e3Id The failed E3 ID
+    /// @param originalPayment The original payment amount
+    /// @param honestNodes Array of honest node addresses
+    function calculateRefund(
+        uint256 e3Id,
+        uint256 originalPayment,
+        address[] calldata honestNodes
+    ) external;
+
+    /// @notice Requester claims their refund
+    /// @param e3Id The failed E3 ID
+    /// @return amount The amount claimed
+    function claimRequesterRefund(
+        uint256 e3Id
+    ) external returns (uint256 amount);
+
+    /// @notice Honest node claims their reward
+    /// @param e3Id The failed E3 ID
+    /// @return amount The amount claimed
+    function claimHonestNodeReward(
+        uint256 e3Id
+    ) external returns (uint256 amount);
+
+    /// @notice Route slashed funds to E3 refund pool
+    /// @param e3Id The E3 ID
+    /// @param amount The slashed amount
+    function routeSlashedFunds(uint256 e3Id, uint256 amount) external;
+
+    /// @notice Get refund distribution for an E3
+    /// @param e3Id The E3 ID
+    /// @return distribution The refund distribution
+    function getRefundDistribution(
+        uint256 e3Id
+    ) external view returns (RefundDistribution memory distribution);
+
+    /// @notice Check if address has claimed refund
+    /// @param e3Id The E3 ID
+    /// @param claimant The address to check
+    /// @return claimed Whether the address has claimed
+    function hasClaimed(
+        uint256 e3Id,
+        address claimant
+    ) external view returns (bool claimed);
+
+    /// @notice Calculate work value for a given stage
+    /// @param stage The stage when E3 failed
+    /// @return workCompletedBps Work completed in basis points
+    /// @return workRemainingBps Work remaining in basis points
+    function calculateWorkValue(
+        IEnclave.E3Stage stage
+    ) external view returns (uint16 workCompletedBps, uint16 workRemainingBps);
+
+    /// @notice Set work value allocation
+    /// @param allocation The new work allocation
+    function setWorkAllocation(
+        WorkValueAllocation calldata allocation
+    ) external;
+
+    /// @notice Get current work allocation
+    /// @return allocation The current work allocation
+    function getWorkAllocation()
+        external
+        view
+        returns (WorkValueAllocation memory allocation);
+}

package/contracts/interfaces/IEnclave.sol

@@ -12,6 +12,63 @@ import { IDecryptionVerifier } from "./IDecryptionVerifier.sol";
 import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
 interface IEnclave {
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                         Enums                          //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+
+    /// @notice Lifecycle stages of an E3 computation
+    enum E3Stage {
+        None,
+        Requested,
+        CommitteeFinalized,
+        // Once a key is published, it is possible to then accept inputs
+        // as long as we are within the input deadline (start and end)
+        KeyPublished,
+        CiphertextReady,
+        Complete,
+        Failed
+    }
+
+    /// @notice Reasons why an E3 failed
+    enum FailureReason {
+        None,
+        CommitteeFormationTimeout,
+        InsufficientCommitteeMembers,
+        DKGTimeout,
+        DKGInvalidShares,
+        NoInputsReceived,
+        ComputeTimeout,
+        ComputeProviderExpired,
+        ComputeProviderFailed,
+        RequesterCancelled,
+        DecryptionTimeout,
+        DecryptionInvalidShares,
+        VerificationFailed
+    }
+
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                        Structs                         //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+
+    /// @notice Timeout configuration for E3 stages
+    struct E3TimeoutConfig {
+        uint256 dkgWindow;
+        uint256 computeWindow;
+        uint256 decryptionWindow;
+        uint256 gracePeriod;
+    }
+
+    /// @notice Deadlines for each E3
+    struct E3Deadlines {
+        uint256 dkgDeadline;
+        uint256 computeDeadline;
+        uint256 decryptionDeadline;
+    }
+
     ////////////////////////////////////////////////////////////
     //                                                        //
     //                         Events                         //
@@ -24,16 +81,6 @@ interface IEnclave {
     /// @param e3Program Address of the Computation module selected.
     event E3Requested(uint256 e3Id, E3 e3, IE3Program indexed e3Program);
 
-    /// @notice This event MUST be emitted when an Encrypted Execution Environment (E3) is successfully activated.
-    /// @param e3Id ID of the E3.
-    /// @param expiration Timestamp when committee duties expire.
-    /// @param committeePublicKey Hash of the public key of the committee.
-    event E3Activated(
-        uint256 e3Id,
-        uint256 expiration,
-        bytes32 committeePublicKey
-    );
-
     /// @notice This event MUST be emitted when an input to an Encrypted Execution Environment (E3) is
     /// successfully published.
     /// @param e3Id ID of the E3.
@@ -106,6 +153,45 @@ interface IEnclave {
     /// @param e3ProgramParams Array of encoded encryption scheme parameters (e.g, for BFV)
     event AllowedE3ProgramsParamsSet(bytes[] e3ProgramParams);
 
+    /// @notice Emitted when E3RefundManager contract is set.
+    /// @param e3RefundManager The address of the E3RefundManager contract.
+    event E3RefundManagerSet(address indexed e3RefundManager);
+
+    /// @notice Emitted when a failed E3 is processed for refunds.
+    /// @param e3Id The ID of the failed E3.
+    /// @param paymentAmount The original payment amount being refunded.
+    /// @param honestNodeCount The number of honest nodes in the refund distribution.
+    event E3FailureProcessed(
+        uint256 indexed e3Id,
+        uint256 paymentAmount,
+        uint256 honestNodeCount
+    );
+
+    /// @notice Emitted when a committee is published and E3 lifecycle is updated.
+    /// @param e3Id The ID of the E3.
+    event CommitteeFormed(uint256 indexed e3Id);
+
+    /// @notice Emitted when a committee is finalized (sortition complete, DKG starting).
+    /// @param e3Id The ID of the E3.
+    event CommitteeFinalized(uint256 indexed e3Id);
+
+    /// @notice Emitted when E3 stage changes
+    event E3StageChanged(
+        uint256 indexed e3Id,
+        E3Stage previousStage,
+        E3Stage newStage
+    );
+
+    /// @notice Emitted when an E3 is marked as failed
+    event E3Failed(
+        uint256 indexed e3Id,
+        E3Stage failedAtStage,
+        FailureReason reason
+    );
+
+    /// @notice Emitted when timeout config is updated
+    event TimeoutConfigUpdated(E3TimeoutConfig config);
+
     ////////////////////////////////////////////////////////////
     //                                                        //
     //                  Structs                               //
@@ -114,16 +200,14 @@ interface IEnclave {
 
     /// @notice This struct contains the parameters to submit a request to Enclave.
     /// @param threshold The M/N threshold for the committee.
-    /// @param startWindow The start window for the computation.
-    /// @param duration The duration of the computation in seconds.
+    /// @param inputWindow When the program will start and stop accepting inputs.
     /// @param e3Program The address of the E3 Program.
     /// @param e3ProgramParams The ABI encoded computation parameters.
     /// @param computeProviderParams The ABI encoded compute provider parameters.
     /// @param customParams Arbitrary ABI-encoded application-defined parameters.
     struct E3RequestParams {
         uint32[2] threshold;
-        uint256[2] startWindow;
-        uint256 duration;
+        uint256[2] inputWindow;
         IE3Program e3Program;
         bytes e3ProgramParams;
         bytes computeProviderParams;
@@ -145,26 +229,6 @@ interface IEnclave {
         E3RequestParams calldata requestParams
     ) external returns (uint256 e3Id, E3 memory e3);
 
-    /// @notice This function should be called to activate an Encrypted Execution Environment (E3) once it has been
-    /// initialized and is ready for input.
-    /// @dev This function MUST emit the E3Activated event.
-    /// @dev This function MUST revert if the given E3 has not yet been requested.
-    /// @dev This function MUST revert if the selected node committee has not yet published a public key.
-    /// @param e3Id ID of the E3.
-    /// @return success True if the E3 was successfully activated.
-    function activate(uint256 e3Id) external returns (bool success);
-
-    /// @notice This function should be called to publish input data for Encrypted Execution Environment (E3).
-    /// @dev This function MUST revert if the E3 is not yet activated.
-    /// @dev This function MUST emit the InputPublished event.
-    /// @param e3Id ID of the E3.
-    /// @param data ABI encoded input data to publish.
-    /// @return success True if the input was successfully published.
-    function publishInput(
-        uint256 e3Id,
-        bytes calldata data
-    ) external returns (bool success);
-
     /// @notice This function should be called to publish output data for an Encrypted Execution Environment (E3).
     /// @dev This function MUST emit the CiphertextOutputPublished event.
     /// @param e3Id ID of the E3.
@@ -197,72 +261,51 @@ interface IEnclave {
 
     /// @notice This function should be called to set the maximum duration of requested computations.
     /// @param _maxDuration The maximum duration of a computation in seconds.
-    /// @return success True if the max duration was successfully set.
-    function setMaxDuration(
-        uint256 _maxDuration
-    ) external returns (bool success);
+    function setMaxDuration(uint256 _maxDuration) external;
 
     /// @notice Sets the Ciphernode Registry contract address.
     /// @dev This function MUST revert if the address is zero or the same as the current registry.
     /// @param _ciphernodeRegistry The address of the new Ciphernode Registry contract.
-    /// @return success True if the registry was successfully set.
     function setCiphernodeRegistry(
         ICiphernodeRegistry _ciphernodeRegistry
-    ) external returns (bool success);
+    ) external;
 
     /// @notice Sets the Bonding Registry contract address.
     /// @dev This function MUST revert if the address is zero or the same as the current registry.
     /// @param _bondingRegistry The address of the new Bonding Registry contract.
-    /// @return success True if the registry was successfully set.
-    function setBondingRegistry(
-        IBondingRegistry _bondingRegistry
-    ) external returns (bool success);
+    function setBondingRegistry(IBondingRegistry _bondingRegistry) external;
 
     /// @notice Sets the fee token used for E3 payments.
     /// @dev This function MUST revert if the address is zero or the same as the current fee token.
     /// @param _feeToken The address of the new fee token.
-    /// @return success True if the fee token was successfully set.
-    function setFeeToken(IERC20 _feeToken) external returns (bool success);
+    function setFeeToken(IERC20 _feeToken) external;
 
     /// @notice This function should be called to enable an E3 Program.
     /// @param e3Program The address of the E3 Program.
-    /// @return success True if the E3 Program was successfully enabled.
-    function enableE3Program(
-        IE3Program e3Program
-    ) external returns (bool success);
+    function enableE3Program(IE3Program e3Program) external;
 
     /// @notice This function should be called to disable an E3 Program.
     /// @param e3Program The address of the E3 Program.
-    /// @return success True if the E3 Program was successfully disabled.
-    function disableE3Program(
-        IE3Program e3Program
-    ) external returns (bool success);
+    function disableE3Program(IE3Program e3Program) external;
 
     /// @notice Sets or enables a decryption verifier for a specific encryption scheme.
     /// @dev This function MUST revert if the verifier address is zero or already set to the same value.
     /// @param encryptionSchemeId The unique identifier for the encryption scheme.
     /// @param decryptionVerifier The address of the decryption verifier contract.
-    /// @return success True if the verifier was successfully set.
     function setDecryptionVerifier(
         bytes32 encryptionSchemeId,
         IDecryptionVerifier decryptionVerifier
-    ) external returns (bool success);
+    ) external;
 
     /// @notice Disables a previously enabled encryption scheme.
     /// @dev This function MUST revert if the encryption scheme is not currently enabled.
     /// @param encryptionSchemeId The unique identifier for the encryption scheme to disable.
-    /// @return success True if the encryption scheme was successfully disabled.
-    function disableEncryptionScheme(
-        bytes32 encryptionSchemeId
-    ) external returns (bool success);
+    function disableEncryptionScheme(bytes32 encryptionSchemeId) external;
 
     /// @notice Sets the allowed E3 program parameters.
     /// @dev This function enables specific parameter sets for E3 programs (e.g., BFV encryption parameters).
     /// @param _e3ProgramsParams Array of ABI encoded parameter sets to allow.
-    /// @return success True if the parameters were successfully set.
-    function setE3ProgramsParams(
-        bytes[] memory _e3ProgramsParams
-    ) external returns (bool success);
+    function setE3ProgramsParams(bytes[] memory _e3ProgramsParams) external;
 
     ////////////////////////////////////////////////////////////
     //                                                        //
@@ -293,4 +336,83 @@ interface IEnclave {
 
     /// @notice Returns the ERC20 token used to pay for E3 fees.
     function feeToken() external view returns (IERC20);
+
+    /// @notice Returns the BondingRegistry contract.
+    function bondingRegistry() external view returns (IBondingRegistry);
+
+    /// @notice Called by CiphernodeRegistry when committee is finalized (sortition complete).
+    /// @dev Updates E3 lifecycle to CommitteeFinalized stage, starts DKG deadline.
+    /// @param e3Id ID of the E3.
+    function onCommitteeFinalized(uint256 e3Id) external;
+
+    /// @notice Called by CiphernodeRegistry when committee public key is published (DKG complete).
+    /// @dev Updates E3 lifecycle to KeyPublished stage.
+    /// @param e3Id ID of the E3.
+    /// @param committeePublicKeyHash Hash of the committee public key.
+    function onCommitteePublished(
+        uint256 e3Id,
+        bytes32 committeePublicKeyHash
+    ) external;
+
+    /// @notice Called by authorized contracts to mark an E3 as failed with a specific reason.
+    /// @dev Updates E3 lifecycle to Failed stage with the given reason.
+    /// @param e3Id ID of the E3.
+    /// @param reason The failure reason from FailureReason enum.
+    function onE3Failed(uint256 e3Id, uint8 reason) external;
+
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                  Lifecycle Functions                   //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+
+    /// @notice Anyone can mark an E3 as failed if timeout passed
+    /// @param e3Id The E3 ID
+    /// @return reason The failure reason
+    function markE3Failed(uint256 e3Id) external returns (FailureReason reason);
+
+    /// @notice Check if E3 can be marked as failed
+    /// @param e3Id The E3 ID
+    /// @return canFail Whether failure condition is met
+    /// @return reason The failure reason if applicable
+    function checkFailureCondition(
+        uint256 e3Id
+    ) external view returns (bool canFail, FailureReason reason);
+
+    /// @notice Get current stage of an E3
+    /// @param e3Id The E3 ID
+    /// @return stage The current stage
+    function getE3Stage(uint256 e3Id) external view returns (E3Stage stage);
+
+    /// @notice Get failure reason for an E3
+    /// @param e3Id The E3 ID
+    /// @return reason The failure reason
+    function getFailureReason(
+        uint256 e3Id
+    ) external view returns (FailureReason reason);
+
+    /// @notice Get requester address for an E3
+    /// @param e3Id The E3 ID
+    /// @return requester The requester address
+    function getRequester(
+        uint256 e3Id
+    ) external view returns (address requester);
+
+    /// @notice Get deadlines for an E3
+    /// @param e3Id The E3 ID
+    /// @return deadlines The E3 deadlines
+    function getDeadlines(
+        uint256 e3Id
+    ) external view returns (E3Deadlines memory deadlines);
+
+    /// @notice Get timeout configuration
+    /// @return config The current timeout config
+    function getTimeoutConfig()
+        external
+        view
+        returns (E3TimeoutConfig memory config);
+
+    /// @notice Set timeout configuration
+    /// @param config The new timeout config
+    function setTimeoutConfig(E3TimeoutConfig calldata config) external;
 }