hardhat 3.2.0 → 3.3.0

package/src/internal/builtin-plugins/network-manager/edr/edr-provider.ts

@@ -15,23 +15,17 @@ import type {
 import type { RequireField } from "../../../../types/utils.js";
 import type { DefaultHDAccountsConfigParams } from "../accounts/constants.js";
 import type { JsonRpcRequestWrapperFunction } from "../network-manager.js";
+import type { TraceOutputManager } from "./utils/trace-output.js";
 import type {
   SubscriptionEvent,
   Response,
   Provider,
   ProviderConfig,
   TracingConfigWithBuffers,
-  AccountOverride,
   GasReportConfig,
 } from "@nomicfoundation/edr";
 
-import {
-  opGenesisState,
-  opHardforkFromString,
-  l1GenesisState,
-  l1HardforkFromString,
-  ContractDecoder,
-} from "@nomicfoundation/edr";
+import { ContractDecoder, IncludeTraces } from "@nomicfoundation/edr";
 import {
   assertHardhatInvariant,
   HardhatError,
@@ -41,14 +35,9 @@ import { ensureError } from "@nomicfoundation/hardhat-utils/error";
 import { numberToHexString } from "@nomicfoundation/hardhat-utils/hex";
 import { deepEqual } from "@nomicfoundation/hardhat-utils/lang";
 import debug from "debug";
-import { hexToBytes } from "ethereum-cryptography/utils";
-import { addr } from "micro-eth-signer";
 
 import { sendErrorTelemetry } from "../../../cli/telemetry/sentry/reporter.js";
-import {
-  EDR_NETWORK_REVERT_SNAPSHOT_EVENT,
-  OPTIMISM_CHAIN_TYPE,
-} from "../../../constants.js";
+import { EDR_NETWORK_REVERT_SNAPSHOT_EVENT } from "../../../constants.js";
 import { hardhatChainTypeToEdrChainType } from "../../../edr/chain-type.js";
 import { getGlobalEdrContext } from "../../../edr/context.js";
 import { DEFAULT_HD_ACCOUNTS_CONFIG_PARAMS } from "../accounts/constants.js";
@@ -60,6 +49,7 @@ import {
   UnknownError,
 } from "../provider-errors.js";
 
+import { getGenesisStateAndOwnedAccounts } from "./genesis-state.js";
 import { EdrProviderStackTraceGenerationError } from "./stack-traces/stack-trace-generation-errors.js";
 import { createSolidityErrorWithStackTrace } from "./stack-traces/stack-trace-solidity-errors.js";
 import { isEdrProviderErrorData } from "./type-validation.js";
@@ -69,7 +59,6 @@ import {
   hardhatMiningIntervalToEdrMiningInterval,
   hardhatMempoolOrderToEdrMineOrdering,
   hardhatHardforkToEdrSpecId,
-  hardhatAccountsToEdrOwnedAccounts,
   hardhatForkingConfigToEdrForkConfig,
 } from "./utils/convert-to-edr.js";
 import { printLine, replaceLastLine } from "./utils/logger.js";
@@ -135,10 +124,14 @@ interface EdrProviderConfig {
   chainDescriptors: ChainDescriptorsConfig;
   networkConfig: RequireField<EdrNetworkConfig, "chainType">;
   loggerConfig?: LoggerConfig;
-  tracingConfig?: TracingConfigWithBuffers;
+  contractDecoder: ContractDecoder;
   jsonRpcRequestWrapper?: JsonRpcRequestWrapperFunction;
   coverageConfig?: CoverageConfig;
   gasReportConfig?: GasReportConfig;
+  includeCallTraces?: IncludeTraces;
+  connectionId: number;
+  networkName: string;
+  verbosity: number;
 }
 
 export class EdrProvider extends BaseProvider {
@@ -146,6 +139,13 @@ export class EdrProvider extends BaseProvider {
 
   #provider: Provider | undefined;
   #nextRequestId = 1;
+  readonly #traceOutput: TraceOutputManager | undefined;
+
+  public static async createContractDecoder(
+    tracingConfig: TracingConfigWithBuffers,
+  ): Promise<ContractDecoder> {
+    return ContractDecoder.withContracts(tracingConfig);
+  }
 
   /**
    * Creates a new instance of `EdrProvider`.
@@ -154,10 +154,14 @@ export class EdrProvider extends BaseProvider {
     chainDescriptors,
     networkConfig,
     loggerConfig = { enabled: false },
-    tracingConfig = {},
+    contractDecoder,
     jsonRpcRequestWrapper,
     coverageConfig,
     gasReportConfig,
+    includeCallTraces,
+    verbosity,
+    connectionId,
+    networkName,
   }: EdrProviderConfig): Promise<EdrProvider> {
     const printLineFn = loggerConfig.printLineFn ?? printLine;
     const replaceLastLineFn = loggerConfig.replaceLastLineFn ?? replaceLastLine;
@@ -167,15 +171,18 @@ export class EdrProvider extends BaseProvider {
       coverageConfig,
       gasReportConfig,
       chainDescriptors,
+      includeCallTraces,
     );
 
     let edrProvider: EdrProvider;
 
+    // We use a WeakRef to the provider to prevent the subscriptionCallback
+    // below from creating a cycle and leaking the provider.
+    let edrProviderWeakRef: WeakRef<EdrProvider> | undefined;
+
     // We need to catch errors here, as the provider creation can panic unexpectedly,
     // and we want to make sure such a crash is propagated as a ProviderError.
     try {
-      const contractDecoder = ContractDecoder.withContracts(tracingConfig);
-
       const context = await getGlobalEdrContext();
       const provider = await context.createProvider(
         hardhatChainTypeToEdrChainType(networkConfig.chainType),
@@ -199,13 +206,38 @@ export class EdrProvider extends BaseProvider {
         },
         {
           subscriptionCallback: (event: SubscriptionEvent) => {
-            edrProvider.onSubscriptionEvent(event);
+            const deferredProvider = edrProviderWeakRef?.deref();
+            if (deferredProvider !== undefined) {
+              deferredProvider.onSubscriptionEvent(event);
+            }
           },
         },
         contractDecoder,
       );
 
-      edrProvider = new EdrProvider(provider, jsonRpcRequestWrapper);
+      const tracesEnabled =
+        includeCallTraces !== undefined &&
+        includeCallTraces !== IncludeTraces.None;
+
+      let traceOutput: TraceOutputManager | undefined;
+      if (tracesEnabled) {
+        const { TraceOutputManager: TraceOutputManagerImpl } = await import(
+          "./utils/trace-output.js"
+        );
+        traceOutput = new TraceOutputManagerImpl(
+          printLineFn,
+          connectionId,
+          networkName,
+          verbosity,
+        );
+      }
+
+      edrProvider = new EdrProvider(
+        provider,
+        traceOutput,
+        jsonRpcRequestWrapper,
+      );
+      edrProviderWeakRef = new WeakRef(edrProvider);
     } catch (error) {
       ensureError(error);
 
@@ -225,12 +257,22 @@ export class EdrProvider extends BaseProvider {
    */
   private constructor(
     provider: Provider,
+    traceOutput: TraceOutputManager | undefined,
     jsonRpcRequestWrapper?: JsonRpcRequestWrapperFunction,
   ) {
     super();
 
     this.#provider = provider;
+    this.#traceOutput = traceOutput;
     this.#jsonRpcRequestWrapper = jsonRpcRequestWrapper;
+
+    // After a snapshot revert, the same transactions may run again.
+    // Reset traced hashes so their traces are printed a second time.
+    if (this.#traceOutput !== undefined) {
+      this.on(EDR_NETWORK_REVERT_SNAPSHOT_EVENT, () => {
+        this.#traceOutput?.clearTracedHashes();
+      });
+    }
   }
 
   public async request(
@@ -290,8 +332,10 @@ export class EdrProvider extends BaseProvider {
   }
 
   public async close(): Promise<void> {
+    this.removeAllListeners();
     // Clear the provider reference to help with garbage collection
     this.#provider = undefined;
+    this.#traceOutput?.clearTracedHashes();
   }
 
   public async addCompilationResult(
@@ -312,8 +356,11 @@ export class EdrProvider extends BaseProvider {
 
   async #handleEdrResponse(
     edrResponse: Response,
+    method: string,
+    params?: unknown[],
   ): Promise<SuccessfulJsonRpcResponse> {
     let jsonRpcResponse: JsonRpcResponse;
+    let txHash: string | undefined;
 
     if (typeof edrResponse.data === "string") {
       jsonRpcResponse = JSON.parse(edrResponse.data);
@@ -325,6 +372,12 @@ export class EdrProvider extends BaseProvider {
       const responseError = jsonRpcResponse.error;
       let error;
 
+      // Grab the tx hash so trace deduplication can recognize this transaction later
+      const errorData = responseError.data;
+      if (isEdrProviderErrorData(errorData)) {
+        txHash = errorData.transactionHash;
+      }
+
       const stackTrace = edrResponse.stackTrace();
 
       if (stackTrace?.kind === "StackTrace") {
@@ -365,11 +418,33 @@ export class EdrProvider extends BaseProvider {
         error.data = responseError.data;
       }
 
+      this.#traceOutput?.outputCallTraces(edrResponse, method, txHash, true);
+
       /* eslint-disable-next-line no-restricted-syntax -- we may throw
       non-Hardhat errors inside of an EthereumProvider */
       throw error;
     }
 
+    if (this.#traceOutput !== undefined) {
+      // Output call traces for successful responses. The tx hash is resolved
+      // from the response/params so the trace manager can deduplicate.
+
+      if (
+        method === "eth_sendTransaction" ||
+        method === "eth_sendRawTransaction"
+      ) {
+        txHash =
+          typeof jsonRpcResponse.result === "string"
+            ? jsonRpcResponse.result
+            : undefined;
+      } else if (method === "eth_getTransactionReceipt") {
+        // params[0] is the tx hash being queried — used to dedup receipt polling
+        txHash = typeof params?.[0] === "string" ? params[0] : undefined;
+      }
+
+      this.#traceOutput.outputCallTraces(edrResponse, method, txHash, false);
+    }
+
     return jsonRpcResponse;
   }
 
@@ -421,7 +496,11 @@ export class EdrProvider extends BaseProvider {
       throw new UnknownError(error.message, error);
     }
 
-    return this.#handleEdrResponse(edrResponse);
+    return this.#handleEdrResponse(
+      edrResponse,
+      request.method,
+      Array.isArray(request.params) ? request.params : undefined,
+    );
   }
 }
 
@@ -430,49 +509,20 @@ export async function getProviderConfig(
   coverageConfig: CoverageConfig | undefined,
   gasReportConfig: GasReportConfig | undefined,
   chainDescriptors: ChainDescriptorsConfig,
+  includeCallTraces?: IncludeTraces,
 ): Promise<ProviderConfig> {
   const specId = hardhatHardforkToEdrSpecId(
     networkConfig.hardfork,
     networkConfig.chainType,
   );
 
-  const ownedAccounts = await hardhatAccountsToEdrOwnedAccounts(
+  const { genesisState, ownedAccounts } = await getGenesisStateAndOwnedAccounts(
     networkConfig.accounts,
+    networkConfig.forking,
+    networkConfig.chainType,
+    specId,
   );
 
-  const genesisState: Map<Uint8Array, AccountOverride> = new Map(
-    ownedAccounts.map(({ secretKey, balance }) => {
-      const address = hexToBytes(addr.fromPrivateKey(secretKey));
-      const accountOverride: AccountOverride = {
-        address,
-        balance: BigInt(balance),
-        code: new Uint8Array(), // Empty account code, removing potential delegation code when forking
-      };
-
-      return [address, accountOverride];
-    }),
-  );
-
-  const chainGenesisState =
-    networkConfig.forking !== undefined
-      ? [] // TODO: Add support for overriding remote fork state when the local fork is different
-      : networkConfig.chainType === OPTIMISM_CHAIN_TYPE
-        ? opGenesisState(opHardforkFromString(specId))
-        : l1GenesisState(l1HardforkFromString(specId));
-
-  for (const account of chainGenesisState) {
-    const existingOverride = genesisState.get(account.address);
-    if (existingOverride !== undefined) {
-      // Favor the genesis state specified by the user
-      account.balance = account.balance ?? existingOverride.balance;
-      account.nonce = account.nonce ?? existingOverride.nonce;
-      account.code = account.code ?? existingOverride.code;
-      account.storage = account.storage ?? existingOverride.storage;
-    } else {
-      genesisState.set(account.address, account);
-    }
-  }
-
   return {
     allowBlocksWithSameTimestamp: networkConfig.allowBlocksWithSameTimestamp,
     allowUnlimitedContractSize: networkConfig.allowUnlimitedContractSize,
@@ -506,6 +556,7 @@ export async function getProviderConfig(
     observability: {
       codeCoverage: coverageConfig,
       gasReport: gasReportConfig,
+      includeCallTraces,
     },
     ownedAccounts: ownedAccounts.map((account) => account.secretKey),
     precompileOverrides: [],

package/src/internal/builtin-plugins/network-manager/edr/genesis-state.ts

@@ -0,0 +1,179 @@
+import type {
+  EdrNetworkAccountsConfig,
+  EdrNetworkForkingConfig,
+} from "../../../../types/config.js";
+import type { ChainType } from "../../../../types/network.js";
+import type * as MicroEthSignerAddressT from "micro-eth-signer/address";
+
+import {
+  l1GenesisState,
+  l1HardforkFromString,
+  opGenesisState,
+  opHardforkFromString,
+  type AccountOverride,
+} from "@nomicfoundation/edr";
+import { AsyncMutex } from "@nomicfoundation/hardhat-utils/synchronization";
+import { hexToBytes } from "ethereum-cryptography/utils";
+
+import { OPTIMISM_CHAIN_TYPE } from "../../../constants.js";
+
+import { hardhatAccountsToEdrOwnedAccounts } from "./utils/convert-to-edr.js";
+
+// micro-eth-signer is known to be slow to load, so we lazy load it
+let microEthSignerAddress: typeof MicroEthSignerAddressT | undefined;
+
+const noForkingConfigCacheMarkerObject = {};
+
+/**
+ * We cache the genesis state and owned accounts because computing them can be
+ * expensive, especially when run multiple times for the same configuration
+ * (e.g. when creating many EDR connections to the same network config).
+ *
+ * We use mostly references as cache keys, which means that we can miss some
+ * cache hits if an equivalent config is used with a different reference, but
+ * in practice this should rarely happen, except when using network config
+ * overrides that generate the same config. These cases should be the minority
+ * within a test suite.
+ *
+ * Note: the main reason that we don't use the entire NetworkConfig as cache
+ * key is that EDR initialization path recreates the NetworkConfig object to
+ * override some properties like `allowUnlimitedContractSize`, leading to a
+ * different NetworkConfig reference, despite keeping the references of most
+ * of its properties (including the accounts and forking config) the same.
+ */
+const genesisStateAndAccountsCache: WeakMap<
+  EdrNetworkAccountsConfig,
+  WeakMap<
+    EdrNetworkForkingConfig | typeof noForkingConfigCacheMarkerObject,
+    Map<
+      ChainType,
+      Map<
+        string,
+        {
+          genesisState: Map<Uint8Array, AccountOverride>;
+          ownedAccounts: Array<{ secretKey: string; balance: bigint }>;
+        }
+      >
+    >
+  >
+> = new WeakMap();
+
+const genesisStateAndAccountsCacheMutex = new AsyncMutex();
+
+export async function getGenesisStateAndOwnedAccounts(
+  accountsConfig: EdrNetworkAccountsConfig,
+  forkingConfig: EdrNetworkForkingConfig | undefined,
+  chainType: ChainType,
+  specId: string,
+): Promise<{
+  genesisState: Map<Uint8Array, AccountOverride>;
+  ownedAccounts: Array<{ secretKey: string; balance: bigint }>;
+}> {
+  const cached = genesisStateAndAccountsCache
+    .get(accountsConfig)
+    ?.get(forkingConfig ?? noForkingConfigCacheMarkerObject)
+    ?.get(chainType)
+    ?.get(specId);
+
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  return genesisStateAndAccountsCacheMutex.exclusiveRun(async () => {
+    // We need to check again inside the mutex callback in case another async
+    // operation initialized it while we were waiting to acquire the mutex
+    const cachedAfterWaiting = genesisStateAndAccountsCache
+      .get(accountsConfig)
+      ?.get(forkingConfig ?? noForkingConfigCacheMarkerObject)
+      ?.get(chainType)
+      ?.get(specId);
+
+    if (cachedAfterWaiting !== undefined) {
+      return cachedAfterWaiting;
+    }
+
+    const result = await createGenesisStateAndOwnedAccounts(
+      accountsConfig,
+      forkingConfig,
+      chainType,
+      specId,
+    );
+
+    let secondLevelCacheMap = genesisStateAndAccountsCache.get(accountsConfig);
+    if (secondLevelCacheMap === undefined) {
+      secondLevelCacheMap = new WeakMap();
+      genesisStateAndAccountsCache.set(accountsConfig, secondLevelCacheMap);
+    }
+
+    const forkingConfigCacheKey =
+      forkingConfig ?? noForkingConfigCacheMarkerObject;
+    let thirdLevelCacheMap = secondLevelCacheMap.get(forkingConfigCacheKey);
+    if (thirdLevelCacheMap === undefined) {
+      thirdLevelCacheMap = new Map();
+      secondLevelCacheMap.set(forkingConfigCacheKey, thirdLevelCacheMap);
+    }
+
+    let fourthLevelCacheMap = thirdLevelCacheMap.get(chainType);
+    if (fourthLevelCacheMap === undefined) {
+      fourthLevelCacheMap = new Map();
+      thirdLevelCacheMap.set(chainType, fourthLevelCacheMap);
+    }
+
+    fourthLevelCacheMap.set(specId, result);
+
+    return result;
+  });
+}
+
+async function createGenesisStateAndOwnedAccounts(
+  accountsConfig: EdrNetworkAccountsConfig,
+  forkingConfig: EdrNetworkForkingConfig | undefined,
+  chainType: ChainType,
+  specId: string,
+): Promise<{
+  genesisState: Map<Uint8Array, AccountOverride>;
+  ownedAccounts: Array<{ secretKey: string; balance: bigint }>;
+}> {
+  if (microEthSignerAddress === undefined) {
+    microEthSignerAddress = await import("micro-eth-signer/address");
+  }
+
+  const { addr } = microEthSignerAddress;
+
+  const ownedAccounts = await hardhatAccountsToEdrOwnedAccounts(accountsConfig);
+
+  const genesisState: Map<Uint8Array, AccountOverride> = new Map(
+    ownedAccounts.map(({ secretKey, balance }) => {
+      const address = hexToBytes(addr.fromPrivateKey(secretKey));
+      const accountOverride: AccountOverride = {
+        address,
+        balance: BigInt(balance),
+        code: new Uint8Array(), // Empty account code, removing potential delegation code when forking
+      };
+
+      return [address, accountOverride];
+    }),
+  );
+
+  const chainGenesisState =
+    forkingConfig !== undefined
+      ? [] // TODO: Add support for overriding remote fork state when the local fork is different
+      : chainType === OPTIMISM_CHAIN_TYPE
+        ? opGenesisState(opHardforkFromString(specId))
+        : l1GenesisState(l1HardforkFromString(specId));
+
+  for (const account of chainGenesisState) {
+    const existingOverride = genesisState.get(account.address);
+    if (existingOverride !== undefined) {
+      // Favor the genesis state specified by the user
+      account.balance = account.balance ?? existingOverride.balance;
+      account.nonce = account.nonce ?? existingOverride.nonce;
+      account.code = account.code ?? existingOverride.code;
+      account.storage = account.storage ?? existingOverride.storage;
+    } else {
+      genesisState.set(account.address, account);
+    }
+  }
+
+  return { genesisState, ownedAccounts };
+}

package/src/internal/builtin-plugins/network-manager/edr/utils/trace-formatters.ts

@@ -0,0 +1,197 @@
+import type { Colorizer } from "../../../../utils/colorizer.js";
+import type {
+  LogTrace,
+  CallTrace,
+  DecodedTraceParameters,
+} from "@nomicfoundation/edr";
+
+import { LogKind, CallKind, IncludeTraces } from "@nomicfoundation/edr";
+import { bytesToHexString } from "@nomicfoundation/hardhat-utils/hex";
+
+type NestedArray<T> = Array<T | NestedArray<T>>;
+
+export function verbosityToIncludeTraces(verbosity: number): IncludeTraces {
+  if (verbosity >= 4) {
+    return IncludeTraces.All;
+  } else if (verbosity >= 3) {
+    return IncludeTraces.Failing;
+  }
+
+  return IncludeTraces.None;
+}
+
+export function formatTraces(
+  traces: CallTrace[],
+  prefix: string,
+  colorizer: Colorizer,
+): string {
+  const lines = traces.map((trace) => formatTrace(trace, colorizer));
+  const formattedTraces = formatNestedArray(lines, prefix);
+  // Remove the trailing newline
+  return formattedTraces.slice(0, -1);
+}
+
+function formatInputs(
+  inputs: DecodedTraceParameters | Uint8Array,
+  color?: (text: string) => string,
+): string | undefined {
+  if (inputs instanceof Uint8Array) {
+    return inputs.length > 0 ? bytesToHexString(inputs) : undefined;
+  } else {
+    const formattedName =
+      color !== undefined ? color(inputs.name) : inputs.name;
+    return `${formattedName}(${inputs.arguments.join(", ")})`;
+  }
+}
+
+function formatOutputs(outputs: string | Uint8Array): string | undefined {
+  if (outputs instanceof Uint8Array) {
+    return outputs.length > 0 ? bytesToHexString(outputs) : undefined;
+  } else {
+    return outputs;
+  }
+}
+
+function formatLog(log: LogTrace, colorizer: Colorizer): string[] {
+  const { parameters } = log;
+  const tag = colorizer.yellow("[event]");
+  const lines = [];
+
+  if (Array.isArray(parameters)) {
+    const hexValues = parameters.map((bytes) => bytesToHexString(bytes));
+    const topicCount = hexValues.length - 1;
+
+    for (let i = 0; i < topicCount; i++) {
+      const prefix = i === 0 ? `${tag} topic 0` : `        topic ${i}`;
+      lines.push(`${prefix}: ${colorizer.cyan(hexValues[i])}`);
+    }
+
+    if (hexValues.length > 0) {
+      const dataPrefix = topicCount > 0 ? "           data" : `${tag}    data`;
+      lines.push(
+        `${dataPrefix}: ${colorizer.cyan(hexValues[hexValues.length - 1])}`,
+      );
+    }
+  } else {
+    lines.push(
+      `${tag} ${parameters.name}(${colorizer.cyan(parameters.arguments.join(", "))})`,
+    );
+  }
+  return lines;
+}
+
+function formatTrace(
+  trace: CallTrace,
+  colorizer: Colorizer,
+): NestedArray<string> {
+  const {
+    success,
+    address,
+    contract,
+    inputs,
+    gasUsed,
+    value,
+    kind,
+    isCheatcode,
+    outputs,
+  } = trace;
+  let color;
+  if (isCheatcode) {
+    color = colorizer.blue;
+  } else if (success) {
+    color = colorizer.green;
+  } else {
+    color = colorizer.red;
+  }
+
+  const formattedInputs = formatInputs(inputs, color);
+  const formattedOutputs = formatOutputs(outputs);
+
+  let openingLine: string;
+  let closingLine: string | undefined;
+  if (kind === CallKind.Create) {
+    openingLine = `[${gasUsed}] ${colorizer.yellow("→ new")} ${contract ?? "<unknown>"}@${address}`;
+    // TODO: Uncomment this when the formattedInputs starts containing
+    // the address of where the contract was deployed instead of the code.
+    // if (formattedInputs !== undefined) {
+    //   openingLine = `${openingLine}@${formattedInputs}`;
+    // }
+  } else {
+    openingLine = `[${gasUsed}] ${color(contract ?? address)}`;
+    if (formattedInputs !== undefined) {
+      openingLine = `${openingLine}::${formattedInputs}`;
+    }
+    if (value !== 0n) {
+      openingLine = `${openingLine} {value: ${value}}`;
+    }
+    if (kind === CallKind.StaticCall) {
+      openingLine = `${openingLine} ${colorizer.yellow("[staticcall]")}`;
+    } else if (kind === CallKind.DelegateCall) {
+      openingLine = `${openingLine} ${colorizer.yellow("[delegatecall]")}`;
+    } else if (kind === CallKind.CallCode) {
+      openingLine = `${openingLine} ${colorizer.yellow("[callcode]")}`;
+    }
+  }
+  if (formattedOutputs !== undefined) {
+    if (
+      formattedOutputs === "EvmError: Revert" ||
+      formattedOutputs.startsWith("revert:")
+    ) {
+      closingLine = `${color("←")} ${color("[Revert]")} ${formattedOutputs}`;
+    } else {
+      closingLine = `${color("←")} ${formattedOutputs}`;
+    }
+  }
+
+  const lines = [];
+  lines.push(openingLine);
+  for (const child of trace.children) {
+    if (child.kind === LogKind.Log) {
+      lines.push(formatLog(child, colorizer));
+    } else {
+      lines.push(formatTrace(child, colorizer));
+    }
+  }
+  if (closingLine !== undefined) {
+    lines.push([closingLine]);
+  }
+  return lines;
+}
+
+function formatNestedArray(
+  data: NestedArray<string>,
+  prefix = "",
+  isTopLevel = true,
+): string {
+  let output = "";
+
+  for (let i = 0; i < data.length; i++) {
+    const item = data[i];
+
+    if (Array.isArray(item) && typeof item[0] === "string") {
+      const [label, ...children] = item;
+
+      if (isTopLevel) {
+        // Blank line between top-level traces
+        if (i > 0) {
+          output += "\n";
+        }
+
+        output += `${prefix}${label}\n`;
+        output += formatNestedArray(children, prefix, false);
+      } else {
+        const isLast = i === data.length - 1;
+        const connector = isLast ? "  └─ " : "  ├─ ";
+        const childPrefix = isLast ? "     " : "  │  ";
+        output += `${prefix}${connector}${label}\n`;
+        output += formatNestedArray(children, prefix + childPrefix, false);
+      }
+    } else if (typeof item === "string") {
+      const isLast = i === data.length - 1;
+      const connector = isLast ? "  └─ " : "  ├─ ";
+      output += `${prefix}${connector}${item}\n`;
+    }
+  }
+
+  return output;
+}