@inco/lightning 0.8.0-devnet-9 → 0.8.0-devnet-11

package/src/lightning-parts/EList.sol

@@ -0,0 +1,323 @@
+// SPDX-License-Identifier: No License
+pragma solidity ^0.8;
+
+import {
+    ETypes,
+    EOps,
+    typeToBitMask,
+    isTypeSupported,
+    IndexOutOfRange,
+    InvalidRange,
+    ListTypeMismatch,
+    UnsupportedType,
+    elist
+} from "../Types.sol";
+import {EncryptedOperations} from "./EncryptedOperations.sol";
+import {EncryptedInput} from "./EncryptedInput.sol";
+import {EListHandleGeneration} from "./primitives/EListHandleGeneration.sol";
+import {IEList} from "./interfaces/IEList.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.
+abstract contract EList is IEList, EncryptedOperations, EncryptedInput, EListHandleGeneration {
+
+    event NewEList(bytes32 indexed result, ETypes listType, bytes32[] handles, uint256 eventId);
+    event EListAppend(elist indexed list, bytes32 indexed value, elist indexed result, uint256 eventId);
+    event EListGet(elist indexed list, uint16 indexed index, bytes32 indexed result, uint256 eventId);
+    event EListGetOr(
+        elist indexed list, bytes32 index, bytes32 indexed defaultValue, bytes32 indexed result, uint256 eventId
+    );
+    event EListSet(elist list, bytes32 indexed index, bytes32 indexed value, elist indexed result, uint256 eventId);
+    event EListInsert(elist list, bytes32 indexed index, bytes32 indexed value, elist indexed result, uint256 eventId);
+    event EListConcat(elist indexed list1, elist indexed list2, elist indexed result, uint256 eventId);
+    event EListSlice(
+        elist list,
+        bytes32 indexed start,
+        uint16 length,
+        bytes32 indexed defaultValue,
+        elist indexed result,
+        uint256 eventId
+    );
+    event EListRange(uint256 indexed start, uint256 indexed end, elist indexed result, uint256 eventId);
+    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)
+    {
+        require(isTypeSupported(listType), UnsupportedType(listType));
+
+        // TODO: Add a new event to create new elist from inputs, can be done as an upgrade to optimize for gas and castore.
+        bytes32[] memory handles = new bytes32[](inputs.length);
+        for (uint256 i = 0; i < inputs.length; i++) {
+            // we check payment for multiple inputs ahead of this func
+            handles[i] = newInputNotPaying(inputs[i], user, listType);
+        }
+        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++) {
+            checkInput(handles[i], typeToBitMask(listType));
+        }
+
+        bytes32 newHandle = createListInputHandle(handles, listType);
+
+        allowTransientInternal(newHandle, msg.sender);
+
+        emit NewEList(newHandle, listType, handles, getNewEventId());
+
+        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
+        payingMultiple(inputs.length)
+        returns (elist newList)
+    {
+        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))));
+
+        result = elist.wrap(
+            createListResultHandle(
+                EOps.EListAppend,
+                listTypeOf(elist.unwrap(list)),
+                lengthOf(elist.unwrap(list)) + 1,
+                abi.encodePacked(elist.unwrap(list), value)
+            )
+        );
+        allowTransientInternal(elist.unwrap(result), msg.sender);
+        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));
+
+        result =
+            createResultHandle(EOps.EListGet, listTypeOf(elist.unwrap(list)), abi.encodePacked(elist.unwrap(list), i));
+        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))));
+        checkInput(index, typeToBitMask(ETypes.Uint256)); //Currently we only support euint256 for index
+
+        result = createResultHandle(
+            EOps.EListGetOr, listTypeOf(elist.unwrap(list)), abi.encodePacked(elist.unwrap(list), index, defaultValue)
+        );
+        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
+        checkInput(value, typeToBitMask(listTypeOf(elist.unwrap(list))));
+
+        result = elist.wrap(
+            createListResultHandle(
+                EOps.EListSet,
+                listTypeOf(elist.unwrap(list)),
+                lengthOf(elist.unwrap(list)),
+                abi.encodePacked(elist.unwrap(list), index, value)
+            )
+        );
+        allowTransientInternal(elist.unwrap(result), msg.sender);
+        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
+        checkInput(value, typeToBitMask(listTypeOf(elist.unwrap(list))));
+
+        result = elist.wrap(
+            createListResultHandle(
+                EOps.EListInsert,
+                listTypeOf(elist.unwrap(list)),
+                lengthOf(elist.unwrap(list)) + 1,
+                abi.encodePacked(elist.unwrap(list), index, value)
+            )
+        );
+        allowTransientInternal(elist.unwrap(result), msg.sender);
+        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));
+        ETypes lhsType = listTypeOf(elist.unwrap(lhs));
+        ETypes rhsType = listTypeOf(elist.unwrap(rhs));
+        require(lhsType == rhsType, ListTypeMismatch(lhsType, rhsType));
+
+        result = elist.wrap(
+            createListResultHandle(
+                EOps.EListConcat,
+                listTypeOf(elist.unwrap(lhs)),
+                lengthOf(elist.unwrap(lhs)) + lengthOf(elist.unwrap(rhs)),
+                abi.encodePacked(elist.unwrap(lhs), elist.unwrap(rhs))
+            )
+        );
+        allowTransientInternal(elist.unwrap(result), msg.sender);
+        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))));
+        checkInput(start, typeToBitMask(ETypes.Uint256));
+
+        result = elist.wrap(
+            createListResultHandle(
+                EOps.EListSlice,
+                listTypeOf(elist.unwrap(list)),
+                len,
+                abi.encodePacked(elist.unwrap(list), start, defaultValue)
+            )
+        );
+        allowTransientInternal(elist.unwrap(result), msg.sender);
+        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));
+
+        result = elist.wrap(
+            createListResultHandle(EOps.EListRange, ETypes.Uint256, end - start, abi.encodePacked(start, end))
+        );
+        allowTransientInternal(elist.unwrap(result), msg.sender);
+        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++;
+        result = elist.wrap(
+            createListResultHandle(
+                EOps.EListShuffle,
+                listTypeOf(elist.unwrap(list)),
+                lengthOf(elist.unwrap(list)),
+                abi.encodePacked(elist.unwrap(list), bytes32(randCounter))
+            )
+        );
+        allowTransientInternal(elist.unwrap(result), msg.sender);
+        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));
+
+        result = elist.wrap(
+            createListResultHandle(
+                EOps.EListReverse,
+                listTypeOf(elist.unwrap(list)),
+                lengthOf(elist.unwrap(list)),
+                abi.encodePacked(elist.unwrap(list))
+            )
+        );
+        allowTransientInternal(elist.unwrap(result), msg.sender);
+        emit EListReverse(list, result, getNewEventId());
+    }
+
+}

