🔍 Soroban Verify

A production-ready Soroban smart contract verification tool for the Stellar ecosystem

Soroban Verify is a complete verification platform that allows developers to verify their deployed Soroban contracts, similar to Sourcify on Ethereum. It provides a CLI tool, REST API, web dashboard, and automated indexer.

---

📋 Table of Contents

• Overview
• Why This Project
• Features
• Tech Stack
• Architecture
• Project Structure
• Quick Start
• CLI Tool
• API Documentation
• Frontend Dashboard
• Development
• Testing
• Docker
• Deployment
• Contributing
• Security
• Support
• License

---

🎯 Overview

Soroban Verify is a decentralized verification platform for Stellar Soroban smart contracts. It solves a critical gap in the ecosystem: there is currently no standardized way to verify that a deployed contract's bytecode matches its public source code.

This project provides:

Component	Description
CLI Tool	Developers run soroban verify to upload and verify their contracts
Verification API	REST API for block explorers and wallets to query verification status
Web Dashboard	Browse and search verified contracts
Automated Indexer	Scans the blockchain and automatically detects new contracts

---

🔥 Why This Project

Problem	Solution
No contract verification on Stellar	First complete verification tool
Users can't trust contracts	✅ Verified badge shows trust
Explorers lack metadata	API provides source code and ABIs
Developers have no standard	CLI tool standardizes the process

---

✨ Features

Feature	Description
CLI Verification	One-command verification: soroban verify
Multi-platform CLI	Works on Windows, Mac, Linux
WASM Hash Matching	Compares local WASM with on-chain bytecode
Source Code Storage	Stores source code and metadata permanently
Verification API	REST endpoints for explorers and wallets
Web Dashboard	Browse and search verified contracts
Automated Indexer	Scans Stellar for new contract deployments
GitHub Actions CI	Automated testing and deployment
Docker Support	Easy deployment with docker-compose

---

🛠 Tech Stack

Component	Technology	Version
CLI Tool	Rust	1.70+
CLI Framework	Clap	4.4
WASM Processing	wasmparser	0.118
Backend API	NestJS	10.x
Backend Language	TypeScript	5.x
Database	PostgreSQL	15.x
ORM	TypeORM	0.3.x
Frontend	Next.js	14.2
Frontend Language	TypeScript	5.x
Styling	Tailwind CSS	3.4
Indexer	Node.js	20.x
Container	Docker	-
CI/CD	GitHub Actions	-

---

🏗 Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│ Developer Workflow                                                         │
│                                                                             │
│ ┌──────────────┐   ┌──────────────┐   ┌──────────────┐                     │
│ │ Developer    │──▶│ soroban      │──▶│ Soroban      │                     │
│ │ (Rust)       │   │ verify       │   │ Verify API   │                     │
│ └──────────────┘   └──────────────┘   └──────────────┘                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Soroban Verify Platform                                                    │
│                                                                             │
│ ┌──────────────┐   ┌──────────────┐   ┌──────────────┐                     │
│ │ CLI Tool     │   │ REST API     │   │ Dashboard    │                     │
│ │ (Rust)       │──▶│ (NestJS)     │──▶│ (Next.js)    │                     │
│ └──────────────┘   └──────────────┘   └──────────────┘                     │
│         │                  │                  │                             │
│         ▼                  ▼                  ▼                             │
│ ┌──────────────────────────────────────────────────────────┐                │
│ │ PostgreSQL Database                                     │                │
│ │ (Contracts, Verifications, Users)                       │                │
│ └──────────────────────────────────────────────────────────┘                │
│                                                                             │
│ ┌──────────────────────────────────────────────────────────┐                │
│ │ Automated Indexer                                       │                │
│ │ (Scans Stellar for new contract deploys)                │                │
│ └──────────────────────────────────────────────────────────┘                │
│                                                                             │
│ ▼                                                                           │
│ ┌──────────────────────────────────────────────────────────┐                │
│ │ Stellar Blockchain                                      │                │
│ │ (Soroban Contract Deployments)                          │                │
│ └──────────────────────────────────────────────────────────┘                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ End Users                                                                   │
│                                                                             │
│ ┌──────────────┐   ┌──────────────┐   ┌──────────────┐                     │
│ │ Block        │──▶│ Wallets      │──▶│ Developers   │                     │
│ │ Explorers    │   │ (Freighter)  │   │ (Checking)   │                     │
│ └──────────────┘   └──────────────┘   └──────────────┘                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

