Cosmos

A lightweight Starknet block explorer designed for local development with devnet environments.

Features

• Real-time indexing of blocks, transactions, events, and L1↔L2 messages
• Fast search by block number, transaction hash, or contract address
• WebSocket updates for live data streaming
• ABI decoding for event parameters and function calls
• Dark mode UI with responsive design

Quick Start with Docker

Option 1: With Local Devnet (Recommended for Development)

Run Cosmos with a local Starknet devnet for testing:

cp .env.example .env
docker compose -f docker-compose.yml -f docker-compose.devnet.yml up

This starts:

• Starknet devnet at http://localhost:5500
• PostgreSQL database at localhost:55432
• Backend API at http://localhost:4600
• Frontend UI at http://localhost:5600

Option 2: With External RPC (Sepolia, Mainnet, or External Devnet)

If you already have a Starknet RPC endpoint or want to use a network:

cp .env.example .env
# Edit .env and set your STARKNET_RPC_URL
# Example: STARKNET_RPC_URL=https://starknet-sepolia.infura.io/v3/YOUR_KEY
docker compose up

This starts only the necessary services (PostgreSQL, Backend, Frontend).

Open http://localhost:5600 in your browser to use the explorer.

Local Development

Prerequisites

• Node.js 20+
• pnpm 9+
• PostgreSQL 15+
• Starknet devnet or RPC endpoint

Setup

1. Install dependencies:

corepack enable
pnpm install

2. Configure environment:

cp .env.example .env
# Edit .env with your database and RPC settings

3. Start PostgreSQL (if not using Docker):

docker run --name cosmos-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=cosmos \
  -p 55432:5432 \
  -d postgres:15

4. Run database migrations:

pnpm --filter @cosmos/backend prisma:migrate dev

5. Start the development servers:

pnpm dev

The backend will be available at http://localhost:4600 and the frontend at http://localhost:5600.

Generating Test Data

Create sample transactions and blocks on devnet:

# Mint ETH to random accounts (creates transactions)
pnpm devnet:mint

# Force create empty blocks
pnpm devnet:blocks

Project Structure

cosmos/
├── apps/
│   ├── backend/    # Fastify API + Prisma indexer
│   └── frontend/   # React + Vite UI
└── packages/       # Shared utilities and configs

Environment Variables

Key configuration options in .env:

• STARKNET_RPC_URL - Starknet RPC endpoint
  • Local devnet: http://localhost:5500 (if using docker-compose.devnet.yml)
  • Sepolia testnet: https://starknet-sepolia.infura.io/v3/YOUR_KEY
  • Mainnet: https://starknet-mainnet.infura.io/v3/YOUR_KEY
  • Custom RPC: Any compatible Starknet JSON-RPC endpoint
• DATABASE_URL - PostgreSQL connection string
• BACKEND_PORT - Backend server port (default: 4600)
• FRONTEND_PORT - Frontend dev server port (default: 5600)
• INDEXER_POLL_INTERVAL_MS - Polling interval in milliseconds (default: 2000)

Commands

pnpm dev              # Start backend + frontend
pnpm build            # Build for production
pnpm lint             # Run ESLint
pnpm test             # Run tests
pnpm devnet:mint      # Generate test transactions
pnpm devnet:blocks    # Create empty blocks

Production Build

Build static assets:

pnpm build

Run the built backend:

export DATABASE_URL=postgres://postgres:postgres@localhost:55432/cosmos
node apps/backend/dist/index.js

Troubleshooting

Backend won't start:

• Verify PostgreSQL is running and accessible
• Check DATABASE_URL is correct
• Ensure Starknet RPC endpoint is reachable
• Check logs: docker compose logs backend

No data appearing:

• Confirm the indexer is connected to the correct RPC URL
• Check backend logs for errors
• Generate test data with pnpm devnet:mint

Prisma errors:

• Regenerate the client: pnpm --filter @cosmos/backend prisma:generate
• Verify migrations are applied: pnpm --filter @cosmos/backend prisma:migrate dev

Docker issues:

• Check all containers are healthy: docker compose ps
• View logs: docker compose logs -f
• Clean restart: docker compose down -v && docker compose up

License

MIT