From c8031eac5c54478e85997aa4fd7db5b11dd1f805 Mon Sep 17 00:00:00 2001 From: Matthew Whitehead Date: Thu, 11 Apr 2024 16:04:10 +0100 Subject: [PATCH 1/2] Add documentation to outline how EVM revert errors are handled Signed-off-by: Matthew Whitehead --- .../blockchain_connector_framework.md | 83 ++++++++++++++++++- 1 file changed, 82 insertions(+), 1 deletion(-) diff --git a/docs/architecture/blockchain_connector_framework.md b/docs/architecture/blockchain_connector_framework.md index 20d81adb69..d0b5d8f501 100644 --- a/docs/architecture/blockchain_connector_framework.md +++ b/docs/architecture/blockchain_connector_framework.md @@ -191,4 +191,85 @@ Some high architectural principals that informed the code: - Plugged in between detection of the events, and assembling into batches - Determines the final order based on order of confirmation on the blockchain -[![FireFly Connector Toolkit Event Streams](../images/firefly_connector_toolkit_event_streams.jpg)](../images/firefly_connector_toolkit_event_streams.jpg) \ No newline at end of file +[![FireFly Connector Toolkit Event Streams](../images/firefly_connector_toolkit_event_streams.jpg)](../images/firefly_connector_toolkit_event_streams.jpg) + +## Transaction error messages + +The receipt for a FireFly blockchain operation contains an `extraInfo` section that records additional information about the transaction. For example: + +``` +"receipt": { + ... + "extraInfo": [ + { + { + "contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436", + "cumulativeGasUsed":"33812", + "from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae", + "to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3", + "gasUsed":"33812", + "status":"0", + "errorMessage":"Not enough tokens", + } + } + ], + ... +}, +``` + +The `errorMessage` field can be used to understand the reason why a transaction failed. The value stored in the `errorMessage` field will vary depending on the type of error, the configuration of the EVM client the connector is using, and the smart contract logic. + +### Format of an error message + +The `errorMessage` field may contain one of the following: + +1. An error message from the FireFly blockchain connector + - For example `"FF23054", "Error return value unavailable"` +2. A decoded error string from the blockchain transaction + - For example `Not enough tokens` + - This could be an error string from a smart contract e.g. `require(requestedTokens <= allowance, "Not enough tokens");` +3. An un-decoded byte string from the blockchain transaction + - For example +``` +FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010 +``` + - This could be a custom error from a smart contract e.g. +``` +error AllowanceTooSmall(uint256 requested, uint256 allowance); +... +revert AllowanceTooSmall({ requested: 100, allowance: 20 }); +``` + - If an error reason cannot be decoded the `returnValue` of the `extraInfo` will be set to the raw byte string. For example: +``` +"receipt": { + ... + "extraInfo": [ + { + { + "contractAddress":"0x87ae94ab290932c4e6269648bb47c86978af4436", + "cumulativeGasUsed":"33812", + "from":"0x2b1c769ef5ad304a4889f2a07a6617cd935849ae", + "to":"0x302259069aaa5b10dc6f29a9a3f72a8e52837cc3", + "gasUsed":"33812", + "status":"0", + "errorMessage":"FF23053: Error return value for custom error: 0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010", + "returnValue":"0x1320fa6a00000000000000000000000000000000000000000000000000000000000000640000000000000000000000000000000000000000000000000000000000000010" + } + } + ], + ... +}, +``` + +### Retrieving blockchain transaction errors + +For an EVM blockchain the error reason for a failed blockchain transaction is recorded through the `REVERT` op code, with a `REASON` set to the reason for the failure. By default, most EVM clients do not store this reason in the transaction receipt. This is typically to reduce resource consumption such as memory usage in the client. It is usually possible to configure an EVM client to store the revert reason in the transaction receipt. For example Hyperledger Besu provides the `--revert-reason-enabled` configuration option. If the transaction receipt does not contain the revert reason it is possible to request that an EVM client re-run the transaction and return a trace of all of the op-codes, including the final `REVERT` `REASON`. This can be a resource intensive request to submit to an EVM client, and is only available on archive nodes or for very recent blocks. + +The `firefly-evmconnect` blockchain connector attempts to obtain the reason for a transaction revert and include it in the `extraInfo` field. It uses the following mechanisms, in this order: + +1. Checks if the blockchain transaction receipt contains the revert reason. +2. If the revert reason is not in the receipt, and the `connector.traceTXForRevertReason` configuration option is set to `true`, calls `debug_traceTransaction` to obtain a full trace of the transaction and extract the revert reason. By default, `connector.traceTXForRevertReason` is set to `false` to avoid submitting high-resource requests to the EVM client. + +If the revert reason can be obtained using either mechanism above, the revert reason bytes are decoded in the following way: + - Attempts to decode the bytes as the standard `Error(string)` signature format and includes the decoded string in the `errorMessage` + - If the reason is not a standard `Error(String)` error, sets the `errorMessage` to `FF23053: Error return value for custom error: ` and includes the raw byte string in the `returnValue` field. From e8bbcc8b88819ed3a39d71f6ef9ac9ee3adce8b5 Mon Sep 17 00:00:00 2001 From: Matthew Whitehead Date: Fri, 12 Apr 2024 09:54:04 +0100 Subject: [PATCH 2/2] Refactor to distinguish between generic information and connector-specific behaviour Signed-off-by: Matthew Whitehead --- .../architecture/blockchain_connector_framework.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/architecture/blockchain_connector_framework.md b/docs/architecture/blockchain_connector_framework.md index d0b5d8f501..ab0fd9dd20 100644 --- a/docs/architecture/blockchain_connector_framework.md +++ b/docs/architecture/blockchain_connector_framework.md @@ -193,7 +193,7 @@ Some high architectural principals that informed the code: [![FireFly Connector Toolkit Event Streams](../images/firefly_connector_toolkit_event_streams.jpg)](../images/firefly_connector_toolkit_event_streams.jpg) -## Transaction error messages +## Blockchain error messages The receipt for a FireFly blockchain operation contains an `extraInfo` section that records additional information about the transaction. For example: @@ -217,11 +217,13 @@ The receipt for a FireFly blockchain operation contains an `extraInfo` section t }, ``` -The `errorMessage` field can be used to understand the reason why a transaction failed. The value stored in the `errorMessage` field will vary depending on the type of error, the configuration of the EVM client the connector is using, and the smart contract logic. +The `errorMessage` field can be be set by a blockchain connector to provide FireFly and the end-user with more information about the reason why a tranasction failed. The blockchain connector can choose what information to include in `errorMessage` field. It may be set to an error message relating to the blockchain connector itself or an error message passed back from the blockchain or smart contract that was invoked. -### Format of an error message +### Format of a `firefly-evmconnect` error message -The `errorMessage` field may contain one of the following: +The following section describes the way that the `firefly-evmconnect` plugin uses the `errorMessage` field. This serves both as an explanation of how EVM-based transaction errors will be formatted, and as a guide that other blockchain connectors may decide to follow. + +The `errorMessage` field for a `firefly-evmconnect` transaction may contain one of the following: 1. An error message from the FireFly blockchain connector - For example `"FF23054", "Error return value unavailable"` @@ -261,9 +263,9 @@ revert AllowanceTooSmall({ requested: 100, allowance: 20 }); }, ``` -### Retrieving blockchain transaction errors +### Retrieving EVM blockchain transaction errors -For an EVM blockchain the error reason for a failed blockchain transaction is recorded through the `REVERT` op code, with a `REASON` set to the reason for the failure. By default, most EVM clients do not store this reason in the transaction receipt. This is typically to reduce resource consumption such as memory usage in the client. It is usually possible to configure an EVM client to store the revert reason in the transaction receipt. For example Hyperledger Besu provides the `--revert-reason-enabled` configuration option. If the transaction receipt does not contain the revert reason it is possible to request that an EVM client re-run the transaction and return a trace of all of the op-codes, including the final `REVERT` `REASON`. This can be a resource intensive request to submit to an EVM client, and is only available on archive nodes or for very recent blocks. +The ability of a blockchain connector such as `firefly-evmconnect` to retrieve the reason for a transaction failure, is dependent on by the configuration of the blockchain it is connected to. For an EVM blockchain the reason why a transaction failed is recorded with the `REVERT` op code, with a `REASON` set to the reason for the failure. By default, most EVM clients do not store this reason in the transaction receipt. This is typically to reduce resource consumption such as memory usage in the client. It is usually possible to configure an EVM client to store the revert reason in the transaction receipt. For example Hyperledger Besu™ provides the `--revert-reason-enabled` configuration option. If the transaction receipt does not contain the revert reason it is possible to request that an EVM client re-run the transaction and return a trace of all of the op-codes, including the final `REVERT` `REASON`. This can be a resource intensive request to submit to an EVM client, and is only available on archive nodes or for very recent blocks. The `firefly-evmconnect` blockchain connector attempts to obtain the reason for a transaction revert and include it in the `extraInfo` field. It uses the following mechanisms, in this order: