feat(gateway-contracts): introduce the generic bytes metadata

Author: isaacdecoded

gateway-contracts/contracts/Decryption.sol

@@ -38,6 +38,8 @@ contract InputVerification is
         address contractAddress;
         /// @notice The host chain's chain ID of the contract requiring the ZK Proof verification.
         uint256 contractChainId;
+        /// @notice Generic bytes metadata for versioned payloads. First byte is for the version.
+        bytes extraData;
     }
 
     /// @notice The stored structure for the received ZK Proof verification request inputs.
@@ -55,7 +57,7 @@ contract InputVerification is
 
     /// @notice The definition of the CiphertextVerification structure typed data.
     string private constant EIP712_ZKPOK_TYPE =
-        "CiphertextVerification(bytes32[] ctHandles,address userAddress,address contractAddress,uint256 contractChainId)";
+        "CiphertextVerification(bytes32[] ctHandles,address userAddress,address contractAddress,uint256 contractChainId,bytes extraData)";
 
     /// @notice The hash of the CiphertextVerification structure typed data definition used for signature validation.
     bytes32 private constant EIP712_ZKPOK_TYPE_HASH = keccak256(bytes(EIP712_ZKPOK_TYPE));
@@ -124,7 +126,8 @@ contract InputVerification is
         uint256 contractChainId,
         address contractAddress,
         address userAddress,
