@diamondslab/diamonds 1.0.0

package/src/utils/diffDeployedFacets.ts

@@ -0,0 +1,131 @@
+import { Fragment, Interface, JsonFragment } from "@ethersproject/abi";
+import { Signer } from "@ethersproject/abstract-signer";
+import chalk from "chalk";
+import { JsonRpcProvider } from "ethers";
+import { DeployedDiamondData } from "../schemas";
+import { getDeployedFacets } from "./loupe";
+
+export async function diffDeployedFacets(
+  deployedDiamondData: DeployedDiamondData,
+  signerOrProvider: Signer | JsonRpcProvider,
+  verboseGetDeployedFacets?: boolean,
+): Promise<boolean> {
+  const diamondAddress = deployedDiamondData.DiamondAddress!;
+  const onChainFacets = await getDeployedFacets(diamondAddress, signerOrProvider as any, undefined, verboseGetDeployedFacets);
+
+  const localFacets = deployedDiamondData.DeployedFacets ?? {};
+
+  const seen = new Set<string>();
+
+  let pass: boolean = true;
+
+  console.log(chalk.magentaBright("\n🔍 Diffing on-chain facets against deployment metadata:\n"));
+
+  for (const facet of onChainFacets) {
+    const match = Object.entries(localFacets).find(([_, meta]) => meta.address?.toLowerCase() === facet.facetAddress.toLowerCase());
+    if (!match) {
+      console.log(chalk.red(`  ❌ On-chain facet ${facet.facetAddress} not found in deployment record.`));
+      continue;
+    }
+
+    const [name, meta] = match;
+    seen.add(name);
+
+    const expected = meta.funcSelectors ?? [];
+    const actual = facet.functionSelectors;
+
+    const added: string[] = actual.filter((sel: string) => !expected.includes(sel));
+    const removed = expected.filter(sel => !actual.includes(sel));
+
+    if (added.length ?? removed.length) {
+      console.log(chalk.yellow(`  ⚠️ Mismatch in selectors for facet ${name} (${facet.facetAddress})`));
+      if (added.length) console.log(chalk.green(`    + Added: ${added.join(", ")}`));
+      if (removed.length) console.log(chalk.red(`    - Missing: ${removed.join(", ")}`));
+    } else {
+      console.log(chalk.green(`  ✅ ${name} matches.`));
+    }
+  }
+
+  for (const localFacetName of Object.keys(localFacets)) {
+    if (pass && !seen.has(localFacetName)) {
+      console.log(chalk.red(`  ❌ Deployed facet ${localFacetName} missing from on-chain state.`));
+      pass = false;
+    }
+  }
+  if (pass) {
+    console.log(chalk.bgGreenBright("  ✅ All facets exist in deplyoment metadata!"));
+  } else {
+    console.log(chalk.bgRed("  ❌ Some facets do not match!"));
+  }
+  return pass;
+}
+
+export function printFacetSelectorFunctions(abi: readonly (string | Fragment | JsonFragment)[], selectors: string[]) {
+  const iface = new Interface(abi);
+
+  console.log(chalk.cyan("\n🔎 Matching selectors to functions:"));
+  for (const selector of selectors) {
+    const fragment = Object.values(iface.functions).find(fn =>
+      iface.getSighash(fn) === selector
+    );
+    console.log(`  ${selector} → ${fragment ? fragment.format() : chalk.gray("unknown")}`);
+  }
+}
+
+export async function isProtocolInitRegistered(
+  deployedDiamondData: DeployedDiamondData,
+  protocolInitFacet: string,
+  initializerSig: string
+): Promise<boolean> {
+  const facet = deployedDiamondData.DeployedFacets?.[protocolInitFacet];
+  console.log(`Checking if ${protocolInitFacet} is registered with ${initializerSig}...`);
+
+  if (!facet || !facet.funcSelectors) return false;
+  if (!initializerSig) {
+    console.warn(chalk.yellow(`  ❌ No initializer signature provided for ${protocolInitFacet}.`));
+    return false;
+  }
+  const iface = new Interface([`function ${initializerSig}`]);
+  const selector = iface.getSighash(initializerSig);
+  console.log(`  Found selector: ${selector}`);
+  return facet.funcSelectors.includes(selector);
+}
+
+/**
+ * Compares facet selectors from on-chain DiamondLoupe with local DeployedDiamondData
+ *
+ * @param deployedFacetData - local metadata (facetName -> { address, funcSelectors[] })
+ * @param onChainFacets - list of { facetAddress, functionSelectors[] } from DiamondLoupe
+ * @returns map of facetName -> { extraOnChain[], missingOnChain[], matched[] }
+ */
+export function compareFacetSelectors(
+  deployedFacetData: Record<string, { address?: string; funcSelectors?: string[] }>,
+  onChainFacets: { facetAddress: string; functionSelectors: string[] }[]
+) {
+  const result: Record<string, {
+    extraOnChain: string[];
+    missingOnChain: string[];
+    matched: string[];
+  }> = {};
+
+  const addressToName = Object.entries(deployedFacetData).reduce((acc, [name, meta]) => {
+    if (meta.address) acc[meta.address.toLowerCase()] = name;
+    return acc;
+  }, {} as Record<string, string>);
+
+  for (const { facetAddress, functionSelectors } of onChainFacets) {
+    const lowerAddr = facetAddress.toLowerCase();
+    const name = addressToName[lowerAddr] ?? "unknown";
+
+    const expected = new Set(deployedFacetData[name]?.funcSelectors ?? []);
+    const actual = new Set(functionSelectors);
+
+    result[name] = {
+      extraOnChain: [...actual].filter(sel => !expected.has(sel)).sort(),
+      missingOnChain: [...expected].filter(sel => !actual.has(sel)).sort(),
+      matched: [...actual].filter(sel => expected.has(sel)).sort(),
+    };
+  }
+
+  return result;
+}

