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

| | | | | |---|---|---|---| | <img width="4112" height="3518" alt="Screenshot 2025-10-13 at 16-23-46 Cosmos Explorer" src="https://github.com/user-attachments/assets/17c87b19-30f8-4321-b10f-f80adfb75757" /> | <img width="4112" height="2864" alt="Screenshot 2025-10-13 at 16-24-01 Cosmos Explorer" src="https://github.com/user-attachments/assets/9146e9d7-a8a8-4f12-b841-c230314371a7" /> | <img width="4112" height="3312" alt="Screenshot 2025-10-13 at 16-24-09 Cosmos Explorer" src="https://github.com/user-attachments/assets/e934ecae-72f1-41a2-a0cb-8b5f219f468f" /> | <img width="4112" height="3200" alt="Screenshot 2025-10-13 at 16-24-17 Cosmos Explorer" src="https://github.com/user-attachments/assets/3dd522be-4d5c-4053-b665-43466b362459" /> | | <img width="4112" height="3232" alt="Screenshot 2025-10-13 at 16-24-23 Cosmos Explorer" src="https://github.com/user-attachments/assets/de39b3a8-3540-4830-98ff-5c33f20d735b" /> | <img width="4112" height="6610" alt="Screenshot 2025-10-13 at 16-26-04 Cosmos Explorer" src="https://github.com/user-attachments/assets/5889e00e-e164-4530-84b2-5a41ee2dce7d" /> | <img width="4112" height="5790" alt="Screenshot 2025-10-13 at 16-26-25 Cosmos Explorer" src="https://github.com/user-attachments/assets/3c6fcf0c-dd65-4b2e-a7aa-02331c4deb2b" /> | <img width="4112" height="4958" alt="Screenshot 2025-10-13 at 16-26-35 Cosmos Explorer" src="https://github.com/user-attachments/assets/b36bf349-1d40-41a8-baa6-736e42606bfe" /> |

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