# Lethean Testnet — Docker Deployment

Run the full Lethean ecosystem in Docker. No compilation needed.

## Deployment Options

| Compose File | For | Services |
|---|---|---|
| `docker-compose.node.yml` | Home node operator | Daemon + wallet (PoS staking) |
| `docker-compose.exit.yml` | VPN exit node operator | Daemon + wallet + WireGuard |
| `docker-compose.pull.yml` | Full ecosystem | All 8 services + databases |

## Helper Scripts

```bash
bash demos/helpers/chain-info.sh      # Chain height, difficulty, status
bash demos/helpers/chain-aliases.sh   # List on-chain aliases
bash demos/helpers/wallet-address.sh  # Show your wallet address
bash demos/helpers/wallet-balance.sh  # Check LTHN balance
bash health.sh                        # Full ecosystem health check
```

## Quick Start

```bash
# 1. Configure
cp .env.example .env
# Edit .env — at minimum change JWT_SECRET and WALLET_PASSWORD

# 2. Start
docker compose -f docker-compose.pull.yml up -d

# 3. Check
docker compose -f docker-compose.pull.yml ps
```

The daemon takes ~30 seconds to initialise the chain database on first run.
Other services wait for the daemon health check before starting.

## Services

| Service | URL | Description |
|---------|-----|-------------|
| Block Explorer | http://localhost:3335 | Browse blocks, transactions, aliases |
| Trade DEX | http://localhost:3338 | Decentralised exchange frontend |
| Trade API | http://localhost:3336 | REST API for trade operations |
| Mining Pool | http://localhost:2117 | Pool stats API |
| Pool Stratum | localhost:5555 | Connect miners here |
| LNS | http://localhost:5553 | Lethean Name Service HTTP API |
| LNS DNS | localhost:5354 | DNS resolver for .lthn names |
| Daemon RPC | http://localhost:46941 | Chain node JSON-RPC |
| Wallet RPC | http://localhost:46944 | Wallet JSON-RPC |
| Docs | http://localhost:8099 | Documentation site |

## Mining

Connect a ProgPoWZ miner to the pool stratum:

```
stratum+tcp://YOUR_IP:5555
```

Compatible miners:
- **progminer** (recommended) — `progminer -P stratum+tcp://YOUR_WALLET_ADDRESS@localhost:5555`
- **T-Rex** — ProgPoWZ algorithm
- **TeamRedMiner** — ProgPoWZ algorithm

## Wallet

The wallet auto-creates on first start. To check your balance:

```bash
curl -s http://localhost:46944/json_rpc \
  -d '{"jsonrpc":"2.0","id":"0","method":"getbalance"}' \
  -H 'Content-Type: application/json'
```

The wallet runs with PoS mining enabled (`--do-pos-mining`), so it will stake
any balance automatically.

## Chain Status

```bash
curl -s http://localhost:46941/json_rpc \
  -d '{"jsonrpc":"2.0","id":"0","method":"getinfo"}' \
  -H 'Content-Type: application/json' | python3 -m json.tool
```

## Volumes

| Volume | Contains | Backup? |
|--------|----------|---------|
| `chain-data` | Blockchain database (LMDB) | Optional — can resync |
| `wallet-data` | Wallet file + keys | **Critical — back up regularly** |
| `explorer-db` | Explorer PostgreSQL | Can recreate from chain |
| `trade-db` | Trade PostgreSQL | Important for trade history |

### Backup wallet

```bash
docker compose -f docker-compose.pull.yml stop wallet
docker cp lthn-wallet:/wallet ./wallet-backup-$(date +%Y%m%d)
docker compose -f docker-compose.pull.yml start wallet
```

## Ports

All ports can be changed via `.env`. See `.env.example` for the full list.

If you're running behind a firewall and want external access:
- **P2P:** Open port 46942 (TCP) for other nodes to connect
- **Stratum:** Open port 5555 (TCP) for external miners
- **Explorer:** Open port 3335 (TCP) for public block explorer

## Troubleshooting

**Daemon crashes on start:**
Check logs with `docker logs lthn-daemon`. Common causes:
- Port already in use — change ports in `.env`
- Corrupt chain data — remove volume: `docker volume rm docker_chain-data`

**Wallet shows 0 balance:**
The wallet needs to sync with the daemon first. Check sync status in daemon logs.
New wallets start empty — mine or receive LTHN to fund them.

**Pool shows "Daemon died":**
The pool needs both the daemon and wallet running. Check both are healthy:
```bash
docker compose -f docker-compose.pull.yml ps daemon wallet
```

**Explorer shows "offline":**
The explorer connects to the daemon internally. If the daemon is still syncing,
the explorer will show offline until sync completes.

## Stopping

```bash
docker compose -f docker-compose.pull.yml down        # stop containers
docker compose -f docker-compose.pull.yml down -v      # stop + delete data
```

## Building from Source

If you want to build the images yourself instead of pulling pre-built ones:

```bash
docker compose -f docker-compose.ecosystem.yml build
docker compose -f docker-compose.ecosystem.yml up -d
```

This requires the full source tree — see the main repository README.