feat: forc-call abi backtracing (#7502)

## Description

This PR introduces panic/error traces to the forc call trace output.
This functionality is built on top of the existing abi-backtracing
introduced in the following:
-
https://github.com/FuelLabs/sway-rfcs/blob/master/rfcs/0016-abi-backtracing.md
- #7224
- #7277
- FuelLabs/fuel-abi-types#36
- https://github.com/FuelLabs/fuel-abi-types/pull/40/files

Supplying verbosity level greater than 1 (i.e. `-vv` or `-v=2`) will
display the panic/error traces when using `forc-call`.
If the called function panics, the panic message and the full backtrace
will be displayed in the trace output.

## Example

<details>
<summary>Example contract code</summary>

```sway
contract;

abi AbiErrorDemo {
    #[storage(write)]
    fn write_non_zero(value: u64);
    #[storage(read)]
    fn read_value() -> u64;
}

storage {
    value: u64 = 0,
}

#[error_type]
pub enum PanicError {
    #[error(m = "The provided value must be greater than zero.")]
    ZeroValue: (),
}

impl AbiErrorDemo for Contract {
    #[storage(write)]
    fn write_non_zero(value: u64) {
        set_non_zero_value(value);
    }
    #[storage(read)]
    fn read_value() -> u64 {
        storage.value.read()
    }
}

#[trace(always)]
#[storage(write)]
fn set_non_zero_value(value: u64) {
    ensure_non_zero(value);
    storage.value.write(value);
}

#[trace(always)]
fn ensure_non_zero(value: u64) {
    ensure_non_zero_impl(value);
}

#[trace(always)]
fn ensure_non_zero_impl(value: u64) {
    if value == 0 {
        panic PanicError::ZeroValue;
    }
}
```

</details>

Example Call:

```sh
cargo run -p forc-client --bin forc-call -- \
  --abi out/debug/abi_errors-abi.json \
  babdc125da45eac42309e60d3aea63a53843f5ff2438d1a88bf8c788e8348c58 \
  write_non_zero "0" -vv
```

Example Output:

<img width="857" height="340" alt="Screenshot 2025-11-24 at 8 36 00 PM"
src="https://github.com/user-attachments/assets/9a14053e-9318-4543-a01a-0d794e30dff2"
/>

## Checklist

- [ ] I have linked to any relevant issues.
- [ ] I have commented my code, particularly in hard-to-understand
areas.
- [ ] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] If my change requires substantial documentation changes, I have
[requested support from the DevRel
team](https://github.com/FuelLabs/devrel-requests/issues/new/choose)
- [ ] I have added tests that prove my fix is effective or that my
feature works.
- [ ] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [ ] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [ ] I have requested a review from the relevant team or maintainers.

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Adds ABI-aware revert decoding to forc-call, displaying panic
messages, values, and backtraces in verbose traces and surfacing revert
errors early.
> 
> - **forc-client (call/trace)**:
> - Add ABI-aware revert decoding (`RevertInfoSummary`) and integrate
into `TraceEvent::Revert`; render panic message, value, location, and
backtrace in `display_transaction_trace`.
> - New helpers: `decode_revert_info` and `first_revert_info` to extract
revert details from receipts and trace.
> - `call_function`: generate receipts once, include in interpreter,
display detailed info on verbosity, and return an error early when a
revert is detected; parse outputs after.
> - Minor: reference `trace::display_transaction_trace` directly; extend
tests to cover revert detail rendering.
> - **forc-util**:
> - Add `revert_info_from_receipts` to build `RevertInfo` (revert code,
panic metadata) from receipts using optional ABI.
> - **forc-test**:
> - Replace `revert_code()` with `revert_info()` using new utility;
filter by actual revert code; simplify API.
> - **Docs**:
> - Add "Seeing revert information and backtraces" section with example
usage/output for `forc call -vv`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
957d411. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: z <[email protected]>

Author: zees-dev

docs/book/src/testing/testing_with_forc_call.md

@@ -199,6 +199,37 @@ forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --wallet
 forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --signing-key <KEY>
 ```
 
+### Seeing revert information and backtraces
+
+If the contract ABI contains `errorCodes` and `panickingCalls` (generated by `panic`-aware builds), `forc call` will display rich revert information — panic message, panic value, and backtrace — inline in the trace output. Run with verbosity to see it:
+
+```bash
+forc call <CONTRACT_ID> \
+  --abi ./out/debug/my_contract-abi.json \
+  write_non_zero 0 -vv
+```
+
+Example (formatted):
+
+```text
+  [Script]
+    ├─ [1017] <contract>::write_non_zero(0)
+    │    ├─ emit ZeroValue
+    │    └─ ← [Revert]
+    │       ├─ revert code: 8000000000001001
+    │       ├─ panic message: The provided value must be greater than zero.
+    │       ├─ panic value:   ZeroValue
+    │       ├─ panicked:      in my_contract::ensure_non_zero
+    │       │                  └─ at src/main.sw:45:9
+    │       └─ backtrace:     called in my_contract::set_non_zero_value
+    │                          └─ at src/main.sw:38:5
+    │                          called in <Contract as AbiErrorDemo>::write_non_zero
+    │                          └─ at src/main.sw:26:9
+  [ScriptResult] result: Revert, gas_used: 784
+```
+
+If the ABI does not include those sections, only the raw revert code is displayed.
+
 ### Asset Transfers
 
 ```sh

forc-plugins/forc-client/src/op/call/call_function.rs

@@ -284,29 +284,11 @@ pub async fn call_function(
     let fuel_tx::Transaction::Script(script) = &tx else {
         bail!("Transaction is not a script");
     };
-
-    // Parse the result based on output format
-    let mut receipt_parser =
-        ReceiptParser::new(tx_execution.result.receipts(), DecoderConfig::default());
-    let result = match output {
-        cmd::call::OutputFormat::Default | cmd::call::OutputFormat::Json => {
-            let data = receipt_parser
-                .extract_contract_call_data(contract_id)
-                .ok_or(anyhow!("Failed to extract contract call data"))?;
-            ABIDecoder::default()
-                .decode_as_debug_str(&output_param, data.as_slice())
-                .map_err(|e| anyhow!("Failed to decode as debug string: {e}"))?
-        }
-        cmd::call::OutputFormat::Raw => {
-            let token = receipt_parser
-                .parse_call(contract_id, &output_param)
-                .map_err(|e| anyhow!("Failed to parse call data: {e}"))?;
-            token_to_string(&token)
-                .map_err(|e| anyhow!("Failed to convert token to string: {e}"))?
-        }
-    };
+    let receipts = tx_execution.result.receipts();
 
     // Generate execution trace events by stepping through VM interpreter
+    #[cfg(test)]
+    let trace_events: Vec<crate::op::call::trace::TraceEvent> = vec![];
     #[cfg(not(test))]
     let trace_events = {
         use crate::op::call::trace::interpret_execution_trace;
@@ -315,17 +297,14 @@ pub async fn call_function(
             &mode,
             &consensus_params,
             script,
-            tx_execution.result.receipts(),
+            receipts,
             storage_reads,
             &abi_map,
         )
         .await
         .map_err(|e| anyhow!("Failed to generate execution trace: {e}"))?
     };
 
-    #[cfg(test)]
-    let trace_events = vec![];
-
     // display detailed call info if verbosity is set
     if cmd.verbosity > 0 {
         // Convert labels from Vec to HashMap
@@ -346,6 +325,36 @@ pub async fn call_function(
         )?;
     }
 
+    // If the call reverted, exit early; return an error with the revert details
+    if let Some((contract_id, revert_info)) =
+        crate::op::call::trace::first_revert_info(&trace_events)
+    {
+        return Err(anyhow!(
+            "Contract 0x{contract_id} reverted with code 0x{:x}",
+            revert_info.revert_code
+        ));
+    }
+
+    // Parse the result based on output format
+    let mut receipt_parser = ReceiptParser::new(receipts, DecoderConfig::default());
+    let result = match output {
+        cmd::call::OutputFormat::Default | cmd::call::OutputFormat::Json => {
+            let data = receipt_parser
+                .extract_contract_call_data(contract_id)
+                .ok_or(anyhow!("Failed to extract contract call data"))?;
+            ABIDecoder::default()
+                .decode_as_debug_str(&output_param, data.as_slice())
+                .map_err(|e| anyhow!("Failed to decode as debug string: {e}"))?
+        }
+        cmd::call::OutputFormat::Raw => {
+            let token = receipt_parser
+                .parse_call(contract_id, &output_param)
+                .map_err(|e| anyhow!("Failed to parse call data: {e}"))?;
+            token_to_string(&token)
+                .map_err(|e| anyhow!("Failed to convert token to string: {e}"))?
+        }
+    };
+
     // display tx info
     super::display_tx_info(
         tx_execution.id.to_string(),

forc-plugins/forc-client/src/op/call/mod.rs

@@ -10,8 +10,7 @@ use crate::{
     cmd,
     constants::DEFAULT_PRIVATE_KEY,
     op::call::{
-        call_function::call_function, list_functions::list_contract_functions,
-        trace::display_transaction_trace, transfer::transfer,
+        call_function::call_function, list_functions::list_contract_functions, transfer::transfer,
     },
     util::tx::{prompt_forc_wallet_password, select_local_wallet_account},
 };
@@ -286,7 +285,7 @@ pub(crate) fn display_detailed_call_info(
         forc_tracing::println_label_green("receipts:", &formatted_receipts);
     }
     if verbosity >= 2 {
-        display_transaction_trace(*tx.result.total_gas(), trace_events, labels, writer)
+        trace::display_transaction_trace(*tx.result.total_gas(), trace_events, labels, writer)
             .map_err(|e| anyhow!("Failed to display transaction trace: {e}"))?;
     }
     if verbosity >= 1 {