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

package/src/lightning-parts/EncryptedOperations.sol

@@ -7,9 +7,21 @@ import {HandleGeneration} from "./primitives/HandleGeneration.sol";
 import {IEncryptedOperations} from "./interfaces/IEncryptedOperations.sol";
 import {Fee} from "./Fee.sol";
 
+/// @title EncryptedOperations
+/// @notice Provides operations on encrypted values.
+/// @dev All operations require the caller to have access to the input handles. Results are granted
+/// transient access to the caller. Each operation emits an event that is processed by the covalidator
+/// to perform the actual computation off-chain. The result handle is deterministically derived
+/// from the operation and inputs, enabling consistent state across chains.
 abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControlList, HandleGeneration, Fee {
 
+    /// @notice Thrown when an operation receives a handle of an unexpected type.
+    /// @param actual The actual type of the handle.
+    /// @param expectedTypes A bitmask of the expected types.
     error UnexpectedType(ETypes actual, bytes32 expectedTypes);
+
+    /// @notice Thrown when an operation receives an unsupported type.
+    /// @param actual The unsupported type.
     error UnsupportedType(ETypes actual);
 
     uint256 internal randCounter;
@@ -55,17 +67,26 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
     event ENot(ebool indexed operand, ebool indexed result, uint256 eventId);
     event ECast(bytes32 indexed ct, uint8 indexed toType, bytes32 indexed result, uint256 eventId);
 
+    /// @dev Validates that both inputs are euint256 and the caller has access to them.
     modifier checked(euint256 lhs, euint256 rhs) {
         checkInput(euint256.unwrap(lhs), typeToBitMask(ETypes.Uint256));
         checkInput(euint256.unwrap(rhs), typeToBitMask(ETypes.Uint256));
         _;
     }
 
+    /// @dev Validates that the caller has access to the input handle and that its type matches the required types.
+    /// @param input The handle to validate.
+    /// @param requiredTypes A bitmask of acceptable types for this input.
     function checkInput(bytes32 input, bytes32 requiredTypes) internal view {
         require(isAllowed(input, msg.sender), SenderNotAllowedForHandle(input, msg.sender));
         require(requiredTypes & typeToBitMask(typeOf(input)) != 0, UnexpectedType(typeOf(input), requiredTypes));
     }
 
+    /// @dev Creates a result handle for an operation and grants transient access to the caller.
+    /// @param op The operation type.
+    /// @param returnType The type of the result handle.
+    /// @param packedInputs The packed input handles.
+    /// @return result The generated result handle.
     function createResultHandle(EOps op, ETypes returnType, bytes memory packedInputs)
         internal
         returns (bytes32 result)
@@ -74,6 +95,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         allowTransientInternal(result, msg.sender);
     }
 