📁 Project Structure

soroban-verify/
├── cli/ # Rust CLI Tool (13 files)
│   ├── src/
│   │   ├── main.rs # Entry point
│   │   ├── commands/
│   │   │   ├── mod.rs # Command module
│   │   │   ├── verify.rs # Verify command logic
│   │   │   ├── publish.rs # Publish command
│   │   │   ├── status.rs # Check verification status
│   │   │   └── list.rs # List verified contracts
│   │   ├── config.rs # Configuration management
│   │   ├── api.rs # API client for backend
│   │   ├── wasm.rs # WASM compilation & hashing
│   │   ├── error.rs # Error handling
│   │   └── utils.rs # Utility functions
│   ├── tests/
│   │   └── integration_test.rs # Integration tests
│   └── Cargo.toml # Rust dependencies
│
├── api/ # NestJS Backend (28 files)
│   ├── src/
│   │   ├── main.ts # Application entry point
│   │   ├── app.module.ts # Root module
│   │   ├── modules/
│   │   │   ├── contracts/ # Contract management
│   │   │   ├── verification/ # Verification logic
│   │   │   ├── users/ # User management
│   │   │   ├── auth/ # Authentication
│   │   │   ├── admin/ # Admin panel
│   │   │   └── stats/ # Statistics
│   │   ├── common/ # Shared utilities
│   │   ├── config/
│   │   ├── database/
│   │   └── workers/
│   ├── test/
│   ├── package.json
│   └── Dockerfile
│
├── frontend/ # Next.js Dashboard (18 files)
│   ├── src/
│   │   ├── app/
│   │   ├── components/
│   │   ├── lib/
│   │   ├── hooks/
│   │   ├── contexts/
│   │   └── styles/
│   ├── package.json
│   └── Dockerfile
│
├── indexer/ # Automated Indexer
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
│
├── .github/
│   └── workflows/
│
├── docker-compose.yml
├── .gitignore
├── LICENSE
└── README.md

---

🚀 Quick Start

Prerequisites

Requirement	Version	Installation
Node.js	18+	https://nodejs.org
Rust	1.70+	https://rustup.rs
PostgreSQL	15+	https://postgresql.org
Docker	Latest	https://docker.com

Using Docker (Recommended)

# Clone the repository
git clone https://github.com/SorobanVerify/soroban-verify.git
cd soroban-verify

# Start all services
docker-compose up -d

# Services will be available at:
# - API: http://localhost:3001
# - Frontend: http://localhost:3000
# - PostgreSQL: localhost:5432

Manual Installation

# Backend
cd api
npm install
cp .env.example .env
npm run start:dev

# Frontend (new terminal)
cd frontend
npm install
cp .env.example .env.local
npm run dev

# Indexer (new terminal)
cd indexer
npm install
npm run start:dev

---

🔧 CLI Tool

Installation

# From source
cd cli
cargo install --path .

# Or via cargo
cargo install soroban-verify

Usage

# Verify a contract
soroban verify --contract-id <CONTRACT_ID> --path ./contract

# Check verification status
soroban status --contract-id <CONTRACT_ID>

# List all verified contracts
soroban list

# Publish source code only
soroban publish --contract-id <CONTRACT_ID> --path ./contract

---

📡 API Documentation

Base URL

http://localhost:3001/api/v1

Endpoints

Method	Endpoint	Description
POST	/contracts	Create contract entry
GET	/contracts	List contracts
GET	/contracts/:id	Get contract details
POST	/verification/verify	Submit for verification
GET	/verification/status/:id	Check verification status
GET	/verification/contract/:contractId	Get verification for contract
POST	/users	Create user
GET	/users/me	Get current user
POST	/auth/login	Login
POST	/auth/register	Register
GET	/stats	Platform statistics
GET	/health	Health check

