From 6ac7923a7c2bb1c217b4bc03dace166e92ccd876 Mon Sep 17 00:00:00 2001 From: Jason Fabritz Date: Tue, 12 Dec 2023 10:18:41 -0500 Subject: [PATCH] HIP-820 Cherry Pick Select Changes (#843) Signed-off-by: Jason Fabritz --- HIP/hip-820.md | 41 ++++++++++++++++++++++++++++++++--------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/HIP/hip-820.md b/HIP/hip-820.md index f1e380d4d..327d5b964 100644 --- a/HIP/hip-820.md +++ b/HIP/hip-820.md @@ -9,7 +9,7 @@ needs-council-approval: No status: Review created: 2023-10-05 discussions-to: https://github.com/hashgraph/hedera-improvement-proposal/discussions/819 -updated: 2023-11-30 +updated: 2023-12-11 requires: 30 replaces: 179 --- @@ -60,8 +60,8 @@ The identifiers described above shall be used during the Wallet Connect 2.0 pair What is not included in previous work is the definition of the Wallet Connect custom methods and events that complete the support for the use cases identified above. The following namespace methods shall be supported: -### hedera_signTransactionBody -When a dApp requires only the signature from the controller (wallet), it can use the `hedera_signTransactionBody` method. This method accepts a base64 encoded protobuf representation of the Hedera API [`TransactionBody`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_body.proto#L90) message as input. The controller decodes and interprets the contents, and if valid and approved, returns an encoded [`SignatureMap`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/basic_types.proto#L780) structure that includes one or more signatures generated by the controller. +### hedera_signTransaction +When a dApp requires only the signature from the controller (wallet), it can use the `hedera_signTransaction` method. This method accepts a base64 encoded protobuf representation of the Hedera API [`TransactionBody`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_body.proto#L90) message as input. The controller decodes and interprets the contents, and if valid and approved, returns an encoded [`SignatureMap`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/basic_types.proto#L780) structure that includes one or more signatures generated by the controller. #### Parameters `transactionBody` – a base64 encoding of the protobuf endoded Hedera API [`TransactionBody`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_body.proto#L90) message. While the controller should decode the contents for security reasons, it should sign the literal bytes provided, not a re-encoding of the [`TransactionBody`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_body.proto#L90) message. This is necessary because re-encoding the message could potentially result in slightly different array of bytes. @@ -71,8 +71,8 @@ When a dApp requires only the signature from the controller (wallet), it can use #### Returns `signatureMap` – a base64 encoding of the protobuf endoded Hedera API [`SignatureMap`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/basic_types.proto#L780) message. The encoded structure must include at least one signature within the property’s [`SignatureMap`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/basic_types.proto#L780) structure. It is allowed to provide more if the context warrants multiple signatures. -### hedera_signTransactionAndSend -When a dApp needs the services of the controller to sign a transaction message and then submit it to the network, it can use the `hedera_signTransactionAndSend` method. This method accepts a base64 encoded protobuf representation of the Hedera API [`SignedTransaction`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_contents.proto#L31) message as input. The controller decodes the message, interprets the contents, and if valid and approved, appends it’s signature to the [`SignatureMap`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/basic_types.proto#L780) structure identified as the [sigMap](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_contents.proto#L40C13-L40C13) property of the [`SignedTransaction`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_contents.proto#L31) repackages the message as appropriate for transmission to the Hedera network and sends it to the network. The controller shall wait for the initial response from the Hedera node and return the resulting Node Precheck Code generated by the submission. +### hedera_signAndExecuteTransaction +When a dApp needs the services of the controller to sign a transaction message and then submit it to the network, it can use the `hedera_signAndExecuteTransaction` method. This method accepts a base64 encoded protobuf representation of the Hedera API [`SignedTransaction`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_contents.proto#L31) message as input. The controller decodes the message, interprets the contents, and if valid and approved, appends it’s signature to the [`SignatureMap`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/basic_types.proto#L780) structure identified as the [sigMap](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_contents.proto#L40C13-L40C13) property of the [`SignedTransaction`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_contents.proto#L31) repackages the message as appropriate for transmission to the Hedera network and sends it to the network. The controller shall wait for the initial response from the Hedera node and return the resulting Node Precheck Code generated by the submission. The controller is allowed to retry submitting the signed transaction to the Hedera Network for certain types of error conditions; such as gRPC connection droppage or Hedera `BUSY` signals. This specification does not obligate the controller to retry, but recommends the practice to help improve perceived user experience for consumer applications. @@ -82,7 +82,8 @@ The controller is allowed to retry submitting the signed transaction to the Hede `signerAccountId` – an Hedera Account identifier in [HIP-30](https://hips.hedera.com/hip/hip-30) (`:..`) form. This value identifies the account (and therefore associated key set) that the dApp is requesting to sign the transaction. It is permissible to omit this value if necessary for keys not associated with an account (for example, a token supply key). The controller (wallet) may choose to reject the request based on the identifed account or omission of this property, or provide additional signatures beyond the request if the controller deems it necessary or proper. #### Returns -`precheckCode` – an integer representing the [`ResponseCodeEnum`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/response_code.proto#L32) value returned from the Hedera Node, which may indicate success or failure. A response code indicating success does not necessarily indicate the transaction will reach consensus nor succeed, it solely indicates whether the submitted transaction passed initial validation to warrant further processing. + +##### For Success (when `ResponseCodeEnum` is 0) `transactionId` – a string encoded transaction identifier of the signed message that was sent to the Hedera node, in `..@.` format. @@ -90,8 +91,18 @@ The controller is allowed to retry submitting the signed transaction to the Hede `transactionHash`– a base64 encoding of the SHA384 digest of the [signedTransactionBytes](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction.proto#L68C19-L68C19) of the [Transaction](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction.proto#L43C13-L43C13) message that was submitted to the Hedera Network. -### hedera_sendTransactionOnly -When a dApp only requires the services of the controller to act as a relay to the Hedera network for submitting an already signed transaction, it can use the `hedera_sendTransactionOnly` method. This method accepts a base64 encoded protobuf representation of the Hedera API [`SignedTransaction`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_contents.proto#L31) message as input. The controller decodes the message, interprets the contents, and if valid and approved, transmits the message unaltered to the Hedera network. The controller shall wait for the initial response from the Hedera node and return the resulting Node Precheck Code generated by the submission. +##### For Submission Failure (when `ResponseCodeEnum` is non zero) + +When the Hedera network responds with a non-zero `ResponseCodeEnum`, this indicates an error. This error is passed to the remote requestor using the `error` property of the underlying Wallet Connect JsonRpc response. The error object shall include the following properties: + +`code` - `9000`, the reserved Wallet Connect error code for unknown or errors not related to the Wallet Connect protocol. + +`message` - A human readable string describing the nature of the failure. + +`data` – an integer representing the [`ResponseCodeEnum`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/response_code.proto#L32) value returned from the Hedera Node, which indicates the reason for the failure. + +### hedera_executeTransaction +When a dApp only requires the services of the controller to act as a relay to the Hedera network for submitting an already signed transaction, it can use the `hedera_executeTransaction` method. This method accepts a base64 encoded protobuf representation of the Hedera API [`SignedTransaction`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction_contents.proto#L31) message as input. The controller decodes the message, interprets the contents, and if valid and approved, transmits the message unaltered to the Hedera network. The controller shall wait for the initial response from the Hedera node and return the resulting Node Precheck Code generated by the submission. The controller is allowed to retry submitting the signed transaction to the Hedera Network for certain types of error conditions; such as gRPC connection droppage or Hedera `BUSY` signals. This specification does not obligate the controller to retry, but recommends the practice to help improve perceived user experience for consumer applications. @@ -101,7 +112,8 @@ The controller is allowed to retry submitting the signed transaction to the Hede Note: the [CAIP-217](https://chainagnostic.org/CAIPs/caip-217) Scope property of the RPC call shall be used to identify which network shall be assumed when sending the transaction if multiple chainids were authorized in the pairing process. It is not necessary to transmit that value as a method parameter. #### Returns -`precheckCode` – an integer representing the [`ResponseCodeEnum`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/response_code.proto#L32) vaue returned from the Hedera Node, which may indicate success or failure. A response code indicating success does not necessarily indicate the transaction will reach consensus nor succeed, it solely indicates whether the submitted transaction passed initial validation to warrant further processing. + +##### For Success (when `ResponseCodeEnum` is 0) `transactionId` – a string encoded transaction identifier of the signed message that was sent to the Hedera node, in `..@.` format. @@ -109,6 +121,16 @@ Note: the [CAIP-217](https://chainagnostic.org/CAIPs/caip-217) Scope property of `transactionHash`– a base64 encoding of the SHA384 digest of the [signedTransactionBytes](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction.proto#L68C19-L68C19) of the [Transaction](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/transaction.proto#L43C13-L43C13) message that was submitted to the Hedera Network. +##### For Submission Failure (when `ResponseCodeEnum` is non zero) + +When the Hedera network responds with a non-zero `ResponseCodeEnum`, this indicates an error. This error is passed to the remote requestor using the `error` property of the underlying Wallet Connect JsonRpc response. The error object shall include the following properties: + +`code` - `9000`, the reserved Wallet Connect error code for unknown or errors not related to the Wallet Connect protocol. + +`message` - A human readable string describing the nature of the failure. + +`data` – an integer representing the [`ResponseCodeEnum`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/response_code.proto#L32) value returned from the Hedera Node, which indicates the reason for the failure. + ### hedera_signQueryAndSend When a dApp needs the services of the controller to perform an Hedera Network Query, it can use the `hedera_signQueryAndSend` method. This method accepts a base64 encoded protobuf representation of the Hedera API [`Query`](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/query.proto#L68) message as input. The controller decodes the message, interprets the contents, and if valid and approved, adds an appropriate signed transaction to the `header` field of the [Query](https://github.com/hashgraph/hedera-protobufs/blob/f36e05bd6bf3f572707ca9bb338f5ad6421a4241/services/query.proto#L68) (if applicable), repackages the message as appropriate and sends the message to the network. The controller shall wait for the query response and returns the resulting base64 encoded protobuf Response message received from the network. @@ -200,6 +222,7 @@ After approval of this HIP (or its replacement) there may be additional CAIP and - [CAIP-217](https://chainagnostic.org/CAIPs/caip-217): Authorization Scopes - [Wallet Connect Documentation](https://docs.walletconnect.com/) - [Wallet Connect Specifications](https://github.com/WalletConnect/walletconnect-specs) +- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification) ## Copyright/license