Open-Audit

The Google Translate for Soroban — an open-source transparency tool for the Stellar/Soroban ecosystem.

---

What is Open-Audit?

Smart contracts on Stellar/Soroban emit events as cryptic, hex-encoded binary data. To the average user — or even most developers — these events are completely unreadable. Open-Audit solves this by:

1. Fetching raw contract events from the Stellar network via Horizon/RPC.
2. Translating them into plain English sentences using a community-maintained Translation Registry.
3. Displaying the results in a clean, searchable dashboard anyone can use.

Example:

Before (Raw)	After (Translated)
0x000000000000000000000000...	Public Key [GABC...1234] transferred 100 USDC to [GXYZ...5678]

---

Tech Stack

• Framework: Next.js 14 (App Router) + TypeScript
• Design System: Tailwind CSS + shadcn/ui
• Stellar Integration: stellar-sdk
• State Management: React Context + Server Components

---

Getting Started

Prerequisites

• Node.js >= 18
• npm >= 9

Installation

git clone https://github.com/your-org/open-audit.git
cd open-audit
npm install
npm run dev

Open http://localhost:3000 in your browser.

For the custom server with WebSocket support and /metrics, run:

npm run dev:ws

Environment Variables

Copy .env.example to .env.local and fill in the values:

cp .env.example .env.local

For microservices architecture, use:

cp .env.microservices.example .env.local

Variable	Description	Default
NEXT_PUBLIC_HORIZON_URL	Stellar Horizon endpoint	https://horizon-testnet.stellar.org
NEXT_PUBLIC_SOROBAN_RPC_URL	Soroban RPC endpoint	https://soroban-testnet.stellar.org
NEXT_PUBLIC_NETWORK_PASSPHRASE	Network passphrase	Testnet passphrase
REDIS_URL	Redis connection URL (microservices)	redis://localhost:6379
REDIS_CHANNEL	Redis Pub/Sub channel (microservices)	stellar:events
PORT	HTTP server port	3000

Available Scripts

Development:

npm run dev              # Standard Next.js dev server
npm run dev:ws           # Legacy monolithic server with WebSocket
npm run dev:decoupled    # Microservices web server (requires Redis)
npm run worker:indexer   # Microservices indexer worker (requires Redis)
npm run test:websocket   # Test WebSocket connection

Production (Microservices):

npm run docker:build     # Build Docker images
npm run docker:up        # Start all services with Docker Compose
npm run docker:down      # Stop all Docker services
npm run docker:logs      # View Docker logs

npm run start:pm2        # Start services with PM2
npm run stop:pm2         # Stop PM2 services
npm run monit:pm2        # Monitor PM2 processes
npm run logs:pm2         # View PM2 logs

Testing & Quality:

npm run test             # Run all tests
npm run lint             # Run ESLint
npm run lint:registry    # Validate translation registry
npm run format           # Format code with Prettier

---

Telemetry

The custom server exposes Prometheus metrics on http://localhost:3000/metrics when running npm run dev:ws.

You can configure OpenTelemetry to export spans to Jaeger by setting:

export JAEGER_ENDPOINT="http://localhost:14268/api/traces"
export OTEL_SERVICE_NAME="open-audit"

The default Jaeger endpoint is http://localhost:14268/api/traces.

---

Architecture

Open-Audit supports two deployment architectures:

🆕 Microservices Architecture (Recommended for Production)

Decoupled, scalable, fault-isolated system using Redis Pub/Sub:

Stellar Network → Indexer Worker → Redis Pub/Sub → Web Server → WebSocket Clients

Benefits:

