web3.js ↔ JSON‑RPC Provider: Decoding Revert Reasons on Failed Deployments

Reliable Provider Configurations

To consistently obtain a populated revertReason in the transaction receipt, you must use a node implementation that extends the standard eth_getTransactionReceipt response. Geth (v1.10+) and Besu typically provide this field when the EVM reverts. However, managed services like Infura or Alchemy often adhere strictly to the official Ethereum JSON-RPC specification, which does not include revertReason in the receipt. For these providers, the receipt will only indicate a status of 0 (failure) without a human-readable string.

web3.js v4 and Custom Error Handling

When using Deployment.catch in web3.js v4, the behavior regarding custom errors (EIP-838) is determined by the availability of the ABI at the time of decoding:

• With ABI: The library maps the 4-byte error selector to the named error and decodes the associated arguments.
• Without ABI: web3.js cannot resolve the selector to a human-readable name. It returns the raw 4-byte hex selector (e.g., 0x...), leaving the developer to manually look up the selector in a database or the contract source.

Fallback Strategy for Limited Providers

If your provider does not support debug_traceTransaction or the revertReason receipt field, the most reliable fallback is Manual Simulation via eth_call. Since a deployment is essentially a transaction to the null address with the constructor bytecode as data, you can simulate the failure to extract the error message.

Implementation Steps

1. Capture the data field (bytecode + constructor arguments) used in the failed deployment.
2. Execute web3.eth.call using the same from address and data, targeting the 0x0 address or leaving the to field empty (depending on provider support for contract creation simulation).
3. The provider will return the revert reason in the JSON-RPC error object, which web3.js can then parse.

Verification Command

To verify if your current provider supports the extended receipt field, execute a failing deployment and check the raw response:

// Example check for raw receipt field
const receipt = await web3.eth.getTransactionReceipt(txHash);
console.log("Revert Reason present:", !!receipt.revertReason);

Note: This approach does not work for "Out of Gas" errors, as these are execution environment failures rather than EVM reverts and do not generate a revert string.

Diagnostic Detail Required: Are you encountering Out of Gas errors specifically, or are these logic-based require()/revert() failures?