@inco/lightning 0.8.0-devnet-4 → 0.8.0-devnet-5

package/README.md

@@ -1,8 +1,66 @@
 # Inco Lightning
 
+![coverage](./coverage.svg)
+
 The core Inco Lightning smart contracts library for building confidential applications on EVM chains.
 
-![coverage](./coverage.svg)
+## Architecture
+
+The Inco Lightning protocol consists of two main contracts that work together:
+
+- **IncoLightning**: The core encrypted operations contract - handles encrypted inputs, operations (arithmetic, bitwise, comparisons), trivial encryption, and access control
+- **IncoVerifier**: The attestation contract - manages TEE lifecycle, decryption attestations, and advanced access control with signed vouchers
+
+```mermaid
+flowchart TB
+    subgraph IncoLightning["IncoLightning (Operations)"]
+        EI[EncryptedInput]
+        EO[EncryptedOperations]
+        TE[TrivialEncryption]
+        ACL[BaseAccessControlList]
+        FEE[Fee Management]
+    end
+
+    subgraph IncoVerifier["IncoVerifier (Attestation)"]
+        AAC[AdvancedAccessControl]
+        DA[DecryptionAttester]
+        TEE[TEELifecycle]
+        SV[SignatureVerifier]
+    end
+
+    subgraph External["External"]
+        CLIENT[Client App]
+        COVAL[Covalidator TEE]
+        QV[Quote Verifier]
+    end
+
+    CLIENT -->|"encrypted input"| EI
+    CLIENT -->|"plaintext → encrypted"| TE
+    EI --> EO
+    TE --> EO
+    EO -->|"operations emit events"| COVAL
+    EO --> ACL
+    ACL -->|"verify access proofs"| AAC
+    COVAL -->|"decryption attestations"| DA
+    COVAL -->|"TEE quotes"| TEE
+    TEE --> QV
+    DA --> SV
+    TEE --> SV
+```
+
+### Key Components
+
+| Contract      | Module                | Purpose                                                 |
+| ------------- | --------------------- | ------------------------------------------------------- |
+| IncoLightning | EncryptedInput        | Accept client-encrypted values with replay protection   |
+| IncoLightning | EncryptedOperations   | 29 operations (arithmetic, bitwise, comparison, random) |
+| IncoLightning | TrivialEncryption     | Create encrypted handles from plaintext constants       |
+| IncoLightning | BaseAccessControlList | Persistent + transient access permissions               |
+| IncoLightning | Fee Management        | Collect fees for covalidator processing                 |
+| IncoVerifier  | AdvancedAccessControl | EIP-712 signed vouchers for access delegation           |
+| IncoVerifier  | DecryptionAttester    | Verify covalidator signatures on decryptions            |
+| IncoVerifier  | TEELifecycle          | Bootstrap, upgrade, and manage TEE nodes                |
+| IncoVerifier  | SignatureVerifier     | Multi-signature threshold verification                  |
 
 ## Install dependencies
 

package/manifest.yaml

