Ledger entry

[BigMick03]

Close: #86

🚀 Introduce Prism — Soroban Transaction Debugger

Summary

This PR introduces Prism, a CLI-native diagnostic tool for Soroban that transforms opaque transaction errors into actionable insights.

Prism provides a full debugging pipeline — from instant error decoding to historical transaction replay and interactive time-travel debugging — enabling developers to move from cryptic failures to root cause analysis in seconds.

---

✨ Why This Matters

Debugging Soroban transactions today is slow and fragmented:

• Errors like Error(Contract, #3) lack context

• Developers rely on source code digging, guesswork, or redeploy cycles

• No tooling exists for replaying real transactions with full execution visibility

Prism solves this by becoming the missing diagnostic layer in the Soroban ecosystem.

---

🧠 What This PR Adds

Tier 1 — Decode (Fast Path)

• Plain-English decoding of Soroban host errors

• Contract-specific error resolution via WASM metadata (contractspecv0)

• Root cause analysis with ranked suggested fixes

• Full transaction context (args, auth, fees, resource usage)

Tier 2 — Trace (Diagnostic Path)

• Historical ledger state reconstruction

• Full transaction replay with execution trace

• Hierarchical timeline of:

  • Contract invocations

  • Host function calls

  • Storage reads/writes

  • Auth checks

  • Budget usage

• Resource profiling + hotspot detection

• Ledger state diff (before vs after execution)

Tier 3 — Time-Travel Debugging (Investigation Path)

• Interactive debugging with breakpoints

• Step-through execution at host-call granularity

• State inspection at any point in execution

• What-if simulation (modify inputs + compare outcomes)

---

🧩 Architecture Overview

• Core (Rust): Decode engine, replay engine, breakpoint controller, what-if engine

• Infrastructure Layer:

  • XDR codec

  • Contract spec decoder

  • Soroban RPC + History Archive clients

  • Error taxonomy database

  • Local cache layer

• Interfaces:

  • CLI (primary)

  • VS Code extension (planned)

  • Web app (planned)

  • WASM / Rust library

---

🛠 CLI Commands

Command | Tier | Description -- | -- | -- prism decode | 1 | Decode error + root cause prism inspect | 1 | Full transaction context prism trace | 2 | Execution timeline prism profile | 2 | Resource hotspot analysis prism diff | 2 | Ledger state changes prism replay --interactive | 3 | TUI debugger prism whatif | 3 | Simulate modified execution

---

📦 Key Features

• 🔍 Instant error decoding with taxonomy database

• 🧾 Contract-aware error resolution

• ⏪ Historical state reconstruction

• 🧬 Full execution trace replay

• 📊 Resource profiling + budget analysis

• 🔄 State diff visualization

• 🧭 Interactive time-travel debugging

• 🔌 Multi-interface support (CLI, IDE, Web, Library)

---

🔐 Security

• Read-only tool (no signing, no key handling)

• Fully sandboxed replay environment

• Strict validation of all external inputs

• Local, non-sensitive caching

---

🌐 Supported Networks

• Mainnet ✅

• Testnet ✅

• Futurenet ⚠️ (partial replay support)

• Custom RPC endpoints ✅

---

📍 Roadmap

• Phase 1: CLI + decoding (current)

• Phase 2: VS Code extension

• Phase 3: Web app (WASM-based)

• Phase 4: Replay engine

• Phase 5: Time-travel debugger

• Phase 6: CI integrations + ecosystem tooling

---

🧪 How to Test

cargo install sextant
prism decode <transaction-hash>

---

📣 Naming Note

Prism is the user-facing name. Internally and in installation (cargo install sextant), the project may still reference Sextant.

---

🔥 Impact

This PR establishes Prism as a foundational debugging tool for Soroban:

• Reduces debugging time from hours → seconds

• Eliminates guesswork in error interpretation

• Enables deterministic replay of real-world failures

• Unlocks deep introspection into contract execution

---

📌 Next Steps

• Expand error taxonomy coverage

• Stabilize CLI UX

• Begin VS Code extension development

• Design replay engine interfaces

---

Prism turns “something went wrong” into “here’s exactly why.”

[Emrys02]

@BigMick03 i do not understand this PR, this was not the task you were given. Please check the task description properly, if you have questions you can reach out to me on Discord