Merge pull request #3248 from ethereum/feature/revert-reason-string

Adds revert instruction handling

CHANGELOG.md

@@ -107,6 +107,7 @@ Released with 1.0.0-beta.37 code base.
 - ``eth_getProof`` as ``getProof`` added to web3-eth package (#3220)
 - ``BN`` and ``BigNumber`` objects are now supported by the ``abi.encodeParameter(s)`` method (#3238) 
 - ``getPendingTransactions`` added to web3-eth package (#3239)
+- Revert instruction handling added which can get activated with the ``handleRevert`` module property (#3248)
 
 ### Changed
 

docs/web3-eth-contract.rst

@@ -362,6 +362,28 @@ Returns
 
 ------------------------------------------------------------------------------
 
+.. _eth-contract-module-handlerevert:
+
+handleRevert
+============
+
+.. code-block:: javascript
+
+    web3.eth.Contract.handleRevert
+    contract.handleRevert // on contract instance
+
+The ``handleRevert`` options property does default to ``false`` and will return the revert reason string if enabled on :ref:`send <contract-send>` or :ref:`call <contract-call>` of a contract method.
+
+.. note:: The revert reason string and the signature does exist as property on the returned error.
+
+-------
+Returns
+-------
+
+``boolean``: The current value of ``handleRevert`` (default: false)
+
+------------------------------------------------------------------------------
+
 options
 =========
 
@@ -383,6 +405,13 @@ Properties
 - ``from`` - ``String``: The address transactions should be made from.
 - ``gasPrice`` - ``String``: The gas price in wei to use for transactions.
 - ``gas`` - ``Number``: The maximum gas provided for a transaction (gas limit).
+- ``handleRevert`` - ``Boolean``: It will otherwise use the default value provided from the Eth module. See :ref:`handleRevert <eth-contract-module-handlerevert>`.
+- ``transactionBlockTimeout`` - ``Number``: It will otherwise use the default value provided from the Eth module. See :ref:`transactionBlockTimeout <eth-contract-transactionblocktimeout>`.
+- ``transactionConfirmationBlocks`` - ``Number``: It will otherwise use the default value provided from the Eth module. See :ref:`transactionConfirmationBlocks <eth-contract-module-transactionconfirmationblocks>`.
+- ``transactionPollingTimeout`` - ``Number``: It will otherwise use the default value provided from the Eth module. See :ref:`transactionPollingTimeout <eth-contract-module-transactionpollingtimeout>`.
+- ``chain`` - ``Number``: It will otherwise use the default value provided from the Eth module. See :ref:`defaultChain <eth-contract-defaultchain>`.
+- ``hardfork`` - ``Number``: It will otherwise use the default value provided from the Eth module. See :ref:`defaultHardfork <eth-contract-defaulthardfork>`.
+- ``common`` - ``Number``: It will otherwise use the default value provided from the Eth module. See :ref:`defaultCommon <eth-contract-defaultcommon>`.
 
 
 -------

docs/web3-eth.rst

@@ -402,6 +402,32 @@ Returns
 
 ------------------------------------------------------------------------------
 
+.. _web3-module-handlerevert:
+
+handleRevert
+============
+
+.. code-block:: javascript
+
+    web3.eth.handleRevert
+
+The ``handleRevert`` options property does default to ``false`` and will return the revert reason string if enabled for the following methods:
+
+- :ref:`web3.eth.call() <eth-call>`
+- :ref:`web3.eth.sendTransaction() <eth-sendtransaction>`
+- :ref:`contract.methods.myMethod(...).send(...) <contract-send>`
+- :ref:`contract.methods.myMethod(...).call(...) <contract-call>`
+
+.. note:: The revert reason string and the signature does exist as property on the returned error.
+
+-------
+Returns
+-------
+
+``boolean``: The current value of ``handleRevert`` (default: false)
+
+------------------------------------------------------------------------------
+
 getProtocolVersion
 =====================
 

packages/web3-core-helpers/src/errors.js

@@ -43,5 +43,19 @@ module.exports = {
     },
     ConnectionTimeout: function (ms){
         return new Error('CONNECTION TIMEOUT: timeout of ' + ms + ' ms achived');
+    },
+    RevertInstructionError: function(reason, signature) {
+        var error = new Error('Your request got reverted with the following reason string: ' + reason);
+        error.reason = reason;
+        error.signature = signature;
+
+        return error;
+    },
+    TransactionRevertInstructionError: function(reason, signature, receipt) {
+        var error = new Error('Transaction has been reverted by the EVM:\n' + JSON.stringify(receipt, null, 2));
+        error.reason = reason;
+        error.signature = signature;
+
+        return error;
     }
 };

packages/web3-core-helpers/types/index.d.ts

@@ -66,6 +66,8 @@ export class errors {
     static InvalidProvider(): Error;
     static InvalidResponse(result: Error): Error;
     static ConnectionTimeout(ms: string): Error;
+    static RevertInstructionError(reason: string, signature: string): RevertInstructionError
+    static TransactionRevertInstructionError(reason: string, signature: string, receipt: object): TransactionRevertInstructionError
 }
 
 export class WebsocketProviderBase {
@@ -182,3 +184,13 @@ export interface JsonRpcResponse {
     result?: any;
     error?: string;
 }
+
+export interface RevertInstructionError extends Error {
+    reason: string;
+    signature: string;
+}
+
+export interface TransactionRevertInstructionError extends Error {
+    reason: string;
+    signature: string;
+}

packages/web3-core-helpers/types/tests/errors-test.ts

@@ -36,3 +36,9 @@ errors.InvalidResponse(new Error('hey'));
 
 // $ExpectType Error
 errors.ConnectionTimeout('timeout');
+
+// $ExpectType RevertInstructionError
+errors.RevertInstructionError('reason', 'signature');
+
+// $ExpectType TransactionRevertInstructionError
+errors.TransactionRevertInstructionError('reason', 'signature', {});