refactor(core): extract shared formatTokenAmount + add ERC-1155 tests (#156)

The token amount formatter was duplicated between event-decoder.ts
(formatAmount) and slot-decoder.ts (formatTokenAmount) with subtle
differences in null-decimal handling. Extract the canonical version
into a shared format.ts module that both files now import.

Also adds:
- 11 unit tests for formatTokenAmount covering zero, dust amounts,
  large numbers, fractional truncation, and null-decimal fallback
- 3 tests for ERC-1155 TransferSingle and TransferBatch decoding
  (previously untested)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: Th0rgal

packages/core/src/lib/simulation/__tests__/event-decoder.test.ts

@@ -15,6 +15,10 @@ const TRANSFER_TOPIC =
   "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
 const APPROVAL_TOPIC =
   "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925";
+const TRANSFER_SINGLE_TOPIC =
+  "0xc3d58168c5ae7397731d063d5bbf3d657854427343f4c083240f7aacaa2d0f62";
+const TRANSFER_BATCH_TOPIC =
+  "0x4a39dc06d4c0dbc64b70af90fd698a233a518aa5d07e595d983b8c0526c8f7fb";
 const DEPOSIT_TOPIC =
   "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c";
 const WITHDRAWAL_TOPIC =
@@ -221,6 +225,113 @@ describe("decodeSimulationEvents", () => {
   });
 });
 
