From 1b07f280ffe9afe6f44696edf8a1cd2e728d62c6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Caner=20Yakupo=C4=9Flu?= <caneryakupoglu@outlook.com>
Date: Tue, 29 Sep 2026 15:51:51 +0300
Subject: [PATCH 1/2] feat(soroban-footprint-diff): compare simulation
 footprint access modes offline

---
 features/soroban-footprint-diff/README.md     |  22 +++
 .../SorobanFootprintDiffPanel.test.tsx        |  40 +++++
 .../__tests__/a11y.test.tsx                   |  27 ++++
 .../__tests__/access-diff.test.ts             |  27 ++++
 .../__tests__/footprint-parser.test.ts        |  38 +++++
 .../__tests__/format.test.ts                  |  25 +++
 .../__tests__/resource-summary.test.ts        |  32 ++++
 .../__tests__/schema.test.ts                  |  36 +++++
 .../__tests__/sorobanFootprintDiff.test.ts    |  36 +++++
 .../useSorobanFootprintDiff.test.tsx          |  46 ++++++
 .../components/AccessChanges.tsx              |  24 +++
 .../components/FootprintGroups.tsx            |  46 ++++++
 .../components/ResourceSummary.tsx            |  52 +++++++
 .../SorobanFootprintDiffEmptyState.tsx        |  15 ++
 .../components/SorobanFootprintDiffForm.tsx   |  60 ++++++++
 .../components/SorobanFootprintDiffPanel.tsx  |  45 ++++++
 .../components/SorobanFootprintDiffResult.tsx |  49 ++++++
 features/soroban-footprint-diff/copy.ts       |  57 +++++++
 .../e2e/access-mode-change.spec.ts            |  15 ++
 .../e2e/soroban-footprint-diff.spec.ts        |  17 +++
 .../fixtures/access-conflicts.fixture.ts      |   4 +
 .../fixtures/simulations.fixture.ts           |   5 +
 .../fixtures/sorobanFootprintDiff.fixture.ts  |  45 ++++++
 .../hooks/useSorobanFootprintDiff.ts          |  56 +++++++
 .../soroban-footprint-diff/lib/access-diff.ts |  84 ++++++++++
 .../lib/footprint-parser.ts                   | 143 ++++++++++++++++++
 features/soroban-footprint-diff/lib/format.ts |  21 +++
 .../lib/resource-summary.ts                   |  18 +++
 .../lib/sorobanFootprintDiff.errors.ts        |   7 +
 .../lib/sorobanFootprintDiff.ts               |  30 ++++
 features/soroban-footprint-diff/manifest.ts   |  16 ++
 .../soroban-footprint-diff/msw/handlers.ts    |   1 +
 features/soroban-footprint-diff/panel.tsx     |   1 +
 features/soroban-footprint-diff/schema.ts     |  26 ++++
 features/soroban-footprint-diff/types.ts      |  51 +++++++
 35 files changed, 1217 insertions(+)
 create mode 100644 features/soroban-footprint-diff/README.md
 create mode 100644 features/soroban-footprint-diff/__tests__/SorobanFootprintDiffPanel.test.tsx
 create mode 100644 features/soroban-footprint-diff/__tests__/a11y.test.tsx
 create mode 100644 features/soroban-footprint-diff/__tests__/access-diff.test.ts
 create mode 100644 features/soroban-footprint-diff/__tests__/footprint-parser.test.ts
 create mode 100644 features/soroban-footprint-diff/__tests__/format.test.ts
 create mode 100644 features/soroban-footprint-diff/__tests__/resource-summary.test.ts
 create mode 100644 features/soroban-footprint-diff/__tests__/schema.test.ts
 create mode 100644 features/soroban-footprint-diff/__tests__/sorobanFootprintDiff.test.ts
 create mode 100644 features/soroban-footprint-diff/__tests__/useSorobanFootprintDiff.test.tsx
 create mode 100644 features/soroban-footprint-diff/components/AccessChanges.tsx
 create mode 100644 features/soroban-footprint-diff/components/FootprintGroups.tsx
 create mode 100644 features/soroban-footprint-diff/components/ResourceSummary.tsx
 create mode 100644 features/soroban-footprint-diff/components/SorobanFootprintDiffEmptyState.tsx
 create mode 100644 features/soroban-footprint-diff/components/SorobanFootprintDiffForm.tsx
 create mode 100644 features/soroban-footprint-diff/components/SorobanFootprintDiffPanel.tsx
 create mode 100644 features/soroban-footprint-diff/components/SorobanFootprintDiffResult.tsx
 create mode 100644 features/soroban-footprint-diff/copy.ts
 create mode 100644 features/soroban-footprint-diff/e2e/access-mode-change.spec.ts
 create mode 100644 features/soroban-footprint-diff/e2e/soroban-footprint-diff.spec.ts
 create mode 100644 features/soroban-footprint-diff/fixtures/access-conflicts.fixture.ts
 create mode 100644 features/soroban-footprint-diff/fixtures/simulations.fixture.ts
 create mode 100644 features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture.ts
 create mode 100644 features/soroban-footprint-diff/hooks/useSorobanFootprintDiff.ts
 create mode 100644 features/soroban-footprint-diff/lib/access-diff.ts
 create mode 100644 features/soroban-footprint-diff/lib/footprint-parser.ts
 create mode 100644 features/soroban-footprint-diff/lib/format.ts
 create mode 100644 features/soroban-footprint-diff/lib/resource-summary.ts
 create mode 100644 features/soroban-footprint-diff/lib/sorobanFootprintDiff.errors.ts
 create mode 100644 features/soroban-footprint-diff/lib/sorobanFootprintDiff.ts
 create mode 100644 features/soroban-footprint-diff/manifest.ts
 create mode 100644 features/soroban-footprint-diff/msw/handlers.ts
 create mode 100644 features/soroban-footprint-diff/panel.tsx
 create mode 100644 features/soroban-footprint-diff/schema.ts
 create mode 100644 features/soroban-footprint-diff/types.ts

