StellarScope

The interpretation layer for Soroban — a block explorer that translates Stellar transactions into human-readable activity.

Overview

StellarScope is a Soroban-native block explorer built for the next phase of the Stellar ecosystem. It provides a unified, human-readable interface for both classic Stellar operations and smart contract interactions.

As Soroban introduces programmable finance to Stellar, existing tools expose low-level data but lack meaningful interpretation. StellarScope bridges this gap by decoding raw blockchain activity into clear, understandable financial actions.

The Problem

Existing explorers such as StellarExpert provide strong support for classic Stellar operations (payments, trustlines, offers). However, Soroban smart contract activity remains difficult to interpret.

While Soroban data is accessible via RPC and explorer interfaces:

• Contract invocations are displayed as low-level XDR or minimally decoded structures
• Event logs lack semantic meaning
• There is no intent-based interpretation (e.g. swaps, lending, liquidations)
• No unified view combines classic operations and Soroban activity

Protocols like Soroswap, Blend, and Aquarius generate meaningful on-chain activity, but this activity is not surfaced in a human-readable or aggregated way.

This creates a major usability gap for:

• Developers debugging contracts
• Users tracking transactions
• Analysts understanding ecosystem activity

Project Structure

stellarscope/
├── apps/
│   └── web/                 # Next.js frontend application
├── services/
│   ├── api/                 # Axum REST API service
│   ├── indexer/             # Blockchain data indexer
│   └── workers/             # Background job workers
├── crates/
│   ├── decoder/             # XDR decoding library
│   ├── db/                  # Database layer (SQLx)
│   └── types/               # Shared type definitions
├── infrastructure/
│   ├── docker/              # Docker configurations
│   └── scripts/             # Setup and utility scripts
├── Cargo.toml               # Rust workspace configuration
├── package.json             # Node.js workspace configuration
└── .env.example             # Environment variables template

Tech Stack

• Backend: Rust with Axum framework
• Async Runtime: Tokio
• Database: PostgreSQL with SQLx
• Frontend: Next.js with TypeScript and Tailwind CSS
• Package Manager: pnpm (frontend), Cargo (Rust)
• Containerization: Docker & Docker Compose

Getting Started

Prerequisites

• Rust 1.75+
• Node.js 18+
• Docker & Docker Compose
• PostgreSQL 16+ (or use Docker)

Setup

1. Clone the repository

2. Copy environment variables:

   cp .env.example .env

3. Start services with Docker Compose:

   docker-compose -f infrastructure/docker/docker-compose.yml up

4. Or build and run locally:

   # Build Rust services
   cargo build --release
   
   # Install frontend dependencies
   pnpm install
   
   # Run frontend
   pnpm dev

Services

API Service (Port 3000)

REST API for querying blockchain data.

Endpoints:

• GET /health - Health check
• GET /tx/:hash - Get transaction details
• GET /address/:id - Get address information

Indexer Service

Ingests and indexes blockchain data from Stellar network.

TODO: Configure data source and indexing parameters

Workers Service

Background job processing for async tasks.

TODO: Define job types and handlers

Frontend

Next.js application with pages for:

• Homepage with network overview
• Transaction details (/tx/[hash])
• Address details (/address/[id])

Development

Build Rust Services

cargo build

Run Tests

cargo test

Format Code

cargo fmt

Lint

cargo clippy

Frontend Development

cd apps/web
pnpm dev

Database

PostgreSQL is used for data persistence.

TODO: Add migration scripts and schema definitions

Docker

Build Images

docker-compose -f infrastructure/docker/docker-compose.yml build

Start Services

docker-compose -f infrastructure/docker/docker-compose.yml up -d

View Logs

docker-compose -f infrastructure/docker/docker-compose.yml logs -f

Stop Services

docker-compose -f infrastructure/docker/docker-compose.yml down

Configuration

Environment variables are defined in .env. See .env.example for available options.

License

MIT