@inco/lightning 0.9.0-devnet-test-10 → 0.10.0-devnet-1

package/src/Lib.template.sol

@@ -3,11 +3,25 @@
 pragma solidity ^0.8;
 
 import {IncoLightning} from "./IncoLightning.sol";
-import {ebool, euint256, eaddress, ETypes} from "./Types.sol";
-import {DecryptionAttestation} from "./lightning-parts/DecryptionAttester.types.sol";
+import {
+    ebool,
+    euint256,
+    eaddress,
+    ETypes,
+    elist,
+    IndexOutOfRange,
+    InvalidRange,
+    SliceOutOfRange,
+    UnsupportedListType,
+    HandleMismatch,
+    InvalidTEEAttestation,
+    UnexpectedDecryptedValue
+} from "./Types.sol";
+import {asBool} from "./shared/TypeUtils.sol";
+import {DecryptionAttestation, ElementAttestationWithProof} from "./lightning-parts/DecryptionAttester.types.sol";
 
 // forge-lint: disable-next-line(screaming-snake-case-const)
-IncoLightning constant inco = IncoLightning(0x000000000000000000000000000000000000baBe);
+IncoLightning constant inco = IncoLightning(payable(0x000000000000000000000000000000000000baBe));
 // forge-lint: disable-next-line(screaming-snake-case-const)
 address constant deployedBy = 0x000000000000000000000000000000000000baBe;
 