+// ── ERC-1155 ──────────────────────────────────────────────────────
+
+describe("ERC-1155 TransferSingle", () => {
+  const OPERATOR = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
+  const NFT_CONTRACT = "0x0000000000000000000000000000000000000099";
+
+  it("decodes a TransferSingle (receive)", () => {
+    const tokenId = 7n;
+    const amount = 3n;
+    // data = abi.encode(uint256 id, uint256 value)
+    const data = "0x" + tokenId.toString(16).padStart(64, "0") + amount.toString(16).padStart(64, "0");
+    const logs: SimulationLog[] = [
+      {
+        address: NFT_CONTRACT,
+        topics: [
+          TRANSFER_SINGLE_TOPIC,
+          pad32(OPERATOR),
+          pad32("0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"),
+          pad32(SAFE),
+        ],
+        data,
+      },
+    ];
+
+    const events = decodeSimulationEvents(logs, SAFE);
+    expect(events).toHaveLength(1);
+    expect(events[0].kind).toBe("erc1155-transfer");
+    expect(events[0].tokenId).toBe("7");
+    expect(events[0].amountRaw).toBe("3");
+    expect(events[0].amountFormatted).toContain("3x");
+    expect(events[0].amountFormatted).toContain("#7");
+    expect(events[0].direction).toBe("receive");
+  });
+});
+
+describe("ERC-1155 TransferBatch", () => {
+  const OPERATOR = "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee";
+  const NFT_CONTRACT = "0x0000000000000000000000000000000000000099";
+
+  it("decodes a batch with 2 items", () => {
+    // ABI layout:
+    // word 0: offset to ids array (0x40 = 64 bytes)
+    // word 1: offset to vals array (0xa0 = 160 bytes)
+    // word 2: ids length (2)
+    // word 3: ids[0] = 10
+    // word 4: ids[1] = 20
+    // word 5: vals length (2)
+    // word 6: vals[0] = 5
+    // word 7: vals[1] = 1
+    const words = [
+      64n,  // offset to ids
+      160n, // offset to vals
+      2n,   // ids length
+      10n,  // ids[0]
+      20n,  // ids[1]
+      2n,   // vals length
+      5n,   // vals[0]
+      1n,   // vals[1]
+    ];
+    const data = "0x" + words.map((w) => w.toString(16).padStart(64, "0")).join("");
+    const logs: SimulationLog[] = [
+      {
+        address: NFT_CONTRACT,
+        topics: [
+          TRANSFER_BATCH_TOPIC,
+          pad32(OPERATOR),
+          pad32(SAFE),
+          pad32("0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"),
+        ],
+        data,
+      },
+    ];
+
+    const events = decodeSimulationEvents(logs, SAFE);
+    expect(events).toHaveLength(2);
+
+    expect(events[0].kind).toBe("erc1155-transfer");
+    expect(events[0].tokenId).toBe("10");
+    expect(events[0].amountRaw).toBe("5");
+    expect(events[0].direction).toBe("send");
+
+    expect(events[1].kind).toBe("erc1155-transfer");
+    expect(events[1].tokenId).toBe("20");
+    expect(events[1].amountRaw).toBe("1");
+    expect(events[1].direction).toBe("send");
+  });
+
+  it("skips malformed batch data gracefully", () => {
+    // Too-short data (< 5 words = 320 hex chars)
+    const logs: SimulationLog[] = [
+      {
+        address: NFT_CONTRACT,
+        topics: [
+          TRANSFER_BATCH_TOPIC,
+          pad32(OPERATOR),
+          pad32(SAFE),
+          pad32("0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"),
+        ],
+        data: "0x" + "00".repeat(64),
+      },
+    ];
+
+    const events = decodeSimulationEvents(logs, SAFE);
+    expect(events).toHaveLength(0);
+  });
+});
+
 // ── decodeNativeTransfers ──────────────────────────────────────────
 
 describe("decodeNativeTransfers", () => {

packages/core/src/lib/simulation/__tests__/format.test.ts

@@ -0,0 +1,65 @@
+import { describe, it, expect } from "vitest";
+import { formatTokenAmount } from "../format";
+
+describe("formatTokenAmount", () => {
+  describe("known decimals", () => {
+    it("formats zero", () => {
+      expect(formatTokenAmount(0n, 18, "WETH")).toBe("0 WETH");
+      expect(formatTokenAmount(0n, 6, null)).toBe("0");
+    });
+
+    it("formats whole amounts with thousands separators", () => {
+      expect(formatTokenAmount(5000n * 10n ** 18n, 18, "WETH")).toContain("5,000");
+      expect(formatTokenAmount(5000n * 10n ** 18n, 18, "WETH")).toContain("WETH");
+    });
+
+    it("formats fractional amounts up to 4 decimals", () => {
+      // 1.5 USDC = 1_500_000 raw (6 decimals)
+      expect(formatTokenAmount(1_500_000n, 6, "USDC")).toBe("1.5 USDC");
+    });
+
+    it("strips trailing fractional zeros", () => {
+      // 2.10 DAI → should show 2.1, not 2.10 or 2.1000
+      expect(formatTokenAmount(2_100_000_000_000_000_000n, 18, "DAI")).toBe("2.1 DAI");
+    });
+
+    it("shows <0.0001 for dust amounts", () => {
+      // 1 wei of WETH = too small for 4 decimal places
+      expect(formatTokenAmount(1n, 18, "WETH")).toBe("<0.0001 WETH");
+      // 100 wei (still under 0.0001 WETH = 10^14 wei)
+      expect(formatTokenAmount(100n, 18, null)).toBe("<0.0001");
+    });
+
+    it("formats large amounts correctly", () => {
+      // 1,234,567.89 DAI
+      const raw = 1_234_567_890_000_000_000_000_000n;
+      const result = formatTokenAmount(raw, 18, "DAI");
+      expect(result).toContain("1,234,567");
+      expect(result).toContain("DAI");
+    });
+
+    it("works without a symbol", () => {
+      expect(formatTokenAmount(1_000_000n, 6, null)).toBe("1");
+      expect(formatTokenAmount(1_500_000n, 6, null)).toBe("1.5");
+    });
+
+    it("truncates to 4 decimal places (no rounding)", () => {
+      // 1.123456789 with 9 decimals → show 1.1234
+      expect(formatTokenAmount(1_123_456_789n, 9, "TOK")).toBe("1.1234 TOK");
+    });
+  });
+
+  describe("null decimals (unknown token)", () => {
+    it("returns raw bigint as string", () => {
+      expect(formatTokenAmount(12345n, null, null)).toBe("12345");
+    });
+
+    it("appends symbol when available", () => {
+      expect(formatTokenAmount(42n, null, "???")).toBe("42 ???");
+    });
+
+    it("handles zero with null decimals", () => {
+      expect(formatTokenAmount(0n, null, "X")).toBe("0 X");
+    });
+  });
+});

packages/core/src/lib/simulation/event-decoder.ts

@@ -12,6 +12,7 @@
  */
 
 import type { SimulationLog, NativeTransfer } from "../types";
+import { formatTokenAmount } from "./format";
 
 // ── Event signatures (keccak256 hashes) ──────────────────────────────
 
@@ -152,29 +153,9 @@ function hexToDecimal(hex: string): string {
   return BigInt("0x" + clean).toString();
 }
 
-/** Format a raw token amount with decimals. */
+/** Format a raw token amount with decimals (delegates to shared formatter). */
 function formatAmount(raw: string, decimals: number, symbol: string | null): string {
-  const value = BigInt(raw);
-  if (value === 0n) return symbol ? `0 ${symbol}` : "0";
-
-  const divisor = BigInt(10) ** BigInt(decimals);
-  const whole = value / divisor;
-  const remainder = value % divisor;
-
-  // Use commas for thousands
-  const wholeStr = whole.toLocaleString("en-US");
-  const fractional = remainder.toString().padStart(decimals, "0").slice(0, 4).replace(/0+$/, "");
-
-  let numStr: string;
-  if (fractional.length > 0) {
-    numStr = `${wholeStr}.${fractional}`;
-  } else if (whole === 0n && remainder > 0n) {
-    // Non-zero amount too small for 4 decimal places (e.g. 1 wei of WETH)
-    numStr = "<0.0001";
-  } else {
-    numStr = wholeStr;
-  }
-  return symbol ? `${numStr} ${symbol}` : numStr;
+  return formatTokenAmount(BigInt(raw), decimals, symbol);
 }
 
 /** Look up token metadata. */

packages/core/src/lib/simulation/format.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared token amount formatting utilities.
+ *
+ * Used by both the event decoder (for display of decoded events) and
+ * the slot decoder (for proven balance/allowance deltas). Keeping
+ * this in one place prevents drift between the two formatters.
+ */
+
+/**
+ * Format a token amount for human-readable display.
+ *
+ * - Adds thousands separators (e.g. "1,234,567")
+ * - Shows up to 4 fractional digits, stripping trailing zeros
+ * - Shows "<0.0001" for dust amounts that round to zero at 4 decimals
+ * - Falls back to raw string when `decimals` is null (unknown token)
+ *
+ * @param raw      - Raw token amount as a bigint.
+ * @param decimals - Token decimals, or null for unknown tokens.
+ * @param symbol   - Token symbol for display, or null.
+ */
+export function formatTokenAmount(
+  raw: bigint,
+  decimals: number | null,
+  symbol: string | null,
+): string {
+  if (decimals == null) {
+    const str = raw.toString();
+    return symbol ? `${str} ${symbol}` : str;
+  }
+
+  if (raw === 0n) return symbol ? `0 ${symbol}` : "0";
+
+  const divisor = 10n ** BigInt(decimals);
+  const whole = raw / divisor;
+  const remainder = (raw < 0n ? -raw : raw) % divisor;
+
+  const wholeStr = whole.toLocaleString("en-US");
+  const fractional = remainder
+    .toString()
+    .padStart(decimals, "0")
+    .slice(0, 4)
+    .replace(/0+$/, "");
+
+  let numStr: string;
+  if (fractional.length > 0) {
+    numStr = `${wholeStr}.${fractional}`;
+  } else if (whole === 0n && remainder > 0n) {
+    numStr = "<0.0001";
+  } else {
+    numStr = wholeStr;
+  }
+  return symbol ? `${numStr} ${symbol}` : numStr;
+}

packages/core/src/lib/simulation/slot-decoder.ts

@@ -23,6 +23,7 @@ import {
 } from "viem";
 import type { StateDiffEntry } from "../types";
 import type { DecodedEvent } from "./event-decoder";
+import { formatTokenAmount } from "./format";
 
 // ── ERC-20 storage layout definitions ──────────────────────────────
 
@@ -143,38 +144,6 @@ function hexToUint256(hex: string): bigint {
   return BigInt(hex);
 }
 
-function formatTokenAmount(
-  raw: bigint,
-  decimals: number | null,
-  symbol: string | null,
-): string {
-  if (decimals == null) {
-    const str = raw.toString();
-    return symbol ? `${str} ${symbol}` : str;
-  }
-
-  const divisor = 10n ** BigInt(decimals);
-  const whole = raw / divisor;
-  const remainder = (raw < 0n ? -raw : raw) % divisor;
-
-  const wholeStr = whole.toLocaleString("en-US");
-  const fractional = remainder
-    .toString()
-    .padStart(decimals, "0")
-    .slice(0, 4)
-    .replace(/0+$/, "");
-
-  let numStr: string;
-  if (fractional.length > 0) {
-    numStr = `${wholeStr}.${fractional}`;
-  } else if (whole === 0n && remainder > 0n) {
-    numStr = "<0.0001";
-  } else {
-    numStr = wholeStr;
-  }
-  return symbol ? `${numStr} ${symbol}` : numStr;
-}
-
 function formatDelta(
   before: bigint,
   after: bigint,