package/src/utils/index.ts

@@ -0,0 +1,15 @@
+export * from '../repositories/jsonFileHandler';
+export { FileDeploymentRepository } from '../repositories/FileDeploymentRepository';
+export { DeploymentRepository } from '../repositories/DeploymentRepository';
+export * from './common';
+export * from './signer';
+export * from './txlogging';
+export * from './diffDeployedFacets';
+export * from './loupe';
+export * from './defenderStore';
+export * from './defenderClients';
+export * from './contractMapping';
+export * from './configurationResolver';
+export * from './workspaceSetup';
+export * from './diamondAbiGenerator';
+export * from './rpcStore';

package/src/utils/loupe.ts

@@ -0,0 +1,159 @@
+import '@nomicfoundation/hardhat-ethers';
+import chalk from "chalk";
+import { Contract, ContractTransactionResponse, Interface, InterfaceAbi, Log, LogDescription, Provider, Signer, TransactionReceipt } from "ethers";
+import hre from "hardhat";
+import { logTx } from "./txlogging";
+
+/** ----------------------------------------------------------------
+ *  Minimal ABI for DiamondLoupeFacet.facets()
+ *  (tuple[] is encoded exactly the same as the struct array returned
+ *   by the real contract, so we can decode it safely.)
+ *  ----------------------------------------------------------------
+ */
+const DIAMOND_LOUPE_ABI = new Interface([
+  "function facets() view returns (tuple(address facetAddress, bytes4[] functionSelectors)[])"
+]);
+
+/** Optional convenience type for TS consumers (no TypeChain) */
+export interface FacetStruct {
+  facetAddress: string;
+  functionSelectors: string[];
+}
+
+// -----------------------------------------------------------------------------
+// logDiamondLoupe ­– decodes *events* that were emitted during a diamondCut()
+// -----------------------------------------------------------------------------
+/** 
+ * logDiamondLoupe
+ * • pretty‑prints the transaction receipt
+ * • decodes the logs emitted by the DiamondLoupeFacet
+ * • decodes the logs emitted by the facets that were passed in
+ *  (e.g. the facets that were added/removed)
+ * • prints the decoded events to the console
+ * • returns the transaction receipt
+ * @param tx               The awaited transaction object (e.g. from `contract.fn()`)
+ * @param diamondLoupe     Address of the diamond proxy
+ * @param facetABIs        One or more `ethers.Interface` (or plain ABIs) used to decode
+ *                         the `receipt.logs`.  Pass the primary contract interface first;
+ *                         additional ABIs (e.g. library or facet events) can follow.
+ *                         Pass an empty array if you don’t want to decode any facet events.
+ *                         (e.g. `[]`)
+ *                        (NB: this is not the same as the diamondLoupe address)
+ * @returns              The transaction receipt
+ */
+export async function logDiamondLoupe(
+  tx: ContractTransactionResponse,
+  diamondLoupe: string,
+  facetABIs: readonly (InterfaceAbi | Interface)[] = []
+): Promise<TransactionReceipt> {
+  const receipt = await logTx(tx, `DiamondLoupe (${diamondLoupe})`, facetABIs.map(abi => abi instanceof Interface ? abi : new Interface(abi)));
+
+  const iface = Array.isArray(facetABIs) && facetABIs.length
+    ? new Interface(
+      facetABIs.map(i => (i instanceof Interface ? i.fragments : i)).reduce((acc, val) => acc.concat(val), [])
+    )
+    : undefined;
+
+  console.log(chalk.cyan("\n📜 Decoded Loupe logs:"));
+  if (receipt && receipt.logs) {
+    receipt.logs.forEach((log: Log, idx: number) => {
+      if (!iface) {
+        console.log(chalk.dim(`  Event[${idx}] – no ABI supplied`));
+        return;
+      }
+
+      let parsed: LogDescription | undefined;
+      try {
+        const result = iface.parseLog(log);
+        if (result !== null) {
+          parsed = result;
+        }
+      } catch {
+        /* swallow – this log wasn’t emitted by any of the supplied facets */
+      }
+
+      if (parsed) {
+        const argsPretty = parsed.args
+          .map((arg: unknown, i: number) => `${parsed?.fragment.inputs[i].name}: ${arg}`)
+          .join(", ");
+
+        console.log(
+          chalk.yellowBright(`  Event[${idx}]`) +
+          chalk.bold(` ${parsed.name}`) +
+          `  →  ${argsPretty}`
+        );
+      } else {
+        console.log(
+          chalk.dim(`  Event[${idx}]`) + ` – unable to decode (topic0 = ${log.topics[0]})`
+        );
+      }
+    });
+
+    return receipt;
+  }
+
+  // Always return the receipt, even if logs are missing
+  if (!receipt) {
+    throw new Error("Transaction receipt is null");
+  }
+  return receipt;
+}
+
+/**
+ * Fetch the list of deployed facets from a diamond without relying on
+ * TypeChain’s IDiamondLoupe typings.
+ * getDeployedFacets – convenience wrapper around DiamondLoupe.facets()
+ * • fetches the facet list
+ * • pretty‑prints it
+ * • (optionally) calls logDiamondLoupe if you pass a receipt
+ *
+ * @param diamondAddress   Address of the diamond proxy
+ * @param signerOrProvider Signer (for tx) or provider (for read‑only)
+ * @param receiptToDecode  Optional transaction receipt to decode
+ *                         (e.g. from a diamondCut() transaction)
+ * @returns              Array of FacetStruct objects
+ *                       (address + functionSelectors)
+ *                       (see DiamondLoupeFacet.sol)
+ */
+export async function getDeployedFacets(
+  diamondAddress: string,
+  signerOrProvider: Signer | Provider = hre.ethers.provider,
+  receiptToDecode?: TransactionReceipt,
+  logDeployedFacets?: boolean, // default: assumed false
+): Promise<FacetStruct[]> {
+  // Generic ethers.Contract instance built only from the tiny ABI above
+  const loupe = new Contract(diamondAddress, DIAMOND_LOUPE_ABI, signerOrProvider);
+
+  // NB: cast is just to help TS‑users downstream; at runtime this is the raw array
+  const facets = (await loupe.facets()) as FacetStruct[];
+
+  if (logDeployedFacets === true) {
+    console.log(chalk.magentaBright("\n🔍 Currently deployed facets (via DiamondLoupe):"));
+    facets.forEach((f: { facetAddress: string; functionSelectors: string[] }, i: number) => {
+      console.log(chalk.blueBright(
+        `  [${i.toString().padStart(2, "0")}]  ${chalk.bold(f.facetAddress)}  –  ${f.functionSelectors.length
+        } selector${f.functionSelectors.length === 1 ? "" : "s"}`
+      ));
+      f.functionSelectors.forEach((s: string, j: number) => {
+        console.log(`    ${j.toString().padStart(2, "0")}:  ${s}`);
+      });
+      console.log();
+    });
+  }
+
+  // If the caller supplied a receipt from a recent diamondCut, decode it too
+  if (receiptToDecode) {
+    await logDiamondLoupe(
+      // fabricate a ContractTransaction‑like object so logDiamondLoupe
+      // can stay reception‑agnostic
+      {
+        ...receiptToDecode,
+        wait: async () => receiptToDecode,
+      } as unknown as ContractTransactionResponse,
+      diamondAddress,
+      [loupe.interface]
+    );
+  }
+
+  return facets;
+}

