feat: Soft failure reason for evm op results (besu-eth#9109)

Add soft failure reasons for evm operation results.

Signed-off-by: Usman Saleem <usman@usmans.info>
Signed-off-by: georgereuben <reubengeorge101@gmail.com>

Author: usmansaleem

evm/src/main/java/org/hyperledger/besu/evm/frame/SoftFailureReason.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright contributors to Besu.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+ * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations under the License.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package org.hyperledger.besu.evm.frame;
+
+/** The enum Soft Failure reason. */
+public enum SoftFailureReason {
+
+  /** Soft failure due to insufficient balance. Mainly use to provide visibility to Tracers. */
+  LEGACY_INSUFFICIENT_BALANCE("insufficient balance for transfer"),
+  /** Soft failure due to max call depth. Mainly use to provide visibility to Tracers. */
+  LEGACY_MAX_CALL_DEPTH("max call depth exceeded");
+
+  /** The Description of soft failure. */
+  final String description;
+
+  /**
+   * Enum constructor with description
+   *
+   * @param description to set
+   */
+  SoftFailureReason(final String description) {
+    this.description = description;
+  }
+
+  /**
+   * Returns Description
+   *
+   * @return description.
+   */
+  public String getDescription() {
+    return description;
+  }
+}

evm/src/main/java/org/hyperledger/besu/evm/operation/AbstractCallOperation.java

@@ -14,6 +14,8 @@
  */
 package org.hyperledger.besu.evm.operation;
 
+import static org.hyperledger.besu.evm.frame.SoftFailureReason.LEGACY_INSUFFICIENT_BALANCE;
+import static org.hyperledger.besu.evm.frame.SoftFailureReason.LEGACY_MAX_CALL_DEPTH;
 import static org.hyperledger.besu.evm.internal.Words.clampedAdd;
 import static org.hyperledger.besu.evm.internal.Words.clampedToLong;
 import static org.hyperledger.besu.evm.worldstate.CodeDelegationHelper.getTarget;
@@ -29,6 +31,7 @@
 import org.hyperledger.besu.evm.frame.ExceptionalHaltReason;
 import org.hyperledger.besu.evm.frame.MessageFrame;
 import org.hyperledger.besu.evm.frame.MessageFrame.State;
+import org.hyperledger.besu.evm.frame.SoftFailureReason;
 import org.hyperledger.besu.evm.gascalculator.GasCalculator;
 import org.hyperledger.besu.evm.worldstate.CodeDelegationHelper;
 
@@ -204,15 +207,19 @@ public OperationResult execute(final MessageFrame frame, final EVM evm) {
 
     // If the call is sending more value than the account has or the message frame is too deep
     // return a failed call
-    if (value(frame).compareTo(balance) > 0 || frame.getDepth() >= 1024) {
+    final boolean insufficientBalance = value(frame).compareTo(balance) > 0;
+    final boolean isFrameDepthTooDeep = frame.getDepth() >= 1024;
+    if (insufficientBalance || isFrameDepthTooDeep) {
       frame.expandMemory(inputDataOffset(frame), inputDataLength(frame));
       frame.expandMemory(outputDataOffset(frame), outputDataLength(frame));
       // For the following, we either increment the gas or return zero, so we don't get double
       // charged. If we return zero then the traces don't have the right per-opcode cost.
       frame.incrementRemainingGas(gasAvailableForChildCall(frame) + cost);
       frame.popStackItems(getStackItemsConsumed());
       frame.pushStackItem(LEGACY_FAILURE_STACK_ITEM);
-      return new OperationResult(cost, null);
+      final SoftFailureReason softFailureReason =
+          insufficientBalance ? LEGACY_INSUFFICIENT_BALANCE : LEGACY_MAX_CALL_DEPTH;
+      return new OperationResult(cost, 1, softFailureReason);
     }
 
     final Bytes inputData = frame.readMutableMemory(inputDataOffset(frame), inputDataLength(frame));

evm/src/main/java/org/hyperledger/besu/evm/operation/Operation.java

@@ -17,6 +17,9 @@
 import org.hyperledger.besu.evm.EVM;
 import org.hyperledger.besu.evm.frame.ExceptionalHaltReason;
 import org.hyperledger.besu.evm.frame.MessageFrame;
+import org.hyperledger.besu.evm.frame.SoftFailureReason;
+
+import java.util.Optional;
 
 /** The interface Operation. */
 public interface Operation {
@@ -32,6 +35,9 @@ class OperationResult {
     /** The increment. */
     final int pcIncrement;
 
+    /** Soft Failure Reason. Mainly used to provide visibility to tracers. */
+    final SoftFailureReason softFailureReason;
+
     /**
      * Instantiates a new Operation result.
      *
@@ -54,6 +60,22 @@ public OperationResult(
       this.gasCost = gasCost;
       this.haltReason = haltReason;
       this.pcIncrement = pcIncrement;
+      this.softFailureReason = null;
+    }
+
+    /**
+     * Instantiate a new Operation Result with a Soft Failure Reason.
+     *
+     * @param gasCost Gas Cost
+     * @param pcIncrement The increment
+     * @param softFailureReason The Soft Failure Reason
+     */
+    public OperationResult(
+        final long gasCost, final int pcIncrement, final SoftFailureReason softFailureReason) {
+      this.gasCost = gasCost;
+      this.haltReason = null;
+      this.pcIncrement = pcIncrement;
+      this.softFailureReason = softFailureReason;
     }
 
     /**
@@ -82,6 +104,15 @@ public ExceptionalHaltReason getHaltReason() {
     public int getPcIncrement() {
       return pcIncrement;
     }
+
+    /**
+     * Returns optional Soft Failure Reason.
+     *
+     * @return Optional Soft Failure Reason
+     */
+    public Optional<SoftFailureReason> getSoftFailureReason() {
+      return Optional.ofNullable(this.softFailureReason);
+    }
   }
 
   /**