@enclave-e3/contracts 0.1.4 → 0.1.6

package/contracts/interfaces/IBondingRegistry.sol

@@ -0,0 +1,446 @@
+// 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 { IERC20 } from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import { ICiphernodeRegistry } from "./ICiphernodeRegistry.sol";
+import { EnclaveTicketToken } from "../token/EnclaveTicketToken.sol";
+
+/**
+ * @title IBondingRegistry
+ * @notice Interface for the main bonding registry that holds operator balance and license bonds
+ */
+interface IBondingRegistry {
+    // ======================
+    // Custom Errors
+    // ======================
+
+    // General
+    error ZeroAddress();
+    error ZeroAmount();
+    error CiphernodeBanned();
+    error Unauthorized();
+    error InsufficientBalance();
+    error NotLicensed();
+    error AlreadyRegistered();
+    error NotRegistered();
+    error ExitInProgress();
+    error ExitNotReady();
+    error InvalidAmount();
+    error InvalidConfiguration();
+    error NoPendingDeregistration();
+    error OnlyRewardDistributor();
+    error ArrayLengthMismatch();
+
+    // ======================
+    // Events (Protocol-Named)
+    // ======================
+
+    /**
+     * @notice Emitted when operator's ticket balance changes
+     * @param operator Address of the operator
+     * @param delta Change in balance (positive for increase, negative for decrease)
+     * @param newBalance New total balance
+     * @param reason Reason for the change (e.g., "DEPOSIT", "WITHDRAW", slash reason)
+     */
+    event TicketBalanceUpdated(
+        address indexed operator,
+        int256 delta,
+        uint256 newBalance,
+        bytes32 indexed reason
+    );
+
+    /**
+     * @notice Emitted when operator's license bond changes
+     * @param operator Address of the operator
+     * @param delta Change in bond (positive for increase, negative for decrease)
+     * @param newBond New total license bond
+     * @param reason Reason for the change (e.g., "BOND", "UNBOND", slash reason)
+     */
+    event LicenseBondUpdated(
+        address indexed operator,
+        int256 delta,
+        uint256 newBond,
+        bytes32 indexed reason
+    );
+
+    /**
+     * @notice Emitted when operator requests deregistration from the protocol
+     * @param operator Address of the operator
+     * @param unlockAt Timestamp when deregistration can be finalized
+     */
+    event CiphernodeDeregistrationRequested(
+        address indexed operator,
+        uint64 unlockAt
+    );
+
+    /**
+     * @notice Emitted when operator active status changes
+     * @param operator Address of the operator
+     * @param active True if active, false if inactive
+     */
+    event OperatorActivationChanged(address indexed operator, bool active);
+
+    /**
+     * @notice Emitted when configuration is updated
+     * @param parameter Name of the parameter
+     * @param oldValue Previous value
+     * @param newValue New value
+     */
+    event ConfigurationUpdated(
+        bytes32 indexed parameter,
+        uint256 oldValue,
+        uint256 newValue
+    );
+
+    /**
+     * @notice Emitted when treasury withdraws slashed funds
+     * @param to Treasury address
+     * @param ticketAmount Amount of slashed ticket balance withdrawn
+     * @param licenseAmount Amount of slashed license bond withdrawn
+     */
+    event SlashedFundsWithdrawn(
+        address indexed to,
+        uint256 ticketAmount,
+        uint256 licenseAmount
+    );
+
+    // ======================
+    // View Functions
+    // ======================
+
+    /**
+     * @notice Get license token address
+     * @return License token address
+     */
+    function getLicenseToken() external view returns (address);
+
+    /**
+     * @notice Get ticket token address
+     * @return Ticket token address
+     */
+    function getTicketToken() external view returns (address);
+
+    /**
+     * @notice Get operator's current ticket balance
+     * @param operator Address of the operator
+     * @return Current collateral balance
+     */
+    function getTicketBalance(address operator) external view returns (uint256);
+
+    /**
+     * @notice Get operator's current license bond
+     * @param operator Address of the operator
+     * @return Current license bond
+     */
+    function getLicenseBond(address operator) external view returns (uint256);
+
+    /**
+     * @notice Get current ticket price
+     * @return Price per ticket in collateral token units
+     */
+    function ticketPrice() external view returns (uint256);
+
+    /**
+     * @notice Calculate available tickets for an operator
+     * @param operator Address of the operator
+     * @return Number of tickets available (floor(balance / ticketPrice))
+     */
+    function availableTickets(address operator) external view returns (uint256);
+
+    /**
+     * @notice Check if operator is licensed
+     * @param operator Address of the operator
+     * @return True if operator has sufficient license bond
+     */
+    function isLicensed(address operator) external view returns (bool);
+
+    /**
+     * @notice Check if operator is registered
+     * @param operator Address of the operator
+     * @return True if operator is registered
+     */
+    function isRegistered(address operator) external view returns (bool);
+
+    /**
+     * @notice Check if operator is active
+     * @param operator Address of the operator
+     * @return True if operator is active (licensed, registered, and has min tickets)
+     */
+    function isActive(address operator) external view returns (bool);
+
+    /**
+     * @notice Check if operator has deregistration in progress
+     * @param operator Address of the operator
+     * @return True if exit requested but not finalized
+     */
+    function hasExitInProgress(address operator) external view returns (bool);
+
+    /**
+     * @notice Get license bond price required
+     * @return License bond price amount
+     */
+    function licenseRequiredBond() external view returns (uint256);
+
+    /**
+     * @notice Get minimum ticket balance required for activation
+     * @return Minimum number of tickets required
+     */
+    function minTicketBalance() external view returns (uint256);
+
+    /**
+     * @notice Get exit delay period
+     * @return Number of seconds operators must wait after requesting exit
+     */
+    function exitDelay() external view returns (uint64);
+
+    /**
+     * @notice Get operator's ticket balance at a specific block
+     * @param operator Address of the operator
+     * @param blockNumber Block number to query
+     * @return Ticket balance at the specified block
+     */
+    function getTicketBalanceAtBlock(
+        address operator,
+        uint256 blockNumber
+    ) external view returns (uint256);
+
+    /**
+     * @notice Get operator's total pending exit amounts
+     * @param operator Address of the operator
+     * @return ticket Total pending ticket balance in exit queue
+     * @return license Total pending license bond in exit queue
+     */
+    function pendingExits(
+        address operator
+    ) external view returns (uint256 ticket, uint256 license);
+
+    /**
+     * @notice Preview how much an operator can currently claim
+     * @param operator Address of the operator
+     * @return ticket Claimable ticket balance
+     * @return license Claimable license bond
+     */
+    function previewClaimable(
+        address operator
+    ) external view returns (uint256 ticket, uint256 license);
+
+    /**
+     * @notice Get slashed funds treasury address
+     * @return Address where slashed funds are sent
+     */
+    function slashedFundsTreasury() external view returns (address);
+
+    /**
+     * @notice Get total slashed ticket balance
+     * @return Amount of ticket balance slashed and available for treasury withdrawal
+     */
+    function slashedTicketBalance() external view returns (uint256);
+
+    /**
+     * @notice Get total slashed license bond
+     * @return Amount of license bond slashed and available for treasury withdrawal
+     */
+    function slashedLicenseBond() external view returns (uint256);
+
+    // ======================
+    // Operator Functions
+    // ======================
+
+    /**
+     * @notice Register as an operator (callable by licensed operators)
+     * @dev Requires sufficient license bond and calls registry
+     */
+    function registerOperator() external;
+
+    /**
+     * @notice Deregister as an operator and remove from IMT
+     * @param siblingNodes Sibling node proofs for IMT removal
+     * @dev Requires operator to provide sibling nodes for immediate IMT removal
+     */
+    function deregisterOperator(uint256[] calldata siblingNodes) external;
+
+    /**
+     * @notice Increase operator's ticket balance by depositing tokens
+     * @param amount Amount of ticket tokens to deposit
+     * @dev Requires approval for ticket token transfer
+     */
+    function addTicketBalance(uint256 amount) external;
+
+    /**
+     * @notice Decrease operator's ticket balance by withdrawing tokens
+     * @param amount Amount of ticket tokens to withdraw
+     * @dev Reverts if operator is in any active committee
+     */
+    function removeTicketBalance(uint256 amount) external;
+
+    /**
+     * @notice Bond license tokens to become eligible for registration
+     * @param amount Amount of license tokens to bond
+     * @dev Requires approval for license token transfer
+     */
+    function bondLicense(uint256 amount) external;
+
+    /**
+     * @notice Unbond license tokens
+     * @param amount Amount of license tokens to unbond
+     * @dev Reverts if operator is in any active committee or still registered
+     */
+    function unbondLicense(uint256 amount) external;
+
+    // ======================
+    // Claim Functions
+    // ======================
+
+    /**
+     * @notice Claim operator's ticket balance and license bond
+     * @param maxTicketAmount Maximum amount of ticket tokens to claim
+     * @param maxLicenseAmount Maximum amount of license tokens to claim
+     */
+    function claimExits(
+        uint256 maxTicketAmount,
+        uint256 maxLicenseAmount
+    ) external;
+
+    // ======================
+    // Slashing Functions
+    // ======================
+
+    /**
+     * @notice Slash operator's ticket balance by absolute amount
+     * @param operator Address of the operator to slash
+     * @param amount Amount to slash
+     * @param reason Reason for slashing (stored in event)
+     * @dev Only callable by authorized slashing manager
+     */
+    function slashTicketBalance(
+        address operator,
+        uint256 amount,
+        bytes32 reason
+    ) external;
+
+    /**
+     * @notice Slash operator's license bond by absolute amount
+     * @param operator Address of the operator to slash
+     * @param amount Amount to slash
+     * @param reason Reason for slashing (stored in event)
+     * @dev Only callable by authorized slashing manager
+     */
+    function slashLicenseBond(
+        address operator,
+        uint256 amount,
+        bytes32 reason
+    ) external;
+
+    // ======================
+    // Reward Distribution Functions
+    // ======================
+    /**
+     * @notice Distribute rewards to operators
+     * @param rewardToken Reward token contract
+     * @param operators Addresses of the operators to distribute rewards to
+     * @param amounts Amounts of rewards to distribute to each operator
+     * @dev Only callable by contract owner
+     */
+    function distributeRewards(
+        IERC20 rewardToken,
+        address[] calldata operators,
+        uint256[] calldata amounts
+    ) external;
+
+    // ======================
+    // Admin Functions
+    // ======================
+
+    /**
+     * @notice Set ticket price
+     * @param newTicketPrice New price per ticket
+     * @dev Only callable by contract owner
+     */
+    function setTicketPrice(uint256 newTicketPrice) external;
+
+    /**
+     * @notice Set license bond price required
+     * @param newLicenseRequiredBond New license bond price
+     * @dev Only callable by contract owner
+     */
+    function setLicenseRequiredBond(uint256 newLicenseRequiredBond) external;
+
+    /**
+     * @notice Set license active BPS
+     * @param newBps New license active BPS
+     * @dev Only callable by contract owner
+     */
+    function setLicenseActiveBps(uint256 newBps) external;
+
+    /**
+     * @notice Set minimum ticket balance required for activation
+     * @param newMinTicketBalance New minimum ticket balance
+     * @dev Only callable by contract owner
+     */
+    function setMinTicketBalance(uint256 newMinTicketBalance) external;
+
+    /**
+     * @notice Set exit delay period
+     * @param newExitDelay New exit delay in seconds
+     * @dev Only callable by contract owner
+     */
+    function setExitDelay(uint64 newExitDelay) external;
+
+    /**
+     * @notice Set ticket token
+     * @param newTicketToken New ticket token
+     * @dev Only callable by contract owner
+     */
+    function setTicketToken(EnclaveTicketToken newTicketToken) external;
+
+    /**
+     * @notice Set license token
+     * @param newLicenseToken New license token
+     * @dev Only callable by contract owner
+     */
+    function setLicenseToken(IERC20 newLicenseToken) external;
+
+    /**
+     * @notice Set slashed funds treasury address
+     * @param newSlashedFundsTreasury New slashed funds treasury address
+     * @dev Only callable by contract owner
+     */
+    function setSlashedFundsTreasury(address newSlashedFundsTreasury) external;
+
+    /**
+     * @notice Set registry address
+     * @param newRegistry New registry contract address
+     * @dev Only callable by contract owner
+     */
+    function setRegistry(ICiphernodeRegistry newRegistry) external;
+
+    /**
+     * @notice Set slashing manager address
+     * @param newSlashingManager New slashing manager contract address
+     * @dev Only callable by contract owner
+     */
+    function setSlashingManager(address newSlashingManager) external;
+
+    /**
+     * @notice Set reward distributor address
+     * @param newRewardDistributor New reward distributor address
+     * @dev Only callable by contract owner
+     */
+    function setRewardDistributor(address newRewardDistributor) external;
+
+    /**
+     * @notice Withdraw slashed funds to treasury
+     * @param ticketAmount Amount of slashed ticket balance to withdraw
+     * @param licenseAmount Amount of slashed license bond to withdraw
+     * @dev Only callable by contract owner, sends to treasury address
+     */
+    function withdrawSlashedFunds(
+        uint256 ticketAmount,
+        uint256 licenseAmount
+    ) external;
+}