diff --git a/features/soroban-footprint-diff/README.md b/features/soroban-footprint-diff/README.md
new file mode 100644
index 0000000..014890d
--- /dev/null
+++ b/features/soroban-footprint-diff/README.md
@@ -0,0 +1,22 @@
+# Soroban Footprint Difference Inspector
+
+Fully offline comparison of two pasted simulation-result JSON payloads.
+
+## Behavior
+
+1. Validate both pastes (non-empty, size-capped).
+2. Require `footprint.readOnly` / `footprint.readWrite` arrays.
+3. Decode ledger keys (opaque labels or LedgerKey XDR).
+4. Treat the same key in both sets as an access-mode conflict.
+5. Diff additions, removals and mode changes; show optional resource fields as simulation outputs only.
+
+## Data boundaries
+
+- No network calls (`networks: []`, `offline: true`).
+- Pastes are never persisted.
+- Input size capped at 100,000 characters per side.
+
+## Design decisions
+
+- A footprint is a proposal for one simulated transaction, not proof of a later ledger write.
+- Resource fields are shown only when present and labeled as simulation output.
diff --git a/features/soroban-footprint-diff/__tests__/SorobanFootprintDiffPanel.test.tsx b/features/soroban-footprint-diff/__tests__/SorobanFootprintDiffPanel.test.tsx
new file mode 100644
index 0000000..1392826
--- /dev/null
+++ b/features/soroban-footprint-diff/__tests__/SorobanFootprintDiffPanel.test.tsx
@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { renderFeature, screen } from "@/core/testing/render";
+import { SorobanFootprintDiffPanel } from "@/features/soroban-footprint-diff/components/SorobanFootprintDiffPanel";
+import { copy, errorCopy } from "@/features/soroban-footprint-diff/copy";
+import {
+  firstSimulationJson,
+  secondSimulationJson
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
+
+type User = ReturnType<typeof renderFeature>["user"];
+
+async function compare(user: User, first: string, second: string) {
+  await user.click(screen.getByLabelText(copy.firstLabel));
+  await user.paste(first);
+  await user.click(screen.getByLabelText(copy.secondLabel));
+  await user.paste(second);
+  await user.click(screen.getByRole("button", { name: copy.submit }));
+}
+
+describe("SorobanFootprintDiffPanel", () => {
+  it("shows empty state", () => {
+    renderFeature(<SorobanFootprintDiffPanel />);
+    expect(screen.getByText(copy.emptyTitle)).toBeInTheDocument();
+  });
+
+  it("renders a successful comparison", async () => {
+    const { user } = renderFeature(<SorobanFootprintDiffPanel />);
+    await compare(user, firstSimulationJson, secondSimulationJson);
+    expect(await screen.findByText(copy.modeTitle)).toBeInTheDocument();
+    expect(screen.getByText(copy.addedTitle)).toBeInTheDocument();
+  });
+
+  it("explains empty second result", async () => {
+    const { user } = renderFeature(<SorobanFootprintDiffPanel />);
+    await user.click(screen.getByLabelText(copy.firstLabel));
+    await user.paste(firstSimulationJson);
+    await user.click(screen.getByRole("button", { name: copy.submit }));
+    expect(await screen.findByText(errorCopy.empty_second_result.title)).toBeInTheDocument();
+  });
+});
diff --git a/features/soroban-footprint-diff/__tests__/a11y.test.tsx b/features/soroban-footprint-diff/__tests__/a11y.test.tsx
new file mode 100644
index 0000000..1444e91
--- /dev/null
+++ b/features/soroban-footprint-diff/__tests__/a11y.test.tsx
@@ -0,0 +1,27 @@
+import { describe, it } from "vitest";
+import { renderFeature, screen } from "@/core/testing/render";
+import { expectNoAxeViolations } from "@/core/testing/axe";
+import { SorobanFootprintDiffPanel } from "@/features/soroban-footprint-diff/components/SorobanFootprintDiffPanel";
+import { copy } from "@/features/soroban-footprint-diff/copy";
+import {
+  firstSimulationJson,
+  secondSimulationJson
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
+
+describe("SorobanFootprintDiffPanel accessibility", () => {
+  it("has no WCAG A/AA violations idle", async () => {
+    const { container } = renderFeature(<SorobanFootprintDiffPanel />);
+    await expectNoAxeViolations(container);
+  });
+
+  it("has no WCAG A/AA violations after success", async () => {
+    const { container, user } = renderFeature(<SorobanFootprintDiffPanel />);
+    await user.click(screen.getByLabelText(copy.firstLabel));
+    await user.paste(firstSimulationJson);
+    await user.click(screen.getByLabelText(copy.secondLabel));
+    await user.paste(secondSimulationJson);
+    await user.click(screen.getByRole("button", { name: copy.submit }));
+    await screen.findByText(copy.modeTitle);
+    await expectNoAxeViolations(container);
+  });
+});
diff --git a/features/soroban-footprint-diff/__tests__/access-diff.test.ts b/features/soroban-footprint-diff/__tests__/access-diff.test.ts
new file mode 100644
index 0000000..d99982a
--- /dev/null
+++ b/features/soroban-footprint-diff/__tests__/access-diff.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { diffAccessModes } from "@/features/soroban-footprint-diff/lib/access-diff";
+
+describe("diffAccessModes", () => {
+  it("reports additions, removals and mode changes", () => {
+    const diff = diffAccessModes(
+      [
+        { id: "A", label: "A", mode: "read_only" },
+        { id: "B", label: "B", mode: "read_only" },
+        { id: "C", label: "C", mode: "read_write" }
+      ],
+      [
+        { id: "A", label: "A", mode: "read_only" },
+        { id: "B", label: "B", mode: "read_write" },
+        { id: "D", label: "D", mode: "read_write" }
+      ]
+    );
+
+    expect(diff.added.map((key) => key.id)).toEqual(["D"]);
+    expect(diff.removed.map((key) => key.id)).toEqual(["C"]);
+    expect(diff.modeChanges.find((change) => change.id === "B")).toMatchObject({
+      kind: "mode_changed",
+      before: "read_only",
+      after: "read_write"
+    });
+  });
+});
diff --git a/features/soroban-footprint-diff/__tests__/footprint-parser.test.ts b/features/soroban-footprint-diff/__tests__/footprint-parser.test.ts
new file mode 100644
index 0000000..ab5bafb
--- /dev/null
+++ b/features/soroban-footprint-diff/__tests__/footprint-parser.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { parseSimulationFootprint } from "@/features/soroban-footprint-diff/lib/footprint-parser";
+import {
+  conflictSimulationJson,
+  firstSimulationJson,
+  invalidXdrSimulationJson
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
+
+describe("parseSimulationFootprint", () => {
+  it("parses labeled keys and resources", () => {
+    const result = parseSimulationFootprint(firstSimulationJson);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.keys).toHaveLength(3);
+    expect(result.value.resources.minResourceFee).toBe("100");
+  });
+
+  it("marks the same key in both sets as conflict", () => {
+    const result = parseSimulationFootprint(conflictSimulationJson);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.keys).toEqual([
+      { id: "CONTRACT_DATA:X", label: "CONTRACT_DATA:X", mode: "conflict" }
+    ]);
+  });
+
+  it("rejects invalid JSON shapes", () => {
+    expect(parseSimulationFootprint("{")).toEqual({ ok: false, code: "invalid_json" });
+    expect(parseSimulationFootprint("{}")).toEqual({ ok: false, code: "invalid_json" });
+  });
+
+  it("rejects undecodable XDR-looking entries", () => {
+    expect(parseSimulationFootprint(invalidXdrSimulationJson)).toEqual({
+      ok: false,
+      code: "invalid_footprint_xdr"
+    });
+  });
+});
diff --git a/features/soroban-footprint-diff/__tests__/format.test.ts b/features/soroban-footprint-diff/__tests__/format.test.ts
new file mode 100644
index 0000000..7459899
--- /dev/null
+++ b/features/soroban-footprint-diff/__tests__/format.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { formatChangeLine, formatKeyLabel, formatSummary } from "@/features/soroban-footprint-diff/lib/format";
+
+describe("format helpers", () => {
+  it("formats key labels and change lines", () => {
+    expect(
+      formatKeyLabel({ id: "A", label: "CONTRACT_DATA:A", mode: "read_only" })
+    ).toContain("read-only");
+    expect(
+      formatChangeLine({
+        id: "B",
+        label: "CONTRACT_DATA:B",
+        before: "read_only",
+        after: "read_write",
+        kind: "mode_changed"
+      })
+    ).toContain("read-only → read-write");
+  });
+
+  it("formats summary counts", () => {
+    expect(formatSummary({ added: 1, removed: 2, modeChanges: 3 })).toBe(
+      "1 added · 2 removed · 3 mode changes"
+    );
+  });
+});
diff --git a/features/soroban-footprint-diff/__tests__/resource-summary.test.ts b/features/soroban-footprint-diff/__tests__/resource-summary.test.ts
new file mode 100644
index 0000000..b47c595
--- /dev/null
+++ b/features/soroban-footprint-diff/__tests__/resource-summary.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { summarizeResources } from "@/features/soroban-footprint-diff/lib/resource-summary";
+
+describe("summarizeResources", () => {
+  it("includes only present fields", () => {
+    expect(
+      summarizeResources({
+        minResourceFee: "100",
+        cpuInsns: null,
+        memBytes: "2",
+        labeledAsSimulation: true
+      })
+    ).toEqual({
+      hasAny: true,
+      rows: [
+        { label: "minResourceFee", value: "100" },
+        { label: "memBytes", value: "2" }
+      ]
+    });
+  });
+
+  it("reports empty summaries", () => {
+    expect(
+      summarizeResources({
+        minResourceFee: null,
+        cpuInsns: null,
+        memBytes: null,
+        labeledAsSimulation: true
+      }).hasAny
+    ).toBe(false);
+  });
+});
diff --git a/features/soroban-footprint-diff/__tests__/schema.test.ts b/features/soroban-footprint-diff/__tests__/schema.test.ts
new file mode 100644
index 0000000..fe7f69f
--- /dev/null
+++ b/features/soroban-footprint-diff/__tests__/schema.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { parseSorobanFootprintDiffInput } from "@/features/soroban-footprint-diff/schema";
+import { MAX_INPUT_CHARS } from "@/features/soroban-footprint-diff/types";
+import {
+  firstSimulationJson,
+  secondSimulationJson
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
+
+describe("parseSorobanFootprintDiffInput", () => {
+  it("accepts two non-empty payloads under the size cap", () => {
+    expect(
+      parseSorobanFootprintDiffInput({
+        firstResult: firstSimulationJson,
+        secondResult: secondSimulationJson
+      }).ok
+    ).toBe(true);
+  });
+
+  it("rejects empty sides", () => {
+    expect(
+      parseSorobanFootprintDiffInput({ firstResult: "", secondResult: secondSimulationJson })
+    ).toEqual({ ok: false, code: "empty_first_result" });
+    expect(
+      parseSorobanFootprintDiffInput({ firstResult: firstSimulationJson, secondResult: "  " })
+    ).toEqual({ ok: false, code: "empty_second_result" });
+  });
+
+  it("rejects oversized pastes", () => {
+    expect(
+      parseSorobanFootprintDiffInput({
+        firstResult: "x".repeat(MAX_INPUT_CHARS + 1),
+        secondResult: secondSimulationJson
+      })
+    ).toEqual({ ok: false, code: "too_large" });
+  });
+});
diff --git a/features/soroban-footprint-diff/__tests__/sorobanFootprintDiff.test.ts b/features/soroban-footprint-diff/__tests__/sorobanFootprintDiff.test.ts
new file mode 100644
index 0000000..fe74389
--- /dev/null
+++ b/features/soroban-footprint-diff/__tests__/sorobanFootprintDiff.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { runSorobanFootprintDiff } from "@/features/soroban-footprint-diff/lib/sorobanFootprintDiff";
+import {
+  firstSimulationJson,
+  invalidXdrSimulationJson,
+  secondSimulationJson
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
+
+describe("runSorobanFootprintDiff", () => {
+  it("diffs two simulation footprints", async () => {
+    const result = await runSorobanFootprintDiff({
+      firstResult: firstSimulationJson,
+      secondResult: secondSimulationJson
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.added.map((key) => key.id)).toEqual(["CONTRACT_DATA:D"]);
+    expect(result.value.removed.map((key) => key.id)).toEqual(["CONTRACT_DATA:C"]);
+    expect(result.value.modeChanges.some((change) => change.id === "CONTRACT_DATA:B")).toBe(true);
+  });
+
+  it("maps invalid JSON", async () => {
+    expect(
+      await runSorobanFootprintDiff({ firstResult: "{", secondResult: secondSimulationJson })
+    ).toEqual({ ok: false, code: "invalid_json" });
+  });
+
+  it("maps invalid footprint XDR", async () => {
+    expect(
+      await runSorobanFootprintDiff({
+        firstResult: invalidXdrSimulationJson,
+        secondResult: secondSimulationJson
+      })
+    ).toEqual({ ok: false, code: "invalid_footprint_xdr" });
+  });
+});
diff --git a/features/soroban-footprint-diff/__tests__/useSorobanFootprintDiff.test.tsx b/features/soroban-footprint-diff/__tests__/useSorobanFootprintDiff.test.tsx
new file mode 100644
index 0000000..9e6cfb9
--- /dev/null
+++ b/features/soroban-footprint-diff/__tests__/useSorobanFootprintDiff.test.tsx
@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { useSorobanFootprintDiff } from "@/features/soroban-footprint-diff/hooks/useSorobanFootprintDiff";
+import {
+  firstSimulationJson,
+  secondSimulationJson
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
+
+describe("useSorobanFootprintDiff", () => {
+  it("starts idle", () => {
+    const { result } = renderHook(() => useSorobanFootprintDiff());
+    expect(result.current.state).toEqual({ status: "idle" });
+  });
+
+  it("compares footprints", async () => {
+    const { result } = renderHook(() => useSorobanFootprintDiff());
+    await act(async () => {
+      await result.current.submit({
+        firstResult: firstSimulationJson,
+        secondResult: secondSimulationJson
+      });
+    });
+    await waitFor(() => expect(result.current.state.status).toBe("success"));
+  });
+
+  it("surfaces empty first result", async () => {
+    const { result } = renderHook(() => useSorobanFootprintDiff());
+    await act(async () => {
+      await result.current.submit({ firstResult: "", secondResult: secondSimulationJson });
+    });
+    expect(result.current.state).toEqual({ status: "error", code: "empty_first_result" });
+  });
+
+  it("resets", async () => {
+    const { result } = renderHook(() => useSorobanFootprintDiff());
+    await act(async () => {
+      await result.current.submit({
+        firstResult: firstSimulationJson,
+        secondResult: secondSimulationJson
+      });
+    });
+    await waitFor(() => expect(result.current.state.status).toBe("success"));
+    act(() => result.current.reset());
+    expect(result.current.state).toEqual({ status: "idle" });
+  });
+});
diff --git a/features/soroban-footprint-diff/components/AccessChanges.tsx b/features/soroban-footprint-diff/components/AccessChanges.tsx
new file mode 100644
index 0000000..c5ab47e
--- /dev/null
+++ b/features/soroban-footprint-diff/components/AccessChanges.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import { copy } from "@/features/soroban-footprint-diff/copy";
+import { formatChangeLine } from "@/features/soroban-footprint-diff/lib/format";
+import type { AccessChange } from "@/features/soroban-footprint-diff/types";
+
+export function AccessChanges({ changes }: { changes: AccessChange[] }) {
+  if (changes.length === 0) {
+    return <p className="text-sm text-[#68758a]">{copy.noModeChanges}</p>;
+  }
+
+  return (
+    <ul className="space-y-2">
+      {changes.map((change) => (
+        <li
+          key={`${change.id}-${change.kind}`}
+          className="rounded-md border border-[#e3ebf5] bg-white/60 px-3 py-2 font-mono text-xs text-[#172033]"
+        >
+          {formatChangeLine(change)}
+        </li>
+      ))}
+    </ul>
+  );
+}
diff --git a/features/soroban-footprint-diff/components/FootprintGroups.tsx b/features/soroban-footprint-diff/components/FootprintGroups.tsx
new file mode 100644
index 0000000..446d1db
--- /dev/null
+++ b/features/soroban-footprint-diff/components/FootprintGroups.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import { copy } from "@/features/soroban-footprint-diff/copy";
+import { formatKeyLabel } from "@/features/soroban-footprint-diff/lib/format";
+import type { FootprintKey } from "@/features/soroban-footprint-diff/types";
+
+export function FootprintGroups({
+  added,
+  removed
+}: {
+  added: FootprintKey[];
+  removed: FootprintKey[];
+}) {
+  return (
+    <div className="space-y-4">
+      <section>
+        <h3 className="mb-2 text-sm font-bold text-[#172033]">{copy.addedTitle}</h3>
+        {added.length === 0 ? (
+          <p className="text-sm text-[#68758a]">{copy.noAdded}</p>
+        ) : (
+          <ul className="space-y-1">
+            {added.map((key) => (
+              <li key={key.id} className="font-mono text-xs text-[#29364d]">
+                {formatKeyLabel(key)}
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+      <section>
+        <h3 className="mb-2 text-sm font-bold text-[#172033]">{copy.removedTitle}</h3>
+        {removed.length === 0 ? (
+          <p className="text-sm text-[#68758a]">{copy.noRemoved}</p>
+        ) : (
+          <ul className="space-y-1">
+            {removed.map((key) => (
+              <li key={key.id} className="font-mono text-xs text-[#29364d]">
+                {formatKeyLabel(key)}
+              </li>
+            ))}
+          </ul>
+        )}
+      </section>
+    </div>
+  );
+}
diff --git a/features/soroban-footprint-diff/components/ResourceSummary.tsx b/features/soroban-footprint-diff/components/ResourceSummary.tsx
new file mode 100644
index 0000000..e8a3caf
--- /dev/null
+++ b/features/soroban-footprint-diff/components/ResourceSummary.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import { copy } from "@/features/soroban-footprint-diff/copy";
+import { summarizeResources } from "@/features/soroban-footprint-diff/lib/resource-summary";
+import type { ResourceSummaryData } from "@/features/soroban-footprint-diff/types";
+
+export function ResourceSummary({
+  first,
+  second
+}: {
+  first: ResourceSummaryData;
+  second: ResourceSummaryData;
+}) {
+  const firstRows = summarizeResources(first);
+  const secondRows = summarizeResources(second);
+
+  return (
+    <div className="space-y-3">
+      <p className="text-sm text-[#68758a]">{copy.simulationNote}</p>
+      <div className="grid gap-4 sm:grid-cols-2">
+        <section>
+          <h3 className="mb-2 text-sm font-bold text-[#172033]">{copy.firstResourcesLabel}</h3>
+          {firstRows.hasAny ? (
+            <ul className="space-y-1 text-xs text-[#4e5c73]">
+              {firstRows.rows.map((row) => (
+                <li key={row.label}>
+                  {row.label}: <span className="font-mono">{row.value}</span>
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <p className="text-sm text-[#68758a]">No resource fields present.</p>
+          )}
+        </section>
+        <section>
+          <h3 className="mb-2 text-sm font-bold text-[#172033]">{copy.secondResourcesLabel}</h3>
+          {secondRows.hasAny ? (
+            <ul className="space-y-1 text-xs text-[#4e5c73]">
+              {secondRows.rows.map((row) => (
+                <li key={row.label}>
+                  {row.label}: <span className="font-mono">{row.value}</span>
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <p className="text-sm text-[#68758a]">No resource fields present.</p>
+          )}
+        </section>
+      </div>
+    </div>
+  );
+}
diff --git a/features/soroban-footprint-diff/components/SorobanFootprintDiffEmptyState.tsx b/features/soroban-footprint-diff/components/SorobanFootprintDiffEmptyState.tsx
new file mode 100644
index 0000000..e8a6903
--- /dev/null
+++ b/features/soroban-footprint-diff/components/SorobanFootprintDiffEmptyState.tsx
@@ -0,0 +1,15 @@
+"use client";
+
+import { Card, CardHeader, CardTitle } from "@/core/ui/Card";
+import { copy } from "@/features/soroban-footprint-diff/copy";
+
+export function SorobanFootprintDiffEmptyState() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>{copy.emptyTitle}</CardTitle>
+      </CardHeader>
+      <p className="text-sm text-[#68758a]">{copy.emptyDescription}</p>
+    </Card>
+  );
+}
diff --git a/features/soroban-footprint-diff/components/SorobanFootprintDiffForm.tsx b/features/soroban-footprint-diff/components/SorobanFootprintDiffForm.tsx
new file mode 100644
index 0000000..c01cc01
--- /dev/null
+++ b/features/soroban-footprint-diff/components/SorobanFootprintDiffForm.tsx
@@ -0,0 +1,60 @@
+"use client";
+
+import { useState, type FormEvent } from "react";
+import { Button } from "@/core/ui/Button";
+import { Field } from "@/core/ui/Field";
+import { copy } from "@/features/soroban-footprint-diff/copy";
+import type { RawSorobanFootprintDiffForm } from "@/features/soroban-footprint-diff/schema";
+
+export function SorobanFootprintDiffForm({
+  onSubmit,
+  pending
+}: {
+  onSubmit: (values: RawSorobanFootprintDiffForm) => void;
+  pending: boolean;
+}) {
+  const [firstResult, setFirstResult] = useState("");
+  const [secondResult, setSecondResult] = useState("");
+
+  function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    onSubmit({ firstResult, secondResult });
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4" noValidate>
+      <p className="text-sm text-[#68758a]">{copy.formHint}</p>
+      <Field label={copy.firstLabel} required>
+        {({ inputId, describedBy, invalid, required }) => (
+          <textarea
+            id={inputId}
+            aria-describedby={describedBy}
+            aria-invalid={invalid}
+            required={required}
+            value={firstResult}
+            onChange={(event) => setFirstResult(event.target.value)}
+            rows={8}
+            className="w-full rounded-md border border-[#c7d6e8] bg-white/80 p-3 font-mono text-xs text-[#172033]"
+          />
+        )}
+      </Field>
+      <Field label={copy.secondLabel} required>
+        {({ inputId, describedBy, invalid, required }) => (
+          <textarea
+            id={inputId}
+            aria-describedby={describedBy}
+            aria-invalid={invalid}
+            required={required}
+            value={secondResult}
+            onChange={(event) => setSecondResult(event.target.value)}
+            rows={8}
+            className="w-full rounded-md border border-[#c7d6e8] bg-white/80 p-3 font-mono text-xs text-[#172033]"
+          />
+        )}
+      </Field>
+      <Button type="submit" disabled={pending}>
+        {pending ? copy.loading : copy.submit}
+      </Button>
+    </form>
+  );
+}
diff --git a/features/soroban-footprint-diff/components/SorobanFootprintDiffPanel.tsx b/features/soroban-footprint-diff/components/SorobanFootprintDiffPanel.tsx
new file mode 100644
index 0000000..263fd44
--- /dev/null
+++ b/features/soroban-footprint-diff/components/SorobanFootprintDiffPanel.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import { Card } from "@/core/ui/Card";
+import { SkeletonRows } from "@/core/ui/Skeleton";
+import { StatusMessage } from "@/core/ui/StatusMessage";
+import { SorobanFootprintDiffEmptyState } from "@/features/soroban-footprint-diff/components/SorobanFootprintDiffEmptyState";
+import { SorobanFootprintDiffForm } from "@/features/soroban-footprint-diff/components/SorobanFootprintDiffForm";
+import { SorobanFootprintDiffResultView } from "@/features/soroban-footprint-diff/components/SorobanFootprintDiffResult";
+import { copy, errorCopy } from "@/features/soroban-footprint-diff/copy";
+import { useSorobanFootprintDiff } from "@/features/soroban-footprint-diff/hooks/useSorobanFootprintDiff";
+
+export function SorobanFootprintDiffPanel() {
+  const { state, submit } = useSorobanFootprintDiff();
+
+  return (
+    <div className="space-y-5">
+      <Card>
+        <SorobanFootprintDiffForm onSubmit={submit} pending={state.status === "loading"} />
+      </Card>
+
+      {state.status === "loading" ? (
+        <Card>
+          <p className="sr-only" role="status">
+            {copy.loading}
+          </p>
+          <SkeletonRows rows={3} />
+        </Card>
+      ) : null}
+
+      {state.status === "error" ? (
+        <StatusMessage
+          type="error"
+          title={errorCopy[state.code].title}
+          description={errorCopy[state.code].description}
+        />
+      ) : null}
+
+      {state.status === "success" ? (
+        <SorobanFootprintDiffResultView result={state.result} />
+      ) : null}
+
+      {state.status === "idle" ? <SorobanFootprintDiffEmptyState /> : null}
+    </div>
+  );
+}
diff --git a/features/soroban-footprint-diff/components/SorobanFootprintDiffResult.tsx b/features/soroban-footprint-diff/components/SorobanFootprintDiffResult.tsx
new file mode 100644
index 0000000..7d5c855
--- /dev/null
+++ b/features/soroban-footprint-diff/components/SorobanFootprintDiffResult.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import { Card, CardHeader, CardTitle } from "@/core/ui/Card";
+import { StatusMessage } from "@/core/ui/StatusMessage";
+import { AccessChanges } from "@/features/soroban-footprint-diff/components/AccessChanges";
+import { FootprintGroups } from "@/features/soroban-footprint-diff/components/FootprintGroups";
+import { ResourceSummary } from "@/features/soroban-footprint-diff/components/ResourceSummary";
+import { copy } from "@/features/soroban-footprint-diff/copy";
+import { formatSummary } from "@/features/soroban-footprint-diff/lib/format";
+import type { SorobanFootprintDiffResult } from "@/features/soroban-footprint-diff/types";
+
+export function SorobanFootprintDiffResultView({
+  result
+}: {
+  result: SorobanFootprintDiffResult;
+}) {
+  return (
+    <div className="space-y-4">
+      <StatusMessage
+        type="info"
+        title={copy.resultTitle}
+        description={formatSummary({
+          added: result.added.length,
+          removed: result.removed.length,
+          modeChanges: result.modeChanges.length
+        })}
+      />
+      <p className="text-sm text-[#68758a]">{result.disclaimer}</p>
+
+      <Card>
+        <FootprintGroups added={result.added} removed={result.removed} />
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>{copy.modeTitle}</CardTitle>
+        </CardHeader>
+        <AccessChanges changes={result.modeChanges} />
+      </Card>
+
+      <Card>
+        <CardHeader>
+          <CardTitle>{copy.resourcesTitle}</CardTitle>
+        </CardHeader>
+        <ResourceSummary first={result.firstResources} second={result.secondResources} />
+      </Card>
+    </div>
+  );
+}
diff --git a/features/soroban-footprint-diff/copy.ts b/features/soroban-footprint-diff/copy.ts
new file mode 100644
index 0000000..4b5bf29
--- /dev/null
+++ b/features/soroban-footprint-diff/copy.ts
@@ -0,0 +1,57 @@
+import type { SorobanFootprintDiffErrorCode } from "@/features/soroban-footprint-diff/types";
+import { MAX_INPUT_CHARS } from "@/features/soroban-footprint-diff/types";
+
+export const copy = {
+  firstLabel: "First simulation result JSON",
+  secondLabel: "Second simulation result JSON",
+  formHint: "Paste two simulation-result JSON payloads. Nothing is sent or stored.",
+  submit: "Compare footprints",
+  loading: "Comparing footprints locally...",
+  emptyTitle: "No footprint comparison yet",
+  emptyDescription:
+    "Compare read-only and read-write ledger keys from two pasted simulation results. A footprint is a proposal for one simulated transaction, not proof of a later ledger write.",
+  resultTitle: "Footprint difference",
+  addedTitle: "Keys added in the second result",
+  removedTitle: "Keys removed in the second result",
+  modeTitle: "Access mode changes",
+  resourcesTitle: "Simulation resources",
+  firstResourcesLabel: "First result",
+  secondResourcesLabel: "Second result",
+  noAdded: "No keys were added.",
+  noRemoved: "No keys were removed.",
+  noModeChanges: "No access-mode changes.",
+  feeLabel: "minResourceFee",
+  cpuLabel: "cpuInsns",
+  memLabel: "memBytes",
+  simulationNote: "Simulation output only — not a confirmed ledger write.",
+  disclaimer:
+    "A simulation footprint is a proposal for one simulated transaction, not proof of a later ledger write."
+} as const;
+
+export const errorCopy: Record<
+  SorobanFootprintDiffErrorCode,
+  { title: string; description: string }
+> = {
+  empty_first_result: {
+    title: "First simulation result is empty",
+    description: "Paste the first simulation-result JSON payload."
+  },
+  empty_second_result: {
+    title: "Second simulation result is empty",
+    description: "Paste the second simulation-result JSON payload."
+  },
+  invalid_json: {
+    title: "Simulation JSON is not valid",
+    description:
+      "Each payload must be JSON with a footprint.readOnly and footprint.readWrite array."
+  },
+  invalid_footprint_xdr: {
+    title: "A footprint ledger key could not be decoded",
+    description:
+      "One or more footprint entries looked like XDR but failed to decode as a LedgerKey."
+  },
+  too_large: {
+    title: "Pasted payload is too large",
+    description: `Keep each simulation result under ${MAX_INPUT_CHARS} characters. Nothing is persisted.`
+  }
+};
diff --git a/features/soroban-footprint-diff/e2e/access-mode-change.spec.ts b/features/soroban-footprint-diff/e2e/access-mode-change.spec.ts
new file mode 100644
index 0000000..d832e9b
--- /dev/null
+++ b/features/soroban-footprint-diff/e2e/access-mode-change.spec.ts
@@ -0,0 +1,15 @@
+import {
+  firstSimulationJson,
+  secondSimulationJson
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
+
+export const spec = {
+  route: "/tools/soroban-footprint-diff",
+  steps: [
+    { action: "visit", target: "/tools/soroban-footprint-diff" },
+    { action: "fill", target: "First simulation result JSON", value: firstSimulationJson },
+    { action: "fill", target: "Second simulation result JSON", value: secondSimulationJson },
+    { action: "click", target: "Compare footprints" },
+    { action: "expect", target: "text", value: "read-only → read-write" }
+  ]
+} as const;
diff --git a/features/soroban-footprint-diff/e2e/soroban-footprint-diff.spec.ts b/features/soroban-footprint-diff/e2e/soroban-footprint-diff.spec.ts
new file mode 100644
index 0000000..a0411ab
--- /dev/null
+++ b/features/soroban-footprint-diff/e2e/soroban-footprint-diff.spec.ts
@@ -0,0 +1,17 @@
+import {
+  firstSimulationJson,
+  secondSimulationJson
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
+
+export const spec = {
+  route: "/tools/soroban-footprint-diff",
+  steps: [
+    { action: "visit", target: "/tools/soroban-footprint-diff" },
+    { action: "expect", target: "heading", value: "Soroban Footprint Difference Inspector" },
+    { action: "expect", target: "text", value: "No footprint comparison yet" },
+    { action: "fill", target: "First simulation result JSON", value: firstSimulationJson },
+    { action: "fill", target: "Second simulation result JSON", value: secondSimulationJson },
+    { action: "click", target: "Compare footprints" },
+    { action: "expect", target: "text", value: "Access mode changes" }
+  ]
+} as const;
diff --git a/features/soroban-footprint-diff/fixtures/access-conflicts.fixture.ts b/features/soroban-footprint-diff/fixtures/access-conflicts.fixture.ts
new file mode 100644
index 0000000..9260c70
--- /dev/null
+++ b/features/soroban-footprint-diff/fixtures/access-conflicts.fixture.ts
@@ -0,0 +1,4 @@
+export {
+  accessConflictsFixture,
+  conflictSimulationJson
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
diff --git a/features/soroban-footprint-diff/fixtures/simulations.fixture.ts b/features/soroban-footprint-diff/fixtures/simulations.fixture.ts
new file mode 100644
index 0000000..4f4795c
--- /dev/null
+++ b/features/soroban-footprint-diff/fixtures/simulations.fixture.ts
@@ -0,0 +1,5 @@
+export {
+  firstSimulationJson,
+  secondSimulationJson,
+  simulationsFixture
+} from "@/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture";
diff --git a/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture.ts b/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture.ts
new file mode 100644
index 0000000..d4e2f23
--- /dev/null
+++ b/features/soroban-footprint-diff/fixtures/sorobanFootprintDiff.fixture.ts
@@ -0,0 +1,45 @@
+export const firstSimulation = {
+  footprint: {
+    readOnly: ["CONTRACT_DATA:A", "CONTRACT_DATA:B"],
+    readWrite: ["CONTRACT_DATA:C"]
+  },
+  minResourceFee: "100",
+  cost: { cpuInsns: "1000", memBytes: "2000" }
+};
+
+export const secondSimulation = {
+  footprint: {
+    readOnly: ["CONTRACT_DATA:A"],
+    readWrite: ["CONTRACT_DATA:B", "CONTRACT_DATA:D"]
+  },
+  minResourceFee: "150",
+  cost: { cpuInsns: "1100", memBytes: "2100" }
+};
+
+/** Same key appears in both read-only and read-write → conflict mode. */
+export const conflictSimulation = {
+  footprint: {
+    readOnly: ["CONTRACT_DATA:X"],
+    readWrite: ["CONTRACT_DATA:X"]
+  }
+};
+
+export const firstSimulationJson = JSON.stringify(firstSimulation, null, 2);
+export const secondSimulationJson = JSON.stringify(secondSimulation, null, 2);
+export const conflictSimulationJson = JSON.stringify(conflictSimulation, null, 2);
+
+export const invalidXdrSimulationJson = JSON.stringify({
+  footprint: {
+    readOnly: ["AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"],
+    readWrite: []
+  }
+});
+
+export const simulationsFixture = {
+  first: firstSimulationJson,
+  second: secondSimulationJson
+};
+
+export const accessConflictsFixture = {
+  conflict: conflictSimulationJson
+};
diff --git a/features/soroban-footprint-diff/hooks/useSorobanFootprintDiff.ts b/features/soroban-footprint-diff/hooks/useSorobanFootprintDiff.ts
new file mode 100644
index 0000000..710291e
--- /dev/null
+++ b/features/soroban-footprint-diff/hooks/useSorobanFootprintDiff.ts
@@ -0,0 +1,56 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import { isErr, type Result } from "@/core/result/result";
+import { parseSorobanFootprintDiffInput } from "@/features/soroban-footprint-diff/schema";
+import { runSorobanFootprintDiff } from "@/features/soroban-footprint-diff/lib/sorobanFootprintDiff";
+import { toSorobanFootprintDiffErrorCode } from "@/features/soroban-footprint-diff/lib/sorobanFootprintDiff.errors";
+import type {
+  RawSorobanFootprintDiffForm
+} from "@/features/soroban-footprint-diff/schema";
+import type {
+  SorobanFootprintDiffErrorCode,
+  SorobanFootprintDiffResult
+} from "@/features/soroban-footprint-diff/types";
+
+export type SorobanFootprintDiffState =
+  | { status: "idle" }
+  | { status: "loading" }
+  | { status: "success"; result: SorobanFootprintDiffResult }
+  | { status: "error"; code: SorobanFootprintDiffErrorCode };
+
+export function useSorobanFootprintDiff() {
+  const [state, setState] = useState<SorobanFootprintDiffState>({ status: "idle" });
+  const generation = useRef(0);
+
+  const submit = useCallback(async (raw: RawSorobanFootprintDiffForm) => {
+    const id = ++generation.current;
+    const parsed = parseSorobanFootprintDiffInput(raw);
+    if (isErr(parsed)) {
+      setState({ status: "error", code: parsed.code });
+      return;
+    }
+
+    setState({ status: "loading" });
+    try {
+      const result: Result<SorobanFootprintDiffResult, SorobanFootprintDiffErrorCode> =
+        await runSorobanFootprintDiff(parsed.value);
+      if (id !== generation.current) return;
+      setState(
+        result.ok
+          ? { status: "success", result: result.value }
+          : { status: "error", code: result.code }
+      );
+    } catch (error) {
+      if (id !== generation.current) return;
+      setState({ status: "error", code: toSorobanFootprintDiffErrorCode(error) });
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    generation.current += 1;
+    setState({ status: "idle" });
+  }, []);
+
+  return { state, submit, reset };
+}
diff --git a/features/soroban-footprint-diff/lib/access-diff.ts b/features/soroban-footprint-diff/lib/access-diff.ts
new file mode 100644
index 0000000..49f9a72
--- /dev/null
+++ b/features/soroban-footprint-diff/lib/access-diff.ts
@@ -0,0 +1,84 @@
+import type {
+  AccessChange,
+  AccessMode,
+  FootprintKey
+} from "@/features/soroban-footprint-diff/types";
+
+export function diffAccessModes(
+  before: FootprintKey[],
+  after: FootprintKey[]
+): {
+  added: FootprintKey[];
+  removed: FootprintKey[];
+  modeChanges: AccessChange[];
+  unchanged: FootprintKey[];
+} {
+  const beforeMap = new Map(before.map((key) => [key.id, key]));
+  const afterMap = new Map(after.map((key) => [key.id, key]));
+
+  const added: FootprintKey[] = [];
+  const removed: FootprintKey[] = [];
+  const modeChanges: AccessChange[] = [];
+  const unchanged: FootprintKey[] = [];
+
+  for (const [id, key] of afterMap) {
+    const previous = beforeMap.get(id);
+    if (!previous) {
+      added.push(key);
+      modeChanges.push({
+        id,
+        label: key.label,
+        before: null,
+        after: key.mode,
+        kind: "added"
+      });
+      continue;
+    }
+
+    if (previous.mode !== key.mode) {
+      modeChanges.push({
+        id,
+        label: key.label,
+        before: previous.mode,
+        after: key.mode,
+        kind: "mode_changed"
+      });
+    } else {
+      unchanged.push(key);
+      modeChanges.push({
+        id,
+        label: key.label,
+        before: previous.mode,
+        after: key.mode,
+        kind: "unchanged"
+      });
+    }
+  }
+
+  for (const [id, key] of beforeMap) {
+    if (!afterMap.has(id)) {
+      removed.push(key);
+      modeChanges.push({
+        id,
+        label: key.label,
+        before: key.mode,
+        after: null,
+        kind: "removed"
+      });
+    }
+  }
+
+  return {
+    added,
+    removed,
+    modeChanges: modeChanges.filter((change) => change.kind !== "unchanged"),
+    unchanged
+  };
+}
+
+export function formatAccessMode(mode: AccessMode | null): string {
+  if (!mode) return "—";
+  if (mode === "read_only") return "read-only";
+  if (mode === "read_write") return "read-write";
+  return "conflict (read-only + read-write)";
+}
diff --git a/features/soroban-footprint-diff/lib/footprint-parser.ts b/features/soroban-footprint-diff/lib/footprint-parser.ts
new file mode 100644
index 0000000..a2e5a87
--- /dev/null
+++ b/features/soroban-footprint-diff/lib/footprint-parser.ts
@@ -0,0 +1,143 @@
+import { xdr } from "@stellar/stellar-sdk";
+import { err, ok, type Result } from "@/core/result/result";
+import type {
+  AccessMode,
+  FootprintKey,
+  ParsedFootprint,
+  ResourceSummaryData,
+  SorobanFootprintDiffErrorCode
+} from "@/features/soroban-footprint-diff/types";
+
+const BASE64_XDR = /^[A-Za-z0-9+/=]+$/;
+
+function emptyResources(): ResourceSummaryData {
+  return {
+    minResourceFee: null,
+    cpuInsns: null,
+    memBytes: null,
+    labeledAsSimulation: true
+  };
+}
+
+function summarizeLedgerKey(key: xdr.LedgerKey): string {
+  const kind = key.switch().name;
+  try {
+    switch (kind) {
+      case "account":
+        return `account:${key.account().accountId().ed25519().toString("hex").slice(0, 8)}`;
+      case "contractData":
+        return `contractData:${key.contractData().contract().toString("hex").slice(0, 12)}`;
+      case "contractCode":
+        return `contractCode:${key.contractCode().hash().toString("hex").slice(0, 12)}`;
+      default:
+        return kind;
+    }
+  } catch {
+    return kind;
+  }
+}
+
+function decodeKeyEntry(
+  entry: unknown,
+  mode: Exclude<AccessMode, "conflict">
+): Result<FootprintKey, SorobanFootprintDiffErrorCode> {
+  if (typeof entry === "string") {
+    const value = entry.trim();
+    if (!value) return err("invalid_footprint_xdr");
+
+    // Opaque fixture / already-decoded labels stay as-is.
+    if (!BASE64_XDR.test(value) || value.length < 16 || value.includes(":")) {
+      return ok({ id: value, label: value, mode });
+    }
+
+    try {
+      const key = xdr.LedgerKey.fromXDR(value, "base64");
+      const label = summarizeLedgerKey(key);
+      return ok({ id: value, label, mode });
+    } catch {
+      return err("invalid_footprint_xdr");
+    }
+  }
+
+  if (entry && typeof entry === "object") {
+    const record = entry as { xdr?: unknown; key?: unknown; id?: unknown; label?: unknown };
+    if (typeof record.xdr === "string") return decodeKeyEntry(record.xdr, mode);
+    if (typeof record.key === "string") return decodeKeyEntry(record.key, mode);
+    if (typeof record.id === "string") {
+      const label = typeof record.label === "string" ? record.label : record.id;
+      return ok({ id: record.id, label, mode });
+    }
+  }
+
+  return err("invalid_footprint_xdr");
+}
+
+function mergeModes(existing: AccessMode, next: AccessMode): AccessMode {
+  if (existing === next) return existing;
+  return "conflict";
+}
+
+export function parseSimulationFootprint(
+  raw: string
+): Result<ParsedFootprint, SorobanFootprintDiffErrorCode> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return err("invalid_json");
+  }
+
+  if (!parsed || typeof parsed !== "object") return err("invalid_json");
+  const document = parsed as {
+    footprint?: { readOnly?: unknown; readWrite?: unknown };
+    minResourceFee?: unknown;
+    cost?: { cpuInsns?: unknown; memBytes?: unknown };
+  };
+
+  if (!document.footprint || typeof document.footprint !== "object") {
+    return err("invalid_json");
+  }
+
+  const readOnly = document.footprint.readOnly;
+  const readWrite = document.footprint.readWrite;
+  if (!Array.isArray(readOnly) || !Array.isArray(readWrite)) {
+    return err("invalid_json");
+  }
+
+  const byId = new Map<string, FootprintKey>();
+
+  for (const entry of readOnly) {
+    const decoded = decodeKeyEntry(entry, "read_only");
+    if (!decoded.ok) return decoded;
+    const previous = byId.get(decoded.value.id);
+    byId.set(
+      decoded.value.id,
+      previous
+        ? { ...decoded.value, mode: mergeModes(previous.mode, "read_only") }
+        : decoded.value
+    );
+  }
+
+  for (const entry of readWrite) {
+    const decoded = decodeKeyEntry(entry, "read_write");
+    if (!decoded.ok) return decoded;
+    const previous = byId.get(decoded.value.id);
+    byId.set(
+      decoded.value.id,
+      previous
+        ? { ...decoded.value, mode: mergeModes(previous.mode, "read_write") }
+        : decoded.value
+    );
+  }
+
+  const resources = emptyResources();
+  if (typeof document.minResourceFee === "string") {
+    resources.minResourceFee = document.minResourceFee;
+  }
+  if (document.cost && typeof document.cost === "object") {
+    if (typeof document.cost.cpuInsns === "string") resources.cpuInsns = document.cost.cpuInsns;
+    if (typeof document.cost.memBytes === "string") resources.memBytes = document.cost.memBytes;
+  }
+
+  return ok({ keys: [...byId.values()], resources });
+}
diff --git a/features/soroban-footprint-diff/lib/format.ts b/features/soroban-footprint-diff/lib/format.ts
new file mode 100644
index 0000000..cb5e7d9
--- /dev/null
+++ b/features/soroban-footprint-diff/lib/format.ts
@@ -0,0 +1,21 @@
+import { formatAccessMode } from "@/features/soroban-footprint-diff/lib/access-diff";
+import type {
+  AccessChange,
+  FootprintKey
+} from "@/features/soroban-footprint-diff/types";
+
+export function formatKeyLabel(key: FootprintKey): string {
+  return `${key.label} (${formatAccessMode(key.mode)})`;
+}
+
+export function formatChangeLine(change: AccessChange): string {
+  return `${change.label}: ${formatAccessMode(change.before)} → ${formatAccessMode(change.after)}`;
+}
+
+export function formatSummary(counts: {
+  added: number;
+  removed: number;
+  modeChanges: number;
+}): string {
+  return `${counts.added} added · ${counts.removed} removed · ${counts.modeChanges} mode changes`;
+}
diff --git a/features/soroban-footprint-diff/lib/resource-summary.ts b/features/soroban-footprint-diff/lib/resource-summary.ts
new file mode 100644
index 0000000..e4b5cd1
--- /dev/null
+++ b/features/soroban-footprint-diff/lib/resource-summary.ts
@@ -0,0 +1,18 @@
+import type { ResourceSummaryData } from "@/features/soroban-footprint-diff/types";
+
+export function summarizeResources(resources: ResourceSummaryData): {
+  hasAny: boolean;
+  rows: Array<{ label: string; value: string }>;
+} {
+  const rows: Array<{ label: string; value: string }> = [];
+  if (resources.minResourceFee !== null) {
+    rows.push({ label: "minResourceFee", value: resources.minResourceFee });
+  }
+  if (resources.cpuInsns !== null) {
+    rows.push({ label: "cpuInsns", value: resources.cpuInsns });
+  }
+  if (resources.memBytes !== null) {
+    rows.push({ label: "memBytes", value: resources.memBytes });
+  }
+  return { hasAny: rows.length > 0, rows };
+}
diff --git a/features/soroban-footprint-diff/lib/sorobanFootprintDiff.errors.ts b/features/soroban-footprint-diff/lib/sorobanFootprintDiff.errors.ts
new file mode 100644
index 0000000..d5f049e
--- /dev/null
+++ b/features/soroban-footprint-diff/lib/sorobanFootprintDiff.errors.ts
@@ -0,0 +1,7 @@
+import type { SorobanFootprintDiffErrorCode } from "@/features/soroban-footprint-diff/types";
+
+/** Offline tool — unexpected throws map to invalid JSON rather than network codes. */
+export function toSorobanFootprintDiffErrorCode(error: unknown): SorobanFootprintDiffErrorCode {
+  void error;
+  return "invalid_json";
+}
diff --git a/features/soroban-footprint-diff/lib/sorobanFootprintDiff.ts b/features/soroban-footprint-diff/lib/sorobanFootprintDiff.ts
new file mode 100644
index 0000000..86cb830
--- /dev/null
+++ b/features/soroban-footprint-diff/lib/sorobanFootprintDiff.ts
@@ -0,0 +1,30 @@
+import { ok, type Result } from "@/core/result/result";
+import { copy } from "@/features/soroban-footprint-diff/copy";
+import { diffAccessModes } from "@/features/soroban-footprint-diff/lib/access-diff";
+import { parseSimulationFootprint } from "@/features/soroban-footprint-diff/lib/footprint-parser";
+import type {
+  SorobanFootprintDiffErrorCode,
+  SorobanFootprintDiffInput,
+  SorobanFootprintDiffResult
+} from "@/features/soroban-footprint-diff/types";
+
+export async function runSorobanFootprintDiff(
+  input: SorobanFootprintDiffInput
+): Promise<Result<SorobanFootprintDiffResult, SorobanFootprintDiffErrorCode>> {
+  const first = parseSimulationFootprint(input.firstResult);
+  if (!first.ok) return first;
+  const second = parseSimulationFootprint(input.secondResult);
+  if (!second.ok) return second;
+
+  const diff = diffAccessModes(first.value.keys, second.value.keys);
+
+  return ok({
+    added: diff.added,
+    removed: diff.removed,
+    modeChanges: diff.modeChanges,
+    unchanged: diff.unchanged,
+    firstResources: first.value.resources,
+    secondResources: second.value.resources,
+    disclaimer: copy.disclaimer
+  });
+}
diff --git a/features/soroban-footprint-diff/manifest.ts b/features/soroban-footprint-diff/manifest.ts
new file mode 100644
index 0000000..796a853
--- /dev/null
+++ b/features/soroban-footprint-diff/manifest.ts
@@ -0,0 +1,16 @@
+import { GitCompareArrows } from "lucide-react";
+import type { FeatureManifest } from "@/core/registry/types";
+
+export const manifest: FeatureManifest = {
+  slug: "soroban-footprint-diff",
+  title: "Soroban Footprint Difference Inspector",
+  description:
+    "Compare read-only and read-write ledger-key footprints from two pasted simulation results offline.",
+  character: "A cartographer overlays two proposed footprints and circles every mode flip.",
+  category: "soroban",
+  status: "working",
+  icon: GitCompareArrows,
+  networks: [],
+  offline: true,
+  keywords: ["soroban", "footprint", "simulation", "ledger key", "diff"]
+};
diff --git a/features/soroban-footprint-diff/msw/handlers.ts b/features/soroban-footprint-diff/msw/handlers.ts
new file mode 100644
index 0000000..1d7c6f8
--- /dev/null
+++ b/features/soroban-footprint-diff/msw/handlers.ts
@@ -0,0 +1 @@
+export const handlers: never[] = [];
diff --git a/features/soroban-footprint-diff/panel.tsx b/features/soroban-footprint-diff/panel.tsx
new file mode 100644
index 0000000..fcb4841
--- /dev/null
+++ b/features/soroban-footprint-diff/panel.tsx
@@ -0,0 +1 @@
+export { SorobanFootprintDiffPanel as default } from "@/features/soroban-footprint-diff/components/SorobanFootprintDiffPanel";
diff --git a/features/soroban-footprint-diff/schema.ts b/features/soroban-footprint-diff/schema.ts
new file mode 100644
index 0000000..32ffc42
--- /dev/null
+++ b/features/soroban-footprint-diff/schema.ts
@@ -0,0 +1,26 @@
+import { err, ok, type Result } from "@/core/result/result";
+import {
+  MAX_INPUT_CHARS,
+  type SorobanFootprintDiffErrorCode,
+  type SorobanFootprintDiffInput
+} from "@/features/soroban-footprint-diff/types";
+
+export interface RawSorobanFootprintDiffForm {
+  firstResult: string;
+  secondResult: string;
+}
+
+export function parseSorobanFootprintDiffInput(
+  raw: RawSorobanFootprintDiffForm
+): Result<SorobanFootprintDiffInput, SorobanFootprintDiffErrorCode> {
+  const firstResult = raw.firstResult.trim();
+  const secondResult = raw.secondResult.trim();
+
+  if (!firstResult) return err("empty_first_result");
+  if (!secondResult) return err("empty_second_result");
+  if (firstResult.length > MAX_INPUT_CHARS || secondResult.length > MAX_INPUT_CHARS) {
+    return err("too_large");
+  }
+
+  return ok({ firstResult, secondResult });
+}
diff --git a/features/soroban-footprint-diff/types.ts b/features/soroban-footprint-diff/types.ts
new file mode 100644
index 0000000..7b85dae
--- /dev/null
+++ b/features/soroban-footprint-diff/types.ts
@@ -0,0 +1,51 @@
+export type AccessMode = "read_only" | "read_write" | "conflict";
+
+export interface FootprintKey {
+  id: string;
+  label: string;
+  mode: AccessMode;
+}
+
+export interface AccessChange {
+  id: string;
+  label: string;
+  before: AccessMode | null;
+  after: AccessMode | null;
+  kind: "added" | "removed" | "mode_changed" | "unchanged";
+}
+
+export interface ResourceSummaryData {
+  minResourceFee: string | null;
+  cpuInsns: string | null;
+  memBytes: string | null;
+  labeledAsSimulation: true;
+}
+
+export interface ParsedFootprint {
+  keys: FootprintKey[];
+  resources: ResourceSummaryData;
+}
+
+export interface SorobanFootprintDiffInput {
+  firstResult: string;
+  secondResult: string;
+}
+
+export interface SorobanFootprintDiffResult {
+  added: FootprintKey[];
+  removed: FootprintKey[];
+  modeChanges: AccessChange[];
+  unchanged: FootprintKey[];
+  firstResources: ResourceSummaryData;
+  secondResources: ResourceSummaryData;
+  disclaimer: string;
+}
+
+export type SorobanFootprintDiffErrorCode =
+  | "empty_first_result"
+  | "empty_second_result"
+  | "invalid_json"
+  | "invalid_footprint_xdr"
+  | "too_large";
+
+export const MAX_INPUT_CHARS = 100_000;

From d60d7f46d167cfbedd6ade475e4d407a72e8ce9d Mon Sep 17 00:00:00 2001
From: Ege Hidayet Koca <kocaege777@gmail.com>
Date: Wed, 30 Sep 2026 18:04:38 +0300
Subject: [PATCH 2/2] fix: decode ScAddress before hex-encoding a contractData
 key

contract() on a contractData LedgerKey returns an ScAddress union
(account or contract), not raw bytes; calling .toString("hex")
directly on it doesn't type-check and wasn't decoding anything
meaningful. Branch on the address kind and take the actual bytes
(contractId() or accountId().ed25519()) before hex-encoding.
---
 .../soroban-footprint-diff/lib/footprint-parser.ts     | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/features/soroban-footprint-diff/lib/footprint-parser.ts b/features/soroban-footprint-diff/lib/footprint-parser.ts
index a2e5a87..9289d33 100644
--- a/features/soroban-footprint-diff/lib/footprint-parser.ts
+++ b/features/soroban-footprint-diff/lib/footprint-parser.ts
@@ -25,8 +25,14 @@ function summarizeLedgerKey(key: xdr.LedgerKey): string {
     switch (kind) {
       case "account":
         return `account:${key.account().accountId().ed25519().toString("hex").slice(0, 8)}`;
-      case "contractData":
-        return `contractData:${key.contractData().contract().toString("hex").slice(0, 12)}`;
+      case "contractData": {
+        const address = key.contractData().contract();
+        const bytes =
+          address.switch().name === "scAddressTypeContract"
+            ? address.contractId()
+            : address.accountId().ed25519();
+        return `contractData:${bytes.toString("hex").slice(0, 12)}`;
+      }
       case "contractCode":
         return `contractCode:${key.contractCode().hash().toString("hex").slice(0, 12)}`;
       default: