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

package/src/lightning-parts/AccessControl/AdvancedAccessControl.sol

@@ -10,14 +10,24 @@ import {SignatureChecker} from "@openzeppelin/contracts/utils/cryptography/Signa
 import {IBaseAccessControlList} from "./interfaces/IBaseAccessControlList.sol";
 import {LightningAddressGetter} from "../primitives/LightningAddressGetter.sol";
 
+/// @title AdvancedAccessControlStorage
+/// @notice Diamond storage pattern for advanced ACL session nonce tracking
+/// @dev Stores per-account session nonces that allow users to invalidate all previously signed vouchers
 abstract contract AdvancedAccessControlStorage {
 
+    /// @notice Storage struct for advanced access control state
     struct AacStorage {
-        mapping(address => bytes32) activeVouchersSessionNonce; // initial session nonce is 0
+        /// @notice Maps account addresses to their active voucher session nonce
+        /// @dev Vouchers signed with a different nonce are invalid. Initial nonce is bytes32(0).
+        mapping(address => bytes32) activeVouchersSessionNonce;
     }
 
+    /// @notice Storage slot location using keccak256 of a unique namespace string
     bytes32 private constant AAC_STORAGE_LOCATION = keccak256("inco.storage.AdvancedAccessControl");
 
+    /// @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 AacStorage struct
     function getAacStorage() internal pure returns (AacStorage storage $) {
         bytes32 loc = AAC_STORAGE_LOCATION;
         assembly {
@@ -27,12 +37,24 @@ abstract contract AdvancedAccessControlStorage {
 
 }
 
+/// @title VoucherEip712Checker
+/// @notice EIP-712 typed data signing utilities for allowance vouchers
+/// @dev Provides deterministic hashing of AllowanceVoucher structs for signature verification.
+///      The voucher structure allows sharers to delegate access to their encrypted data
+///      with flexible verification logic defined by an external contract.
 abstract contract VoucherEip712Checker is IVoucherEip712Checker, EIP712Upgradeable {
 
+    /// @notice EIP-712 type hash for the AllowanceVoucher struct
+    /// @dev Computed once at compile time for gas efficiency
     bytes32 constant ALLOWANCE_VOUCHER_STRUCT_HASH = keccak256(
         "AllowanceVoucher(bytes32 sessionNonce,address verifyingContract,bytes4 callFunction,bytes sharerArgData)"
     );
 
+    /// @notice Computes the EIP-712 digest for an allowance voucher
+    /// @dev The digest can be signed by the sharer to authorize access.
+    ///      Uses EIP-712 structured data hashing with domain separator.
+    /// @param voucher The voucher to compute the digest for
+    /// @return The EIP-712 typed data hash ready for signing
     function allowanceVoucherDigest(AllowanceVoucher memory voucher) public view returns (bytes32) {
         return _hashTypedDataV4(
             keccak256(
@@ -49,6 +71,21 @@ abstract contract VoucherEip712Checker is IVoucherEip712Checker, EIP712Upgradeab
 
 }
 
+/// @title AdvancedAccessControl
+/// @notice Voucher-based access delegation for encrypted data sharing
+/// @dev Enables flexible access control patterns where data owners can sign vouchers
+///      authorizing others to access their encrypted data under specific conditions.
+///
+///      Voucher flow:
+///      1. Sharer signs an AllowanceVoucher specifying conditions (via verifyingContract)
+///      2. Requester presents the voucher with proof when requesting access
+///      3. This contract verifies the signature and calls the verifyingContract
+///      4. Access is granted if the verifyingContract returns ALLOWANCE_GRANTED_MAGIC_VALUE
+///
+///      Security features:
+///      - Session nonces allow sharers to invalidate all previous vouchers
+///      - EIP-712 typed data ensures vouchers are human-readable when signing
+///      - Supports both EOA and smart contract signatures (ERC-1271)
 abstract contract AdvancedAccessControl is
     IAdvancedAccessControl,
     AdvancedAccessControlStorage,
@@ -58,11 +95,28 @@ abstract contract AdvancedAccessControl is
 
     using SignatureChecker for address;
 
+    /// @notice Thrown when a voucher signature is invalid for the claimed signer
+    /// @param signer The address that allegedly signed the voucher
+    /// @param digest The EIP-712 digest that should have been signed
+    /// @param signature The invalid signature provided
     error InvalidVoucherSignature(address signer, bytes32 digest, bytes signature);
+
+    /// @notice Thrown when a voucher's session nonce doesn't match the sharer's active nonce
+    /// @param providedSessionNonce The nonce in the voucher
+    /// @param activeSessionNonce The sharer's current active session nonce
     error InvalidVoucherSessionNonce(bytes32 providedSessionNonce, bytes32 activeSessionNonce);
 
-    /// @dev meant to for simulation, can't be a view function as it calls other contracts
-    /// @dev returns true if the account is allowed to access the handle, false or reverts otherwise
+    /// @notice Checks if an account is allowed to access a handle using a signed voucher proof
+    /// @dev Intended for simulation/off-chain calls. Not a view function as it calls external contracts.
+    ///      Verification steps:
+    ///      1. Verify the sharer has access to the handle
+    ///      2. Verify the voucher signature is valid
+    ///      3. Verify the session nonce is current
+    ///      4. Call the verifyingContract to check access conditions
+    /// @param handle The encrypted value handle to check access for
+    /// @param account The account requesting access
+    /// @param proof The allowance proof containing voucher, signature, and requester data
+    /// @return True if access is allowed, false or reverts otherwise
     function isAllowedWithProof(bytes32 handle, address account, AllowanceProof memory proof) public returns (bool) {
         require(
             IBaseAccessControlList(incoLightningAddress).isAllowed(handle, proof.sharer),
@@ -87,11 +141,18 @@ abstract contract AdvancedAccessControl is
         return (success && result.length >= 32 && abi.decode(result, (bytes32)) == ALLOWANCE_GRANTED_MAGIC_VALUE);
     }
 
+    /// @notice Returns the current active voucher session nonce for an account
+    /// @dev Vouchers must include this nonce to be valid. Initial value is bytes32(0).
+    /// @param account The account to check the session nonce for
+    /// @return The current active session nonce
     function getActiveVouchersSessionNonce(address account) public view returns (bytes32) {
         return getAacStorage().activeVouchersSessionNonce[account];
     }
 
-    /// @notice invalidates all previously signed vouchers
+    /// @notice Invalidates all previously signed vouchers by updating the session nonce
+    /// @dev Generates a new random nonce using the caller's address and block.prevrandao.
+    ///      Any vouchers signed with the previous nonce become invalid immediately.
+    ///      Call this if you suspect voucher compromise or want to revoke all delegations.
     function updateActiveVouchersSessionNonce() external {
         getAacStorage().activeVouchersSessionNonce[msg.sender] =
             keccak256(abi.encodePacked(msg.sender, block.prevrandao));

package/src/lightning-parts/AccessControl/BaseAccessControlList.sol

@@ -7,15 +7,22 @@ import {EventCounter} from "../primitives/EventCounter.sol";
 import {VerifierAddressGetter} from "../primitives/VerifierAddressGetter.sol";
 import {AllowanceProof} from "../AccessControl/AdvancedAccessControl.types.sol";
 
+/// @title AccessControlListStorage
+/// @notice Storage layout for the Access Control List (ACL).
+/// @dev Uses ERC-7201 namespaced storage pattern to avoid storage collisions.
 contract AccessControlListStorage {
 
+    /// @dev Storage struct for ACL state.
     struct AclStorage {
+        /// @dev Maps (handle, account) pairs to persistent access permissions.
         mapping(bytes32 handle => mapping(address account => bool isAllowed)) persistedAllowedPairs;
+        /// @dev Maps handles to whether they are revealed (publicly accessible).
         mapping(bytes32 handle => bool isAllowed) persistedAllowedForDecryption;
     }
 
     bytes32 private constant ACL_STORAGE_LOCATION = keccak256("inco.storage.ACL");
 
+    /// @dev Returns a pointer to the ACL storage struct.
     function getAclStorage() internal pure returns (AclStorage storage $) {
         bytes32 loc = ACL_STORAGE_LOCATION;
         assembly {
@@ -25,6 +32,16 @@ contract AccessControlListStorage {
 
 }
 
+/// @title BaseAccessControlList
+/// @notice Manages access permissions for encrypted handles.
+/// @dev Implements a two-tier permission system:
+/// - **Persistent permissions**: Stored permanently, survive across transactions.
+/// - **Transient permissions**: Stored in transient storage (EIP-1153), cleared at end of transaction.
+///
+/// Access is granted if any of these conditions are true:
+/// 1. Transient permission exists for (handle, account)
+/// 2. Persistent permission exists for (handle, account)
+/// 3. The handle has been revealed (public access)
 abstract contract BaseAccessControlList is
     IBaseAccessControlList,
     AccessControlListStorage,
@@ -32,19 +49,36 @@ abstract contract BaseAccessControlList is
     EventCounter
 {
 
+    /// @notice Thrown when proof verification fails during handle claiming.
+    /// @param verifyingContract The contract that was supposed to verify.
+    /// @param callFunction The function selector that was called.
+    /// @param argData The argument data that failed verification.
     error ProofVerificationFailed(address verifyingContract, bytes4 callFunction, bytes argData);
 
+    /// @notice Emitted when persistent access is granted to an account for a handle.
+    /// @param handle The encrypted handle.
+    /// @param account The account granted access.
+    /// @param eventId The unique event ID.
     event Allow(bytes32 handle, address account, uint256 eventId);
 
+    /// @notice Emitted when a handle is revealed for public access.
+    /// @param handle The encrypted handle that was revealed.
+    /// @param eventId The unique event ID.
     event Reveal(bytes32 handle, uint256 eventId);
 
-    /// @dev persistent
+    /// @notice Grants persistent access to an account for an encrypted handle.
+    /// @dev Caller must already have access to the handle. This permission survives across transactions.
+    /// @param handle The encrypted handle to grant access to.
+    /// @param account The account to grant access to.
     function allow(bytes32 handle, address account) public {
         require(isAllowed(handle, msg.sender), SenderNotAllowedForHandle(handle, msg.sender));
         allowInternal(handle, account);
     }
 
-    /// @dev Permanently allows public decryption/reencryption access to anyone for the given handle.
+    /// @notice Reveals a handle, granting permanent public access to anyone.
+    /// @dev Once revealed, the encrypted value can be decrypted by anyone. This is irreversible.
+    /// Caller must have access to the handle.
+    /// @param handle The encrypted handle to reveal.
     function reveal(bytes32 handle) public {
         require(isAllowed(handle, msg.sender), SenderNotAllowedForHandle(handle, msg.sender));
         AclStorage storage $ = getAclStorage();
@@ -54,7 +88,9 @@ abstract contract BaseAccessControlList is
         setDigest(abi.encodePacked(EOps.Reveal, handle, id));
     }
 
-    /// @dev persistent
+    /// @dev Internal function to grant persistent access without ownership check.
+    /// @param handle The encrypted handle to grant access to.
+    /// @param account The account to grant access to.
     function allowInternal(bytes32 handle, address account) internal {
         AclStorage storage $ = getAclStorage();
         $.persistedAllowedPairs[handle][account] = true;
@@ -63,13 +99,20 @@ abstract contract BaseAccessControlList is
         setDigest(abi.encodePacked(EOps.Allow, handle, account, id));
     }
 
-    // todo current transient allowance is unsafe, make storage account bound + how to clean between UserOps
+    /// @notice Grants transient access to an account for an encrypted handle.
+    /// @dev Transient permissions are cleared at the end of the transaction (EIP-1153).
+    /// Caller must have access to the handle.
+    /// @param handle The encrypted handle to grant access to.
+    /// @param account The account to grant access to.
     function allowTransient(bytes32 handle, address account) public {
         require(isAllowed(handle, msg.sender), SenderNotAllowedForHandle(handle, msg.sender));
         allowTransientInternal(handle, account);
     }
 
-    /// @dev no ownership check is performed
+    /// @dev Internal function to grant transient access without ownership check.
+    /// Uses assembly to store in transient storage and track keys for cleanup.
+    /// @param handle The encrypted handle to grant access to.
+    /// @param account The account to grant access to.
     function allowTransientInternal(bytes32 handle, address account) internal {
         bytes32 key = keccak256(abi.encodePacked(handle, account));
         assembly {
@@ -81,6 +124,10 @@ abstract contract BaseAccessControlList is
         }
     }
 
+    /// @notice Checks if transient access exists for a handle-account pair.
+    /// @param handle The encrypted handle to check.
+    /// @param account The account to check access for.
+    /// @return True if transient access is granted.
     function allowedTransient(bytes32 handle, address account) public view returns (bool) {
         bool isAllowedTransient;
         bytes32 key = keccak256(abi.encodePacked(handle, account));
@@ -90,6 +137,9 @@ abstract contract BaseAccessControlList is
         return isAllowedTransient;
     }
 
+    /// @notice Clears all transient storage entries.
+    /// @dev Should be called at the end of a transaction to reset transient permissions.
+    /// Iterates through all stored keys and clears them.
     function cleanTransientStorage() external {
         assembly {
             let length := tload(0)
@@ -103,6 +153,10 @@ abstract contract BaseAccessControlList is
         }
     }
 
+    /// @notice Claims access to a handle using a signed allowance proof.
+    /// @dev Verifies the proof via IncoVerifier and grants persistent access if valid.
+    /// @param handle The encrypted handle to claim access to.
+    /// @param proof The signed allowance proof from an authorized sharer.
     function claimHandle(bytes32 handle, AllowanceProof memory proof) public {
         require(
             incoVerifier.isAllowedWithProof(handle, msg.sender, proof),
@@ -113,15 +167,27 @@ abstract contract BaseAccessControlList is
         allowInternal(handle, msg.sender);
     }
 
+    /// @notice Checks if persistent access exists for a handle-account pair.
+    /// @param handle The encrypted handle to check.
+    /// @param account The account to check access for.
+    /// @return True if persistent access is granted.
     function persistAllowed(bytes32 handle, address account) public view returns (bool) {
         AclStorage storage $ = getAclStorage();
         return $.persistedAllowedPairs[handle][account];
     }
 
+    /// @notice Checks if an account has access to an encrypted handle.
+    /// @dev Returns true if any of: transient access, persistent access, or handle is revealed.
+    /// @param handle The encrypted handle to check.
+    /// @param account The account to check access for.
+    /// @return True if the account has access to the handle.
     function isAllowed(bytes32 handle, address account) public view returns (bool) {
         return allowedTransient(handle, account) || persistAllowed(handle, account) || isRevealed(handle);
     }
 
+    /// @notice Checks if a handle has been revealed for public access.
+    /// @param handle The encrypted handle to check.
+    /// @return True if the handle has been revealed.
     function isRevealed(bytes32 handle) public view returns (bool) {
         AclStorage storage $ = getAclStorage();
         return $.persistedAllowedForDecryption[handle];

package/src/lightning-parts/DecryptionAttester.sol

@@ -6,20 +6,33 @@ import {EIP712Upgradeable} from "@openzeppelin/contracts-upgradeable/utils/crypt
 import {SignatureVerifier} from "./primitives/SignatureVerifier.sol";
 import {IDecryptionAttester} from "./interfaces/IDecryptionAttester.sol";
 
-// todo pre charging transient decrypted values leads to a superior DevX
-
-// todo #1032 add DecryptionAttester to IncoVerifier, will include signature verifier as well and fix #874
+/// @title DecryptionAttester
+/// @notice Verifies decryption attestations signed by covalidators.
+/// @dev When a user requests decryption of an encrypted handle, the covalidator decrypts
+/// the value and signs an attestation. This contract verifies that attestation using EIP-712
+/// typed data signatures. The attestation binds a handle to its decrypted value, allowing
+/// on-chain verification that a decryption was performed correctly by authorized covalidators.
 abstract contract DecryptionAttester is IDecryptionAttester, SignatureVerifier, EIP712Upgradeable {
 
+    /// @dev EIP-712 type hash for DecryptionAttestation struct.
     bytes32 constant DECRYPTION_ATTESTATION_STRUCT_HASH =
         keccak256("DecryptionAttestation(bytes32 handle,bytes32 value)");
 
+    /// @notice Computes the EIP-712 digest for a decryption attestation.
+    /// @dev Used to verify signatures from covalidators attesting to a decryption result.
+    /// @param decryption The decryption attestation containing the handle and decrypted value.
+    /// @return The EIP-712 typed data hash that should be signed by covalidators.
     function decryptionAttestationDigest(DecryptionAttestation memory decryption) public view returns (bytes32) {
         return _hashTypedDataV4(
             keccak256(abi.encode(DECRYPTION_ATTESTATION_STRUCT_HASH, decryption.handle, decryption.value))
         );
     }
 
+    /// @notice Validates a decryption attestation against covalidator signatures.
+    /// @dev Verifies that the attestation was signed by the required threshold of covalidators.
+    /// @param decryption The decryption attestation to validate.
+    /// @param signatures Array of signatures from covalidators.
+    /// @return True if the attestation has valid signatures from the required covalidators.
     function isValidDecryptionAttestation(DecryptionAttestation memory decryption, bytes[] memory signatures)
         public
         view

package/src/lightning-parts/EncryptedInput.sol

@@ -8,8 +8,14 @@ import {IEncryptedInput} from "./interfaces/IEncryptedInput.sol";
 import {HandleAlreadyExists} from "../Errors.sol";
 import {Fee} from "./Fee.sol";
 
-// This error ordinarily indicates an unintentional mismatch between the client-side context and the ambient on-chain
-// context
+/// @notice Thrown when the handle computed on-chain doesn't match the handle prepended to the input.
+/// @dev This typically indicates a mismatch between client-side encryption context and on-chain context.
+/// @param externalHandle The handle prepended to the input by the client.
+/// @param computedHandle The handle computed on-chain from the ciphertext and context.
+/// @param chainId The chain ID used in handle computation.
+/// @param aclAddress The ACL contract address used in handle computation.
+/// @param userAddress The user address used in handle computation.
+/// @param contractAddress The contract address used in handle computation.
 error ExternalHandleDoesNotMatchComputedHandle(
     bytes32 externalHandle,
     bytes32 computedHandle,
@@ -21,8 +27,19 @@ error ExternalHandleDoesNotMatchComputedHandle(
     int32 version
 );
 
+/// @title EncryptedInput
+/// @notice Handles the submission of client-encrypted values to create on-chain encrypted handles.
+/// @dev Users encrypt values client-side and submit them with a prepended handle as a checksum.
+/// The contract verifies the handle matches the on-chain computation to ensure context consistency.
+/// This is a paid operation - users must send ETH to cover processing costs.
 abstract contract EncryptedInput is IEncryptedInput, BaseAccessControlList, HandleGeneration, Fee {
 
+    /// @notice Emitted when a new encrypted input is submitted.
+    /// @param result The generated handle for the encrypted value.
+    /// @param contractAddress The contract that submitted the input.
+    /// @param user The user who encrypted the value.
+    /// @param ciphertext The encrypted data (without the prepended handle).
+    /// @param eventId The unique event ID for ordering.
     event NewInput(
         bytes32 indexed result,
         address indexed contractAddress,
@@ -32,18 +49,37 @@ abstract contract EncryptedInput is IEncryptedInput, BaseAccessControlList, Hand
         uint256 eventId
     );
 
+    /// @notice Submits a client-encrypted uint256 value to create an encrypted handle.
+    /// @dev This is a paid operation. The input must contain a prepended handle for verification.
+    /// @param input The encrypted input with prepended handle checksum.
+    /// @param user The user address that encrypted the value.
+    /// @return newValue The encrypted uint256 handle.
     function newEuint256(bytes calldata input, address user) external payable returns (euint256 newValue) {
         return euint256.wrap(newInput(input, user, ETypes.Uint256));
     }
 
+    /// @notice Submits a client-encrypted boolean value to create an encrypted handle.
+    /// @dev This is a paid operation. The input must contain a prepended handle for verification.
+    /// @param input The encrypted input with prepended handle checksum.
+    /// @param user The user address that encrypted the value.
+    /// @return newValue The encrypted boolean handle.
     function newEbool(bytes calldata input, address user) external payable returns (ebool newValue) {
         return ebool.wrap(newInput(input, user, ETypes.Bool));
     }
 
+    /// @notice Submits a client-encrypted address value to create an encrypted handle.
+    /// @dev This is a paid operation. The input must contain a prepended handle for verification.
+    /// @param input The encrypted input with prepended handle checksum.
+    /// @param user The user address that encrypted the value.
+    /// @return newValue The encrypted address handle.
     function newEaddress(bytes calldata input, address user) external payable returns (eaddress newValue) {
         return eaddress.wrap(newInput(input, user, ETypes.AddressOrUint160OrBytes20));
     }
 
+    /// @dev Internal function to process encrypted input with fee payment.
+    /// @param user The user address that encrypted the value.
+    /// @param inputType The type of encrypted value.
+    /// @return newHandle The generated handle.
     function newInput(bytes calldata input, address user, ETypes inputType)
         internal
         paying
@@ -52,6 +88,11 @@ abstract contract EncryptedInput is IEncryptedInput, BaseAccessControlList, Hand
         newHandle = _newInput(input, user, inputType);
     }
 
+    /// @dev Internal function to process encrypted input without fee payment.
+    /// Used for internal operations that don't require user payment.
+    /// @param user The user address that encrypted the value.
+    /// @param inputType The type of encrypted value.
+    /// @return newHandle The generated handle.
     function newInputNotPaying(bytes calldata input, address user, ETypes inputType)
         internal
         returns (bytes32 newHandle)
@@ -60,8 +101,13 @@ abstract contract EncryptedInput is IEncryptedInput, BaseAccessControlList, Hand
     }
 
     /// @notice Creates a new input with a prepended handle as a checksum.
+    /// @dev Verifies the external handle matches the computed handle, ensures the handle
+    /// doesn't already exist, emits the NewInput event, and grants access to the user
+    /// and calling contract.
     /// @param input The input that contains the handle prepended to the ciphertext.
     /// @param user The user address associated with the input.
+    /// @param inputType The type of encrypted value being created.
+    /// @return handle The generated handle for the encrypted value.
     function _newInput(bytes calldata input, address user, ETypes inputType) private returns (bytes32 handle) {
         // Since there is no sensible way to handle abi.decode errors (https://github.com/argotorg/solidity/issues/10381)
         // at least fail early on a conservative minimum length