• ✅ Zero CPU starvation (indexer runs in separate process)
• ✅ Independent horizontal scaling
• ✅ Fault isolation (crashes don't affect other services)
• ✅ Auto-reconnect and message queuing
• ✅ Zero-downtime deployments

Quick Start:

# Option 1: Docker Compose (Easiest)
npm run docker:up

# Option 2: PM2 Process Manager
npm run start:pm2

# Option 3: Manual
Terminal 1: redis-server
Terminal 2: npm run dev:decoupled
Terminal 3: npm run worker:indexer

📚 Documentation:

• Quick Start Guide - Get running in 5 minutes
• Architecture Details - Complete technical documentation
• Testing Guide - Comprehensive testing walkthrough

Legacy Monolithic Architecture

Single-process system (for simple deployments):

Stellar Network → Event Indexer → Translation Engine → WebSocket Server → Frontend Dashboard

⚠️ Known limitations: Under heavy load, indexing can starve the HTTP/WebSocket server of CPU cycles. See deprecation notice in server.ts.

npm run dev:ws

---

For new contributors wanting to understand the system's data flow and internal architecture, see the comprehensive ARCHITECTURE.md guide which includes:

• 📊 Interactive Mermaid diagrams showing data flow
• 🔍 Component deep dives for each service
• 📝 Step-by-step event journey from blockchain to UI
• 🛠️ Development guides for adding new features

Quick Overview:

1. Event Indexer (lib/stellar/, src/worker/) — Polls Stellar RPC with resilient rate limiting
2. Translation Engine (lib/translator/) — Converts XDR to human-readable text
3. Redis Pub/Sub (microservices only) — Message broker for event distribution
4. WebSocket Server (server-decoupled.ts or server.ts) — Broadcasts events in real-time
5. Frontend Dashboard (app/dashboard/, components/) — Interactive UI

---

Project Structure

open-audit/
├── app/                    # Next.js App Router pages
│   ├── dashboard/          # Main dashboard page
│   ├── api/                # API routes (health checks, etc.)
│   ├── layout.tsx          # Root layout with theme provider
│   └── page.tsx            # Landing / redirect
├── components/             # Reusable UI components
│   ├── ui/                 # shadcn/ui primitives
│   ├── dashboard/          # Dashboard-specific components
│   └── theme/              # Dark mode toggle
├── lib/
│   ├── translator/         # 🔑 The Translation Registry core logic
│   │   ├── types.ts        # RawEvent / TranslatedEvent interfaces
│   │   ├── registry.ts     # Registry lookup function
│   │   └── blueprints/     # Per-contract translation blueprints
│   ├── stellar/            # Stellar SDK helpers
│   │   ├── indexer.ts      # Event polling with rate limit handling
│   │   └── client.ts       # RPC client configuration
│   ├── resilience/         # ⚡ Rate limiting & circuit breaker
│   │   ├── token-bucket.ts # Token bucket rate limiter
│   │   ├── circuit-breaker.ts # Circuit breaker pattern
│   │   └── resilient-client.ts # Resilient RPC client wrapper
│   ├── hooks/              # React hooks for live data
│   └── utils.ts            # Shared utilities
├── src/
│   └── worker/             # 🆕 Microservices architecture
│       └── indexer.ts      # Standalone indexer worker
├── scripts/
│   ├── lint-registry.ts    # Translation registry validation
│   └── test-websocket-client.js # WebSocket testing tool
├── docs/
│   └── good-first-issues.json
├── server.ts               # Legacy monolithic server (deprecated)
├── server-decoupled.ts     # 🆕 Microservices web server
├── ecosystem.config.js     # 🆕 PM2 configuration
├── docker-compose.microservices.yml # 🆕 Docker Compose config
├── Dockerfile.worker       # 🆕 Indexer worker Docker image
├── Dockerfile.web          # 🆕 Web server Docker image
├── ARCHITECTURE.md         # 📖 Detailed architecture guide
├── MICROSERVICES_ARCHITECTURE.md # 🆕 Microservices documentation
├── QUICKSTART_MICROSERVICES.md   # 🆕 Quick start guide
├── MICROSERVICES_TESTING_GUIDE.md # 🆕 Testing guide
└── public/

---

The Translation Registry

The heart of Open-Audit is the Translation Registry in /lib/translator/. Each contract gets a blueprint — a mapping from raw event topics/data to a human-readable template.

To add support for a new contract, create a file in /lib/translator/blueprints/ and register it in registry.ts. See CONTRIBUTING.md for a step-by-step guide.

---

Contributing

We welcome contributions of all sizes! See CONTRIBUTING.md to get started.

Good first issues are listed in /docs/good-first-issues.json.

---

License

MIT © Open-Audit Contributors