# SolaceScan Explorer

Multi-tier block explorer and access-control plane for **Chain 138**.

Four access tiers:

| Track | Who | Auth | Examples |
|------|-----|------|---------|
| 1 | Public | None | `/blocks`, `/transactions`, `/search` |
| 2 | Wallet-verified | SIWE JWT | RPC API keys, subscriptions, usage reports |
| 3 | Analytics | SIWE JWT (admin or billed) | Advanced analytics, audit logs |
| 4 | Operator | SIWE JWT (`operator.*`) | `run-script`, mission-control, ops |

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for diagrams of how the
tracks, services, and data stores fit together, and [docs/API.md](docs/API.md)
for the endpoint reference generated from `backend/api/rest/swagger.yaml`.

## Repository layout

```
backend/           Go 1.23 services (api/rest, indexer, auth, analytics, ...)
frontend/          Next.js 14 pages-router app
deployment/        docker-compose and deploy manifests
scripts/           e2e specs, smoke scripts, operator runbooks
docs/              Architecture, API, testing, security, runbook
```

## Quickstart (local)

Prereqs: Docker (+ compose), Go 1.23.x, Node 20.

```bash
# 1. Infra deps
docker compose -f deployment/docker-compose.yml up -d postgres elasticsearch redis

# 2. DB schema
cd backend && go run database/migrations/migrate.go && cd ..

# 3. Backend (port 8080)
export JWT_SECRET=$(openssl rand -hex 32)
export CSP_HEADER="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' http://localhost:8080 ws://localhost:8080"
cd backend/api/rest && go run . &

# 4. Frontend (port 3000)
cd frontend && npm ci && npm run dev
```

Or let `make e2e-full` do everything end-to-end and run Playwright
against the stack (see [docs/TESTING.md](docs/TESTING.md)).

## Configuration

Every credential, URL, and RPC endpoint is an env var. There is no
in-repo production config. Minimum required by a non-dev binary:

| Var | Purpose | Notes |
|-----|---------|-------|
| `JWT_SECRET` | HS256 wallet-auth signing key | Fail-fast if empty |
| `CSP_HEADER` | `Content-Security-Policy` response header | Fail-fast if empty |
| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | Postgres connection | |
| `REDIS_HOST` / `REDIS_PORT` | Redis cache | |
| `ELASTICSEARCH_URL` | Indexer / search backend | |
| `RPC_URL` / `WS_URL` | Upstream Chain 138 RPC | |
| `RPC_PRODUCTS_PATH` | Optional override for `backend/config/rpc_products.yaml` | PR #7 |

Full list: `deployment/ENVIRONMENT_TEMPLATE.env`.

## Testing

```bash
# Unit tests + static checks
cd backend && go test ./... && staticcheck ./... && govulncheck ./...
cd frontend && npm test && npm run test:unit

# Production canary
EXPLORER_URL=https://explorer.d-bis.org make test-e2e

# Full local stack + Playwright
make e2e-full
```

See [docs/TESTING.md](docs/TESTING.md).

## Contributing

Branching, PR template, CI gates, secret handling: see
[CONTRIBUTING.md](CONTRIBUTING.md). Never commit real credentials —
`.gitleaks.toml` will block the push and rotation steps live in
[docs/SECURITY.md](docs/SECURITY.md).

## Licence

MIT.