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

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

@@ -1,11 +1,21 @@
 // SPDX-License-Identifier: No License
 pragma solidity ^0.8;
 
+/// @title LightningAddressGetter
+/// @notice Provides immutable access to the IncoLightning contract address
+/// @dev Abstract contract that stores the main IncoLightning address at deployment time.
+///      Used by peripheral contracts (like AdvancedAccessControl, SessionVerifier) that need
+///      to call back to the main IncoLightning contract for ACL lookups or other operations.
+///      The address is immutable to prevent redirection attacks.
 abstract contract LightningAddressGetter {
 
+    /// @notice The main IncoLightning contract address
+    /// @dev Set immutably at deployment. Used for delegating calls and ACL lookups.
     // forge-lint: disable-next-line(screaming-snake-case-immutable)
     address internal immutable incoLightningAddress;
 
+    /// @notice Initializes the contract with the IncoLightning address
+    /// @param _incoLightningAddress The address of the deployed IncoLightning contract
     constructor(address _incoLightningAddress) {
         incoLightningAddress = _incoLightningAddress;
     }

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

@@ -4,11 +4,21 @@ pragma solidity ^0.8;
 import {IIncoVerifier} from "../../interfaces/IIncoVerifier.sol";
 import {IVerifierAddressGetter} from "./interfaces/IVerifierAddressGetter.sol";
 
+/// @title VerifierAddressGetter
+/// @notice Provides immutable access to the IncoVerifier contract address
+/// @dev Abstract contract that stores the IncoVerifier address at deployment time.
+///      The IncoVerifier is responsible for validating decryption attestations from covalidators.
+///      This pattern ensures the verifier address is set once and cannot be changed,
+///      which is critical for security as the verifier is trusted for attestation validation.
 abstract contract VerifierAddressGetter is IVerifierAddressGetter {
 
+    /// @notice The IncoVerifier contract used for attestation validation
+    /// @dev Set immutably at deployment. Used to verify decryption proofs from covalidators.
     // forge-lint: disable-next-line(screaming-snake-case-immutable)
     IIncoVerifier public immutable incoVerifier;
 
+    /// @notice Initializes the contract with the IncoVerifier address
+    /// @param _incoVerifier The address of the deployed IncoVerifier contract
     constructor(address _incoVerifier) {
         incoVerifier = IIncoVerifier(_incoVerifier);
     }

package/src/lightning-parts/primitives/test/SignatureVerifier.t.sol

@@ -357,7 +357,6 @@ contract TestSignatureVerifier is TestUtils, SignatureVerifier {
         // Create 3 signatures: Alice, Bob (both valid), and Dave (invalid)
         // After sorting, Dave's signature will be placed according to his address
         // As long as the first 2 signatures checked are from valid signers, it should pass
-        bytes[] memory signatures = new bytes[](3);
         bytes memory aliceSig = getSignatureForDigest(digest, alicePrivKey);
         bytes memory bobSig = getSignatureForDigest(digest, bobPrivKey);
         bytes memory daveSig = getSignatureForDigest(digest, davePrivKey);
@@ -413,7 +412,6 @@ contract TestSignatureVerifier is TestUtils, SignatureVerifier {
         bytes32 digest = keccak256("test message");
 
         // Create signatures where an invalid signer (Dave) will be in the first threshold
-        bytes[] memory signatures = new bytes[](3);
         bytes memory aliceSig = getSignatureForDigest(digest, alicePrivKey);
         bytes memory bobSig = getSignatureForDigest(digest, bobPrivKey);
         bytes memory daveSig = getSignatureForDigest(digest, davePrivKey);

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

@@ -105,8 +105,16 @@ contract TestHandleMetadata is
     {
         // We need a single word here to get correct encoding
         bytes memory ciphertext = abi.encode(word);
-        bytes32 handle = getInputHandle(ciphertext, address(this), user, contractAddress, inputType);
-        input = abi.encode(handle, ciphertext);
+        bytes32 handle = getInputHandle(
+            ciphertext,
+            address(this),
+            user,
+            contractAddress,
+            0,
+            /* unspecified */
+            inputType
+        );
+        input = abi.encodePacked(int32(0), abi.encode(handle, ciphertext));
     }
 
     // ============ Tests for HandleGeneration functions ============
@@ -143,11 +151,8 @@ contract TestHandleMetadata is
     // ============ Tests for EncryptedInput internal functions ============
 
     /// @notice Expose the internal newInputNotPaying for testing
-    function exposedNewInputNotPaying(bytes memory ciphertext, address user, ETypes inputType)
-        public
-        returns (bytes32)
-    {
-        return newInputNotPaying(ciphertext, user, inputType);
+    function exposedNewInputNotPaying(bytes calldata input, address user, ETypes inputType) public returns (bytes32) {
+        return newInputNotPaying(input, user, inputType);
     }
 
     function testNewInputNotPaying() public {
@@ -167,9 +172,10 @@ contract TestHandleMetadata is
         returns (bytes memory input)
     {
         bytes memory ciphertext = abi.encode(word);
+        int32 version = 0; // unspecified
         // For external calls via this., msg.sender is address(this)
-        bytes32 handle = getInputHandle(ciphertext, address(this), user, address(this), inputType);
-        input = abi.encode(handle, ciphertext);
+        bytes32 handle = getInputHandle(ciphertext, address(this), user, address(this), version, inputType);
+        input = abi.encodePacked(version, abi.encode(handle, ciphertext));
     }
 
     // ============ Tests for EncryptedInput error branches ============
@@ -178,7 +184,7 @@ contract TestHandleMetadata is
         address self = address(this);
         // Input less than 64 bytes should revert
         bytes memory shortInput = hex"deadbeef";
-        vm.expectRevert("Input too short, should be at least 64 bytes");
+        vm.expectRevert("Input too short, should be at least 68 bytes");
         this.exposedNewInputNotPaying(shortInput, self, ETypes.Uint256);
     }
 
@@ -188,10 +194,11 @@ contract TestHandleMetadata is
         bytes memory ciphertext = abi.encode(ciphertextData);
         // Create input with wrong handle (just a random bytes32)
         bytes32 wrongHandle = bytes32(uint256(12345));
-        bytes memory badInput = abi.encode(wrongHandle, ciphertext);
+        int32 version = 0; // unspecified
+        bytes memory badInput = abi.encodePacked(version, abi.encode(wrongHandle, ciphertext));
 
         // Compute the expected handle for the error message
-        bytes32 expectedHandle = getInputHandle(ciphertext, address(this), self, address(this), ETypes.Uint256);
+        bytes32 expectedHandle = getInputHandle(ciphertext, address(this), self, address(this), version, ETypes.Uint256);
 
         vm.expectRevert(
             abi.encodeWithSelector(
@@ -201,7 +208,8 @@ contract TestHandleMetadata is
                 block.chainid,
                 address(this),
                 self,
-                address(this)
+                address(this),
+                version
             )
         );
         this.exposedNewInputNotPaying(badInput, self, ETypes.Uint256);

package/src/periphery/IncoUtils.sol

@@ -4,6 +4,7 @@ pragma solidity ^0.8;
 import {StorageSlot} from "@openzeppelin/contracts/utils/StorageSlot.sol";
 
 // Re-export FEE constant for convenience - consumers can import both IncoUtils and FEE from this file
+// forge-lint: disable-next-line(unused-import)
 import {FEE} from "../lightning-parts/Fee.sol";
 
 contract IncoUtils {

package/src/periphery/SessionVerifier.sol

@@ -12,18 +12,33 @@ import {
 import {Version} from "../version/Version.sol";
 import {ALLOWANCE_GRANTED_MAGIC_VALUE} from "../Types.sol";
 
-/// @notice a Session grants a temporary access to a decrypter to all data held by the sharer
-/// @dev abi encode this struct in the sharerArgData field of the voucher
+/// @notice A Session grants temporary access to a decrypter for all data held by the sharer
+/// @dev ABI encode this struct in the sharerArgData field of the voucher.
+///      The session is valid only if:
+///      1. The current block timestamp is before expiresAt
+///      2. The requesting account matches the authorized decrypter
 struct Session {
+    /// @notice The address authorized to decrypt the sharer's data
     address decrypter;
+    /// @notice Unix timestamp after which the session is no longer valid
     uint256 expiresAt;
 }
 
-/// @notice Inco access sharing verifier mainly meant for browser dapp sessions, grants access to all data held by
-/// the sharer to one decrypter for a limited time.
-/// @dev define the selector of canUseSession in the voucher to use this verifier
+/// @title SessionVerifier
+/// @notice Inco access sharing verifier for browser dApp sessions
+/// @dev Grants access to all encrypted data held by the sharer to one decrypter for a limited time.
+///      This is the recommended pattern for dApps that need to decrypt user data during a browsing session.
+///
+///      Usage:
+///      1. User signs a voucher containing a Session struct with their chosen decrypter and expiration
+///      2. The voucher specifies canUseSession.selector as the callFunction
+///      3. When the decrypter requests access, this contract verifies the session is still valid
+///
+///      To use this verifier, set the voucher's callFunction to SessionVerifier.canUseSession.selector
 contract SessionVerifier is UUPSUpgradeable, OwnableUpgradeable, Version {
 
+    /// @notice Initializes the SessionVerifier with version information
+    /// @param salt Unique salt used for deterministic deployment via CreateX
     constructor(bytes32 salt)
         Version(
             SESSION_VERIFIER_MAJOR_VERSION,
@@ -34,7 +49,13 @@ contract SessionVerifier is UUPSUpgradeable, OwnableUpgradeable, Version {
         )
     {}
 
-    // todo add text mention of what is being signed
+    /// @notice Verifies if an account can use a session to access encrypted data
+    /// @dev This function is called by the ACL system when validating access permissions.
+    ///      The session grants blanket access to all handles owned by the sharer - the handle
+    ///      parameter is intentionally ignored.
+    /// @param account The address requesting access (must match session.decrypter)
+    /// @param sharerArgData ABI-encoded Session struct containing decrypter address and expiration
+    /// @return ALLOWANCE_GRANTED_MAGIC_VALUE if session is valid, bytes32(0) otherwise
     function canUseSession(
         bytes32, /* handle */
         address account,
@@ -54,14 +75,21 @@ contract SessionVerifier is UUPSUpgradeable, OwnableUpgradeable, Version {
         return bytes32(0);
     }
 
+    /// @notice Authorizes contract upgrades (restricted to owner only)
+    /// @dev Required by UUPSUpgradeable. Only the contract owner can upgrade.
     function _authorizeUpgrade(address) internal view override {
         require(msg.sender == owner());
     }
 
+    /// @notice Initializes the contract with an owner address
+    /// @dev Must be called immediately after deployment via proxy. Can only be called once.
+    /// @param owner The address that will own this contract and can authorize upgrades
     function initialize(address owner) public initializer {
         __Ownable_init(owner);
     }
 
-    fallback() external {} // must be included for createX deploy
+    /// @notice Required for CreateX deterministic deployment
+    /// @dev Empty fallback allows the contract to be deployed via CreateX's create2 mechanism
+    fallback() external {}
 
 }

package/src/test/FakeIncoInfra/FakeIncoInfraBase.sol

@@ -19,8 +19,16 @@ contract FakeIncoInfraBase is TestUtils, KVStore, HandleGeneration {
     {
         // We need a single word here to get correct encoding
         bytes memory ciphertext = abi.encode(word);
-        bytes32 handle = getInputHandle(ciphertext, address(inco), user, contractAddress, inputType);
-        input = abi.encode(handle, ciphertext);
+        bytes32 handle = getInputHandle(
+            ciphertext,
+            address(inco),
+            user,
+            contractAddress,
+            0,
+            /* unspecified */
+            inputType
+        );
+        input = abi.encodePacked(int32(0), abi.encode(handle, ciphertext));
     }
 
     function fakePrepareEuint256Ciphertext(uint256 value, address userAddress, address contractAddress)

package/src/test/FakeIncoInfra/MockOpHandler.sol

@@ -63,7 +63,7 @@ contract MockOpHandler is FakeIncoInfraBase, FakeComputeServer {
         } else if (op == EOps.NewInput) {
             bytes32 result = log.topics[1];
             // contractAddress and user topics are ignored
-            (bytes memory ciphertext,) = abi.decode(log.data, (bytes, uint256));
+            (, bytes memory ciphertext,) = abi.decode(log.data, (int32, bytes, uint256));
             handleEInput(result, ciphertext);
         }
     }