package/src/utils/rpcStore.ts

@@ -0,0 +1,152 @@
+import { join } from 'path';
+import * as fs from 'fs-extra';
+import { RPCDeploymentRegistry, RPCStepStatus, RPCStepRecord } from '../types/rpc';
+
+/**
+ * Step-by-step deployment store for RPC-based deployments
+ * Similar to DefenderDeploymentStore but for RPC deployments
+ */
+export class RPCDeploymentStore {
+  private readonly filePath: string;
+  private readonly diamondName: string;
+  private readonly deploymentId: string;
+
+  constructor(diamondName: string, deploymentId: string, baseDir: string = 'diamonds') {
+    this.diamondName = diamondName;
+    this.deploymentId = deploymentId;
+    const registryDir = join(baseDir, diamondName, 'deployments', 'rpc');
+    fs.ensureDirSync(registryDir);
+    this.filePath = join(registryDir, `${deploymentId}.json`);
+  }
+
+  private loadRegistry(): RPCDeploymentRegistry {
+    if (!fs.existsSync(this.filePath)) {
+      return {
+        diamondName: this.diamondName,
+        deploymentId: this.deploymentId,
+        network: '',
+        chainId: 0,
+        rpcUrl: '',
+        deployerAddress: '',
+        steps: [],
+        startedAt: Date.now(),
+        lastUpdated: Date.now()
+      };
+    }
+    return fs.readJSONSync(this.filePath);
+  }
+
+  private saveRegistry(registry: RPCDeploymentRegistry) {
+    registry.lastUpdated = Date.now();
+    fs.writeJSONSync(this.filePath, registry, { spaces: 2 });
+  }
+
+  public initializeDeployment(network: string, chainId: number, rpcUrl: string, deployerAddress: string): void {
+    const registry = this.loadRegistry();
+    registry.network = network;
+    registry.chainId = chainId;
+    registry.rpcUrl = rpcUrl;
+    registry.deployerAddress = deployerAddress;
+    this.saveRegistry(registry);
+  }
+
+  public saveStep(step: RPCStepRecord): void {
+    const registry = this.loadRegistry();
+    const existing = registry.steps.find(s => s.stepName === step.stepName);
+    if (existing) {
+      Object.assign(existing, step);
+    } else {
+      registry.steps.push(step);
+    }
+    this.saveRegistry(registry);
+  }
+
+  public getStep(stepName: string): RPCStepRecord | undefined {
+    return this.loadRegistry().steps.find(s => s.stepName === stepName);
+  }
+
+  public updateStatus(stepName: string, status: RPCStepStatus, txHash?: string, contractAddress?: string, error?: string): void {
+    const registry = this.loadRegistry();
+    const step = registry.steps.find(s => s.stepName === stepName);
+    if (step) {
+      step.status = status;
+      step.timestamp = Date.now();
+      if (txHash) step.txHash = txHash;
+      if (contractAddress) step.contractAddress = contractAddress;
+      if (error) step.error = error;
+      this.saveRegistry(registry);
+    }
+  }
+
+  public list(): RPCStepRecord[] {
+    return this.loadRegistry().steps;
+  }
+
+  public getRegistry(): RPCDeploymentRegistry {
+    return this.loadRegistry();
+  }
+
+  public isStepCompleted(stepName: string): boolean {
+    const step = this.getStep(stepName);
+    return step?.status === 'completed';
+  }
+
+  public isStepFailed(stepName: string): boolean {
+    const step = this.getStep(stepName);
+    return step?.status === 'failed';
+  }
+
+  public getCompletedSteps(): RPCStepRecord[] {
+    return this.list().filter(s => s.status === 'completed');
+  }
+
+  public getFailedSteps(): RPCStepRecord[] {
+    return this.list().filter(s => s.status === 'failed');
+  }
+
+  public getPendingSteps(): RPCStepRecord[] {
+    return this.list().filter(s => s.status === 'pending' || s.status === 'in_progress');
+  }
+
+  public markDeploymentComplete(): void {
+    const registry = this.loadRegistry();
+    registry.completedAt = Date.now();
+    this.saveRegistry(registry);
+  }
+
+  public markDeploymentFailed(error: string): void {
+    const registry = this.loadRegistry();
+    registry.failedAt = Date.now();
+    registry.lastError = error;
+    this.saveRegistry(registry);
+  }
+
+  public clearFailedSteps(): void {
+    const registry = this.loadRegistry();
+    registry.steps = registry.steps.filter(s => s.status !== 'failed');
+    this.saveRegistry(registry);
+  }
+
+  public getDeploymentSummary(): {
+    total: number;
+    completed: number;
+    failed: number;
+    pending: number;
+    isComplete: boolean;
+    hasFailed: boolean;
+  } {
+    const steps = this.list();
+    const completed = steps.filter(s => s.status === 'completed').length;
+    const failed = steps.filter(s => s.status === 'failed').length;
+    const pending = steps.filter(s => s.status === 'pending' || s.status === 'in_progress').length;
+    
+    return {
+      total: steps.length,
+      completed,
+      failed,
+      pending,
+      isComplete: failed === 0 && pending === 0 && completed > 0,
+      hasFailed: failed > 0
+    };
+  }
+}

