Soroban Pulse

A lightweight Rust backend service that indexes Soroban smart contract events on the Stellar network and exposes them via a REST API.

Tech Stack

• Rust + Axum (web framework)
• Tokio (async runtime)
• PostgreSQL + SQLx (database + migrations)
• Stellar Soroban RPC (event source)

Project Structure

src/
├── main.rs       # Entry point, wires everything together
├── config.rs     # Environment config
├── db.rs         # DB pool + migrations
├── models.rs     # Data types (Event, RPC response shapes)
├── indexer.rs    # Background event polling worker
├── routes.rs     # Axum router
├── handlers.rs   # Request handlers
└── error.rs      # Unified error type
migrations/
└── 20260314000000_create_events.sql

Setup

1. Prerequisites

• Rust (stable)
• PostgreSQL 14+
• sqlx-cli (optional, for manual migrations)

2. Configure environment

cp .env.example .env
# Edit .env with your values

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	required
STELLAR_RPC_URL	Soroban RPC endpoint	https://soroban-testnet.stellar.org
START_LEDGER	Ledger to start indexing from (0 = latest)	0
PORT	HTTP server port	3000

3. Run with Docker Compose (easiest)

docker-compose up --build

4. Run locally

# Start PostgreSQL, then:
cargo run

Migrations run automatically on startup.

API

GET /health

{ "status": "ok" }

GET /events?page=1&limit=20

Returns paginated events across all contracts.

{
  "data": [
    {
      "id": "uuid",
      "contract_id": "CABC...",
      "event_type": "contract",
      "tx_hash": "abc123...",
      "ledger": 1234567,
      "timestamp": "2026-03-14T00:00:00Z",
      "event_data": { "value": {}, "topic": [] },
      "created_at": "2026-03-14T00:00:01Z"
    }
  ],
  "total": 100,
  "page": 1,
  "limit": 20
}

GET /events/{contract_id}

Returns all events for a specific contract.

GET /events/tx/{tx_hash}

Returns all events from a specific transaction.

How It Works

1. On startup, the app connects to PostgreSQL and runs migrations.
2. A background Tokio task (indexer.rs) polls the Soroban RPC getEvents method in a loop.
3. New events are inserted with ON CONFLICT DO NOTHING to avoid duplicates.
4. The Axum HTTP server runs concurrently, serving queries against the indexed data.

Notes

• The indexer polls every 5 seconds when no new ledgers are available, and 10 seconds on error.
• START_LEDGER=0 automatically starts from the latest ledger at boot time.
• All endpoints return JSON. Errors include an "error" field with a description.