package/contracts/interfaces/ICiphernodeRegistry.sol

@@ -5,21 +5,83 @@
 // or FITNESS FOR A PARTICULAR PURPOSE.
 pragma solidity >=0.8.27;
 
+/**
+ * @title ICiphernodeRegistry
+ * @notice Interface for managing ciphernode registration and committee selection
+ * @dev This registry maintains an Incremental Merkle Tree (IMT) of registered ciphernodes
+ * and coordinates committee selection for E3 computations
+ */
 interface ICiphernodeRegistry {
+    /// @notice Struct representing the sortition state for an E3 round.
+    /// @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 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.
+    /// @param topNodes The top nodes in the round.
+    /// @param committee The committee for the round.
+    /// @param submitted Mapping of nodes to their submission status.
+    /// @param scoreOf Mapping of nodes to their scores.
+    struct Committee {
+        bool initialized;
+        bool finalized;
+        uint256 seed;
+        uint256 requestBlock;
+        uint256 submissionDeadline;
+        bytes32 publicKey;
+        uint32[2] threshold;
+        address[] topNodes;
+        address[] committee;
+        mapping(address node => bool submitted) submitted;
+        mapping(address node => uint256 score) scoreOf;
+    }
+
     /// @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 filter Address of the contract that will coordinate committee selection.
+    /// @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.
     event CommitteeRequested(
         uint256 indexed e3Id,
-        address filter,
-        uint32[2] threshold
+        uint256 seed,
+        uint32[2] threshold,
+        uint256 requestBlock,
+        uint256 submissionDeadline
     );
 
+    /// @notice This event MUST be emitted when a ticket is submitted for sortition
+    /// @param e3Id ID of the E3 computation
+    /// @param node Address of the ciphernode submitting the ticket
+    /// @param ticketId The ticket number being submitted
+    /// @param score The computed score for the ticket
+    event TicketSubmitted(
+        uint256 indexed e3Id,
+        address indexed node,
+        uint256 ticketId,
+        uint256 score
+    );
+
+    /// @notice This event MUST be emitted when a committee is finalized
+    /// @param e3Id ID of the E3 computation
+    /// @param committee Array of selected ciphernode addresses
+    event CommitteeFinalized(uint256 indexed e3Id, address[] committee);
+
     /// @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.
-    event CommitteePublished(uint256 indexed e3Id, bytes publicKey);
+    event CommitteePublished(
+        uint256 indexed e3Id,
+        address[] nodes,
+        bytes publicKey
+    );
+
+    /// @notice This event MUST be emitted when a committee's active status changes.
+    /// @param e3Id ID of the E3 for which the committee status changed.
+    /// @param active True if committee is now active, false if completed.
+    event CommitteeActivationChanged(uint256 indexed e3Id, bool active);
 
     /// @notice This event MUST be emitted when `enclave` is set.
     /// @param enclave Address of the enclave contract.
@@ -49,27 +111,53 @@ interface ICiphernodeRegistry {
         uint256 size
     );
 
+    /// @notice This event MUST be emitted any time the `sortitionSubmissionWindow` is set.
+    /// @param sortitionSubmissionWindow The submission window for the E3 sortition in seconds.
+    event SortitionSubmissionWindowSet(uint256 sortitionSubmissionWindow);
+
+    /// @notice Check if a ciphernode is eligible for committee selection
+    /// @dev A ciphernode is eligible if it is enabled in the registry and meets bonding requirements
+    /// @param ciphernode Address of the ciphernode to check
+    /// @return eligible Whether the ciphernode is eligible for committee selection
     function isCiphernodeEligible(address ciphernode) external returns (bool);
 
+    /// @notice Check if a ciphernode is enabled in the registry
+    /// @param node Address of the ciphernode
+    /// @return enabled Whether the ciphernode is enabled
+    function isEnabled(address node) external view returns (bool enabled);
+
+    /// @notice Add a ciphernode to the registry
+    /// @param node Address of the ciphernode to add
+    function addCiphernode(address node) external;
+
+    /// @notice Remove a ciphernode from the registry
+    /// @param node Address of the ciphernode to remove
+    /// @param siblingNodes Array of sibling node indices for tree operations
+    function removeCiphernode(
+        address node,
+        uint256[] calldata siblingNodes
+    ) external;
+
     /// @notice Initiates the committee selection process for a specified E3.
     /// @dev This function MUST revert when not called by the Enclave contract.
     /// @param e3Id ID of the E3 for which to select the committee.
-    /// @param filter The address of the filter responsible for the committee selection process.
+    /// @param seed Random seed for score computation.
     /// @param threshold The M/N threshold for the committee.
     /// @return success True if committee selection was successfully initiated.
     function requestCommittee(
         uint256 e3Id,
-        address filter,
+        uint256 seed,
         uint32[2] calldata threshold
     ) external returns (bool success);
 
     /// @notice Publishes the public key resulting from the committee selection process.
-    /// @dev This function MUST revert if not called by the previously selected filter.
+    /// @dev This function MUST revert if not called by the owner.
     /// @param e3Id ID of the E3 for which to select the committee.
-    /// @param publicKey The hash of the public key generated by the given committee.
+    /// @param nodes Array of ciphernode addresses selected for the committee.
+    /// @param publicKey The public key generated by the given committee.
     function publishCommittee(
         uint256 e3Id,
-        bytes calldata proof,
+        address[] calldata nodes,
         bytes calldata publicKey
     ) external;
 
@@ -81,4 +169,60 @@ interface ICiphernodeRegistry {
     function committeePublicKey(
         uint256 e3Id
     ) external view returns (bytes32 publicKeyHash);
+
+    /// @notice This function should be called by the Enclave contract to get the committee for a given E3.
+    /// @dev This function MUST revert if no committee has been requested for the given E3.
+    /// @param e3Id ID of the E3 for which to get the committee.
+    /// @return committeeNodes The nodes in the committee for the given E3.
+    function getCommitteeNodes(
+        uint256 e3Id
+    ) external view returns (address[] memory committeeNodes);
+
+    /// @notice Returns the current root of the ciphernode IMT
+    /// @return Current IMT root
+    function root() external view returns (uint256);
+
+    /// @notice Returns the IMT root at the time a committee was requested
+    /// @param e3Id ID of the E3
+    /// @return IMT root at time of committee request
+    function rootAt(uint256 e3Id) external view returns (uint256);
+
+    /// @notice Returns the current size of the ciphernode IMT
+    /// @return Size of the IMT
+    function treeSize() external view returns (uint256);
+
+    /// @notice Returns the address of the bonding registry
+    /// @return Address of the bonding registry contract
+    function getBondingRegistry() external view returns (address);
+
+    /// @notice Sets the Enclave contract address
+    /// @dev Only callable by owner
+    /// @param _enclave Address of the Enclave contract
+    function setEnclave(address _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;
+
+    /// @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.
+    function setSortitionSubmissionWindow(
+        uint256 _sortitionSubmissionWindow
+    ) external;
+
+    /// @notice Submit a ticket for sortition
+    /// @dev Validates ticket against node's balance at request block
+    /// @param e3Id ID of the E3 computation
+    /// @param ticketNumber The ticket number to submit
+    function submitTicket(uint256 e3Id, uint256 ticketNumber) external;
+
+    /// @notice Finalize the committee after submission window closes
+    /// @param e3Id ID of the E3 computation
+    function finalizeCommittee(uint256 e3Id) external;
+
+    /// @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);
 }

package/contracts/interfaces/IComputeProvider.sol

@@ -7,9 +7,19 @@ pragma solidity >=0.8.27;
 
 import { IDecryptionVerifier } from "./IDecryptionVerifier.sol";
 
+/**
+ * @title IComputeProvider
+ * @notice Interface for compute provider validation and configuration
+ * @dev Compute providers define how computations are executed and verified in the E3 system
+ */
 interface IComputeProvider {
-    /// @notice This function should be called by the Enclave contract to validate the compute provider parameters.
-    /// @param params ABI encoded compute provider parameters.
+    /// @notice Validate compute provider parameters and return the appropriate decryption verifier
+    /// @dev This function is called by the Enclave contract during E3 request to validate
+    ///      compute provider configuration
+    /// @param e3Id ID of the E3 computation
+    /// @param seed Random seed for the computation
+    /// @param params ABI encoded compute provider parameters
+    /// @return decryptionVerifier The decryption verifier contract to use for this computation
     function validate(
         uint256 e3Id,
         uint256 seed,