Encalve Spec

package.json

@@ -7,14 +7,17 @@
     "url": "https://github.com/gnosisguild"
   },
   "scripts": {
+    "clean": "cd packages/evm && yarn clean",
     "compile": "yarn evm:compile",
     "lint": "yarn evm:lint",
     "typechain": "yarn evm:typechain",
+    "test": "yarn evm:test",
     "coverage": "yarn evm:coverage",
     "evm:install": "cd packages/evm && yarn install",
     "evm:compile": "cd packages/evm && yarn compile",
     "evm:lint": "cd packages/evm && yarn lint",
     "evm:typechain": "cd packages/evm && yarn typechain",
+    "evm:test": "cd packages/evm && yarn test",
     "evm:coverage": "cd packages/evm && yarn coverage",
     "preinstall": "yarn evm:install"
   }

packages/docs/contracts.spec.md

@@ -0,0 +1,57 @@
+# Enclave Specification
+
+This document is a specification of the smart contract components to Enclave, an open source protocol for Encrypted Execution Environments (E3).
+
+## Actors
+
+There are five groups of actors in Enclave:
+
+1. **Requesters:** Anyone can request an E3 from the Enclave protocol by calling the corresponding smart contract entrypoint and depositing a bond proportional to the number, threshold, and duration of Cypher Nodes that they request.
+2. **Data Providers:** Individuals and systems providing inputs to a requested E3. Data Providers contribute data encrypted to the public threshold key that is created, and published on chain, by the Cypher Nodes selected for a requested E3.
+3. **Execution Modules:** Enclave is a modular framework, allowing the choice of many different Execution Modules in which to run encrypted computations. Broadly, Execution Modules fall into two categories: (1) Provable (like RISC Zero’s virtual machine[^1], Arbitrum’s WAVM[^2], or Succinct's SP1[^3]) and (2) Oracle-based. The former provides cryptographic guarantees of correct execution, while the latter provides economic guarantees of correct execution.
+4. **Cypher Nodes:** Cypher Nodes are responsible for creating threshold public keys and decrypting the cyphertext output for each requested computation. Cypher Nodes can be registered by anyone staking Enclave tokens.
+5. **Token Holders:** As the top-level governance body, Enclave token holders are responsible for setting protocol parameters, overseeing protocol upgrades, and facilitating dispute resolution.
+
+Enclave is a smart contract protocol for coordinating the interactions between these various actors.
+
+## Components
+
+Enclave is a modular architecture, this section describes each of the various smart contract components that constitute the Enclave protocol.
+
+### Core
+
+Contains the main entrypoints for requesting and publishing inputs to E3s.
+
+**`requestE3(uint256 computationId, bytes memory data)`**
+
+**`publishInput(bytes32 e3Id, bytes memory data)`**
+
+**`publishOutput(bytes32 e3Id, bytes memory data)`**
+
+**`registerNode()`**
+
+### CyphernodeRegistry
+
+Registry of staked Cyphernodes that are eligible to be selected for E3 duties.
+
+### ComputationRegistry
+
+Registry of computations which can be requested via the protocol.
+
+### IComputationModule
+
+Computation module contracts implement any specific
+
+### ExecutionModuleRegistry
+
+Registry of execution modules on which a requested computation can be run.
+
+### IExecutionModule
+
+Interface defining interactions with any given execution module.
+
+---
+
+[^1]: RISC Zero is a general-purpose, zero-knowledge virtual machine. More information can be found on their website at https://risczero.com
+[^2]: WAVM is Arbitrum’s execution environment, provable via optimistic fraud proofs. More information can be found on their website at https://arbitrum.io
+[^3]: SP1 is a performant, 100% open-source, contributor-friendly zero-knowledge virtual machine (zkVM) that can prove the execution of arbitrary Rust (or any LLVM-compiled language) programs. More information can be found on Succinct's github at https://github.com/succinctlabs/sp1

packages/evm/.eslintrc.yml

@@ -5,7 +5,7 @@ extends:
   - "prettier"
 parser: "@typescript-eslint/parser"
 parserOptions:
-  project: "tsconfig.json"
+  project: "packages/evm/tsconfig.json"
 plugins:
   - "@typescript-eslint"
 root: true

packages/evm/.gitignore

@@ -18,5 +18,4 @@ deployments
 .pnp.*
 coverage.json
 package-lock.json
-pnpm-lock.yaml
-yarn.lock
+pnpm-lock.yaml

packages/evm/.prettierrc.yml

@@ -11,7 +11,7 @@ trailingComma: "all"
 overrides:
   - files: "*.sol"
     options:
-      compiler: "0.8.17"
+      compiler: "0.8.26"
       parser: "solidity-parse"
       tabWidth: 4
   - files: "*.ts"

packages/evm/contracts/Enclave.sol

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+pragma solidity >=0.8.26;
+
+import { IEnclave, E3, IComputationModule, IExecutionModule } from "./interfaces/IEnclave.sol";
+import { ICypherNodeRegistry } from "./interfaces/ICypherNodeRegistry.sol";
+import { IInputValidator } from "./interfaces/IInputValidator.sol";
+import { IOutputVerifier } from "./interfaces/IOutputVerifier.sol";
+import { OwnableUpgradeable } from "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";
+
+contract Enclave is IEnclave, OwnableUpgradeable {
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                 Storage Variables                      //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+
+    ICypherNodeRegistry public cypherNodeRegistry; // TODO: add a setter function.
+    uint256 public maxDuration; // TODO: add a setter function.
+    uint256 public nexte3Id; // ID of the next E3.
+    uint256 public requests; // total number of requests made to Enclave.
+
+    // TODO: should computation and execution modules be explicitly allowed?
+    // My intuition is that an allowlist is required since they impose slashing conditions.
+    // But perhaps this is one place where node pools might be utilized, allowing nodes to
+    // opt in to being selected for specific computations, along with the corresponding slashing conditions.
+    // This would reduce the governance overhead for Enclave.
+    // TODO: add setter function
+    mapping(IComputationModule => bool allowed) public computationModules; // Mapping of allowed computation modules.
+    // TODO: add setter function
+    mapping(IExecutionModule => bool allowed) public executionModules; // Mapping of allowed execution modules.
+
+    mapping(uint256 id => E3) public e3s; // Mapping of E3s.
+
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                        Errors                          //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+
+    error CommitteeSelectionFailed();
+    error ComputationModuleNotAllowed(IComputationModule computationModule);
+    error E3AlreadyActivated(uint256 e3Id);
+    error E3DoesNotExist(uint256 e3Id);
+    error ModuleAlreadyEnabled(address module);
+    error ModuleNotEnabled(address module);
+    error InputDeadlinePassed(uint256 e3Id, uint256 expiration);
+    error InputDeadlineNotPassed(uint256 e3Id, uint256 expiration);
+    error InvalidComputation();
+    error InvalidExecutionModuleSetup();
+    error InvalidCypherNodeRegistry(ICypherNodeRegistry cypherNodeRegistry);
+    error InvalidInput();
+    error InvalidDuration(uint256 duration);
+    error InvalidOutput();
+    error InvalidThreshold(uint32[2] threshold);
+    error CiphertextOutputAlreadyPublished(uint256 e3Id);
+    error CiphertextOutputNotPublished(uint256 e3Id);
+    error PaymentRequired(uint256 value);
+    error PlaintextOutputAlreadyPublished(uint256 e3Id);
+
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                   Initialization                       //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+
+    /// @param _owner The owner of this contract
+    /// @param _maxDuration The maximum duration of a computation in seconds
+    constructor(address _owner, ICypherNodeRegistry _cypherNodeRegistry, uint256 _maxDuration) {
+        initialize(_owner, _cypherNodeRegistry, _maxDuration);
+    }
+
+    /// @param _owner The owner of this contract
+    /// @param _maxDuration The maximum duration of a computation in seconds
+    function initialize(
+        address _owner,
+        ICypherNodeRegistry _cypherNodeRegistry,
+        uint256 _maxDuration
+    ) public initializer {
+        __Ownable_init(msg.sender);
+        setMaxDuration(_maxDuration);
+        setCypherNodeRegistry(_cypherNodeRegistry);
+        if (_owner != owner()) transferOwnership(_owner);
+    }
+
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                  Core Entrypoints                      //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+
+    function request(
+        uint256 poolId,
+        uint32[2] calldata threshold,
+        uint256 duration, // TODO: do we also need a start block/time? Would it be possible to have computations where inputs are published before the request is made? This kind of assumes the cypher nodes have already been selected and generated a shared secret.
+        IComputationModule computationModule,
+        bytes memory computationParams,
+        IExecutionModule executionModule,
+        bytes memory emParams
+    ) external payable returns (uint256 e3Id, E3 memory e3) {
+        // TODO: allow for other payment methods or only native tokens?
+        // TODO: should payment checks be done somewhere else? Perhaps in the computation module or cypher node registry?
+        require(msg.value > 0, PaymentRequired(msg.value));
+
+        require(threshold[1] >= threshold[0] && threshold[0] > 0, InvalidThreshold(threshold));
+        require(duration > 0 && duration <= maxDuration, InvalidDuration(duration)); // TODO: should 0 be a magic number for infinite duration?
+        require(computationModules[computationModule], ComputationModuleNotAllowed(computationModule));
+        require(executionModules[executionModule], ModuleNotEnabled(address(executionModule)));
+
+        // TODO: should IDs be incremental or produced deterministic?
+        e3Id = nexte3Id;
+        nexte3Id++;
+
+        IInputValidator inputValidator = computationModule.validate(computationParams);
+        require(address(inputValidator) != address(0), InvalidComputation());
+
+        // TODO: validate that the requested computation can be performed by the given execution module.
+        IOutputVerifier outputVerifier = executionModule.validate(emParams);
+        require(address(outputVerifier) != address(0), InvalidExecutionModuleSetup());
+
+        e3 = E3({
+            threshold: threshold,
+            expiration: 0,
+            computationModule: computationModule,
+            executionModule: executionModule,
+            inputValidator: inputValidator,
+            outputVerifier: outputVerifier,
+            committeePublicKey: hex"",
+            ciphertextOutput: hex"",
+            plaintextOutput: hex""
+        });
+        e3s[e3Id] = e3;
+
+        require(cypherNodeRegistry.selectCommittee(e3Id, poolId, threshold), CommitteeSelectionFailed());
+        // TODO: validate that the selected pool accepts both the computation and execution modules.
+
+        emit E3Requested(e3Id, e3s[e3Id], poolId, computationModule, executionModule);
+    }
+
+    function activate(uint256 e3Id) external returns (bool success) {
+        E3 memory e3 = getE3(e3Id);
+        require(e3.expiration == 0, E3AlreadyActivated(e3Id));
+        e3.expiration = block.timestamp + maxDuration; // TODO: this should be based on the duration requested, not the current max duration.
+
+        bytes memory committeePublicKey = cypherNodeRegistry.getCommitteePublicKey(e3Id);
+        success = committeePublicKey.length > 0;
+        require(success, CommitteeSelectionFailed());
+        e3s[e3Id].committeePublicKey = committeePublicKey;
+
+        emit E3Activated(e3Id, e3.expiration, e3.committeePublicKey);
+    }
+
+    function publishInput(uint256 e3Id, bytes memory data) external returns (bool success) {
+        E3 memory e3 = getE3(e3Id);
+        require(e3.expiration > block.timestamp, InputDeadlinePassed(e3Id, e3.expiration)); // TODO: should we have an input window, including both a start and end timestamp?
+        bytes memory input;
+        (input, success) = e3.inputValidator.validate(msg.sender, data);
+        require(success, InvalidInput());
+        // TODO: do we need to store or accumulate the inputs? Probably yes.
+        emit InputPublished(e3Id, input);
+    }
+
+    function publishCiphertextOutput(uint256 e3Id, bytes memory data) external returns (bool success) {
+        E3 memory e3 = getE3(e3Id);
+        require(e3.expiration <= block.timestamp, InputDeadlineNotPassed(e3Id, e3.expiration));
+        require(e3.ciphertextOutput.length == 0, CiphertextOutputAlreadyPublished(e3Id)); // TODO: should the output verifier be able to change its mind? i.e. should we be able to call this multiple times?
+        bytes memory output;
+        (output, success) = e3.outputVerifier.verify(e3Id, data);
+        require(success, InvalidOutput());
+        e3s[e3Id].ciphertextOutput = output;
+
+        emit CiphertextOutputPublished(e3Id, output);
+    }
+
+    function publishDecryptedOutput(uint256 e3Id, bytes memory data) external returns (bool success) {
+        E3 memory e3 = getE3(e3Id);
+        require(e3.ciphertextOutput.length > 0, CiphertextOutputNotPublished(e3Id));
+        require(e3.plaintextOutput.length == 0, PlaintextOutputAlreadyPublished(e3Id));
+        bytes memory output;
+        (output, success) = e3.computationModule.verify(e3Id, data);
+        require(success, InvalidOutput());
+        e3s[e3Id].plaintextOutput = output;
+
+        emit PlaintextOutputPublished(e3Id, output);
+    }
+
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                   Set Functions                        //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+
+    function setMaxDuration(uint256 _maxDuration) public onlyOwner returns (bool success) {
+        maxDuration = _maxDuration;
+        success = true;
+        emit MaxDurationSet(_maxDuration);
+    }
+
+    function setCypherNodeRegistry(ICypherNodeRegistry _cypherNodeRegistry) public onlyOwner returns (bool success) {
+        require(
+            address(_cypherNodeRegistry) != address(0) && _cypherNodeRegistry != cypherNodeRegistry,
+            InvalidCypherNodeRegistry(_cypherNodeRegistry)
+        );
+        cypherNodeRegistry = _cypherNodeRegistry;
+        success = true;
+        emit CypherNodeRegistrySet(address(_cypherNodeRegistry));
+    }
+
+    function enableComputationModule(IComputationModule computationModule) public onlyOwner returns (bool success) {
+        require(!computationModules[computationModule], ModuleAlreadyEnabled(address(computationModule)));
+        computationModules[computationModule] = true;
+        success = true;
+        emit ComputationModuleEnabled(computationModule);
+    }
+
+    function enableExecutionModule(IExecutionModule executionModule) public onlyOwner returns (bool success) {
+        require(!executionModules[executionModule], ModuleAlreadyEnabled(address(executionModule)));
+        executionModules[executionModule] = true;
+        success = true;
+        emit ExecutionModuleEnabled(executionModule);
+    }
+
+    function disableComputationModule(IComputationModule computationModule) public onlyOwner returns (bool success) {
+        require(computationModules[computationModule], ModuleNotEnabled(address(computationModule)));
+        delete computationModules[computationModule];
+        success = true;
+        emit ComputationModuleDisabled(computationModule);
+    }
+
+    function disableExecutionModule(IExecutionModule executionModule) public onlyOwner returns (bool success) {
+        require(executionModules[executionModule], ModuleNotEnabled(address(executionModule)));
+        delete executionModules[executionModule];
+        success = true;
+        emit ExecutionModuleDisabled(executionModule);
+    }
+
+    ////////////////////////////////////////////////////////////
+    //                                                        //
+    //                   Get Functions                        //
+    //                                                        //
+    ////////////////////////////////////////////////////////////
+
+    function getE3(uint256 e3Id) public view returns (E3 memory e3) {
+        e3 = e3s[e3Id];
+        require(e3.computationModule != IComputationModule(address(0)), E3DoesNotExist(e3Id));
+    }
+}