@@ -684,13 +698,15 @@ library e {
     /// @dev costs the inco fee
     /// @return The encrypted random value
     function rand() internal returns (euint256) {
-        bytes32 result = _callWithFeeRetry(abi.encodeWithSelector(inco.eRand.selector, ETypes.Uint256));
+        bytes32 boundHandle = euint256.unwrap(asEuint256(0));
+        bytes32 result =
+            _callWithFeeRetry(abi.encodeWithSelector(inco.eRandBounded.selector, boundHandle, ETypes.Uint256));
         return euint256.wrap(result);
     }
 
     /// @notice Generates a random encrypted uint256 less than a plaintext upper bound (costs the inco fee)
     /// @dev costs the inco fee
-    /// @param upperBound The plaintext upper bound
+    /// @param upperBound The plaintext upper bound (exclusive). If the upper bound is 0, the whole 256bit range is sampled, equivalent to providing type(uint256).max as upper bound.
     /// @return The encrypted random value
     function randBounded(uint256 upperBound) internal returns (euint256) {
         bytes32 boundHandle = euint256.unwrap(asEuint256(upperBound));
@@ -701,7 +717,7 @@ library e {
 
     /// @notice Generates a random encrypted uint256 less than an encrypted upper bound (costs the inco fee)
     /// @dev costs the inco fee
-    /// @param upperBound The encrypted upper bound
+    /// @param upperBound The encrypted upper bound (exclusive). If the upper bound is e(0), the whole 256bit range is sampled, equivalent to providing e(type(uint256).max) as upper bound.
     /// @return The encrypted random value
     function randBounded(euint256 upperBound) internal returns (euint256) {
         bytes32 boundHandle = euint256.unwrap(s(upperBound));
@@ -731,13 +747,6 @@ library e {
         return inco.asEaddress(a);
     }
 
-    /// @notice Casts an encrypted uint256 to an encrypted bool
-    /// @param a The encrypted uint256 value
-    /// @return The encrypted bool value
-    function asEbool(euint256 a) internal returns (ebool) {
-        return ebool.wrap(inco.eCast(euint256.unwrap(a), ETypes.Bool));
-    }
-
     /// @notice Casts an encrypted bool to an encrypted uint256
     /// @param a The encrypted bool value
     /// @return The encrypted uint256 value
@@ -945,4 +954,339 @@ library e {
         return abi.decode(result, (bytes32));
     }
 
+    // ═══════════════════════════════════════════════════════════
+    //  EList helpers
+    // ═══════════════════════════════════════════════════════════
+
+    /// @notice Returns the type of the elements contained within the list.
+    /// @param handle EList handle to read container type from.
+    /// @return ret Type of each element in the list.
+    function listTypeOf(elist handle) internal pure returns (ETypes ret) {
+        return ETypes(uint8(uint256(elist.unwrap(handle)) >> 16));
+    }
+
+    /// @notice Creates a new empty list. Type must be specified ahead of time and can not be changed.
+    /// @param listType Type of each element in the list.
+    /// @return ret A new elist handle
+    function newEList(ETypes listType) internal returns (elist ret) {
+        return inco.newEList(new bytes32[](0), listType);
+    }
+
+    /// @notice Creates a new list from existing array of handles.
+    /// @param handles An array of handles to create a new list from
+    /// @param listType Type of each element in the list.
+    /// @return ret A new elist handle
+    function newEList(bytes32[] memory handles, ETypes listType) internal returns (elist ret) {
+        return inco.newEList{value: inco.getEListFee(uint16(handles.length), listType)}(handles, listType);
+    }
+
+    /// @notice Takes an array of user encrypted ciphertexts and returns a new elist handle.
+    /// @param ciphertexts An array of encrypted user inputs
+    /// @param listType Expected type of each element in the list.
+    /// @param user Address of the user encrypting the ciphertexts.
+    /// @return ret A new elist handle
+    /// @dev each ciphertext costs the inco fee
+    function newEList(bytes[] memory ciphertexts, ETypes listType, address user) internal returns (elist ret) {
+        return inco.newEList{value: inco.getEListFee(uint16(ciphertexts.length), listType)}(ciphertexts, listType, user);
+    }
+
+    /// @notice Appends an ebool element at the end of a list.
+    /// @param a An elist handle to append to.
+    /// @param b Element value to be appended.
+    /// @return ret A new elist handle with length len(a)+1.
+    function append(elist a, ebool b) internal returns (elist ret) {
+        return inco.listAppend{value: inco.getEListFee(length(a) + 1, listTypeOf(a))}(a, ebool.unwrap(s(b)));
+    }
+
+    /// @notice Appends an euint256 element at the end of a list.
+    /// @param a An elist handle to append to.
+    /// @param b Element value to be appended.
+    /// @return ret A new elist handle with length len(a)+1.
+    function append(elist a, euint256 b) internal returns (elist ret) {
+        return inco.listAppend{value: inco.getEListFee(length(a) + 1, listTypeOf(a))}(a, euint256.unwrap(s(b)));
+    }
+
+    /// @notice Replaces an element at some hidden index "i" (ebool variant).
+    /// @dev If the encrypted index is out of bounds, the operation is silently ignored
+    /// and the returned list is identical to the input. This avoids leaking index validity.
+    /// @param a EList handle to modify element in.
+    /// @param i Hidden index position of an element to modify.
+    /// @param b Element value to be changed.
+    /// @return ret A new elist handle
+    function set(elist a, euint256 i, ebool b) internal returns (elist ret) {
+        return
+            inco.listSet{value: inco.getEListFee(length(a), listTypeOf(a))}(
+                a, euint256.unwrap(s(i)), ebool.unwrap(s(b))
+            );
+    }
+
+    /// @notice Replaces an element at some hidden index "i" (euint256 variant).
+    /// @dev If the encrypted index is out of bounds, the operation is silently ignored
+    /// and the returned list is identical to the input. This avoids leaking index validity.
+    /// @param a EList handle to modify element in.
+    /// @param i Hidden index position of an element to modify.
+    /// @param b Element value to be changed.
+    /// @return ret A new elist handle
+    function set(elist a, euint256 i, euint256 b) internal returns (elist ret) {
+        return inco.listSet{value: inco.getEListFee(length(a), listTypeOf(a))}(
+            a, euint256.unwrap(s(i)), euint256.unwrap(s(b))
+        );
+    }
+
+    /// @notice Replaces an element at plaintext index "i" (ebool variant). Reverts if out of range.
+    /// @param a EList handle to modify element in.
+    /// @param i Index position of element to modify.
+    /// @param b Element value to be changed.
+    /// @return ret A new elist handle
+    function set(elist a, uint16 i, ebool b) internal returns (elist ret) {
+        require(i < length(a), IndexOutOfRange(i, length(a)));
+        return inco.listSet{value: inco.getEListFee(length(a), listTypeOf(a))}(
+            a, euint256.unwrap(asEuint256(uint256(i))), ebool.unwrap(s(b))
+        );
+    }
+
+    /// @notice Replaces an element at plaintext index "i" (euint256 variant). Reverts if out of range.
+    /// @param a EList handle to modify element in.
+    /// @param i Index position of element to modify.
+    /// @param b Element value to be changed.
+    /// @return ret A new elist handle
+    function set(elist a, uint16 i, euint256 b) internal returns (elist ret) {
+        require(i < length(a), IndexOutOfRange(i, length(a)));
+        return inco.listSet{value: inco.getEListFee(length(a), listTypeOf(a))}(
+            a, euint256.unwrap(asEuint256(uint256(i))), euint256.unwrap(s(b))
+        );
+    }
+
+    /// @notice Return hidden element at some hidden position (ebool variant).
+    /// @param a EList handle to get element from.
+    /// @param i Hidden index position to get element at.
+    /// @param defaultValue A default element value returned if index is out of range.
+    /// @return ret A new handle for the element or the defaultValue
+    function getOr(elist a, euint256 i, ebool defaultValue) internal returns (ebool ret) {
+        return ebool.wrap(inco.listGetOr(a, euint256.unwrap(s(i)), ebool.unwrap(s(defaultValue))));
+    }
+
+    /// @notice Return hidden element at some hidden position (euint256 variant).
+    /// @param a EList handle to get element from.
+    /// @param i Hidden index position to get element at.
+    /// @param defaultValue A default element value returned if index is out of range.
+    /// @return ret A new handle for the element or the defaultValue
+    function getOr(elist a, euint256 i, euint256 defaultValue) internal returns (euint256 ret) {
+        return euint256.wrap(inco.listGetOr(a, euint256.unwrap(s(i)), euint256.unwrap(s(defaultValue))));
+    }
+
+    /// @notice Return hidden element at a known position as ebool.
+    /// @param a EList handle to get element from.
+    /// @param i Index position to get element at.
+    /// @return ret Returns a handle for the element.
+    function getEbool(elist a, uint16 i) internal returns (ebool ret) {
+        return ebool.wrap(inco.listGet(a, i));
+    }
+
+    /// @notice Return hidden element at a known position as euint256.
+    /// @param a EList handle to get element from.
+    /// @param i Index position to get element at.
+    /// @return ret Returns a handle for the element.
+    function getEuint256(elist a, uint16 i) internal returns (euint256 ret) {
+        return euint256.wrap(inco.listGet(a, i));
+    }
+
+    /// @notice Inserts a hidden element at a desired hidden position (ebool, hidden index).
+    /// @param a An elist handle to insert into.
+    /// @param i Hidden index position to insert at.
+    /// @param b Element value to be inserted.
+    /// @return ret A new elist handle with length len(a)+1.
+    function insert(elist a, euint256 i, ebool b) internal returns (elist ret) {
+        return inco.listInsert{value: inco.getEListFee(length(a) + 1, listTypeOf(a))}(
+            a, euint256.unwrap(s(i)), ebool.unwrap(s(b))
+        );
+    }
+
+    /// @notice Inserts an ebool element at a known position. Reverts if out of range.
+    /// @param a An elist handle to insert into.
+    /// @param i Index position to insert at.
+    /// @param b Element value to be inserted.
+    /// @return ret A new elist handle with length len(a)+1.
+    function insert(elist a, uint16 i, ebool b) internal returns (elist ret) {
+        require(i < length(a), IndexOutOfRange(i, length(a)));
+        return inco.listInsert{value: inco.getEListFee(length(a) + 1, listTypeOf(a))}(
+            a, euint256.unwrap(asEuint256(uint256(i))), ebool.unwrap(s(b))
+        );
+    }
+
+    /// @notice Inserts a hidden element at a desired hidden position (euint256, hidden index).
+    /// @param a An elist handle to insert into.
+    /// @param i Hidden index position to insert at.
+    /// @param b Element value to be inserted.
+    /// @return ret A new elist handle with length len(a)+1.
+    function insert(elist a, euint256 i, euint256 b) internal returns (elist ret) {
+        return inco.listInsert{value: inco.getEListFee(length(a) + 1, listTypeOf(a))}(
+            a, euint256.unwrap(s(i)), euint256.unwrap(s(b))
+        );
+    }
+
+    /// @notice Inserts a euint256 element at a known position. Reverts if out of range.
+    /// @param a An elist handle to insert into.
+    /// @param i Index position to insert at.
+    /// @param b Element value to be inserted.
+    /// @return ret A new elist handle with length len(a)+1.
+    function insert(elist a, uint16 i, euint256 b) internal returns (elist ret) {
+        require(i < length(a), IndexOutOfRange(i, length(a)));
+        return inco.listInsert{value: inco.getEListFee(length(a) + 1, listTypeOf(a))}(
+            a, euint256.unwrap(asEuint256(uint256(i))), euint256.unwrap(s(b))
+        );
+    }
+
+    /// @notice Concatenates two elists into one.
+    /// @param a EList handle to be prepended
+    /// @param b EList handle to be appended
+    /// @return ret A new elist handle with length len(a)+len(b).
+    function concat(elist a, elist b) internal returns (elist ret) {
+        return inco.listConcat{value: inco.getEListFee(length(a) + length(b), listTypeOf(a))}(a, b);
+    }
+
+    /// @notice Slices a list from plaintext start to plaintext end.
+    /// @param a EList handle to be sliced
+    /// @param start Starting index (inclusive).
+    /// @param end End index (exclusive). Must be >= start and within bounds.
+    /// @return ret A new sliced list with length "end-start".
+    function slice(elist a, uint16 start, uint16 end) internal returns (elist ret) {
+        require(end >= start, InvalidRange(start, end));
+        require(end <= length(a), SliceOutOfRange(start, end, length(a)));
+        require(start < length(a), SliceOutOfRange(start, end, length(a)));
+        bytes32 defaultValue;
+        if (ETypes.Uint256 == listTypeOf(a)) {
+            defaultValue = euint256.unwrap(asEuint256(0));
+        } else if (ETypes.Bool == listTypeOf(a)) {
+            defaultValue = ebool.unwrap(asEbool(false));
+        } else {
+            revert UnsupportedListType(listTypeOf(a));
+        }
+        return inco.listSlice{value: inco.getEListFee(end - start, listTypeOf(a))}(
+            a, euint256.unwrap(asEuint256(start)), end - start, defaultValue
+        );
+    }
+
+    /// @notice Slices at a hidden index with a specified length (euint256 default).
+    /// @param a EList handle to be sliced.
+    /// @param start Hidden starting index.
+    /// @param len Length of the desired slice.
+    /// @param defaultValue Default value if out of range.
+    /// @return ret A new sliced list with length "len".
+    function sliceLen(elist a, euint256 start, uint16 len, euint256 defaultValue) internal returns (elist ret) {
+        return inco.listSlice{value: inco.getEListFee(len, listTypeOf(a))}(
+            a, euint256.unwrap(s(start)), len, euint256.unwrap(s(defaultValue))
+        );
+    }
+
+    /// @notice Slices at a hidden index with a specified length (ebool default).
+    /// @param a EList handle to be sliced.
+    /// @param start Hidden starting index.
+    /// @param len Length of the desired slice.
+    /// @param defaultValue Default value if out of range.
+    /// @return ret A new sliced list with length "len".
+    function sliceLen(elist a, euint256 start, uint16 len, ebool defaultValue) internal returns (elist ret) {
+        return inco.listSlice{value: inco.getEListFee(len, listTypeOf(a))}(
+            a, euint256.unwrap(s(start)), len, ebool.unwrap(s(defaultValue))
+        );
+    }
+
+    /// @notice Creates a new list populated with ordered values from within range.
+    /// @param start Start value of the range, inclusive.
+    /// @param end End of the range, exclusive. Must be >= start.
+    /// @return ret A new elist handle with length "end-start"
+    function range(uint16 start, uint16 end, ETypes listType) internal returns (elist ret) {
+        return inco.listRange{value: inco.getEListFee(end - start, listType)}(start, end, listType);
+    }
+
+    /// @notice Deterministically shuffles elements within a list.
+    /// @dev costs the inco fee
+    /// @param a elist handle to be shuffled
+    /// @return ret A new elist handle with elements shuffled
+    function shuffle(elist a) internal returns (elist ret) {
+        return inco.listShuffle{value: inco.getEListFee(length(a), listTypeOf(a))}(a);
+    }
+
+    /// @notice A convenience function equivalent to range() followed by shuffle().
+    /// @dev costs the inco fee
+    /// @param start Start value of the range, inclusive.
+    /// @param end End of the range, exclusive. Must be >= start.
+    /// @return ret A new elist handle in random order with length "end-start".
+    function shuffledRange(uint16 start, uint16 end, ETypes listType) internal returns (elist ret) {
+        uint256 fee = inco.getEListFee(end - start, listType);
+        elist rangeList = inco.listRange{value: fee}(start, end, listType);
+        return inco.listShuffle{value: fee}(rangeList);
+    }
+
+    /// @notice Reverses the order of elements in a list.
+    /// @param a Elist handle to be reversed
+    /// @return ret A new elist handle with elements in reverse order
+    function reverse(elist a) internal returns (elist ret) {
+        return inco.listReverse{value: inco.getEListFee(length(a), listTypeOf(a))}(a);
+    }
+
+    /// @notice Returns the length of the list in plaintext. Pure function, no gas cost.
+    /// @param a EList handle to read the length from
+    /// @return len The length of the list
+    function length(elist a) internal pure returns (uint16 len) {
+        return inco.lengthOf(elist.unwrap(a));
+    }
+
+    /**
+     * @notice  verifyEListDecryption verifies elist decryption attestation and commitment proof. Each element can be either a pre-computed hash or a commitment-value pair.
+     * @param elistHandle The elist handle that was decrypted
+     * @param proofElements Array of proof elements. Each can provide either pairHash directly, or commitment+value to compute the pairHash
+     * @param proof The expected proof that should match keccak256 of all concatenated pair hashes
+     * @param signatures Array of signatures from attesters
+     * @return bool True if verification succeeds
+     * @dev For privacy, publish only pairHash. For transparency, publish commitment+value. Can mix both in the same array.
+     */
+    function verifyEListDecryption(
+        elist elistHandle,
+        ElementAttestationWithProof[] memory proofElements,
+        bytes32 proof,
+        bytes[] memory signatures
+    ) internal view returns (bool) {
+        return inco.incoVerifier()
+            .isValidEListDecryptionAttestation(elist.unwrap(elistHandle), proofElements, proof, signatures);
+    }
+
+    /**
+     * @notice Checks a decryption attestation for an encrypted bool against an expected plaintext value
+     * @param handle The encrypted handle
+     * @param expected The expected plaintext value
+     * @param decryption The decryption attestation to verify
+     * @param signatures The covalidator signatures for the attestation
+     * @dev Reverts if the handle doesn't match, the decrypted value doesn't match the expected value, or the attestation is invalid
+     */
+    function requireEqual(
+        ebool handle,
+        bool expected,
+        DecryptionAttestation memory decryption,
+        bytes[] memory signatures
+    ) internal view {
+        require(ebool.unwrap(handle) == decryption.handle, HandleMismatch());
+        require(asBool(decryption.value) == expected, UnexpectedDecryptedValue());
+        require(inco.incoVerifier().isValidDecryptionAttestation(decryption, signatures), InvalidTEEAttestation());
+    }
+
+    /**
+     * @notice Checks a decryption attestation for an encrypted uint256 against an expected plaintext value
+     * @param handle The encrypted handle
+     * @param expected The expected plaintext value
+     * @param decryption The decryption attestation to verify
+     * @param signatures The covalidator signatures for the attestation
+     * @dev Reverts if the handle doesn't match, the decrypted value doesn't match the expected value, or the attestation is invalid
+     */
+    function requireEqual(
+        euint256 handle,
+        uint256 expected,
+        DecryptionAttestation memory decryption,
+        bytes[] memory signatures
+    ) internal view {
+        require(euint256.unwrap(handle) == decryption.handle, HandleMismatch());
+        require(uint256(decryption.value) == expected, UnexpectedDecryptedValue());
+        require(inco.incoVerifier().isValidDecryptionAttestation(decryption, signatures), InvalidTEEAttestation());
+    }
+
 }