@@ -1,3 +1,25 @@
+incoLightning_devnet_v4_409204766:
+  executor:
+    name: incoLightning_devnet_v4_409204766
+    majorVersion: 4
+    deployer: "0x8202D2D747784Cb7D48868E44C42C4bf162a70BC"
+    pepper: devnet
+    executorAddress: "0x4046b737B454b0430FBF29cea070e3337AdE95aD"
+    salt: "0x8202d2d747784cb7d48868e44c42c4bf162a70bc003b3f2c4caeb6f787dcce1e"
+  deployments:
+    - name: incoLightningPreview_4_0_0__409204766
+      chainId: "84532"
+      chainName: Base Sepolia
+      version:
+        major: 4
+        minor: 0
+        patch: 0
+        shortSalt: "409204766"
+      blockNumber: "36706685"
+      deployDate: 2026-01-23T15:20:59.956Z
+      commit: v0.8.0-devnet-4-1-g48f40565-dirty
+      active: true
+      includesPreviewFeatures: true
 incoLightning_devnet_v3_976859633:
   executor:
     name: incoLightning_devnet_v3_976859633

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inco/lightning",
-  "version": "0.8.0-devnet-4",
+  "version": "0.8.0-devnet-5",
   "repository": "https://github.com/Inco-fhevm/inco-monorepo",
   "files": [
     "src/",

package/src/DeployUtils.sol

@@ -13,8 +13,9 @@ import {console} from "forge-std/console.sol";
 import {CreateXHelper} from "./CreateXHelper.sol";
 import {IQuoteVerifier} from "./interfaces/automata-interfaces/IQuoteVerifier.sol";
 
-// can be set to 0x01 so the inco address can exist on only one chain, we want the same contract at the same address
-// on all chains
+/// @dev Flag controlling cross-chain deployment authorization.
+///      Set to 0x00 to allow same contract at same address on all chains.
+///      Set to 0x01 to restrict to single chain deployment.
 bytes1 constant CROSS_CHAIN_DEPLOY_AUTHORIZED_FLAG = 0x00;
 
 // GLOSSARY
@@ -25,10 +26,27 @@ bytes1 constant CROSS_CHAIN_DEPLOY_AUTHORIZED_FLAG = 0x00;
 //      using the CROSS_CHAIN_DEPLOY_AUTHORIZED_FLAG, it prevents the contract from being deployed by someone other than
 //      the deployer at the expected address
 
-/// @dev not a script in itself, use this contract in tests or scripts to get new instances of IncoLightning
+/// @title DeployUtils
+/// @notice Deployment utilities for IncoLightning and IncoVerifier contracts
+/// @dev Provides deterministic cross-chain deployment using CreateX (CREATE3 pattern).
+///      This contract is meant to be inherited by deployment scripts and test helpers.
+///
+///      Deployment uses CREATE3 via CreateX to achieve:
+///      - Deterministic addresses across all EVM chains
+///      - Same address regardless of deployer nonce
+///      - Address computed only from salt (derived from name, version, deployer, pepper)
+///
+///      Typical deployment sequence:
+///      1. Compute salts from deployer address and pepper
+///      2. Deploy IncoLightning implementation and proxy
+///      3. Deploy IncoVerifier implementation and proxy
+///      4. Both contracts reference each other via computed addresses
 contract DeployUtils is Script {
 
-    /// @dev CreateX is deployed on most chains, use this method for the testing environment
+    /// @notice Deploys CreateX contract for testing environments
+    /// @dev CreateX is pre-deployed on most production chains. Use this only in test environments
+    ///      where CreateX is not available. Pranks as the CreateX deployer to get expected address.
+    /// @return createX The deployed CreateX instance at the canonical address
     function deployCreateX() public returns (CreateX createX) {
         vm.prank(CREATE_X_DEPLOYER);
         createX = new CreateX();
@@ -36,6 +54,16 @@ contract DeployUtils is Script {
         return createX;
     }
 
+    /// @notice Computes a deployment salt from contract metadata
+    /// @dev The salt incorporates:
+    ///      - Deployer address (first 20 bytes)
+    ///      - Cross-chain flag (1 byte)
+    ///      - Hash of name, version, and pepper (last 11 bytes)
+    /// @param name The contract name (e.g., "IncoLightning")
+    /// @param majorVersionNumber The major version number
+    /// @param deployer The address that will deploy the contract
+    /// @param pepper Additional entropy to avoid address collisions
+    /// @return The 32-byte salt for CreateX deployment
     function getSalt(string memory name, uint8 majorVersionNumber, address deployer, string memory pepper)
         internal
         pure
@@ -50,19 +78,23 @@ contract DeployUtils is Script {
         );
     }
 
-    /// @notice Computes the address of the contract using CreateX based on the deployer and pepper
-    /// @dev not sure what the msg.sender influence is over the result
+    /// @notice Computes the address a contract will be deployed to using CreateX
+    /// @dev Uses CREATE3 address derivation. The address is deterministic based only on salt.
     /// @param salt The salt value that will be passed to CreateX
-    /// @return The address of the deployed contract by CreateX
+    /// @return The address where the contract will be deployed
     function computeAddressFromSalt(bytes32 salt) public returns (address) {
         CreateXHelper createX = new CreateXHelper();
         return createX.computeCreate3DeployAddress({salt: salt});
     }
 
-    /// @dev wrap in prank or broadcast depending on prod or testing environment
-    /// @param deployer MUST be the signer of the transaction
-    /// @param pepper a value used to avoid address collision on deploying the same contract twice with the same deployer
-    /// @param quoteVerifier the address of the QuoteVerifier contract to use in the contract
+    /// @notice Full deployment of IncoLightning and IncoVerifier using configuration
+    /// @dev Computes salts from deployer and pepper, then deploys both contracts.
+    ///      Should be wrapped in prank (testing) or broadcast (production).
+    /// @param deployer The address that will own both deployed proxies (MUST be tx signer)
+    /// @param pepper Entropy string to avoid address collision with previous deployments
+    /// @param quoteVerifier The Automata quote verifier for TEE attestation validation
+    /// @return lightningProxy The deployed IncoLightning proxy
+    /// @return verifierProxy The deployed IncoVerifier proxy
     function deployIncoLightningUsingConfig(address deployer, string memory pepper, IQuoteVerifier quoteVerifier)
         internal
         returns (IIncoLightning lightningProxy, IIncoVerifier verifierProxy)
@@ -78,6 +110,12 @@ contract DeployUtils is Script {
         );
     }
 
+    /// @notice Computes the standard salts for IncoLightning and IncoVerifier
+    /// @dev Uses the contract names and major version from IncoLightningConfig
+    /// @param deployer The deployer address
+    /// @param pepper The pepper string for salt generation
+    /// @return lightningSalt Salt for IncoLightning deployment
+    /// @return verifierSalt Salt for IncoVerifier deployment
     function getIncoSalts(address deployer, string memory pepper)
         internal
         pure
@@ -87,10 +125,13 @@ contract DeployUtils is Script {
         verifierSalt = getSalt(VERIFIER_NAME, MAJOR_VERSION, deployer, pepper);
     }
 
-    /// @notice Deploys the IncoLightning contract
-    /// @param lightningSalt The salt value that will be passed to CreateX
-    /// @param verifierSalt The salt value that will be passed to CreateX
-    /// @param deployer The address of the deployer
+    /// @notice Deploys the IncoLightning contract with proxy
+    /// @dev Creates both implementation and proxy contracts. The verifier address is
+    ///      computed from salt since it may not be deployed yet.
+    /// @param lightningSalt The salt for CreateX deployment
+    /// @param verifierSalt The salt used to compute the verifier address
+    /// @param deployer The address that will own the proxy
+    /// @return lightningProxy The deployed proxy cast to IIncoLightning
     function deployLightning(bytes32 lightningSalt, bytes32 verifierSalt, address deployer)
         internal
         returns (IIncoLightning lightningProxy)
@@ -109,12 +150,14 @@ contract DeployUtils is Script {
         );
     }
 
