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

package/package.json

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

package/src/IncoLightningPreview.sol

@@ -14,12 +14,31 @@ import {OwnableUpgradeable} from "@openzeppelin/contracts-upgradeable/access/Own
 import {EList} from "./lightning-parts/EList.sol";
 import {VerifierAddressGetter} from "@inco/lightning/src/lightning-parts/primitives/VerifierAddressGetter.sol";
 
+/// @title IncoLightningPreview
+/// @notice Extended version of IncoLightning with preview/experimental features
+/// @dev This contract extends the core IncoLightning functionality with additional features
+///      that are still in preview/experimental stage. It uses a diamond-like delegation pattern:
+///
+///      Architecture:
+///      - Inherits EList for encrypted list operations (preview feature)
+///      - Delegates all other calls to the core IncoLightning contract via fallback
+///      - Shares the same version and salt as the base IncoLightning for consistency
+///
+///      Call flow:
+///      1. If the function exists in IncoLightningPreview or EList, it's executed directly
+///      2. Otherwise, the fallback delegatecalls to IncoLightning for core functionality
+///
+///      This pattern allows adding new features without modifying the audited core contract.
 contract IncoLightningPreview is EList, UUPSUpgradeable, Version, OwnableUpgradeable {
 
+    /// @notice Reference to the core IncoLightning contract for delegation
     IncoLightning private immutable LIGHTNING;
 
-    // Note passing in address rather than IncoLightning directly since the contracts mismatch due to different
-    // remappings
+    /// @notice Initializes the preview contract with references to core infrastructure
+    /// @dev Uses address type instead of IncoLightning to avoid remapping issues during deployment.
+    ///      Inherits the same version/salt as the base contract with "Preview" suffix appended.
+    /// @param _lightningAddress The deployed IncoLightning contract address
+    /// @param _verifierAddress The IncoVerifier contract address for attestation validation
     constructor(address _lightningAddress, address _verifierAddress)
         VerifierAddressGetter(_verifierAddress)
         Version(
@@ -33,18 +52,30 @@ contract IncoLightningPreview is EList, UUPSUpgradeable, Version, OwnableUpgrade
         LIGHTNING = IncoLightning(_lightningAddress);
     }
 
+    /// @notice Indicates this contract includes experimental preview features
+    /// @dev Can be used by clients to detect if preview features are available
+    /// @return Always returns true for IncoLightningPreview
     function includesPreviewFeatures() public pure returns (bool) {
         return true;
     }
 
+    /// @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.
+    /// @param owner The address that will own this contract and can authorize upgrades
     function initialize(address owner) public initializer {
         __Ownable_init(owner);
     }
 
+    /// @notice Delegates unhandled calls to the core IncoLightning contract
+    /// @dev Uses assembly delegatecall for gas efficiency and to properly forward all data.
+    ///      Any function not defined in IncoLightningPreview or its parents will be
+    ///      executed on IncoLightning in the context of this contract's storage.
     fallback() external {
         // get facet from function selector
         address logic = address(LIGHTNING);

package/src/PreviewDeployUtils.sol

@@ -10,8 +10,25 @@ import {IIncoVerifier} from "@inco/lightning/src/interfaces/IIncoVerifier.sol";
 import {IQuoteVerifier} from "@inco/lightning/src/interfaces/automata-interfaces/IQuoteVerifier.sol";
 import {console} from "forge-std/console.sol";
 
+/// @title PreviewDeployUtils
+/// @notice Deployment utilities for IncoLightningPreview and its dependencies
+/// @dev Extends DeployUtils to add preview-specific deployment functions.
+///      Uses CreateX for deterministic cross-chain deployments with computed addresses.
+///
+///      Deployment order:
+///      1. Deploy IncoLightning implementation (base contract)
+///      2. Deploy IncoLightningPreview implementation (extends base with preview features)
+///      3. Deploy proxy pointing to preview implementation
+///      4. Deploy IncoVerifier with reference to the proxy
 contract PreviewDeployUtils is DeployUtils {
 
+    /// @notice Deploys IncoLightningPreview with all required infrastructure
+    /// @dev Creates the implementation contracts and proxy in a single transaction.
+    ///      The verifier address is computed from salt for use before deployment.
+    /// @param lightningSalt Salt for deterministic deployment of lightning contracts
+    /// @param verifierSalt Salt for deterministic deployment of the verifier
+    /// @param deployer Address that will own the deployed proxy
+    /// @return lightningPreview The deployed proxy contract cast to IIncoLightningPreview
     function deployLightningPreview(bytes32 lightningSalt, bytes32 verifierSalt, address deployer)
         internal
         returns (IIncoLightningPreview lightningPreview)
@@ -32,6 +49,14 @@ contract PreviewDeployUtils is DeployUtils {
         );
     }
 
+    /// @notice Full deployment of IncoLightningPreview using configuration-based salts
+    /// @dev Computes salts from deployer and pepper, then deploys both lightning preview
+    ///      and verifier contracts. Logs the deployment configuration for verification.
+    /// @param deployer Address that will own both deployed proxies
+    /// @param pepper String used to generate unique deployment salts
+    /// @param quoteVerifier The Automata quote verifier for TEE attestation validation
+    /// @return lightningPreviewProxy The deployed IncoLightningPreview proxy
+    /// @return verifierProxy The deployed IncoVerifier proxy
     function deployIncoLightningPreviewUsingConfig(address deployer, string memory pepper, IQuoteVerifier quoteVerifier)
         internal
         returns (IIncoLightningPreview lightningPreviewProxy, IIncoVerifier verifierProxy)

package/src/lightning-parts/EList.sol

@@ -10,6 +10,11 @@ import {EListHandleGeneration} from "./primitives/EListHandleGeneration.sol";
 import {IEList} from "./IEList.sol";
 import {elist, ListTypeMismatch, InvalidRange} from "../TypesPreview.sol";
 
+/// @title EList
+/// @notice Provides operations for encrypted lists (elist) - ordered collections of encrypted values.
+/// @dev Encrypted lists are immutable; all operations return new list handles rather than modifying in place.
+/// Lists are homogeneous - all elements must be of the same encrypted type. Operations are processed
+/// by the covalidator off-chain. This is a preview feature and may change in future versions.
 abstract contract EList is
     AccessControlListStorage,
     EListHandleGeneration,
@@ -39,6 +44,13 @@ abstract contract EList is
     event EListShuffle(elist indexed list, uint256 indexed counter, elist indexed result, uint256 eventId);
     event EListReverse(elist indexed list, elist indexed result, uint256 eventId);
 
+    /// @notice Creates a new encrypted list from client-encrypted inputs.
+    /// @dev Internal function that processes multiple encrypted inputs without individual payment.
+    /// Payment should be handled by the caller for the batch.
+    /// @param inputs Array of encrypted inputs with prepended handles.
+    /// @param listType The type of elements in the list.
+    /// @param user The user address that encrypted the values.
+    /// @return newList The new encrypted list handle.
     function newEListFromInputs(bytes[] calldata inputs, ETypes listType, address user)
         internal
         returns (elist newList)
@@ -54,6 +66,11 @@ abstract contract EList is
         return newEListFromHandles(handles, listType);
     }
 
+    /// @notice Creates a new encrypted list from existing encrypted handles.
+    /// @dev Validates that all handles are of the expected type and caller has access.
+    /// @param handles Array of encrypted value handles to include in the list.
+    /// @param listType The type of elements in the list (must match handle types).
+    /// @return newList The new encrypted list handle.
     function newEListFromHandles(bytes32[] memory handles, ETypes listType) internal returns (elist newList) {
         require(isTypeSupported(listType), UnsupportedType(listType));
         for (uint256 i = 0; i < handles.length; i++) {
@@ -69,10 +86,21 @@ abstract contract EList is
         return elist.wrap(newHandle);
     }
 
+    /// @notice Creates a new encrypted list from existing encrypted handles.
+    /// @dev External wrapper for newEListFromHandles.
+    /// @param handles Array of encrypted value handles to include in the list.
+    /// @param listType The type of elements in the list.
+    /// @return newList The new encrypted list handle.
     function newEList(bytes32[] memory handles, ETypes listType) external returns (elist newList) {
         return newEListFromHandles(handles, listType);
     }
 
+    /// @notice Creates a new encrypted list from client-encrypted inputs.
+    /// @dev This is a paid operation. Payment scales with the number of inputs.
+    /// @param inputs Array of encrypted inputs with prepended handles.
+    /// @param listType The type of elements in the list.
+    /// @param user The user address that encrypted the values.
+    /// @return newList The new encrypted list handle.
     function newEList(bytes[] calldata inputs, ETypes listType, address user)
         external
         payable
@@ -82,10 +110,19 @@ abstract contract EList is
         return newEListFromInputs(inputs, listType, user);
     }
 
+    /// @notice Returns the element type of an encrypted list handle.
+    /// @dev Extracts the type from the handle's metadata bytes.
+    /// @param handle The list handle to inspect.
+    /// @return The ETypes enum value representing the element type.
     function elementTypeOf(bytes32 handle) internal pure returns (ETypes) {
         return ETypes(uint8(uint256(handle) >> 16));
     }
 
+    /// @notice Appends an encrypted value to the end of an encrypted list.
+    /// @dev Returns a new list with the value appended; original list is unchanged.
+    /// @param list The encrypted list to append to.
+    /// @param value The encrypted value to append (must match list element type).
+    /// @return result A new encrypted list with the value appended.
     function listAppend(elist list, bytes32 value) external returns (elist result) {
         checkInput(elist.unwrap(list), typeToBitMask(ETypes.List));
         checkInput(value, typeToBitMask(listTypeOf(elist.unwrap(list))));
@@ -102,6 +139,11 @@ abstract contract EList is
         emit EListAppend(list, value, result, getNewEventId());
     }
 
+    /// @notice Retrieves an encrypted element at a specific index.
+    /// @dev Reverts if the index is out of range. For safe access with a default, use listGetOr.
+    /// @param list The encrypted list to access.
+    /// @param i The index to retrieve (0-based).
+    /// @return result The encrypted element at the specified index.
     function listGet(elist list, uint16 i) external returns (bytes32 result) {
         require(i < lengthOf(elist.unwrap(list)), IndexOutOfRange(i, lengthOf(elist.unwrap(list))));
         checkInput(elist.unwrap(list), typeToBitMask(ETypes.List));
@@ -111,6 +153,12 @@ abstract contract EList is
         emit EListGet(list, i, result, getNewEventId());
     }
 
+    /// @notice Retrieves an encrypted element at an encrypted index, with a default value for out-of-range access.
+    /// @dev Returns the default value if the index is out of range. Index must be euint256.
+    /// @param list The encrypted list to access.
+    /// @param index The encrypted index to retrieve.
+    /// @param defaultValue The encrypted value to return if index is out of range.
+    /// @return result The encrypted element at the index, or defaultValue if out of range.
     function listGetOr(elist list, bytes32 index, bytes32 defaultValue) external returns (bytes32 result) {
         checkInput(elist.unwrap(list), typeToBitMask(ETypes.List));
         checkInput(defaultValue, typeToBitMask(listTypeOf(elist.unwrap(list))));
@@ -122,6 +170,13 @@ abstract contract EList is
         emit EListGetOr(list, index, defaultValue, result, getNewEventId());
     }
 
+    /// @notice Sets an encrypted element at an encrypted index.
+    /// @dev Returns a new list with the element replaced; original list is unchanged.
+    /// Index must be euint256. Out-of-range behavior is handled by the covalidator.
+    /// @param list The encrypted list to modify.
+    /// @param index The encrypted index to set.
+    /// @param value The new encrypted value (must match list element type).
+    /// @return result A new encrypted list with the element replaced.
     function listSet(elist list, bytes32 index, bytes32 value) external returns (elist result) {
         checkInput(elist.unwrap(list), typeToBitMask(ETypes.List));
         checkInput(index, typeToBitMask(ETypes.Uint256)); //Currently we only support euint256 for index
@@ -139,6 +194,12 @@ abstract contract EList is
         emit EListSet(list, index, value, result, getNewEventId());
     }
 
+    /// @notice Inserts an encrypted element at an encrypted index, shifting subsequent elements.
+    /// @dev Returns a new list with one additional element. Index must be euint256.
+    /// @param list The encrypted list to modify.
+    /// @param index The encrypted index at which to insert.
+    /// @param value The encrypted value to insert (must match list element type).
+    /// @return result A new encrypted list with the element inserted.
     function listInsert(elist list, bytes32 index, bytes32 value) external returns (elist result) {
         checkInput(elist.unwrap(list), typeToBitMask(ETypes.List));
         checkInput(index, typeToBitMask(ETypes.Uint256)); //Currently we only support euint256 for index
@@ -156,6 +217,11 @@ abstract contract EList is
         emit EListInsert(list, index, value, result, getNewEventId());
     }
 
+    /// @notice Concatenates two encrypted lists into a new list.
+    /// @dev Both lists must have the same element type. Returns a new list with all elements.
+    /// @param lhs The first encrypted list.
+    /// @param rhs The second encrypted list (must have same element type as lhs).
+    /// @return result A new encrypted list containing all elements from both lists.
     function listConcat(elist lhs, elist rhs) external returns (elist result) {
         checkInput(elist.unwrap(lhs), typeToBitMask(ETypes.List));
         checkInput(elist.unwrap(rhs), typeToBitMask(ETypes.List));
@@ -175,6 +241,13 @@ abstract contract EList is
         emit EListConcat(lhs, rhs, result, getNewEventId());
     }
 
+    /// @notice Extracts a slice from an encrypted list starting at an encrypted index.
+    /// @dev Returns a new list of the specified length. Uses defaultValue for out-of-range positions.
+    /// @param list The encrypted list to slice.
+    /// @param start The encrypted starting index.
+    /// @param len The number of elements to include in the slice.
+    /// @param defaultValue The encrypted value to use for out-of-range positions.
+    /// @return result A new encrypted list containing the slice.
     function listSlice(elist list, bytes32 start, uint16 len, bytes32 defaultValue) external returns (elist result) {
         checkInput(elist.unwrap(list), typeToBitMask(ETypes.List));
         checkInput(defaultValue, typeToBitMask(listTypeOf(elist.unwrap(list))));
@@ -192,6 +265,11 @@ abstract contract EList is
         emit EListSlice(list, start, len, defaultValue, result, getNewEventId());
     }
 
+    /// @notice Creates an encrypted list containing a range of encrypted integers.
+    /// @dev Creates a list of euint256 values from start (inclusive) to end (exclusive).
+    /// @param start The starting value (inclusive).
+    /// @param end The ending value (exclusive). Must be >= start.
+    /// @return result A new encrypted list containing the range [start, end).
     function listRange(uint16 start, uint16 end) external returns (elist result) {
         require(start <= end, InvalidRange(start, end));
 
@@ -202,6 +280,11 @@ abstract contract EList is
         emit EListRange(start, end, result, getNewEventId());
     }
 
+    /// @notice Randomly shuffles the elements of an encrypted list.
+    /// @dev This is a paid operation. Returns a new list with elements in random order.
+    /// The shuffle is cryptographically secure, computed by the covalidator.
+    /// @param list The encrypted list to shuffle.
+    /// @return result A new encrypted list with elements in random order.
     function listShuffle(elist list) external payable paying returns (elist result) {
         checkInput(elist.unwrap(list), typeToBitMask(ETypes.List));
         randCounter++;
@@ -217,6 +300,10 @@ abstract contract EList is
         emit EListShuffle(list, randCounter, result, getNewEventId());
     }
 
+    /// @notice Reverses the order of elements in an encrypted list.
+    /// @dev Returns a new list with elements in reverse order; original list is unchanged.
+    /// @param list The encrypted list to reverse.
+    /// @return result A new encrypted list with elements in reverse order.
     function listReverse(elist list) external returns (elist result) {
         checkInput(elist.unwrap(list), typeToBitMask(ETypes.List));
 

package/src/lightning-parts/primitives/EListHandleGeneration.sol

@@ -5,8 +5,27 @@ import {ETypes, EOps} from "@inco/lightning/src/Types.sol";
 import {HandleGeneration} from "@inco/lightning/src/lightning-parts/primitives/HandleGeneration.sol";
 import {EListHandleMetadata} from "./EListHandleMetadata.sol";
 
+/// @title EListHandleGeneration
+/// @notice Generates deterministic handles for encrypted list operations
+/// @dev Extends the base HandleGeneration with list-specific handle creation.
+///      List handles incorporate additional metadata:
+///      - List length (number of elements)
+///      - Element type (encrypted type of individual elements)
+///      - List marker (ETypes.List to identify as a list)
+///
+///      The handle is derived from:
+///      - The operation type (EOps.NewEList for list creation)
+///      - The packed input handles (for lists created from existing handles)
 contract EListHandleGeneration is HandleGeneration, EListHandleMetadata {
 
+    /// @notice Creates a handle for a list operation result
+    /// @dev Generates a deterministic handle by hashing the operation and inputs,
+    ///      then embedding list metadata (length, element type, list marker, version).
+    /// @param op The operation that produced this list (e.g., NewEList, Slice)
+    /// @param listType The encrypted type of individual list elements (euint8, euint64, etc.)
+    /// @param len The number of elements in the resulting list
+    /// @param packedInputs ABI-packed representation of the input handles
+    /// @return result The deterministic handle for this list
     function createListResultHandle(EOps op, ETypes listType, uint16 len, bytes memory packedInputs)
         internal
         pure
@@ -18,6 +37,13 @@ contract EListHandleGeneration is HandleGeneration, EListHandleMetadata {
         result = embedTypeVersion(baseHandle, ETypes.List);
     }
 
+    /// @notice Creates a handle for a new list composed from individual encrypted handles
+    /// @dev This is the primary entry point for creating lists from existing encrypted values.
+    ///      The handle is deterministically derived from the input handles, ensuring the same
+    ///      inputs always produce the same list handle.
+    /// @param handles Array of encrypted value handles to combine into a list
+    /// @param listType The encrypted type of all elements (must be uniform)
+    /// @return newHandle The deterministic handle for the new list
     function createListInputHandle(bytes32[] memory handles, ETypes listType)
         internal
         pure

package/src/lightning-parts/primitives/EListHandleMetadata.sol

@@ -4,23 +4,55 @@ pragma solidity ^0.8;
 import {ETypes} from "@inco/lightning/src/Types.sol";
 import {IEListHandleMetadata} from "./interfaces/IEListHandleMetadata.sol";
 
+/// @title EListHandleMetadata
+/// @notice Utilities for embedding and extracting metadata from encrypted list handles
+/// @dev Encrypted lists have additional metadata compared to scalar handles:
+///      Handle structure (32 bytes / 256 bits):
+///      - Bytes 0-26: Handle-specific data (hash, counters, etc.)
+///      - Bytes 27-28: List length (uint16, max 65535 elements)
+///      - Byte 29: Element type (ETypes enum value for individual elements)
+///      - Byte 30: List type marker (identifies this as a list handle)
+///      - Byte 31: Handle version
+///
+///      This allows efficient extraction of list metadata without external calls.
 contract EListHandleMetadata is IEListHandleMetadata {
 
+    /// @notice Embeds the list length into a list handle
+    /// @dev Sets bytes 27-28 of the handle to the list length.
+    ///      Clears existing length bits before setting new value.
+    /// @param prehandle The 32-byte handle before length embedding
+    /// @param len The number of elements in the list (max 65535)
+    /// @return result The handle with embedded list length
     function embedListLength(bytes32 prehandle, uint16 len) internal pure returns (bytes32 result) {
         // 27 and 28 bits are used for the list length
         result = prehandle & 0xffffffffffffffffffffffffffffffffffffffffffffffffffffff0000ffffff;
         result = bytes32(uint256(result) | (uint256(len) << 24)); // append length
     }
 
+    /// @notice Extracts the list length from a list handle
+    /// @dev Reads bytes 27-28 of the handle as a uint16
+    /// @param handle The encrypted list handle to inspect
+    /// @return The number of elements in the list
     function lengthOf(bytes32 handle) public pure returns (uint16) {
         return uint16(uint256(handle) >> 24);
     }
 
+    /// @notice Embeds the element type into a list handle
+    /// @dev Sets byte 29 of the handle to the element type.
+    ///      This indicates the encrypted type of individual elements (euint8, euint64, etc.).
+    /// @param prehandle The 32-byte handle before type embedding
+    /// @param listType The encrypted type of list elements
+    /// @return result The handle with embedded element type
     function embedListType(bytes32 prehandle, ETypes listType) internal pure returns (bytes32 result) {
         result = prehandle & 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffff00ffff;
         result = bytes32(uint256(result) | (uint256(listType) << 16)); // append element type
     }
 
+    /// @notice Extracts the element type from a list handle
+    /// @dev Reads byte 29 of the handle and casts to ETypes enum.
+    ///      This is the type of individual elements, not the list container type.
+    /// @param handle The encrypted list handle to inspect
+    /// @return The encrypted type of list elements (euint8, euint64, etc.)
     function listTypeOf(bytes32 handle) internal pure returns (ETypes) {
         return ETypes(uint8(uint256(handle) >> 16));
     }