SorobanTrace

Open-source transaction inspection and debugging infrastructure for Stellar smart contracts.

Overview

SorobanTrace helps developers understand what happened during a Stellar smart-contract transaction by decoding transaction XDR, contract events, diagnostic events, authorization entries, resource usage and ledger changes.

The core question it answers:

"Why did my Soroban transaction do this?"

Features

• Transaction Inspection: Decode and analyze Stellar transactions
• Diagnostic Engine: Human-readable explanations of errors and issues
• Resource Analysis: CPU, memory, and fee usage breakdown
• Storage Tracking: Ledger entry reads and modifications
• Event Analysis: Contract and system event decoding
• Error Explanations: What happened, why, and what to investigate

Architecture

Raw transaction (hash or XDR)
        ↓
    Stellar RPC
        ↓
    XDR Decoder
        ↓
    Trace Engine
        ↓
    Diagnostic Engine
        ↓
    Human-readable diagnosis

Project Structure

sorobantrace/
├── crates/
│   ├── core/           # Domain models and error types
│   ├── xdr/            # XDR encoding/decoding
│   ├── decoder/        # Transaction decoding pipeline
│   ├── simulator/      # Stellar RPC client
│   └── inspector/      # Transaction inspection and diagnostics
│
├── cli/                # Command-line interface
├── fixtures/           # Test data
├── docs/               # Documentation
├── tests/              # Integration tests
└── examples/           # Example usage

Quick Start

Build

cargo build

Test

cargo test

CLI Usage

# Inspect a transaction
sorobantrace tx <TX_HASH>

# Explain an error
sorobantrace explain "HostError: InvalidAction"

Documentation

• ARCHITECTURE.md - System design and components
• ENGINEERING_PRINCIPLES.md - Code standards and practices
• CONTRIBUTING.md - How to contribute
• CONTRIBUTOR_ROADMAP.md - Development roadmap
• PROVENANCE.md - Project origin and history
• SECURITY.md - Security policy
• CODE_OF_CONDUCT.md - Community standards

Development

Prerequisites

• Rust 1.75+
• Cargo

Building

cargo build

Running Tests

cargo test

Code Quality

cargo check
cargo clippy
cargo fmt

Contributing

See CONTRIBUTING.md for detailed guidelines.

Good First Issues

Check out issues labeled good first issue for beginner-friendly tasks.

Issue Complexity

• Trivial: 1-2 hours
• Medium: 4-8 hours
• High: 1-2 days

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

Built for the Stellar/Soroban developer ecosystem.