feat: forc call tracing

docs/book/src/testing/testing_with_forc_call.md

@@ -196,6 +196,74 @@ forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --gas-forwarded 1000
 forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> --max-fee 5000
 ```
 
+### Transaction Tracing
+
+When you need to debug contract interactions or understand the execution flow, `forc call` provides detailed transaction traces with verbosity level 3 or higher (`-vvv` or `-v=3`).
+
+```sh
+# Enable transaction tracing
+forc call <CONTRACT_ID> --abi <PATH> <FUNCTION> -vvv
+```
+
+The transaction trace provides a hierarchical view of all contract calls, showing:
+
+- Gas consumption for each call (`[gas_amount]`)
+- Contract addresses being called
+- Return values and data
+- Emitted logs and events
+- Nested contract calls with proper indentation
+- Overall transaction result and gas usage
+
+#### Example Transaction Trace Output
+
+```bash
+forc call 0x9275a76531bce733cfafdbcb6727ea533ebbdc358d685152169b3c4eaa47b965 \
+  --abi ./demo/demo-caller-abi.json \
+  call_increment_count -vvv
+```
+
+**Output:**
+
+```log
+Traces:
+  [Script]
+    ├─ [124116] 0x9275a76531bce733cfafdbcb6727ea533ebbdc358d685152169b3c4eaa47b965
+    │    ├─ [111500] 0xb792b1e233a2c06bccec611711acc3bb61bdcb28f16abdde86d1478ee02f6e42
+    │    │    └─ ← ()
+    │    ├─ emit AsciiString { data: "incremented count" }
+    │    ├─ [86284] 0xb792b1e233a2c06bccec611711acc3bb61bdcb28f16abdde86d1478ee02f6e42
+    │    │    └─ ← 0x0000000000000002
+    │    ├─ emit 2
+    │    ├─ emit AsciiString { data: "done" }
+    │    ├─ [72699] 0xb792b1e233a2c06bccec611711acc3bb61bdcb28f16abdde86d1478ee02f6e42
+    │    │    └─ ← ()
+    │    ├─ [48287] 0xb792b1e233a2c06bccec611711acc3bb61bdcb28f16abdde86d1478ee02f6e42
+    │    │    └─ ← 0x0000000000000003
+    │    └─ ← 0x0000000000000003
+    └─ ← [Return] val: 1
+  [ScriptResult] result: Success, gas_used: 89279
+
+Transaction successfully executed.
+Gas used: 160676
+```
+
+#### Understanding the Trace Format
+
+- `[Script]` - The root transaction script
+- `├─ [gas_amount] 0xcontract_address` - A contract call with gas consumption
+- `│    └─ ← value` - Return value from the contract call
+- `emit data` - Log/event emitted by the contract
+- Indentation shows the call hierarchy (nested calls are indented further)
+- `[ScriptResult]` - Final transaction result with gas used by the script
+- `Gas used: <gas_used>` - Total gas used by the transaction
+
+This tracing feature is particularly useful for:
+
+- Debugging failed transactions
+- Understanding gas consumption patterns
+- Analyzing complex multi-contract interactions
+- Verifying expected contract behavior
+
 ### Common Use Cases
 
 #### Contract State Queries

forc-plugins/forc-client/Cargo.toml

@@ -9,6 +9,7 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
+ansiterm.workspace = true
 anyhow.workspace = true
 async-trait.workspace = true
 aws-config.workspace = true

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

@@ -3,18 +3,19 @@ use crate::{
     op::call::{
         missing_contracts::determine_missing_contracts,
         parser::{param_type_val_to_token, token_to_string},
-        CallResponse, Either,
+        Abi, CallData, CallResponse, Either,
     },
 };
 use anyhow::{anyhow, bail, Result};
-use fuel_abi_types::abi::{program::ProgramABI, unified_program::UnifiedProgramABI};
+use fuel_abi_types::abi::unified_program::UnifiedProgramABI;
 use fuels::{
     accounts::ViewOnlyAccount,
     programs::calls::{
         receipt_parser::ReceiptParser,
         traits::{ContractDependencyConfigurator, TransactionTuner},
         ContractCall,
     },
+    types::tx_status::TxStatus,
 };
 use fuels_core::{
     codec::{
@@ -29,7 +30,7 @@ use fuels_core::{
         ContractId,
     },
 };
-use std::{collections::HashMap, path::PathBuf};
+use std::{collections::HashMap, path::PathBuf, str::FromStr};
 use url::Url;
 
 /// Calls a contract function with the given parameters
@@ -46,20 +47,19 @@ pub async fn call_function(
         caller,
         call_parameters,
         gas,
-        output,
+        mut output,
         external_contracts,
         ..
     } = cmd;
 
     // Load ABI (already provided in the operation)
     let abi_str = super::load_abi(&abi).await?;
-    let parsed_abi: ProgramABI = serde_json::from_str(&abi_str)?;
-    let unified_program_abi = UnifiedProgramABI::from_counterpart(&parsed_abi)?;
+    let abi = Abi::from_str(&abi_str).map_err(|e| anyhow!("Failed to parse ABI: {}", e))?;
 
     let cmd::call::FuncType::Selector(selector) = function;
 
     let (encoded_data, output_param) =
-        prepare_contract_call_data(&unified_program_abi, &selector, &function_args)?;
+        prepare_contract_call_data(&abi.unified, &selector, &function_args)?;
 
     // Setup connection to node
     let (wallet, tx_policies, base_asset_id) = super::setup_connection(&node, caller, &gas).await?;
@@ -84,8 +84,10 @@ pub async fn call_function(
 
     // Setup variable output policy and log decoder
     let variable_output_policy = VariableOutputPolicy::Exactly(call_parameters.amount as usize);
-    let error_codes = unified_program_abi
+    let error_codes = abi
+        .unified
         .error_codes
+        .as_ref()
         .map_or(HashMap::new(), |error_codes| {
             error_codes
                 .iter()
@@ -193,7 +195,7 @@ pub async fn call_function(
     };
 
     // Display the script JSON when verbosity level is 2 or higher (vv)
-    let script = if cmd.verbosity >= 2 {
+    let script_json = if cmd.verbosity >= 2 {
         let script_json = serde_json::to_value(&script).unwrap();
         forc_tracing::println_label_green(
             "transaction script:\n",
@@ -204,10 +206,28 @@ pub async fn call_function(
         None
     };
 
+    let abi_map = HashMap::from([(contract_id, abi)]);
+
     // Process transaction results
-    let receipts = tx_status
-        .take_receipts_checked(Some(&log_decoder))
-        .map_err(|e| anyhow!("Failed to take receipts: {e}"))?;
+    let receipts = match tx_status.clone().take_receipts_checked(Some(&log_decoder)) {
+        Ok(receipts) => receipts,
+        Err(e) => {
+            // Print receipts when an error occurs and verbosity is high enough
+            super::print_receipts_and_trace(
+                tx_status.total_gas(),
+                &tx_status.clone().take_receipts(),
+                cmd.verbosity,
+                &abi_map,
+                &mut output,
+            )?;
+            match tx_status {
+                TxStatus::Failure(e) | TxStatus::PreconfirmationFailure(e) => {
+                    bail!("Failed to process transaction; reason: {:#?}", e.reason);
+                }
+                _ => bail!("Failed to process transaction: {:#?}", e),
+            }
+        }
+    };
 
     // Parse the result based on output format
     let mut receipt_parser = ReceiptParser::new(&receipts, DecoderConfig::default());
@@ -230,18 +250,21 @@ pub async fn call_function(
     };
 
     // Process and return the final output
-    let program_abi = sway_core::asm_generation::ProgramABI::Fuel(parsed_abi);
     let mut call_response = super::process_transaction_output(
-        &receipts,
+        tx_status,
         &tx_hash.to_string(),
-        &program_abi,
-        Some(result),
         &mode,
         &node,
         cmd.verbosity,
+        &mut output,
+        Some(CallData {
+            contract_id,
+            abis: abi_map,
+            result,
+        }),
     )?;
     if cmd.verbosity >= 2 {
-        call_response.script = script;
+        call_response.script_json = script_json;
     }
 
     Ok(call_response)
@@ -855,7 +878,7 @@ pub mod tests {
             .await
             .unwrap_err()
             .to_string()
-            .contains("PanicInstruction { reason: NotEnoughBalance"));
+            .contains("Failed to process transaction; reason: \"NotEnoughBalance\""));
         assert_eq!(get_contract_balance(id, provider.clone()).await, 1);
 
         // contract call transfer funds to another address