package/src/utils/signer.ts

@@ -0,0 +1,93 @@
+import hre from 'hardhat';
+import { toWei } from './common';
+import { JsonRpcProvider, Signer } from 'ethers';
+import '@nomicfoundation/hardhat-ethers';
+import { HardhatEthersProvider } from '@nomicfoundation/hardhat-ethers/internal/hardhat-ethers-provider';
+
+/**
+ * Impersonates a signer account. This is primarily used in Hardhat's testing environment
+ * to simulate actions from accounts that are not part of the default test accounts.
+ *
+ * @param signerAddress - The address of the account to impersonate.
+ * @returns The impersonated signer object.
+ */
+export async function impersonateSigner(signerAddress: string, provider: JsonRpcProvider): Promise<Signer> {
+  // Request Hardhat to impersonate the account at the specified address
+  await provider.send("hardhat_impersonateAccount", [signerAddress]);
+  return provider.getSigner(signerAddress); // Return the impersonated signer
+}
+
+/**
+ * Sets the Ether balance for a specified address in the Hardhat testing environment.
+ * This is useful for ensuring test accounts have sufficient funds for transactions.
+ *
+ * @param address - The address to set the Ether balance for.
+ * @param amount - The desired balance as a `BigNumber`.
+ */
+export async function setEtherBalance(address: string, amount: bigint, provider: JsonRpcProvider) {
+  await provider.send('hardhat_setBalance', [
+    address, // Address to modify the balance of
+    '0x' + amount.toString(16), // Amount to set, formatted as a hex string
+  ]);
+}
+
+/**        
+ * Impersonates the deployer account and funds it to a balance that is rounded to the next highest 100 ETH.
+ * 
+ * @param provider - The ethers provider instance.
+ * @param deployerAddress - The address of the deployer account.
+ * @param balance - The balance to set for the deployer account (in hex format).
+ */
+export async function impersonateAndFundSigner(deployerAddress: string, provider: JsonRpcProvider | HardhatEthersProvider): Promise<Signer> {
+  try {
+    await provider.send('hardhat_impersonateAccount', [deployerAddress]);
+    const signer = provider.getSigner(deployerAddress);
+
+    // Fund the account
+    await provider.send('hardhat_setBalance', [deployerAddress, '0x56BC75E2D63100000']);
+    return signer;
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error(`Impersonation and funding failed for ${deployerAddress}: ${error.message}`);
+    } else {
+      console.error(`Impersonation and funding failed for ${deployerAddress}: ${String(error)}`);
+    }
+    throw error;
+  }
+}
+
+
+/**
+ * Updates the owner of the contract at the specified root address for testing purposes.
+ * This involves transferring ownership from the current owner to the default signer in the Hardhat environment.
+ *
+ * @param rootAddress - The address of the root contract (e.g., GeniusOwnershipFacet).
+ * @returns The address of the old owner.
+ */
+export const updateOwnerForTest = async (rootAddress: string, provider: JsonRpcProvider) => {
+  // Retrieve the current signer in the Hardhat environment
+  const curOwner = (await hre.ethers.getSigners())[0];
+
+  // Get a reference to the GeniusOwnershipFacet contract at the specified root address
+  const ownership = await hre.ethers.getContractAt('GeniusOwnershipFacet', rootAddress);
+
+  // Retrieve the current owner of the contract
+  const oldOwnerAddress = await ownership.owner();
+
+  // Impersonate the old owner
+  const oldOwner = await impersonateSigner(oldOwnerAddress, provider);
+
+  // If the old owner is not the current signer, transfer ownership to the current signer
+  if (oldOwnerAddress !== curOwner.address) {
+    debuglog(`Transferring ownership from ${oldOwnerAddress}`);
+
+    // Ensure the old owner has enough Ether to perform the ownership transfer
+    await setEtherBalance(oldOwnerAddress, toWei(10), provider);
+
+    await (ownership as any).connect(await oldOwner).transferOwnership(curOwner.address);
+    await (ownership as any).connect(oldOwner).transferOwnership(curOwner.address);
+  }
+
+  // Return the address of the old owner
+  return oldOwnerAddress;
+};