-    /// @notice Deploys the IncoVerifier contract
-    /// @param verifierSalt The salt value that will be passed to CreateX
-    /// @param lightning The previously deployed lightning contract
-    /// @param deployer The address of the deployer
-    /// @param quoteVerifier The address of the TEE lifecycle contract
-    /// @dev lightning implem must already be deployed
+    /// @notice Deploys the IncoVerifier contract with proxy
+    /// @dev Creates both implementation and proxy. Lightning must already be deployed
+    ///      so it can be referenced in the verifier.
+    /// @param verifierSalt The salt for CreateX deployment
+    /// @param lightning The previously deployed IncoLightning proxy
+    /// @param deployer The address that will own the proxy
+    /// @param quoteVerifier The Automata quote verifier for TEE attestation
+    /// @return verifierProxy The deployed proxy cast to IIncoVerifier
     function deployVerifier(
         bytes32 verifierSalt,
         IIncoLightning lightning,
@@ -137,13 +180,16 @@ contract DeployUtils is Script {
         );
     }
 
-    /// @notice deploys a ERC1967Proxy contract using CreateX (create3 pattern), gives the deployer the ownership of
-    ///     the proxy
-    /// @dev deployer is made the owner of the contract
+    /// @notice Deploys an ERC1967 proxy using CreateX (CREATE3 pattern)
+    /// @dev The proxy is initialized with the provided init call during deployment.
+    ///      Uses CREATE3 for deterministic addressing.
+    /// @param salt The salt for CreateX deployment
+    /// @param implem The implementation contract address
+    /// @param initCall ABI-encoded initializer call (selector + arguments)
+    /// @return proxy The deployed proxy address
     function deployProxy(bytes32 salt, address implem, bytes memory initCall) internal returns (address proxy) {
         CreateX createX = CreateX(CREATE_X_ADDRESS);
         bytes memory bytecode = abi.encodePacked(type(ERC1967Proxy).creationCode, abi.encode(implem, initCall));
-        // todo: check if we don't have a double delegatecall cost issue
         proxy = createX.deployCreate3(salt, bytecode);
     }
 

package/src/IncoLightning.sol

@@ -12,11 +12,16 @@ import {Version} from "./version/Version.sol";
 import {IIncoVerifier} from "./interfaces/IIncoVerifier.sol";
 import {VerifierAddressGetter} from "./lightning-parts/primitives/VerifierAddressGetter.sol";
 
-// todo add initialization of tee lifecycle
-
-/// @title Inco Lightning
-/// @notice Onchain singleton for Inco Lightning, TEE-based encrypted data and operations over shared state service
-/// @dev implicitly extends BaseAccessControlList, IncoVerifierGetter
+/// @title IncoLightning
+/// @notice Onchain singleton for Inco Lightning, TEE-based encrypted data and operations over shared state
+/// @dev This is the main entry point contract for the Inco Lightning protocol. It combines:
+///      - EncryptedOperations: Encrypted operations (eAdd, eSub, eMul, etc.)
+///      - TrivialEncryption: Creating encrypted handles from plaintext values
+///      - EncryptedInput: Processing client-encrypted inputs
+///      - BaseAccessControlList: Managing access permissions (via inheritance)
+///
+///      The contract is deployed as a UUPS upgradeable proxy and uses CreateX for deterministic deployment.
+///      All encrypted values are represented as bytes32 handles that reference ciphertexts stored off-chain.
 contract IncoLightning is
     IIncoLightning,
     EncryptedOperations,
