Soroban Registry

A contract registry and package manager for the Soroban smart‑contract ecosystem on Stellar.

Soroban Registry lets developers publish, discover, and verify Soroban contracts across Stellar networks, similar to how npm and crates.io serve JavaScript and Rust communities.[cite:352]

Production: https://soroban-registry.vercel.app/

---

Features

• Registry & Discovery – Search and browse contracts by network, tags, category, and publisher.
• Source Verification – Verify that on‑chain bytecode matches published source.
• Versioning & Changelogs – Track versions, semver compatibility, and breaking changes.
• Multi‑Network Support – Mainnet, Testnet, and Futurenet in a single registry.[cite:352]
• Publisher Profiles – Attach contracts to publishers and their deployment history.
• Analytics – Usage statistics and interaction metrics for contracts.
• Web App + CLI – Next.js frontend for browsing; Rust CLI for developer workflows.

---

Project Layout

soroban-registry/
├── backend/        # Rust backend services (Axum API, indexer, verifier)
├── frontend/       # Next.js web application
├── cli/            # Rust CLI tool
├── database/       # PostgreSQL migrations
└── examples/       # Example contracts

---

Prerequisites

• Rust 1.75+ – https://rustup.rs/
• Node.js 20+ – https://nodejs.org/
• PostgreSQL 16+ – https://www.postgresql.org/download/
• Docker (optional, recommended for local all‑in‑one setup)[cite:352]

---

Quick Start

1. Clone and configure

git clone https://github.com/ALIPHATICHYD/Soroban-Registry.git
cd Soroban-Registry

cp .env.example .env

2. Run everything with Docker (recommended)

docker-compose up -d

# API:      http://localhost:3001
# Frontend: http://localhost:3000

This starts PostgreSQL, the backend API, and the Next.js frontend with sensible defaults.[cite:352]

---

Running From Source

Database

createdb soroban_registry
export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/soroban_registry"

sqlx migrate run --source database/migrations

Persistent PostgreSQL

The repository's docker-compose.yml defines a named volume, postgres_data, for the Postgres service. That means the database survives container restarts and docker-compose down; your data is only removed if you explicitly delete the volume.

# Start or reattach to the same database instance
docker-compose up -d postgres

# Apply migrations against the persistent database
docker-compose exec postgres psql -U postgres -d soroban_registry -c "SELECT 1"
sqlx migrate run --source database/migrations

# Stop services without deleting data
docker-compose down

# Remove the database data only if you want a clean slate
docker-compose down -v

Use the same DATABASE_URL on future runs so the backend, SQLx checks, and any local tools all connect to the same persisted database.

Backend API

cd backend
cargo build --release
cargo run --bin api

The API server will listen on the address configured in your .env (commonly http://localhost:3001).[cite:352]

Frontend

cd frontend
pnpm install
pnpm dev

Visit http://localhost:3000 to browse the registry UI.

---

Installing and Using the CLI

The CLI lets you interact with the registry directly from your terminal.[cite:352]

Install from source

# From the repo root
cargo install --path cli

This installs a soroban-registry binary into your Cargo bin directory.

Common commands

# Search for contracts
soroban-registry search "token" --category defi --verified-only --network testnet,futurenet

# Get contract details
soroban-registry info <contract-id>

# Publish a contract
soroban-registry publish --contract-path ./my-contract

# Verify a contract against source
soroban-registry verify <contract-id> --source ./src

Configuration is stored at ~/.soroban-registry/config.toml. A legacy ~/.soroban-registry.toml file is migrated automatically if present.[cite:352]

---

API Overview

The backend exposes a REST API suitable for integration with dashboards, bots, and CI:

• GET /api/contracts – List and search contracts
• GET /api/contracts/:id – Contract details
• POST /api/contracts – Publish a new contract
• GET /api/contracts/:id/versions – Version history
• GET /api/contracts/:id/changelog – Changelog with breaking‑change markers
• GET /api/publishers/:id – Publisher details
• GET /api/publishers/:id/contracts – Contracts by publisher
• GET /api/stats – Registry‑level stats
• GET /health – Health check endpoint[cite:352]

See the OpenAPI spec (coming soon) or the backend/api handlers for full details.

---

Contributing

Contributions from the Stellar/Soroban community are welcome.

1. Fork the repository.
2. Create a branch: git checkout -b feature/short-description
3. Make changes and add tests where appropriate.
4. Run checks:

   # Rust
   cargo fmt --all
   cargo test --all
   
   # TypeScript
   cd frontend
   pnpm lint
   pnpm test

5. Commit: git commit -m "feat: add <short description>"
6. Push and open a PR against main.

Bug reports and feature requests can be filed as GitHub Issues: https://github.com/ALIPHATICHYD/Soroban-Registry/issues

---

Community & Support

• Soroban SDK – https://github.com/stellar/rs-soroban-sdk
• Stellar Docs – https://developers.stellar.org/
• Stellar Community Discord – https://discord.gg/stellar[cite:352]

---

License

Soroban Registry is licensed under the MIT License. See LICENSE for details.[cite:352]