Example Request

# Verify a contract
curl -X POST http://localhost:3001/api/v1/verification/verify \
  -H "Content-Type: application/json" \
  -d '{
    "contractId": "CCXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "sourceCode": "base64_encoded_source",
    "wasmHash": "0x1234..."
  }'

---

💻 Frontend Dashboard

Pages

Page	Route	Description
Home	/	Landing page
Contract Details	/contracts/:id	View verified contract
Verify	/verify	Submit contract for verification
Dashboard	/dashboard	User dashboard
Admin	/admin	Admin panel

Features

• 🔍 Search verified contracts
• ✅ Verification status badges
• 📄 Source code viewer
• 📊 Statistics dashboard
• 👤 User authentication
• 🛡️ Admin moderation

---

💻 Development

Backend Scripts

Command	Description
npm run start:dev	Start with hot reload
npm run build	Build for production
npm run start:prod	Run production build
npm run lint	Run ESLint
npm run format	Format with Prettier
npm run test	Run unit tests
npm run test:cov	Run tests with coverage
npm run test:e2e	Run e2e tests

Frontend Scripts

Command	Description
npm run dev	Start development server
npm run build	Build for production
npm run start	Run production build
npm run lint	Run ESLint

CLI Development

Command	Description
cargo build	Build the CLI
cargo run -- verify --contract-id	Run with args
cargo test	Run tests
cargo fmt	Format code
cargo clippy	Run linter

---

🧪 Testing

Backend Tests

cd api
npm run test
npm run test:cov
npm run test:e2e

CLI Tests

cd cli
cargo test
cargo test -- --nocapture

Frontend Tests

cd frontend
npm run test
npm run test:e2e

---

🐳 Docker

Build Images

# Build all services
docker-compose build

# Build specific service
docker build -t soroban-verify-api ./api
docker build -t soroban-verify-frontend ./frontend

Run with Docker Compose

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Docker Compose Configuration

version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: soroban_verify
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  api:
    build: ./api
    ports:
      - "3001:3001"
    depends_on:
      - postgres
    environment:
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USERNAME: postgres
      DB_PASSWORD: postgres
      DB_DATABASE: soroban_verify

  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    depends_on:
      - api

volumes:
  postgres_data:

---

🚢 Deployment

Deploy to Production

# Build the application
docker-compose -f docker-compose.prod.yml build

# Push images to registry
docker push soroban-verify-api:latest
docker push soroban-verify-frontend:latest

# Deploy with environment variables
docker-compose -f docker-compose.prod.yml up -d

Environment Variables

Variable	Description	Default
NODE_ENV	Environment	development
PORT	API port	3001
DB_HOST	Database host	localhost
DB_PORT	Database port	5432
DB_USERNAME	Database user	postgres
DB_PASSWORD	Database password	postgres
DB_DATABASE	Database name	soroban_verify
JWT_SECRET	JWT signing secret	-
STELLAR_NETWORK	Stellar network	testnet

---

🤝 Contributing

We welcome contributions! Please read our CONTRIBUTING.md for guidelines.

Commit Convention

Type	Description
feat	New feature
fix	Bug fix
docs	Documentation
style	Code style
refactor	Code refactor
test	Testing
chore	Maintenance

Pull Request Process

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

---

🔒 Security

Reporting Vulnerabilities

Please DO NOT file public issues for security vulnerabilities.

Email: security@sorobanverify.com

Include:

• Description of the vulnerability
• Steps to reproduce
• Potential impact

Security Best Practices

• Never commit .env files
• Always use environment variables for secrets
• Validate all user inputs
• Use HTTPS in production
• Regular security audits

---

🆘 Support

Channel	Link
GitHub Issues	Open an issue
Discord	Join Discord
Email	team@sorobanverify.com

---

📄 License

MIT © Soroban Verify

Built on Stellar Soroban | Making Smart Contracts Trustable 🔍