@@ -27,24 +32,39 @@ contract IncoLightning is
     Version
 {
 
-    // salt embeds the deployer address, the contract name, the version and the pepper
+    /// @notice Initializes the IncoLightning contract with deployment configuration
+    /// @dev The salt embeds the deployer address, contract name, version, and pepper for deterministic deployment.
+    ///      This constructor is called once during proxy implementation deployment.
+    /// @param salt Unique salt used for deterministic deployment via CreateX
+    /// @param _incoVerifier The verifier contract address for attestation validation
     constructor(bytes32 salt, IIncoVerifier _incoVerifier)
         Version(MAJOR_VERSION, MINOR_VERSION, PATCH_VERSION, salt, CONTRACT_NAME)
         VerifierAddressGetter(address(_incoVerifier))
     {}
 
+    /// @notice Authorizes contract upgrades (restricted to owner only)
+    /// @dev Required by UUPSUpgradeable. Only the contract owner can authorize upgrades.
     function _authorizeUpgrade(address) internal view override {
         require(msg.sender == owner());
     }
 
+    /// @notice Initializes the proxy with an owner address
+    /// @dev Must be called immediately after proxy deployment. Can only be called once.
+    ///      This sets up the Ownable state for the proxy instance.
+    /// @param owner The address that will own this contract and can authorize upgrades
     function initialize(address owner) public initializer {
         __Ownable_init(owner);
     }
 
+    /// @notice Withdraws accumulated protocol fees to the owner
+    /// @dev Only callable by the contract owner. Transfers all accumulated fees
+    ///      from encrypted operations to the owner address.
     function withdrawFees() external onlyOwner {
         _withdrawFeesTo(owner());
     }
 
-    fallback() external {} // must be included for createX deploy
+    /// @notice Required for CreateX deterministic deployment
+    /// @dev Empty fallback allows the contract to be deployed via CreateX's create2 mechanism
+    fallback() external {}
 
 }

package/src/IncoVerifier.sol

@@ -9,16 +9,29 @@ import {TEELifecycle} from "./lightning-parts/TEELifecycle.sol";
 import {IIncoVerifier} from "./interfaces/IIncoVerifier.sol";
 import {LightningAddressGetter} from "./lightning-parts/primitives/LightningAddressGetter.sol";
 
-/// @dev implicitly extends OwnableUpgradeable, EIP712Upgradeable, SignatureVerifier, LightningAddressGetter
+/// @title IncoVerifier
+/// @notice Verifier contract for Inco Lightning TEE attestation and decryption authorization
 /// @dev NEVER deploy this contract on its own, always deploy as a joint process with IncoLightning
 contract IncoVerifier is IIncoVerifier, AdvancedAccessControl, DecryptionAttester, TEELifecycle, UUPSUpgradeable {
 
+    /// @notice Initializes the IncoVerifier contract with the IncoLightning address
+    /// @dev This constructor is called once during proxy implementation deployment.
+    /// @param _incoLightningAddress The address of the IncoLightning contract for attestation validation
     constructor(address _incoLightningAddress) LightningAddressGetter(_incoLightningAddress) {}
 
+    /// @notice Authorizes contract upgrades (restricted to owner only)
+    /// @dev Required by UUPSUpgradeable. Only the contract owner can authorize upgrades.
     function _authorizeUpgrade(address) internal view override {
         require(msg.sender == owner());
     }
 
+    /// @notice Initializes the proxy with an owner address and EIP712 parameters
+    /// @dev Must be called immediately after proxy deployment. Can only be called once.
+    ///      This sets up the Ownable state for the proxy instance and initializes EIP712 and TEE lifecycle.
+    /// @param owner The address that will own this contract and can authorize upgrades
+    /// @param name The EIP712 domain name
+    /// @param version The EIP712 domain version
+    /// @param quoteVerifier The quote verifier contract for TEE attestation validation
     function initialize(address owner, string memory name, string memory version, IQuoteVerifier quoteVerifier)
         public
         initializer
@@ -28,11 +41,15 @@ contract IncoVerifier is IIncoVerifier, AdvancedAccessControl, DecryptionAtteste
         __TeeLifecycle_init(quoteVerifier);
     }
 
+    /// @notice Returns the EIP712 domain name
+    /// @dev Used in signing and verifying structured data
     // forge-lint: disable-next-line(mixed-case-function)
     function getEIP712Name() external view returns (string memory) {
         return _EIP712Name();
     }
 
+    /// @notice Returns the EIP712 domain version
+    /// @dev Used in signing and verifying structured data
     // forge-lint: disable-next-line(mixed-case-function)
     function getEIP712Version() external view returns (string memory) {
         return _EIP712Version();