feat: add execution error decode command (#604)

Adds execution error decode command. This command takes a JSON for an
mcms-tools results json and attempts to decode the error revert reason
using the ABI registries injected by the proposal context.

TODO: Remove local replace once mcmslib is released with
smartcontractkit/mcms#547

.
## AI Summary
This pull request introduces significant improvements to error decoding
for EVM transaction failures, adds a new CLI command for error decoding,
and includes dependency updates. The most notable changes are the
addition of robust helpers for decoding EVM execution errors,
comprehensive tests for these helpers, and a new CLI command to decode
errors from JSON files using the ABI registry. Several dependencies in
`go.mod` have also been updated.

**EVM Error Decoding Enhancements**

* Added `DecodedExecutionError` struct and `tryDecodeExecutionError`
function in `err_decode_helpers.go` to extract and decode revert reasons
and underlying reasons from EVM execution errors, handling both custom
and standard errors, and supporting decoding with or without an ABI
registry.
* Introduced `decodeRevertData` and `decodeRevertDataFromBytes` helpers
to convert hex or byte revert data into human-readable error messages,
falling back to custom error selectors if no decoder is available.

**CLI Improvements**

* Added a new CLI command `error-decode-evm` in `mcms_v2.go` that reads
a JSON file containing transaction error data, loads the ABI registry
from the specified environment, decodes the error using the new helpers,
and prints the decoded revert and underlying reasons.
[[1]](diffhunk://#diff-726dd799d05204c24b69b8bda1f4ede5393c5955b360b076db8d11bc01f56a1bR115)
[[2]](diffhunk://#diff-726dd799d05204c24b69b8bda1f4ede5393c5955b360b076db8d11bc01f56a1bR150-R261)

**Testing**

* Added a comprehensive test `Test_tryDecodeExecutionError` in
`err_decode_helpers_test.go` that covers decoding custom errors,
standard errors, selectors, underlying reasons, and nil/empty cases for
the new error decoding logic.

**Dependency Updates**

* Updated several dependencies in `go.mod`, including
`github.com/smartcontractkit/chain-selectors`,
`github.com/smartcontractkit/chainlink-testing-framework/framework`,
`golang.org/x/oauth2`, and others. Also, replaced the
`github.com/smartcontractkit/mcms` dependency to use a local path.
[[1]](diffhunk://#diff-33ef32bf6c23acb95f5902d7097b7a1d5128ca061167ec0716715b0b9eeaa5f6R7-R8)
[[2]](diffhunk://#diff-33ef32bf6c23acb95f5902d7097b7a1d5128ca061167ec0716715b0b9eeaa5f6L30-R39)
[[3]](diffhunk://#diff-33ef32bf6c23acb95f5902d7097b7a1d5128ca061167ec0716715b0b9eeaa5f6L54-R56)
[[4]](diffhunk://#diff-33ef32bf6c23acb95f5902d7097b7a1d5128ca061167ec0716715b0b9eeaa5f6L84-R86)
[[5]](diffhunk://#diff-33ef32bf6c23acb95f5902d7097b7a1d5128ca061167ec0716715b0b9eeaa5f6L123-R131)
[[6]](diffhunk://#diff-33ef32bf6c23acb95f5902d7097b7a1d5128ca061167ec0716715b0b9eeaa5f6L269-R271)
[[7]](diffhunk://#diff-33ef32bf6c23acb95f5902d7097b7a1d5128ca061167ec0716715b0b9eeaa5f6L297)

**Minor Improvements**

* Improved error logging and error joining in the
`MultiClient.retryWithBackups` method for more informative logs when
retryable errors occur.
* Cleaned up unnecessary comments in `maybeDataErr` for code clarity.

These changes collectively improve the developer experience when
diagnosing and understanding EVM transaction failures, both
programmatically and via the CLI.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: ecPablo

.changeset/whole-symbols-vanish.md

@@ -0,0 +1,5 @@
+---
+"chainlink-deployments-framework": minor
+---
+
+add error decode command

chain/evm/provider/rpcclient/multiclient.go

@@ -401,7 +401,10 @@ func (mc *MultiClient) retryWithBackups(ctx context.Context, opName string, op f
 
 			err = op(timeoutCtx, client)
 			if err != nil {
-				mc.lggr.Warnf("traceID %q: chain %q: op: %q: client index %d: failed execution - retryable error '%s'", traceID.String(), mc.chainName, opName, rpcIndex, maybeDataErr(err))
+				detailedErr := maybeDataErr(err)
+				mc.lggr.Warnf("traceID %q: chain %q: op: %q: client index %d: failed execution - retryable error '%s'", traceID.String(), mc.chainName, opName, rpcIndex, detailedErr)
+				err = errors.Join(err, detailedErr)
+
 				return err
 			}
 

engine/cld/legacy/cli/mcmsv2/err_decode_helpers.go

@@ -30,6 +30,10 @@ import (
 
 const noRevertData = "(no revert data)"
 
+type errorSelector [4]byte
+
+var emptySelector = errorSelector{}
+
 type traceConfig struct {
 	DisableStorage bool `json:"disableStorage,omitempty"`
 	DisableMemory  bool `json:"disableMemory,omitempty"`
@@ -57,25 +61,25 @@ type ErrSig struct {
 	TypeVer string
 	Name    string
 	Inputs  abi.Arguments
-	id      [4]byte
+	id      errorSelector
 }
 
 // ErrDecoder indexes custom-error selectors across many ABIs.
 type ErrDecoder struct {
-	bySelector map[[4]byte][]ErrSig
+	bySelector map[errorSelector][]ErrSig
 	registry   analyzer.EVMABIRegistry
 }
 
 // NewErrDecoder builds an index from EVM ABI registry.
 func NewErrDecoder(registry analyzer.EVMABIRegistry) (*ErrDecoder, error) {
-	idx := make(map[[4]byte][]ErrSig)
+	idx := make(map[errorSelector][]ErrSig)
 	for tv, jsonABI := range registry.GetAllABIs() {
 		a, err := abi.JSON(strings.NewReader(jsonABI))
 		if err != nil {
 			return nil, fmt.Errorf("parse ABI for %s: %w", tv, err)
 		}
 		for name, e := range a.Errors {
-			var key [4]byte
+			var key errorSelector
 			copy(key[:], e.ID[:4]) // selector is first 4 bytes of the keccak(sig)
 			idx[key] = append(idx[key], ErrSig{
 				TypeVer: tv,
@@ -181,7 +185,7 @@ func (d *ErrDecoder) decodeRecursive(revertData []byte, preferredABIJSON string)
 	}
 
 	// --- B) Registry lookup
-	var key [4]byte
+	var key errorSelector
 	copy(key[:], sel)
 	cands, ok := d.bySelector[key]
 	if !ok {
@@ -619,6 +623,160 @@ func prettyRevertFromError(err error, preferredABIJSON string, dec *ErrDecoder)
 	return "", false
 }
 
+// DecodedExecutionError contains the decoded revert reasons from an ExecutionError.
+type DecodedExecutionError struct {
+	RevertReason            string
+	RevertReasonDecoded     bool
+	UnderlyingReason        string
+	UnderlyingReasonDecoded bool
+}
+
+// tryDecodeExecutionError decodes an evm.ExecutionError into human-readable strings.
+// It first checks for RevertReasonDecoded and UnderlyingReasonDecoded fields.
+// If those are not available, it extracts RevertReasonRaw and UnderlyingReasonRaw from the struct
+// and decodes them using the provided ErrDecoder to match error selectors against the ABI registry.
+func tryDecodeExecutionError(execError *evm.ExecutionError, dec *ErrDecoder) DecodedExecutionError {
+	if execError == nil {
+		return DecodedExecutionError{}
+	}
+
+	revertReason, revertDecoded := decodeRevertReasonWithStatus(execError, dec)
+	underlyingReason, underlyingDecoded := decodeUnderlyingReasonWithStatus(execError, dec)
+
+	return DecodedExecutionError{
+		RevertReason:            revertReason,
+		RevertReasonDecoded:     revertDecoded,
+		UnderlyingReason:        underlyingReason,
+		UnderlyingReasonDecoded: underlyingDecoded,
+	}
+}
+
+// decodeRevertReasonWithStatus decodes the revert reason and returns both the reason and decoded status.
+func decodeRevertReasonWithStatus(execError *evm.ExecutionError, dec *ErrDecoder) (string, bool) {
+	if execError.RevertReasonDecoded != "" {
+		return execError.RevertReasonDecoded, true
+	}
+
+	if execError.RevertReasonRaw == nil {
+		return "", false
+	}
+
+	hasData := len(execError.RevertReasonRaw.Data) > 0
+	hasSelector := execError.RevertReasonRaw.Selector != emptySelector
+
+	if hasData {
+		if reason, decoded := tryDecodeFromData(execError.RevertReasonRaw, dec); decoded {
+			return reason, true
+		}
+	}
+
+	if hasSelector && !hasData {
+		reason := decodeSelectorOnly(execError.RevertReasonRaw.Selector, dec)
+		return reason, reason != ""
+	}
+
+	return "", false
+}
+
+// tryDecodeFromData attempts to decode revert data from the CustomErrorData.
+func tryDecodeFromData(raw *evm.CustomErrorData, dec *ErrDecoder) (string, bool) {
+	if len(raw.Data) >= 4 {
+		if reason, decoded := decodeRevertDataFromBytes(raw.Data, dec, ""); decoded {
+			return reason, true
+		}
+	}
+
+	if raw.Selector != emptySelector {
+		if combined := raw.Combined(); len(combined) > 4 {
+			return decodeRevertDataFromBytes(combined, dec, "")
+		}
+	}
+
+	return "", false
+}
+
+// decodeSelectorOnly decodes an error when only the selector is available.
+func decodeSelectorOnly(selector errorSelector, dec *ErrDecoder) string {
+	if dec == nil {
+		return formatSelectorHex(selector)
+	}
+
+	if matched, ok := dec.matchErrorSelector(selector); ok {
+		return matched
+	}
+
+	return formatSelectorHex(selector)
+}
+
+// formatSelectorHex formats a selector as a hex string.
+func formatSelectorHex(selector errorSelector) string {
+	return "custom error 0x" + hex.EncodeToString(selector[:])
+}
+
+// decodeUnderlyingReasonWithStatus decodes the underlying reason and returns both the reason and decoded status.
+func decodeUnderlyingReasonWithStatus(execError *evm.ExecutionError, dec *ErrDecoder) (string, bool) {
+	if execError.UnderlyingReasonDecoded != "" {
+		return execError.UnderlyingReasonDecoded, true
+	}
+
+	if execError.UnderlyingReasonRaw == "" {
+		return "", false
+	}
+
+	reason, decoded := decodeRevertData(execError.UnderlyingReasonRaw, dec, "")
+
+	return reason, decoded
+}
+
+// decodeRevertData decodes a hex string containing revert data into a human-readable error message.
+func decodeRevertData(hexStr string, dec *ErrDecoder, preferredABIJSON string) (string, bool) {
+	if hexStr == "" {
+		return "", false
+	}
+
+	data, err := hexutil.Decode(hexStr)
+	if err != nil || len(data) == 0 {
+		return "", false
+	}
+
+	return decodeRevertDataFromBytes(data, dec, preferredABIJSON)
+}
+
+// matchErrorSelector tries to resolve a 4-byte selector to an error name.
+// Returns "ErrorName(...) @Type@Version" if found in registry, or empty string if not found.
+func (d *ErrDecoder) matchErrorSelector(sel4 errorSelector) (string, bool) {
+	if d == nil || d.bySelector == nil {
+		return "", false
+	}
+
+	cands, ok := d.bySelector[sel4]
+	if !ok || len(cands) == 0 {
+		return "", false
+	}
+
+	// If multiple ABIs define the same selector, pick the first.
+	c := cands[0]
+
+	return fmt.Sprintf("%s(...) @%s", c.Name, c.TypeVer), true
+}
+
+// decodeRevertDataFromBytes decodes revert data bytes into a human-readable error message.
+func decodeRevertDataFromBytes(data []byte, dec *ErrDecoder, preferredABIJSON string) (string, bool) {
+	if len(data) == 0 {
+		return "", false
+	}
+
+	if dec == nil {
+		if len(data) >= 4 {
+			return "custom error 0x" + hex.EncodeToString(data[:4]), true
+		}
+
+		return "", false
+	}
+
+	return prettyFromBytes(data, preferredABIJSON, dec)
+}
+
 type callContractClient interface {
 	CallContract(context.Context, ethereum.CallMsg, *big.Int) ([]byte, error)
 }