@enclave-e3/contracts 0.1.4 → 0.1.6

package/contracts/interfaces/IDecryptionVerifier.sol

@@ -5,13 +5,18 @@
 // or FITNESS FOR A PARTICULAR PURPOSE.
 pragma solidity >=0.8.27;
 
+/**
+ * @title IDecryptionVerifier
+ * @notice Interface for verifying decrypted computation outputs
+ * @dev Implements cryptographic verification of plaintext outputs from encrypted computations
+ */
 interface IDecryptionVerifier {
-    /// @notice This function should be called by the Enclave contract to verify the
-    /// decryption of output of a computation.
-    /// @param e3Id ID of the E3.
-    /// @param plaintextOutputHash The keccak256 hash of the plaintext output to be verified.
-    /// @param proof ABI encoded proof of the given output hash.
-    /// @return success Whether or not the plaintextOutputHash was successfully verified.
+    /// @notice Verify the decryption of a computation output
+    /// @dev This function is called by the Enclave contract when plaintext output is published
+    /// @param e3Id ID of the E3 computation
+    /// @param plaintextOutputHash The keccak256 hash of the plaintext output to be verified
+    /// @param proof ABI encoded proof of the decryption validity
+    /// @return success Whether the plaintextOutputHash was successfully verified
     function verify(
         uint256 e3Id,
         bytes32 plaintextOutputHash,

package/contracts/interfaces/IE3.sol

@@ -5,25 +5,29 @@
 // or FITNESS FOR A PARTICULAR PURPOSE.
 pragma solidity >=0.8.27;
 
-import { IInputValidator } from "./IInputValidator.sol";
 import { IE3Program } from "./IE3Program.sol";
 import { IDecryptionVerifier } from "./IDecryptionVerifier.sol";
 
-/// @title E3 struct
-/// @notice This struct represents an E3 computation.
-/// @param threshold M/N threshold for the committee.
-/// @param requestBlock Block number when the E3 was requested.
-/// @param startWindow Start window for the computation: index zero is minimum, index 1 is the maxium.
-/// @param duration Duration of the E3.
-/// @param expiration Timestamp when committee duties expire.
-/// @param e3Program Address of the E3 Program contract.
-/// @param e3ProgramParams ABI encoded computation parameters.
-/// @param computeProvider Address of the compute provider contract.
-/// @param inputValidator Address of the input validator contract.
-/// @param decryptionVerifier Address of the output verifier contract.
-/// @param committeeId ID of the selected committee.
-/// @param ciphertextOutput Encrypted output data.
-/// @param plaintextOutput Decrypted output data.
+/**
+ * @title E3
+ * @notice Represents a complete E3 (Encrypted Execution Environment) computation request and its lifecycle
+ * @dev This struct tracks all parameters, state, and results of an encrypted computation
+ *      from request through completion
+ * @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 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
+ * @param customParams Arbitrary ABI-encoded application-defined parameters.
+ * @param decryptionVerifier Address of the output verifier contract for decryption verification
+ * @param committeePublicKey The public key of the selected committee for this computation
+ * @param ciphertextOutput Hash of the encrypted output data produced by the computation
+ * @param plaintextOutput Decrypted output data after committee decryption
+ */
 struct E3 {
     uint256 seed;
     uint32[2] threshold;
@@ -34,7 +38,7 @@ struct E3 {
     bytes32 encryptionSchemeId;
     IE3Program e3Program;
     bytes e3ProgramParams;
-    IInputValidator inputValidator;
+    bytes customParams;
     IDecryptionVerifier decryptionVerifier;
     bytes32 committeePublicKey;
     bytes32 ciphertextOutput;

package/contracts/interfaces/IE3Program.sol

@@ -5,33 +5,46 @@
 // or FITNESS FOR A PARTICULAR PURPOSE.
 pragma solidity >=0.8.27;
 
-import { IInputValidator } from "./IInputValidator.sol";
-
+/**
+ * @title IE3Program
+ * @notice Interface for E3 program validation and verification
+ * @dev E3 programs define the computation logic and validation rules for encrypted execution environments
+ */
 interface IE3Program {
-    /// @notice This function should be called by the Enclave contract to validate the computation parameters.
-    /// @param e3Id ID of the E3.
-    /// @param seed Seed for the computation.
-    /// @param e3ProgramParams ABI encoded computation parameters.
-    /// @param computeProviderParams ABI encoded compute provider parameters.
-    /// @return encryptionSchemeId ID of the encryption scheme to be used for the computation.
-    /// @return inputValidator The input validator to be used for the computation.
+    /// @notice Validate E3 computation parameters and return encryption scheme and input validator
+    /// @dev This function is called by the Enclave contract during E3 request to configure the computation
+    /// @param e3Id ID of the E3 computation
+    /// @param seed Random seed for the computation
+    /// @param e3ProgramParams ABI encoded E3 program parameters
+    /// @param computeProviderParams ABI encoded compute provider parameters
+    /// @return encryptionSchemeId ID of the encryption scheme to be used for the computation
     function validate(
         uint256 e3Id,
         uint256 seed,
         bytes calldata e3ProgramParams,
         bytes calldata computeProviderParams
-    )
-        external
-        returns (bytes32 encryptionSchemeId, IInputValidator inputValidator);
+    ) external returns (bytes32 encryptionSchemeId);
 
-    /// @notice This function should be called by the Enclave contract to verify the decrypted output of an E3.
-    /// @param e3Id ID of the E3.
-    /// @param ciphertextOutputHash The keccak256 hash of output data to be verified.
-    /// @param proof ABI encoded data to verify the ciphertextOutputHash.
-    /// @return success Whether the output data is valid.
+    /// @notice Verify the ciphertext output of an E3 computation
+    /// @dev This function is called by the Enclave contract when ciphertext output is published
+    /// @param e3Id ID of the E3 computation
+    /// @param ciphertextOutputHash The keccak256 hash of output data to be verified
+    /// @param proof ABI encoded data to verify the ciphertextOutputHash
+    /// @return success Whether the output data is valid
     function verify(
         uint256 e3Id,
         bytes32 ciphertextOutputHash,
         bytes memory proof
     ) 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
+    /// @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;
 }

package/contracts/interfaces/IEnclave.sol

@@ -6,6 +6,10 @@
 pragma solidity >=0.8.27;
 
 import { E3, IE3Program } from "./IE3.sol";
+import { ICiphernodeRegistry } from "./ICiphernodeRegistry.sol";
+import { IBondingRegistry } from "./IBondingRegistry.sol";
+import { IDecryptionVerifier } from "./IDecryptionVerifier.sol";
+import { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
 
 interface IEnclave {
     ////////////////////////////////////////////////////////////
@@ -17,14 +21,8 @@ interface IEnclave {
     /// @notice This event MUST be emitted when an Encrypted Execution Environment (E3) is successfully requested.
     /// @param e3Id ID of the E3.
     /// @param e3 Details of the E3.
-    /// @param filter Address of the pool of nodes from which the Cipher Node committee was selected.
     /// @param e3Program Address of the Computation module selected.
-    event E3Requested(
-        uint256 e3Id,
-        E3 e3,
-        address filter,
-        IE3Program indexed e3Program
-    );
+    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.
@@ -70,6 +68,24 @@ interface IEnclave {
     /// @param ciphernodeRegistry The address of the CiphernodeRegistry contract.
     event CiphernodeRegistrySet(address ciphernodeRegistry);
 
+    /// @notice This event MUST be emitted any time the BondingRegistry is set.
+    /// @param bondingRegistry The address of the BondingRegistry contract.
+    event BondingRegistrySet(address bondingRegistry);
+
+    /// @notice This event MUST be emitted any time the fee token is set.
+    /// @param feeToken The address of the fee token.
+    event FeeTokenSet(address feeToken);
+
+    /// @notice This event MUST be emitted when rewards are distributed to committee members.
+    /// @param e3Id The ID of the E3 computation.
+    /// @param nodes The addresses of the committee members receiving rewards.
+    /// @param amounts The reward amounts for each committee member.
+    event RewardsDistributed(
+        uint256 indexed e3Id,
+        address[] nodes,
+        uint256[] amounts
+    );
+
     /// @notice The event MUST be emitted any time an encryption scheme is enabled.
     /// @param encryptionSchemeId The ID of the encryption scheme that was enabled.
     event EncryptionSchemeEnabled(bytes32 encryptionSchemeId);
@@ -97,20 +113,21 @@ interface IEnclave {
     ////////////////////////////////////////////////////////////
 
     /// @notice This struct contains the parameters to submit a request to Enclave.
-    /// @param filter The address of the pool of nodes from which to select the committee.
     /// @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 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 {
-        address filter;
         uint32[2] threshold;
         uint256[2] startWindow;
         uint256 duration;
         IE3Program e3Program;
         bytes e3ProgramParams;
         bytes computeProviderParams;
+        bytes customParams;
     }
 
     ////////////////////////////////////////////////////////////
@@ -125,8 +142,8 @@ interface IEnclave {
     /// @return e3Id ID of the E3.
     /// @return e3 The E3 struct.
     function request(
-        E3RequestParams memory requestParams
-    ) external payable returns (uint256 e3Id, E3 memory e3);
+        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.
@@ -138,7 +155,7 @@ interface IEnclave {
     /// @return success True if the E3 was successfully activated.
     function activate(
         uint256 e3Id,
-        bytes memory publicKey
+        bytes calldata publicKey
     ) external returns (bool success);
 
     /// @notice This function should be called to publish input data for Encrypted Execution Environment (E3).
@@ -160,8 +177,8 @@ interface IEnclave {
     /// @return success True if the output was successfully published.
     function publishCiphertextOutput(
         uint256 e3Id,
-        bytes memory ciphertextOutput,
-        bytes memory proof
+        bytes calldata ciphertextOutput,
+        bytes calldata proof
     ) external returns (bool success);
 
     /// @notice This function publishes the plaintext output of an Encrypted Execution Environment (E3).
@@ -172,8 +189,8 @@ interface IEnclave {
     /// @param proof ABI encoded data to verify the plaintextOutput.
     function publishPlaintextOutput(
         uint256 e3Id,
-        bytes memory plaintextOutput,
-        bytes memory proof
+        bytes calldata plaintextOutput,
+        bytes calldata proof
     ) external returns (bool success);
 
     ////////////////////////////////////////////////////////////
@@ -189,6 +206,28 @@ interface IEnclave {
         uint256 _maxDuration
     ) external returns (bool success);
 
+    /// @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);
+
+    /// @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);
+
+    /// @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);
+
     /// @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.
@@ -203,6 +242,32 @@ interface IEnclave {
         IE3Program e3Program
     ) external returns (bool success);
 
+    /// @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);
+
+    /// @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);
+
+    /// @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);
+
     ////////////////////////////////////////////////////////////
     //                                                        //
     //                   Get Functions                        //
@@ -215,9 +280,18 @@ interface IEnclave {
     /// @return e3 The struct representing the requested E3.
     function getE3(uint256 e3Id) external view returns (E3 memory e3);
 
-    /// @notice This function returns root of the input merkle tree for a given E3.
-    /// @dev This function MUST revert if the E3 does not exist.
-    /// @param e3Id ID of the E3.
-    /// @return root The root of the input merkle tree.
-    function getInputRoot(uint256 e3Id) external view returns (uint256 root);
+    /// @notice This function returns the fee of an E3
+    /// @dev This function MUST revert if the E3 parameters are invalid.
+    /// @param e3Params the struct representing the E3 request parameters
+    /// @return fee the fee of the E3
+    function getE3Quote(
+        E3RequestParams calldata e3Params
+    ) external view returns (uint256 fee);
+
+    /// @notice Returns the decryption verifier for a given encryption scheme.
+    /// @param encryptionSchemeId The unique identifier for the encryption scheme.
+    /// @return The decryption verifier contract for the specified encryption scheme.
+    function getDecryptionVerifier(
+        bytes32 encryptionSchemeId
+    ) external view returns (IDecryptionVerifier);
 }

package/contracts/interfaces/ISlashVerifier.sol

@@ -0,0 +1,23 @@
+// 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;
+
+/**
+ * @title ISlashVerifier
+ * @notice Interface for verifying slash proofs
+ * @dev Slash verifiers implement cryptographic or logical verification of slash proposals
+ */
+interface ISlashVerifier {
+    /// @notice Verify a slash proof
+    /// @dev This function is called by the SlashingManager contract during slash proposal to verify proof validity
+    /// @param proposalId ID of the slash proposal
+    /// @param proof ABI encoded proof data supporting the slash
+    /// @return success Whether the proof was successfully verified
+    function verify(
+        uint256 proposalId,
+        bytes memory proof
+    ) external view returns (bool success);
+}