package/src/utils/txlogging.ts

@@ -0,0 +1,97 @@
+// ──────────────────────────────────────────────────────────────────────────────
+//  txLogging.ts
+//  Extra helpers for inspecting diamond‑cut transactions
+// ──────────────────────────────────────────────────────────────────────────────
+import "@nomicfoundation/hardhat-ethers";
+import chalk from "chalk";
+import { ContractTransactionResponse, Interface, InterfaceAbi, Log, LogDescription, TransactionReceipt } from "ethers";
+import hre from "hardhat";
+
+
+/**
+ * Pretty‑prints a transaction receipt **and** decodes its logs.
+ *
+ * @param tx               The awaited transaction object (e.g. from `contract.fn()`)
+ * @param description      Optional label that will be shown in the console header.
+ * @param interfaces       One or more `ethers.Interface` (or plain ABIs) used to decode
+ *                         the `receipt.logs`.  Pass the primary contract interface first;   
+ *                         additional ABIs (e.g. library or facet events) can follow.
+ */
+export async function logTx(
+  tx: ContractTransactionResponse,
+  description = "",
+  interfaces: (Interface | InterfaceAbi)[] = [],
+  // verbose?: boolean
+): Promise<TransactionReceipt> {
+  // normalise incoming interfaces => ethers.Interface
+  const decoders: Interface[] = interfaces.map((i) =>
+    i instanceof Interface ? i : new Interface(i)
+  );
+
+  const receipt = await tx.wait();
+  if (!receipt) {
+    throw new Error("Transaction receipt is null");
+  }
+
+  /* --------------------------- basic tx statistics -------------------------- */
+  console.log(chalk.green(`\n⛓️  Transaction Details${description ? ` – ${description}` : ""}`));
+  console.table({
+    Hash: tx.hash,
+    Status: receipt.status === 1 ? "Success" : "Failed",
+    Block: receipt.blockNumber,
+    From: receipt.from,
+    To: receipt.to,
+    "Tx Index": (receipt as any).transactionIndex ?? receipt.index ?? "N/A",
+    "Gas Used": receipt.gasUsed.toString(),
+    "Cumulative Gas": receipt.cumulativeGasUsed.toString(),
+    "Gas Price": (receipt as any).gasPrice?.toString() ?? "N/A",
+    "Block Hash": receipt.blockHash,
+    "Confirmations": receipt.confirmations,
+    "Timestamp": receipt.blockNumber
+      ? new Date(((await tx.wait().then(() => hre.ethers.provider.getBlock(receipt.blockNumber))) ?? { timestamp: 0 }).timestamp * 1000).toLocaleString()
+      : "N/A",
+    "Created Contract": receipt.contractAddress ?? "N/A",
+    "Created By": receipt.from,
+
+    Events: receipt.logs.length,
+  });
+
+  /* ----------------------------- decode events ------------------------------ */
+  if (receipt.logs.length === 0) return receipt;
+  console.log(chalk.cyan("\n📜 Decoded events:"));
+  receipt.logs.forEach((log: Log, idx: number) => {
+    let parsed: LogDescription | undefined;
+    for (const iface of decoders) {
+      try {
+        const result = iface.parseLog(log);
+        if (result !== null) {
+          parsed = result;
+          break; // stop at first successful decoder
+        }
+      } catch (_) {
+        /* ignore and try next */
+      }
+    }
+
+    if (parsed) {
+      const argsPretty = parsed.args
+        .map((arg: unknown, i: number) => {
+          const key = parsed?.fragment.inputs[i].name;
+          return `${key ? key + ": " : ""}${arg}`;
+        })
+        .join(", ");
+
+      console.log(
+        chalk.yellowBright(`  Event[${idx}]`) +
+        chalk.bold(` ${parsed.name}`) +
+        `  →  ${argsPretty}`
+      );
+    } else {
+      console.log(
+        chalk.dim(`  Event[${idx}]`) + ` – unable to decode (topic0 = ${log.topics[0]})`
+      );
+    }
+  });
+
+  return receipt;
+}