package/src/lightning-parts/TrivialEncryption.sol

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: No License
 pragma solidity ^0.8;
 
-import {EventCounter} from "./primitives/EventCounter.sol";
 import {euint256, ebool, eaddress, ETypes} from "../Types.sol";
 import {BaseAccessControlList} from "./AccessControl/BaseAccessControlList.sol";
 import {HandleGeneration} from "./primitives/HandleGeneration.sol";
@@ -13,7 +12,7 @@ import {ITrivialEncryption} from "./interfaces/ITrivialEncryption.sol";
 /// on-chain (emitted in events), so this should only be used for values that are already public.
 /// Common use cases include initializing encrypted state with known values or creating encrypted
 /// constants. The resulting handles are granted transient access to the caller.
-abstract contract TrivialEncryption is ITrivialEncryption, EventCounter, BaseAccessControlList, HandleGeneration {
+abstract contract TrivialEncryption is ITrivialEncryption, BaseAccessControlList, HandleGeneration {
 
     /// @notice Emitted when a trivial encryption is performed.
     /// @param result The handle representing the encrypted value.

package/src/lightning-parts/interfaces/IDecryptionAttester.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: No License
 pragma solidity ^0.8;
 
-import {DecryptionAttestation} from "../DecryptionAttester.types.sol";
+import {DecryptionAttestation, ElementDecryptionProof} from "../DecryptionAttester.types.sol";
 
 interface IDecryptionAttester {
 
@@ -10,5 +10,11 @@ interface IDecryptionAttester {
         external
         view
         returns (bool);
+    function isValidEListDecryptionAttestation(
+        bytes32 elistHandle,
+        ElementDecryptionProof[] memory proofElements,
+        bytes32 proof,
+        bytes[] memory signatures
+    ) external view returns (bool);
 
 }

package/src/lightning-parts/interfaces/IEList.sol

@@ -0,0 +1,35 @@
+/// SPDX-License-Identifier: No License
+pragma solidity ^0.8;
+
+import {elist, ETypes} from "../../Types.sol";
+import {IEListHandleMetadata} from "../primitives/interfaces/IEListHandleMetadata.sol";
+import {IEncryptedOperations} from "./IEncryptedOperations.sol";
+import {IEncryptedInput} from "./IEncryptedInput.sol";
+
+interface IEList is IEncryptedOperations, IEncryptedInput, IEListHandleMetadata {
+
+    function newEList(bytes32[] memory handles, ETypes listType) external returns (elist newList);
+
+    function newEList(bytes[] calldata inputs, ETypes listType, address user) external payable returns (elist newList);
+
+    function listAppend(elist list, bytes32 value) external returns (elist result);
+
+    function listGet(elist list, uint16 i) external returns (bytes32 result);
+
+    function listGetOr(elist list, bytes32 i, bytes32 defaultValue) external returns (bytes32 result);
+
+    function listSet(elist list, bytes32 i, bytes32 value) external returns (elist result);
+
+    function listInsert(elist list, bytes32 i, bytes32 value) external returns (elist result);
+
+    function listConcat(elist lhs, elist rhs) external returns (elist result);
+
+    function listSlice(elist list, bytes32 start, uint16 len, bytes32 defaultValue) external returns (elist result);
+
+    function listRange(uint16 start, uint16 end) external returns (elist result);
+
+    function listShuffle(elist list) external payable returns (elist result);
+
+    function listReverse(elist list) external returns (elist result);
+
+}

package/src/lightning-parts/interfaces/IEncryptedInput.sol

@@ -2,8 +2,10 @@
 pragma solidity ^0.8;
 
 import {euint256, ebool, eaddress} from "../../Types.sol";
+import {IBaseAccessControlList} from "../AccessControl/interfaces/IBaseAccessControlList.sol";
+import {IHandleGeneration} from "../primitives/interfaces/IHandleGeneration.sol";
 
-interface IEncryptedInput {
+interface IEncryptedInput is IBaseAccessControlList, IHandleGeneration {
 
     error InvalidInputVersion(uint16 version);
     error InputLengthTooShort(uint256 length);

package/src/lightning-parts/interfaces/IEncryptedOperations.sol

@@ -2,8 +2,10 @@
 pragma solidity ^0.8;
 
 import {euint256, ebool, ETypes} from "../../Types.sol";
+import {IBaseAccessControlList} from "../AccessControl/interfaces/IBaseAccessControlList.sol";
+import {IHandleGeneration} from "../primitives/interfaces/IHandleGeneration.sol";
 
-interface IEncryptedOperations {
+interface IEncryptedOperations is IBaseAccessControlList, IHandleGeneration {
 
     function eAdd(euint256 lhs, euint256 rhs) external returns (euint256 result);
     function eSub(euint256 lhs, euint256 rhs) external returns (euint256 result);

package/src/lightning-parts/interfaces/ITrivialEncryption.sol

@@ -2,8 +2,10 @@
 pragma solidity ^0.8;
 
 import {euint256, ebool, eaddress} from "../../Types.sol";
+import {IBaseAccessControlList} from "../AccessControl/interfaces/IBaseAccessControlList.sol";
+import {IHandleGeneration} from "../primitives/interfaces/IHandleGeneration.sol";
 
-interface ITrivialEncryption {
+interface ITrivialEncryption is IBaseAccessControlList, IHandleGeneration {
 
     function asEuint256(uint256 value) external returns (euint256 newEuint256);
     function asEbool(bool value) external returns (ebool newEbool);

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

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: No License
+pragma solidity ^0.8;
+
+import {ETypes, EOps} from "../../Types.sol";
+import {HandleGeneration} from "./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
+        returns (bytes32 result)
+    {
+        bytes32 baseHandle = keccak256(abi.encodePacked(op, packedInputs));
+        baseHandle = embedListLength(baseHandle, len);
+        baseHandle = embedListType(baseHandle, listType);
+        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
+        returns (bytes32 newHandle)
+    {
+        newHandle = createListResultHandle(
+            EOps.NewEList,
+            listType,
+            uint16(handles.length),
+            abi.encodePacked(
+                //Since we're only dealing with handles, it should be sufficient to treat this operation as an operand on handles.
+                handles
+            )
+        );
+    }
+
+}

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

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: No License
+pragma solidity ^0.8;
+
+import {ETypes} from "../../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));
+    }
+
+}

package/src/lightning-parts/primitives/interfaces/IEListHandleMetadata.sol

@@ -0,0 +1,8 @@
+/// SPDX-License-Identifier: No License
+pragma solidity ^0.8;
+
+interface IEListHandleMetadata {
+
+    function lengthOf(bytes32 handle) external pure returns (uint16);
+
+}

package/src/lightning-parts/test/Elist.t.sol

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: No License
+pragma solidity ^0.8;
+
+import {IncoTest} from "../../test/IncoTest.sol";
+import {ElistTester} from "../../test/EListTester.sol";
+import {inco, e} from "../../Lib.sol";
+import {ETypes, elist} from "../../Types.sol";
+import {FEE, Fee} from "../Fee.sol";
+import {EList} from "../EList.sol";
+import {VerifierAddressGetter} from "../primitives/VerifierAddressGetter.sol";
+
+contract ElistFeeTester is EList {
+
+    constructor() VerifierAddressGetter(address(0)) {}
+
+}
+
+contract TestEList is IncoTest {
+
+    ElistTester tester;
+    ElistFeeTester feeTester;
+
+    function setUp() public virtual override {
+        super.setUp();
+        tester = new ElistTester(inco);
+        vm.deal(address(tester), 1 ether);
+        feeTester = new ElistFeeTester();
+    }
+
+    function testNewElistFromInputs() public {
+        createList();
+        // todo test read the created list
+    }
+
+    function testListAppend() public {
+        createList();
+        bytes memory ctValue = fakePrepareEuint256Ciphertext(40, address(this), address(tester));
+        tester.listAppend(ctValue);
+    }
+
+    function createList() internal returns (elist list) {
+        bytes[] memory inputs = new bytes[](3);
+        inputs[0] = fakePrepareEuint256Ciphertext(10, address(this), address(tester));
+        inputs[1] = fakePrepareEuint256Ciphertext(20, address(this), address(tester));
+        inputs[2] = fakePrepareEuint256Ciphertext(30, address(this), address(tester));
+        list = tester.newEList(inputs, ETypes.Uint256, address(this));
+    }
+
+    function testRevertsOnBadFeeAmount() public {
+        // should fail if no fee
+        vm.expectRevert(Fee.FeeNotPaid.selector);
+        feeTester.listShuffle(elist.wrap(bytes32(0)));
+
+        // should fail if not enough fee
+        vm.expectRevert(Fee.FeeNotPaid.selector);
+        feeTester.listShuffle{value: FEE - 1}(elist.wrap(bytes32(0)));
+
+        // should fail if too much fee
+        vm.expectRevert(Fee.FeeNotPaid.selector);
+        feeTester.listShuffle{value: FEE + 1}(elist.wrap(bytes32(0)));
+
+        vm.expectRevert(Fee.FeeNotPaid.selector);
+        bytes[] memory inputs = new bytes[](3);
+        feeTester.newEList{value: FEE * 2}(inputs, ETypes.Uint256, address(this));
+    }
+
+}

package/src/misc/ABIHelper.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: No License
+pragma solidity ^0.8;
+
+import {Session} from "@inco/lightning/src/periphery/SessionVerifier.sol";
+
+// @dev this contract is not used on-chain, it is only used to generate the
+// ABI of some symbols that are not exposed directly by the IncoLightning or
+// periphery contracts, but are needed for the JS SDK.
+contract ABIHelper {
+
+    function getSession() public pure returns (Session memory) {
+        revert("This function exists only to include Session struct in ABI");
+    }
+
+}