+    /// @notice Adds two encrypted uint256 values.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand.
+    /// @return result The encrypted sum (lhs + rhs).
     function eAdd(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Add, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -83,6 +108,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Subtracts one encrypted uint256 from another.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand.
+    /// @return result The encrypted difference (lhs - rhs).
     function eSub(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Sub, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -92,6 +121,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Multiplies two encrypted uint256 values.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand.
+    /// @return result The encrypted product (lhs * rhs).
     function eMul(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Mul, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -101,6 +134,11 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Divides one encrypted uint256 by another.
+    /// @dev Division by zero returns zero.
+    /// @param lhs The dividend (encrypted).
+    /// @param rhs The divisor (encrypted).
+    /// @return result The encrypted quotient (lhs / rhs).
     function eDiv(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Div, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -110,6 +148,11 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Computes the remainder of dividing one encrypted uint256 by another.
+    /// @dev Remainder by zero returns zero.
+    /// @param lhs The dividend (encrypted).
+    /// @param rhs The divisor (encrypted).
+    /// @return result The encrypted remainder (lhs % rhs).
     function eRem(euint256 lhs, euint256 rhs) external virtual checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Rem, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -119,6 +162,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Performs bitwise AND on two encrypted values of the same type.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand (must be same type as lhs).
+    /// @return result The encrypted bitwise AND result.
     function eBitAnd(bytes32 lhs, bytes32 rhs) external returns (bytes32 result) {
         ETypes lhsType = typeOf(lhs);
         ETypes rhsType = typeOf(rhs);
@@ -131,6 +178,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Performs bitwise OR on two encrypted values of the same type.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand (must be same type as lhs).
+    /// @return result The encrypted bitwise OR result.
     function eBitOr(bytes32 lhs, bytes32 rhs) external returns (bytes32 result) {
         ETypes lhsType = typeOf(lhs);
         ETypes rhsType = typeOf(rhs);
@@ -143,6 +194,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Performs bitwise XOR on two encrypted values of the same type.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand (must be same type as lhs).
+    /// @return result The encrypted bitwise XOR result.
     function eBitXor(bytes32 lhs, bytes32 rhs) external returns (bytes32 result) {
         ETypes lhsType = typeOf(lhs);
         ETypes rhsType = typeOf(rhs);
@@ -155,6 +210,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Shifts an encrypted uint256 left by an encrypted number of bits.
+    /// @param lhs The value to shift (encrypted).
+    /// @param rhs The number of bits to shift by (encrypted).
+    /// @return result The encrypted left-shifted result.
     function eShl(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Shl, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -164,6 +223,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Shifts an encrypted uint256 right by an encrypted number of bits.
+    /// @param lhs The value to shift (encrypted).
+    /// @param rhs The number of bits to shift by (encrypted).
+    /// @return result The encrypted right-shifted result.
     function eShr(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Shr, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -173,6 +236,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Rotates an encrypted uint256 left by an encrypted number of bits.
+    /// @param lhs The value to rotate (encrypted).
+    /// @param rhs The number of bits to rotate by (encrypted).
+    /// @return result The encrypted left-rotated result.
     function eRotl(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Rotl, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -182,6 +249,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Rotates an encrypted uint256 right by an encrypted number of bits.
+    /// @param lhs The value to rotate (encrypted).
+    /// @param rhs The number of bits to rotate by (encrypted).
+    /// @return result The encrypted right-rotated result.
     function eRotr(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Rotr, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -191,6 +262,11 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Checks if two encrypted values are equal.
+    /// @dev Supports euint256, ebool, and eaddress types.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand.
+    /// @return result An encrypted boolean (true if lhs == rhs).
     function eEq(bytes32 lhs, bytes32 rhs) external returns (ebool result) {
         checkInput(lhs, SUPPORTED_TYPES_MASK);
         checkInput(rhs, SUPPORTED_TYPES_MASK);
@@ -201,6 +277,11 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Checks if two encrypted values are not equal.
+    /// @dev Supports euint256, ebool, and eaddress types.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand.
+    /// @return result An encrypted boolean (true if lhs != rhs).
     function eNe(bytes32 lhs, bytes32 rhs) external returns (ebool result) {
         checkInput(lhs, SUPPORTED_TYPES_MASK);
         checkInput(rhs, SUPPORTED_TYPES_MASK);
@@ -211,6 +292,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Checks if lhs is greater than or equal to rhs.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand.
+    /// @return result An encrypted boolean (true if lhs >= rhs).
     function eGe(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (ebool result) {
         result = ebool.wrap(
             createResultHandle(EOps.Ge, ETypes.Bool, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -220,6 +305,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Checks if lhs is greater than rhs.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand.
+    /// @return result An encrypted boolean (true if lhs > rhs).
     function eGt(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (ebool result) {
         result = ebool.wrap(
             createResultHandle(EOps.Gt, ETypes.Bool, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -229,6 +318,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Checks if lhs is less than or equal to rhs.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand.
+    /// @return result An encrypted boolean (true if lhs <= rhs).
     function eLe(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (ebool result) {
         result = ebool.wrap(
             createResultHandle(EOps.Le, ETypes.Bool, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -238,6 +331,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Checks if lhs is less than rhs.
+    /// @param lhs The left-hand side encrypted operand.
+    /// @param rhs The right-hand side encrypted operand.
+    /// @return result An encrypted boolean (true if lhs < rhs).
     function eLt(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (ebool result) {
         result = ebool.wrap(
             createResultHandle(EOps.Lt, ETypes.Bool, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -247,6 +344,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Returns the minimum of two encrypted uint256 values.
+    /// @param lhs The first encrypted value.
+    /// @param rhs The second encrypted value.
+    /// @return result The encrypted minimum value.
     function eMin(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Min, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -256,6 +357,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Returns the maximum of two encrypted uint256 values.
+    /// @param lhs The first encrypted value.
+    /// @param rhs The second encrypted value.
+    /// @return result The encrypted maximum value.
     function eMax(euint256 lhs, euint256 rhs) external checked(lhs, rhs) returns (euint256 result) {
         result = euint256.wrap(
             createResultHandle(EOps.Max, ETypes.Uint256, abi.encodePacked(euint256.unwrap(lhs), euint256.unwrap(rhs)))
@@ -265,6 +370,9 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Performs logical NOT on an encrypted boolean.
+    /// @param operand The encrypted boolean to negate.
+    /// @return result The negated encrypted boolean.
     function eNot(ebool operand) external returns (ebool result) {
         checkInput(ebool.unwrap(operand), typeToBitMask(ETypes.Bool));
         result = ebool.wrap(createResultHandle(EOps.Not, ETypes.Bool, abi.encodePacked(ebool.unwrap(operand))));
@@ -273,6 +381,11 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Casts an encrypted value to a different encrypted type.
+    /// @dev Supports casting between euint256, ebool, and eaddress.
+    /// @param ct The encrypted value to cast.
+    /// @param toType The target type to cast to.
+    /// @return result The casted encrypted value.
     function eCast(bytes32 ct, ETypes toType) external returns (bytes32 result) {
         checkInput(ct, SUPPORTED_TYPES_MASK);
         require(isTypeSupported(toType), UnsupportedType(toType));
@@ -283,6 +396,10 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Generates an encrypted random value of the specified type.
+    /// @dev This is a paid operation.
+    /// @param randType The type of random value to generate.
+    /// @return result An encrypted random value.
     function eRand(ETypes randType) external payable paying returns (bytes32 result) {
         require(isTypeSupported(randType), UnsupportedType(randType));
         randCounter++;
@@ -292,6 +409,11 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @notice Generates an encrypted random value bounded by an upper limit.
+    /// @dev This is a paid operation. The result is in the range [0, upperBound).
+    /// @param upperBound The encrypted upper bound (exclusive).
+    /// @param randType The type of random value to generate.
+    /// @return result An encrypted random value less than upperBound.
     function eRandBounded(bytes32 upperBound, ETypes randType) external payable paying returns (bytes32 result) {
         require(isTypeSupported(randType), UnsupportedType(randType));
         checkInput(upperBound, typeToBitMask(ETypes.Uint256));
@@ -302,7 +424,13 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
-    // todo add support in testing framework
+    /// @notice Selects between two encrypted values based on an encrypted condition.
+    /// @dev Returns ifTrue if control is true, otherwise returns ifFalse.
+    /// Both ifTrue and ifFalse must be the same type.
+    /// @param control The encrypted boolean condition.
+    /// @param ifTrue The value to return if control is true.
+    /// @param ifFalse The value to return if control is false.
+    /// @return result The selected encrypted value.
     function eIfThenElse(ebool control, bytes32 ifTrue, bytes32 ifFalse) external returns (bytes32 result) {
         ETypes returnType = checkEIfThenElseInputs(control, ifTrue, ifFalse);
         result =
@@ -313,6 +441,11 @@ abstract contract EncryptedOperations is IEncryptedOperations, BaseAccessControl
         setDigest(abi.encodePacked(result, id));
     }
 
+    /// @dev Validates inputs for eIfThenElse operation.
+    /// @param control The encrypted boolean condition (must be ebool).
+    /// @param ifTrue The value to return if control is true.
+    /// @param ifFalse The value to return if control is false (must match ifTrue type).
+    /// @return ifTrueType The type of the ifTrue/ifFalse values.
     function checkEIfThenElseInputs(ebool control, bytes32 ifTrue, bytes32 ifFalse)
         internal
         view

package/src/lightning-parts/Fee.sol

@@ -1,34 +1,57 @@
 // SPDX-License-Identifier: No License
 pragma solidity ^0.8;
 
-// the fee should be modified through upgrades to limit gas cost
+/// @dev The current fee required for paid encryption operations.
+///      This constant may be modified through contract upgrades.
+///      Developers should call getFee() rather than hardcoding this value.
 uint256 constant FEE = 0.000001 ether;
 
-/// @notice Fee utils for lightning functions that require a fee
-/// @dev the fee may be changed through upgrades, develop your apps accordingly!
+/// @title Fee
+/// @notice Fee management utilities for encryption operations that require payment
+/// @dev Certain operations (encrypted inputs, randomness) require a fee to cover covalidator costs.
+///      The fee is paid via msg.value and accumulates in the contract balance.
+///      The contract owner can withdraw accumulated fees via withdrawFees() in IncoLightning.
+///
+///      Important: The fee amount may change through contract upgrades. Always use getFee()
+///      to determine the current fee rather than hardcoding values.
 abstract contract Fee {
 
+    /// @notice Thrown when the exact required fee is not paid
     error FeeNotPaid();
+
+    /// @notice Thrown when the ETH transfer during fee withdrawal fails
     error FeeWithdrawalFailed();
+
+    /// @notice Thrown when attempting to withdraw with zero balance
     error NoFeesToWithdraw();
 
-    /// @notice the fee to pay through msg.value for inputs and randomness IT MAY CHANGE
+    /// @notice Returns the fee required for paid operations
+    /// @dev The fee may change through contract upgrades. Always query this function
+    ///      to get the current fee rather than caching the value.
+    /// @return The fee amount in wei
     function getFee() public pure returns (uint256) {
         return FEE;
     }
 
+    /// @notice Modifier that requires the exact fee to be paid via msg.value
+    /// @dev Use this modifier on functions that require a single fee payment (e.g., single input)
     modifier paying() {
         require(msg.value == FEE, FeeNotPaid());
         _;
     }
 
+    /// @notice Modifier that requires multiple fees to be paid via msg.value
+    /// @dev Use this modifier on functions that require payment for multiple operations (e.g., batch inputs)
+    /// @param nbOfFees The number of fee units required (total cost = FEE * nbOfFees)
     modifier payingMultiple(uint256 nbOfFees) {
         require(msg.value == FEE * nbOfFees, FeeNotPaid());
         _;
     }
 
-    /// @notice Internal helper to withdraw accumulated fees to a recipient
-    /// @param recipient The address to send the fees to
+    /// @notice Withdraws all accumulated fees to the specified recipient
+    /// @dev Internal function called by IncoLightning.withdrawFees(). Transfers the entire
+    ///      contract balance to the recipient.
+    /// @param recipient The address to send the accumulated fees to
     function _withdrawFeesTo(address recipient) internal {
         uint256 fees = address(this).balance;
         require(fees > 0, NoFeesToWithdraw());

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

@@ -5,8 +5,8 @@ import {euint256, ebool, eaddress} from "../../Types.sol";
 
 interface IEncryptedInput {
 
-    function newEuint256(bytes memory ciphertext, address user) external payable returns (euint256 newValue);
-    function newEbool(bytes memory ciphertext, address user) external payable returns (ebool newValue);
-    function newEaddress(bytes memory ciphertext, address user) external payable returns (eaddress newValue);
+    function newEuint256(bytes calldata ciphertext, address user) external payable returns (euint256 newValue);
+    function newEbool(bytes calldata ciphertext, address user) external payable returns (ebool newValue);
+    function newEaddress(bytes calldata ciphertext, address user) external payable returns (eaddress newValue);
 
 }

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

@@ -3,15 +3,25 @@ pragma solidity ^0.8;
 
 import {IEventCounter} from "./interfaces/IEventCounter.sol";
 
+/// @title EventCounterStorage
+/// @notice Diamond storage pattern for the event counter state
+/// @dev Uses a unique storage slot to avoid conflicts with other contracts in the inheritance chain.
+///      The event counter provides unique, sequential identifiers for encrypted operations within a transaction.
 contract EventCounterStorage {
 
+    /// @notice Storage struct containing the event counter state
+    /// @dev eventCounter is incremented for each encrypted operation to ensure unique handle generation
     struct Storage {
-        // TODO: change type to bytes32 when we rename away from "counter".
-        uint256 eventCounter;
+        /// @notice Counter that increments for each event, or stores a digest for batch operations
+        uint256 eventCounter; // TODO: change type to bytes32 when we rename away from "counter".
     }
 
+    /// @notice Storage slot location using keccak256 of a unique namespace string
     bytes32 private constant EVENT_COUNTER_STORAGE_LOCATION = keccak256("lightning.storage.EventCounter");
 
+    /// @notice Retrieves the storage struct from its dedicated slot
+    /// @dev Uses assembly to directly access the storage slot for gas efficiency
+    /// @return $ Reference to the Storage struct
     function getEventCounterStorage() internal pure returns (Storage storage $) {
         bytes32 loc = EVENT_COUNTER_STORAGE_LOCATION;
         assembly {
@@ -21,23 +31,44 @@ contract EventCounterStorage {
 
 }
 
+/// @title EventCounter
+/// @notice Manages unique event identifiers for encrypted operation handle generation
+/// @dev Each encrypted operation requires a unique identifier to generate deterministic handles.
+///      This contract provides two modes:
+///      1. Sequential mode: getNewEventId() increments counter for each operation
+///      2. Digest mode: setDigest() sets counter to hash of serialized operations (for batching)
+///
+///      The event ID is incorporated into handle generation to ensure uniqueness even when
+///      the same operation is performed multiple times in the same transaction.
 contract EventCounter is IEventCounter, EventCounterStorage {
 
+    /// @notice Generates and returns a new unique event ID
+    /// @dev Post-increments the counter, so the returned value is the ID before incrementing.
+    ///      This ensures each call returns a unique ID within the contract's lifetime.
+    /// @return newEventId The event ID to use for this operation
     function getNewEventId() internal returns (uint256 newEventId) {
         newEventId = getEventCounterStorage().eventCounter++;
     }
 
+    /// @notice Sets the event counter to a digest value for batch operation tracking
+    /// @dev Used when processing batched operations where a serialization hash
+    ///      provides better uniqueness than sequential IDs
+    /// @param serialization The serialized batch data to hash
     function setDigest(bytes memory serialization) internal {
         getEventCounterStorage().eventCounter = uint256(keccak256(serialization));
     }
 
-    // @notice Gives the next event ID value to use.
+    /// @notice Returns the next event ID that will be assigned
+    /// @dev View function that does not modify state. Useful for predicting handles
+    ///      or verifying the current state of the counter.
+    /// @return The next event ID value
     function getNextEventId() public view returns (uint256) {
         return getEventCounterStorage().eventCounter;
     }
 
-    // @notice Gives the current value of the event counter.
-    // @dev DEPRECATED: use getNextEventId() instead.
+    /// @notice Returns the current value of the event counter
+    /// @dev Deprecated: Use getNextEventId() instead. Kept for backwards compatibility.
+    /// @return The current event counter value
     function getEventCounter() public view returns (uint256) {
         return getNextEventId();
     }

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

@@ -5,35 +5,63 @@ import {ETypes, EOps, EVM_HOST_CHAIN_PREFIX, HANDLE_INDEX} from "../../Types.sol
 import {HandleMetadata} from "./HandleMetadata.sol";
 import {IHandleGeneration} from "./interfaces/IHandleGeneration.sol";
 
+/// @title HandleGeneration
+/// @notice Generates deterministic handles for encrypted values.
+/// @dev Handles are unique identifiers for encrypted ciphertexts. They are computed deterministically
+/// from the operation type and inputs, ensuring the same encrypted operation always produces the same
+/// handle. This enables consistent state across chains and allows the covalidator to map handles to
+/// their corresponding ciphertexts. Handles embed type and version metadata in their lower bytes.
 contract HandleGeneration is IHandleGeneration, HandleMetadata {
 
+    /// @notice Generates a handle for a trivially encrypted value.
+    /// @dev Trivial encryption creates a handle from a known plaintext. The handle is deterministic
+    /// based on the plaintext value, allowing the same plaintext to always produce the same handle.
+    /// @param plaintextBytes The plaintext value as bytes32.
+    /// @param handleType The type of encrypted value (euint256, ebool, etc.).
+    /// @return generatedHandle The deterministic handle for this trivial encryption.
     function getTrivialEncryptHandle(bytes32 plaintextBytes, ETypes handleType)
         public
         pure
         returns (bytes32 generatedHandle)
     {
-        generatedHandle = keccak256(
-            abi.encodePacked(
-                EOps.TrivialEncrypt, // !! Note[Silas]: I reordered this to be first element for greater regularity 26/08/2025 (remove this note after 1 month) !!
-                plaintextBytes
-            )
-        );
+        generatedHandle = keccak256(abi.encodePacked(EOps.TrivialEncrypt, plaintextBytes));
         generatedHandle = embedTypeVersion(generatedHandle, handleType);
     }
 
-    function getInputHandle(bytes memory ciphertext, address user, address contractAddress, ETypes inputType)
-        internal
-        view
-        returns (bytes32 generatedHandle)
-    {
-        return getInputHandle(ciphertext, address(this), user, contractAddress, inputType);
+    /// @notice Generates a handle for a client-encrypted input.
+    /// @dev Internal version that uses the current contract as the executor address.
+    /// The handle is computed from the ciphertext and context (chain, executor, user, contract).
+    /// @param ciphertext The encrypted input data.
+    /// @param user The user address that encrypted the value.
+    /// @param contractAddress The contract submitting the input.
+    /// @param version The version of the handle format.
+    /// @param inputType The type of encrypted value.
+    /// @return generatedHandle The deterministic handle for this input.
+    function getInputHandle(
+        bytes memory ciphertext,
+        address user,
+        address contractAddress,
+        int32 version,
+        ETypes inputType
+    ) internal view returns (bytes32 generatedHandle) {
+        return getInputHandle(ciphertext, address(this), user, contractAddress, version, inputType);
     }
 
+    /// @notice Generates a handle for a client-encrypted input with explicit executor.
+    /// @dev The handle incorporates the full context (chain ID, executor, user, contract) to ensure
+    /// uniqueness across different chains and deployments. This prevents replay attacks.
+    /// @param ciphertext The encrypted input data.
+    /// @param executorAddress The executor contract address.
+    /// @param user The user address that encrypted the value.
+    /// @param contractAddress The contract submitting the input.
+    /// @param inputType The type of encrypted value.
+    /// @return generatedHandle The deterministic handle for this input.
     function getInputHandle(
         bytes memory ciphertext,
         address executorAddress,
         address user,
         address contractAddress,
+        int32 version,
         ETypes inputType
     ) internal view returns (bytes32 generatedHandle) {
         // Here we ensure that our hashing scheme is binary-compatible between IncoLightning and IncoFhevm, this helps
@@ -49,13 +77,21 @@ contract HandleGeneration is IHandleGeneration, HandleMetadata {
                     block.chainid, // todo cache this
                     executorAddress,
                     user,
-                    contractAddress
+                    contractAddress,
+                    version
                 )
             ),
             inputType
         );
     }
 
+    /// @notice Generates a handle for the result of an encrypted operation.
+    /// @dev The handle is deterministic based on the operation type and input handles.
+    /// This ensures that the same operation on the same inputs always produces the same result handle.
+    /// @param op The operation type (eAdd, eSub, etc.).
+    /// @param returnType The type of the result value.
+    /// @param packedInputs The packed input handles.
+    /// @return generatedHandle The deterministic handle for this operation result.
     function getOpResultHandle(EOps op, ETypes returnType, bytes memory packedInputs)
         public
         pure

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

@@ -3,8 +3,24 @@ pragma solidity ^0.8;
 
 import {HANDLE_VERSION, HANDLE_INDEX, ETypes} from "../../Types.sol";
 
+/// @title HandleMetadata
+/// @notice Utilities for embedding and extracting metadata from encrypted value handles
+/// @dev Handle structure (32 bytes / 256 bits):
+///      - Bytes 0-28: Handle-specific data (hash, counters, etc.)
+///      - Byte 29: Handle index (distinguishes input vs operation handles)
+///      - Byte 30: Encrypted type (ETypes enum value)
+///      - Byte 31: Handle version
 contract HandleMetadata {
 
+    /// @notice Embeds the handle index, encrypted type, and protocol version into a prehandle
+    /// @dev Used for input handles where the index distinguishes the source.
+    ///      Clears bytes 29-31 of the prehandle, then sets:
+    ///      - Byte 29: HANDLE_INDEX constant
+    ///      - Byte 30: inputType enum value
+    ///      - Byte 31: HANDLE_VERSION constant
+    /// @param prehandle The 32-byte hash before metadata embedding
+    /// @param inputType The encrypted type to embed (ebool, euint8, etc.)
+    /// @return result The complete handle with embedded metadata
     function embedIndexTypeVersion(bytes32 prehandle, ETypes inputType) internal pure returns (bytes32 result) {
         // Create a mask to clear the last three bytes
         bytes32 mask = bytes32(uint256(0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF00FFFF));
@@ -15,12 +31,24 @@ contract HandleMetadata {
         result = embedTypeVersion(result, inputType);
     }
 
+    /// @notice Embeds the encrypted type and protocol version into a prehandle
+    /// @dev Used for operation result handles and trivial encryptions.
+    ///      Clears bytes 30-31 of the prehandle, then sets:
+    ///      - Byte 30: handleType enum value
+    ///      - Byte 31: HANDLE_VERSION constant
+    /// @param prehandle The 32-byte hash before metadata embedding
+    /// @param handleType The encrypted type to embed (ebool, euint8, etc.)
+    /// @return result The handle with type and version embedded
     function embedTypeVersion(bytes32 prehandle, ETypes handleType) internal pure returns (bytes32 result) {
         result = prehandle & 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0000;
         result = bytes32(uint256(result) | (uint256(handleType) << 8)); // append type
         result = bytes32(uint256(result) | HANDLE_VERSION);
     }
 
+    /// @notice Extracts the encrypted type from a handle
+    /// @dev Reads byte 30 of the handle and casts to ETypes enum
+    /// @param handle The encrypted value handle to inspect
+    /// @return The encrypted type (ebool, euint8, euint16, etc.)
     function typeOf(bytes32 handle) internal pure returns (ETypes) {
         return ETypes(uint8(uint256(handle) >> 8));
     }