-        bytes calldata ciphertextWithZKProof
+        bytes calldata ciphertextWithZKProof,
+        bytes calldata extraData
     ) external virtual onlyRegisteredHostChain(contractChainId) whenNotPaused {
         InputVerificationStorage storage $ = _getInputVerificationStorage();
 
@@ -134,7 +137,14 @@ contract InputVerification is
         /// @dev The following stored inputs are used during response calls for the EIP712 signature validation.
         $._zkProofInputs[zkProofId] = ZKProofInput(contractChainId, contractAddress, userAddress);
 
-        emit VerifyProofRequest(zkProofId, contractChainId, contractAddress, userAddress, ciphertextWithZKProof);
+        emit VerifyProofRequest(
+            zkProofId,
+            contractChainId,
+            contractAddress,
+            userAddress,
+            ciphertextWithZKProof,
+            extraData
+        );
     }
 
     /**
@@ -145,7 +155,8 @@ contract InputVerification is
     function verifyProofResponse(
         uint256 zkProofId,
         bytes32[] calldata ctHandles,
-        bytes calldata signature
+        bytes calldata signature,
+        bytes calldata extraData
     ) external virtual onlyCoprocessorTxSender {
         InputVerificationStorage storage $ = _getInputVerificationStorage();
 
@@ -162,7 +173,8 @@ contract InputVerification is
             ctHandles,
             zkProofInput.userAddress,
             zkProofInput.contractAddress,
-            zkProofInput.contractChainId
+            zkProofInput.contractChainId,
+            extraData
         );
 
         /// @dev Compute the digest of the CiphertextVerification structure.
@@ -194,7 +206,10 @@ contract InputVerification is
     }
 
     /// @dev See {IInputVerification-rejectProofResponse}.
-    function rejectProofResponse(uint256 zkProofId) external virtual onlyCoprocessorTxSender {
+    function rejectProofResponse(
+        uint256 zkProofId,
+        bytes calldata /* extraData */
+    ) external virtual onlyCoprocessorTxSender {
         InputVerificationStorage storage $ = _getInputVerificationStorage();
 
         /**
@@ -302,7 +317,8 @@ contract InputVerification is
                         keccak256(abi.encodePacked(ctVerification.ctHandles)),
                         ctVerification.userAddress,
                         ctVerification.contractAddress,
-                        ctVerification.contractChainId
+                        ctVerification.contractChainId,
+                        keccak256(abi.encodePacked(ctVerification.extraData))
                     )
                 )
             );

gateway-contracts/contracts/InputVerification.sol

@@ -100,7 +100,8 @@ contract MultichainAcl is
 
     /// @dev See {IMultichainAcl-allowPublicDecrypt}.
     function allowPublicDecrypt(
-        bytes32 ctHandle
+        bytes32 ctHandle,
+        bytes calldata /* extraData */
     ) external virtual onlyCoprocessorTxSender onlyHandleFromRegisteredHostChain(ctHandle) {
         MultichainAclStorage storage $ = _getMultichainAclStorage();
 
@@ -127,7 +128,8 @@ contract MultichainAcl is
     /// @dev See {IMultichainAcl-allowAccount}.
     function allowAccount(
         bytes32 ctHandle,
-        address accountAddress
+        address accountAddress,
+        bytes calldata /* extraData */
     ) external virtual onlyCoprocessorTxSender onlyHandleFromRegisteredHostChain(ctHandle) {
         MultichainAclStorage storage $ = _getMultichainAclStorage();
 

gateway-contracts/contracts/MultichainAcl.sol

@@ -9,6 +9,16 @@ import "../shared/Structs.sol";
  * Both user decryption and public decryption are handled.
  */
 interface IDecryption {
+    /**
+     * @notice A struct that specifies information about the contracts to be used in the decryption.
+     */
+    struct ContractsInfo {
+        /// @notice The chain ID of the contracts to be used in the decryption
+        uint256 chainId;
+        /// @notice The list of contract addresses to be used in the decryption
+        address[] addresses;
+    }
+
     /**
      * @notice A struct that specifies the validity period of a request, starting at "startTimestamp"
      * and remaining valid for "durationDays".
@@ -27,38 +37,57 @@ interface IDecryption {
      * @notice Emitted when an public decryption request is made.
      * @param decryptionId The decryption request ID.
      * @param snsCtMaterials The handles, key IDs and SNS ciphertexts to decrypt.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
-    event PublicDecryptionRequest(uint256 indexed decryptionId, SnsCiphertextMaterial[] snsCtMaterials);
+    event PublicDecryptionRequest(
+        uint256 indexed decryptionId,
+        SnsCiphertextMaterial[] snsCtMaterials,
+        bytes extraData
+    );
 
     /**
      * @notice Emitted when an public decryption response is made.
      * @param decryptionId The decryption request ID associated with the response.
      * @param decryptedResult The decrypted result.
      * @param signatures The signatures of all the KMS connectors that responded.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
-    event PublicDecryptionResponse(uint256 indexed decryptionId, bytes decryptedResult, bytes[] signatures);
+    event PublicDecryptionResponse(
+        uint256 indexed decryptionId,
+        bytes decryptedResult,
+        bytes[] signatures,
+        bytes extraData
+    );
 
     /**
      * @notice Emitted when a user decryption request is made.
      * @param decryptionId The decryption request ID.
      * @param snsCtMaterials The handles, key IDs and SNS ciphertexts to decrypt.
      * @param userAddress The user's address.
      * @param publicKey The user's public key for used reencryption.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
     event UserDecryptionRequest(
         uint256 indexed decryptionId,
         SnsCiphertextMaterial[] snsCtMaterials,
         address userAddress,
-        bytes publicKey
+        bytes publicKey,
+        bytes extraData
     );
 
     /**
      * @notice Emitted when an public decryption response is made.
      * @param decryptionId The decryption request ID associated with the response.
      * @param userDecryptedShares The list of decryption shares reencrypted with the user's public key.
      * @param signatures The signatures of all the KMS connectors that responded.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
-    event UserDecryptionResponse(uint256 indexed decryptionId, bytes[] userDecryptedShares, bytes[] signatures);
+    event UserDecryptionResponse(
+        uint256 indexed decryptionId,
+        bytes[] userDecryptedShares,
+        bytes[] signatures,
+        bytes extraData
+    );
 
     /// @notice Error indicating that the input list of handles is empty.
     error EmptyCtHandles();
@@ -172,87 +201,95 @@ interface IDecryption {
     /**
      * @notice Requests a public decryption.
      * @param ctHandles The handles of the ciphertexts to decrypt.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
-    function publicDecryptionRequest(bytes32[] calldata ctHandles) external;
+    function publicDecryptionRequest(bytes32[] calldata ctHandles, bytes calldata extraData) external;
 
     /**
      * @notice Responds to a public decryption request.
      * @param decryptionId The decryption request ID associated with the response.
      * @param decryptedResult The decrypted result.
      * @param signature The signature of the KMS connector that responded.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
     function publicDecryptionResponse(
         uint256 decryptionId,
         bytes calldata decryptedResult,
-        bytes calldata signature
+        bytes calldata signature,
+        bytes calldata extraData
     ) external;
 
     /**
      * @notice Requests a user decryption.
      * @param ctHandleContractPairs The ciphertexts to decrypt for associated contracts.
      * @param requestValidity The validity period of the user decryption request.
-     * @param contractsChainId The chain ID of the given contract addresses figuring in the signed EIP-712 message.
-     * @param contractAddresses The contract addresses figuring in the signed EIP-712 message.
+     * @param contractsInfo The chain ID and contract addresses to be used in the decryption.
      * @param userAddress The user's address.
      * @param publicKey The user's public key to reencrypt the decryption shares.
      * @param signature The EIP712 signature to verify.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
     function userDecryptionRequest(
         CtHandleContractPair[] calldata ctHandleContractPairs,
         RequestValidity calldata requestValidity,
-        uint256 contractsChainId,
-        address[] calldata contractAddresses,
+        ContractsInfo calldata contractsInfo,
         address userAddress,
         bytes calldata publicKey,
-        bytes calldata signature
+        bytes calldata signature,
+        bytes calldata extraData
     ) external;
 
     /**
      * @notice Requests a delegated user decryption.
      * @param ctHandleContractPairs The ciphertexts to decrypt for associated contracts.
      * @param requestValidity The validity period of the user decryption request.
      * @param delegationAccounts The user's address and the delegated account address for the user decryption.
-     * @param contractsChainId The chain ID of the given contract addresses figuring in the signed EIP-712 message.
-     * @param contractAddresses The contract addresses figuring in the signed EIP-712 message.
+     * @param contractsInfo The chain ID and contract addresses to be used in the decryption.
      * @param publicKey The user's public key to reencrypt the decryption shares.
      * @param signature The EIP712 signature to verify.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
     function delegatedUserDecryptionRequest(
         CtHandleContractPair[] calldata ctHandleContractPairs,
         RequestValidity calldata requestValidity,
         DelegationAccounts calldata delegationAccounts,
-        uint256 contractsChainId,
-        address[] calldata contractAddresses,
+        ContractsInfo calldata contractsInfo,
         bytes calldata publicKey,
-        bytes calldata signature
+        bytes calldata signature,
+        bytes calldata extraData
     ) external;
 
     /**
      * @notice Responds to a user decryption request.
      * @param decryptionId The decryption request ID associated with the response.
      * @param userDecryptedShare The partial decryption share reencrypted with the user's public key.
      * @param signature The signature of the KMS connector that responded.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
     function userDecryptionResponse(
         uint256 decryptionId,
         bytes calldata userDecryptedShare,
-        bytes calldata signature
+        bytes calldata signature,
+        bytes calldata extraData
     ) external;
 
     /**
      * @notice Checks if handles are ready to be decrypted publicly.
      * @param ctHandles The ciphertext handles.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
-    function checkPublicDecryptionReady(bytes32[] calldata ctHandles) external view;
+    function checkPublicDecryptionReady(bytes32[] calldata ctHandles, bytes calldata extraData) external view;
 
     /**
      * @notice Checks if handles are ready to be decrypted by a user.
      * @param userAddress The user's address.
      * @param ctHandleContractPairs The ciphertext handles with associated contract addresses.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
     function checkUserDecryptionReady(
         address userAddress,
-        CtHandleContractPair[] calldata ctHandleContractPairs
+        CtHandleContractPair[] calldata ctHandleContractPairs,
+        bytes calldata extraData
     ) external view;
 
     /**
@@ -261,12 +298,14 @@ interface IDecryption {
      * @param delegationAccounts The delegator and delegated address.
      * @param ctHandleContractPairs The ciphertext handles with associated contract addresses.
      * @param contractAddresses The contract addresses.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
     function checkDelegatedUserDecryptionReady(
         uint256 contractsChainId,
         DelegationAccounts calldata delegationAccounts,
         CtHandleContractPair[] calldata ctHandleContractPairs,
-        address[] calldata contractAddresses
+        address[] calldata contractAddresses,
+        bytes calldata extraData
     ) external view;
 
     /**

gateway-contracts/contracts/interfaces/IDecryption.sol

@@ -13,13 +13,15 @@ interface IInputVerification {
      * @param contractAddress The address of the dapp requiring the ZK Proof verification.
      * @param userAddress The address of the user providing the input.
      * @param ciphertextWithZKProof The combination of the ciphertext (plain text signed with user PK) and the ZK Proof.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
     event VerifyProofRequest(
         uint256 indexed zkProofId,
         uint256 indexed contractChainId,
         address contractAddress,
         address userAddress,
-        bytes ciphertextWithZKProof
+        bytes ciphertextWithZKProof,
+        bytes extraData
     );
 
     /**
@@ -76,21 +78,29 @@ interface IInputVerification {
      * @param contractAddress The address of the dapp the input is used for.
      * @param userAddress The address of the user providing the input.
      * @param ciphertextWithZKProof The combination of the ciphertext (plain text signed with user PK) and the ZK Proof.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
     function verifyProofRequest(
         uint256 contractChainId,
         address contractAddress,
         address userAddress,
-        bytes calldata ciphertextWithZKProof
+        bytes calldata ciphertextWithZKProof,
+        bytes calldata extraData
     ) external;
 
     /**
      * @notice Responds to a correct ZK Proof verification request.
      * @param zkProofId The ID of the requested ZK Proof.
      * @param ctHandles The coprocessor's computed ciphertext handles.
      * @param signature The coprocessor's signature.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
-    function verifyProofResponse(uint256 zkProofId, bytes32[] calldata ctHandles, bytes calldata signature) external;
+    function verifyProofResponse(
+        uint256 zkProofId,
+        bytes32[] calldata ctHandles,
+        bytes calldata signature,
+        bytes calldata extraData
+    ) external;
 
     /**
      * @notice Rejects an incorrect ZK Proof verification request.
@@ -99,8 +109,9 @@ interface IInputVerification {
      * easily verify the sender's identity through `msg.sender`.
      *
      * @param zkProofId The ID of the requested ZK Proof.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
-    function rejectProofResponse(uint256 zkProofId) external;
+    function rejectProofResponse(uint256 zkProofId, bytes calldata extraData) external;
 
     /**
      * @notice Checks that a ZK Proof has been verified.

gateway-contracts/contracts/interfaces/IInputVerification.sol

@@ -92,15 +92,17 @@ interface IMultichainAcl {
     /**
      * @notice Allows access to the ciphertext handle for public decryption.
      * @param ctHandle The ciphertext handle.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
-    function allowPublicDecrypt(bytes32 ctHandle) external;
+    function allowPublicDecrypt(bytes32 ctHandle, bytes calldata extraData) external;
 
     /**
      * @notice Allows an account to access a ciphertext handle.
      * @param ctHandle The handle of the ciphertext.
      * @param accountAddress The address of the account to allow.
+     * @param extraData Generic bytes metadata for versioned payloads. First byte is for the version.
      */
-    function allowAccount(bytes32 ctHandle, address accountAddress) external;
+    function allowAccount(bytes32 ctHandle, address accountAddress, bytes calldata extraData) external;
 
     /**
      * @notice Delegates the access to the delegated and contract addresses.