docs: add ecosystem wiki — Docker deployment, mining, services, troubleshooting
Co-Authored-By: Charon <charon@lethean.io>
Claude
commit
670ec75b6a
6 changed files with 502 additions and 0 deletions
58
Chain-Status.md
Normal file
58
Chain-Status.md
Normal file
|
|
@ -0,0 +1,58 @@
|
|||
# Chain Status
|
||||
|
||||
## Checking 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
|
||||
```
|
||||
|
||||
## Key Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `height` | Current blockchain height |
|
||||
| `is_hardfok_active` | Array of hardfork activation status [HF0..HF6] |
|
||||
| `pow_difficulty` | Current Proof of Work difficulty |
|
||||
| `pos_difficulty` | Current Proof of Stake difficulty |
|
||||
| `incoming_connections_count` | Peers connected to this node |
|
||||
| `outgoing_connections_count` | Peers this node connects to |
|
||||
| `alias_count` | Number of registered .lthn aliases |
|
||||
| `tx_count` | Total transactions on chain |
|
||||
|
||||
## Hardfork Schedule
|
||||
|
||||
| HF | Features |
|
||||
|----|----------|
|
||||
| HF0 | Genesis |
|
||||
| HF1 | Basic chain operations |
|
||||
| HF2 | PoS mining |
|
||||
| HF3 | Alias system |
|
||||
| HF4 | ProgPoWZ mining algorithm |
|
||||
| HF5 | Confidential assets |
|
||||
| HF6 | Pending — next upgrade |
|
||||
|
||||
## Block Explorer
|
||||
|
||||
Browse blocks, transactions, and aliases at:
|
||||
|
||||
```
|
||||
http://localhost:3335
|
||||
```
|
||||
|
||||
## Get Latest Block
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:46941/json_rpc \
|
||||
-d '{"jsonrpc":"2.0","id":"0","method":"getlastblockheader"}' \
|
||||
-H 'Content-Type: application/json'
|
||||
```
|
||||
|
||||
## Get Block by Height
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:46941/json_rpc \
|
||||
-d '{"jsonrpc":"2.0","id":"0","method":"getblockheaderbyheight","params":{"height":100}}' \
|
||||
-H 'Content-Type: application/json'
|
||||
```
|
||||
135
Docker-Deployment.md
Normal file
135
Docker-Deployment.md
Normal file
|
|
@ -0,0 +1,135 @@
|
|||
# Docker Deployment
|
||||
|
||||
Run the full Lethean ecosystem in Docker. No compilation needed.
|
||||
|
||||
## 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
|
||||
bash health.sh
|
||||
```
|
||||
|
||||
The daemon takes ~30 seconds to initialise. 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 | http://localhost:5553 | Lethean Name Service 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 |
|
||||
|
||||
## Configuration
|
||||
|
||||
All settings are in `.env`. Copy from `.env.example`:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Key settings:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `PUBLIC_HOST` | localhost | Hostname for external access |
|
||||
| `WALLET_PASSWORD` | (empty) | Wallet encryption password |
|
||||
| `JWT_SECRET` | change-me... | Trade API authentication secret |
|
||||
| `DAEMON_LOG_LEVEL` | 1 | 0=minimal, 1=normal, 2=detailed |
|
||||
|
||||
All ports can be overridden — see `.env.example` for the full list.
|
||||
|
||||
## Remote Deployment
|
||||
|
||||
Use the deploy script to transfer images and config to a remote server:
|
||||
|
||||
```bash
|
||||
bash deploy.sh user@server
|
||||
bash deploy.sh user@server /opt/lethean/docker
|
||||
```
|
||||
|
||||
This will:
|
||||
1. Build the image bundle if not already built
|
||||
2. Transfer config files and images via SCP
|
||||
3. Load images on the remote server
|
||||
4. Start the stack
|
||||
|
||||
## Auto-start on Boot
|
||||
|
||||
Install the systemd service:
|
||||
|
||||
```bash
|
||||
sudo cp lethean-testnet.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable lethean-testnet
|
||||
```
|
||||
|
||||
## Volumes and Backup
|
||||
|
||||
| Volume | Contains | Backup Priority |
|
||||
|--------|----------|-----------------|
|
||||
| `chain-data` | Blockchain database | Low — can resync from network |
|
||||
| `wallet-data` | Wallet file + keys | **Critical** |
|
||||
| `explorer-db` | Explorer PostgreSQL | Low — rebuilds from chain |
|
||||
| `trade-db` | Trade PostgreSQL | Medium — 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
|
||||
```
|
||||
|
||||
## Building from Source
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.ecosystem.yml build
|
||||
docker compose -f docker-compose.ecosystem.yml up -d
|
||||
```
|
||||
|
||||
Requires the full source tree with all submodules.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Docker Network │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ daemon │◄──│ wallet │ │ lns │ │
|
||||
│ │ :36941 │ │ :36944 │ │ :5553/54 │ │
|
||||
│ └────┬──┬──┘ └──────────┘ └──────────┘ │
|
||||
│ │ │ │
|
||||
│ ┌────┴──┴───────────────┐ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌──────────┐ ┌──────────────┐ ┌──────────┐ │
|
||||
│ │ explorer │ │ trade-api │ │ pool │ │
|
||||
│ │ :3335 │ │ :3336 │ │ :5555 │ │
|
||||
│ └────┬─────┘ └──────┬──────┘ └────┬─────┘ │
|
||||
│ │ │ │ │
|
||||
│ ┌────┴─────┐ ┌──────┴──────┐ ┌───┴──────┐ │
|
||||
│ │explorer-db│ │ trade-db │ │pool-redis│ │
|
||||
│ │ postgres │ │ postgres │ │ redis │ │
|
||||
│ └──────────┘ └─────────────┘ └──────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────┐ │
|
||||
│ │trade-frontend│ │ docs │ │
|
||||
│ │ :30289 │ │ :80 │ │
|
||||
│ └──────────────┘ └──────────┘ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
35
Home.md
Normal file
35
Home.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
# Lethean Blockchain
|
||||
|
||||
Lethean blockchain — Zano fork with ProgPoWZ mining, confidential assets, and the Lethean Name Service.
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Docker Deployment](Docker-Deployment) — run the full ecosystem in Docker
|
||||
- [Mining Guide](Mining-Guide) — connect a miner to the pool
|
||||
- [Chain Status](Chain-Status) — current testnet state
|
||||
- [Services](Services) — all ecosystem services and ports
|
||||
- [Troubleshooting](Troubleshooting) — common issues and fixes
|
||||
|
||||
## Current State
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Hardforks | HF0-5 active, HF6 pending |
|
||||
| Algorithm | ProgPoWZ (PoW) + PoS |
|
||||
| Block time | ~120 seconds target |
|
||||
| Emission | 1 LTHN per block |
|
||||
| Aliases | 14 registered on chain |
|
||||
|
||||
## Ecosystem
|
||||
|
||||
The full ecosystem runs as Docker containers:
|
||||
|
||||
| Service | Description |
|
||||
|---------|-------------|
|
||||
| Chain daemon | C++ node (Zano fork) |
|
||||
| Wallet RPC | CLI wallet with PoS staking |
|
||||
| Block explorer | Next.js web explorer |
|
||||
| Trade DEX | Decentralised exchange |
|
||||
| Mining pool | ProgPoWZ stratum pool |
|
||||
| LNS | Lethean Name Service (DNS + HTTP) |
|
||||
| Docs | Documentation site |
|
||||
66
Mining-Guide.md
Normal file
66
Mining-Guide.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# Mining Guide
|
||||
|
||||
Lethean uses **ProgPoWZ** for Proof of Work and supports **Proof of Stake** via the wallet.
|
||||
|
||||
## ProgPoWZ Mining (GPU)
|
||||
|
||||
Connect a ProgPoWZ-compatible miner to the pool stratum:
|
||||
|
||||
```
|
||||
stratum+tcp://YOUR_WALLET_ADDRESS@POOL_HOST:5555
|
||||
```
|
||||
|
||||
### Compatible Miners
|
||||
|
||||
| Miner | Platform | Command |
|
||||
|-------|----------|---------|
|
||||
| **progminer** | AMD/NVIDIA | `progminer -P stratum+tcp://WALLET@host:5555` |
|
||||
| **T-Rex** | NVIDIA | `t-rex -a progpowz -o stratum+tcp://host:5555 -u WALLET` |
|
||||
| **TeamRedMiner** | AMD | `teamredminer -a progpow -o stratum+tcp://host:5555 -u WALLET` |
|
||||
|
||||
### Pool Endpoints
|
||||
|
||||
| Endpoint | Port | Protocol |
|
||||
|----------|------|----------|
|
||||
| Stratum | 5555 | TCP (unencrypted) |
|
||||
| Stratum SSL | 7777 | TCP (TLS) |
|
||||
| Pool API | 2117 | HTTP |
|
||||
| Pool Web | 8888 | HTTP |
|
||||
|
||||
### Pool Stats
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:2117/stats | python3 -m json.tool
|
||||
```
|
||||
|
||||
## Proof of Stake
|
||||
|
||||
The wallet automatically stakes when `--do-pos-mining` is enabled (default in Docker setup).
|
||||
|
||||
To check staking status:
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:46944/json_rpc \
|
||||
-d '{"jsonrpc":"2.0","id":"0","method":"getbalance"}' \
|
||||
-H 'Content-Type: application/json'
|
||||
```
|
||||
|
||||
PoS requires an unlocked balance. Mined coins need 10 block confirmations before they can stake.
|
||||
|
||||
## Getting a Wallet Address
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:46944/json_rpc \
|
||||
-d '{"jsonrpc":"2.0","id":"0","method":"getaddress"}' \
|
||||
-H 'Content-Type: application/json'
|
||||
```
|
||||
|
||||
## Block Reward
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Block reward | 1 LTHN |
|
||||
| Block time | ~120 seconds |
|
||||
| Blocks per day | ~720 |
|
||||
| Algorithm | ProgPoWZ |
|
||||
| Difficulty | Adaptive |
|
||||
105
Services.md
Normal file
105
Services.md
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
# Ecosystem Services
|
||||
|
||||
All services run as Docker containers and communicate over an internal Docker network.
|
||||
|
||||
## Chain Services
|
||||
|
||||
### Daemon (C++ Node)
|
||||
|
||||
The core blockchain node. Validates blocks, serves RPC, and connects to the P2P network.
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Image | `lthn/chain:testnet` |
|
||||
| RPC Port | 36941 (mapped to 46941) |
|
||||
| P2P Port | 36942 (mapped to 46942) |
|
||||
| API Docs | http://localhost:46943/swagger/ui |
|
||||
| Data | `/data` volume (LMDB) |
|
||||
|
||||
**RPC Example:**
|
||||
|
||||
```bash
|
||||
curl -s http://localhost:46941/json_rpc \
|
||||
-d '{"jsonrpc":"2.0","id":"0","method":"getinfo"}' \
|
||||
-H 'Content-Type: application/json'
|
||||
```
|
||||
|
||||
### Wallet RPC
|
||||
|
||||
CLI wallet with PoS staking enabled.
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Image | `lthn/chain:testnet` |
|
||||
| RPC Port | 36944 (mapped to 46944) |
|
||||
| Data | `/wallet` volume |
|
||||
|
||||
### Block Explorer
|
||||
|
||||
Next.js web application showing blocks, transactions, and aliases.
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Image | `lthn/explorer:testnet` |
|
||||
| Port | 3335 |
|
||||
| Database | PostgreSQL (`explorer-db`) |
|
||||
|
||||
## Trade Services
|
||||
|
||||
### Trade API
|
||||
|
||||
REST API for the decentralised exchange.
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Image | `lthn/trade-api:testnet` |
|
||||
| Port | 3336 |
|
||||
| Database | PostgreSQL (`trade-db`) |
|
||||
|
||||
### Trade Frontend
|
||||
|
||||
Next.js DEX web interface.
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Image | `lthn/trade-frontend:testnet` |
|
||||
| Port | 3338 (internal 30289) |
|
||||
|
||||
## Mining Pool
|
||||
|
||||
ProgPoWZ stratum mining pool with web interface.
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Image | `lthn/pool:testnet` |
|
||||
| Stratum | 5555 |
|
||||
| SSL | 7777 |
|
||||
| API | 2117 |
|
||||
| Web | 8888 |
|
||||
| Cache | Redis (`pool-redis`) |
|
||||
|
||||
## Lethean Name Service (LNS)
|
||||
|
||||
DNS resolver and HTTP API for .lthn domain names.
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Image | `lthn/lns:testnet` |
|
||||
| HTTP API | 5553 |
|
||||
| DNS | 5354 (TCP + UDP) |
|
||||
|
||||
**Query a name:**
|
||||
|
||||
```bash
|
||||
dig @localhost -p 5354 example.lthn A
|
||||
curl -s http://localhost:5553/api/names
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
Static documentation site.
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Image | `lthn/docs:testnet` |
|
||||
| Port | 8099 |
|
||||
103
Troubleshooting.md
Normal file
103
Troubleshooting.md
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
# Troubleshooting
|
||||
|
||||
## Health Check
|
||||
|
||||
Run the health check script:
|
||||
|
||||
```bash
|
||||
bash health.sh
|
||||
```
|
||||
|
||||
All services should show green. If any show red, check the logs:
|
||||
|
||||
```bash
|
||||
docker logs lthn-daemon
|
||||
docker logs lthn-wallet
|
||||
docker logs lthn-explorer
|
||||
docker logs lthn-trade-api
|
||||
docker logs lthn-pool
|
||||
docker logs lthn-lns
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Daemon crashes on start
|
||||
|
||||
**Symptom:** `lthn-daemon` shows `Restarting` in `docker compose ps`
|
||||
|
||||
**Causes:**
|
||||
- Port already in use — another process is on 46941. Kill it or change `DAEMON_RPC_PORT` in `.env`
|
||||
- Corrupt chain data — remove volume: `docker volume rm docker_chain-data`
|
||||
- Lock file — previous daemon didn't shut down cleanly. Remove `/data/lock.lck` inside the volume
|
||||
|
||||
### Wallet shows 0 balance
|
||||
|
||||
**Causes:**
|
||||
- New wallet — Docker creates a fresh wallet on first start. Mine or receive LTHN
|
||||
- Wallet syncing — check daemon height vs wallet's last known block
|
||||
- Wrong wallet file — if migrating, mount the existing wallet via `docker-compose.local.yml`
|
||||
|
||||
### Pool shows "Daemon died"
|
||||
|
||||
**Cause:** Pool can't reach daemon or wallet RPC.
|
||||
|
||||
**Fix:** Check both daemon and wallet are healthy:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.pull.yml ps daemon wallet
|
||||
```
|
||||
|
||||
The pool needs the daemon health check to pass before starting.
|
||||
|
||||
### Explorer shows "offline"
|
||||
|
||||
**Cause:** Explorer can't reach daemon RPC.
|
||||
|
||||
**Fix:** Wait for daemon to fully sync. The explorer connects to `daemon:36941` inside the Docker network.
|
||||
|
||||
### Trade API returns connection errors
|
||||
|
||||
**Cause:** DNS resolution inside Docker network failed.
|
||||
|
||||
**Fix:** Restart the trade-api container:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.pull.yml restart trade-api
|
||||
```
|
||||
|
||||
### Port already in use
|
||||
|
||||
**Symptom:** `failed to bind host port: address already in use`
|
||||
|
||||
**Fix:** Either kill the process using the port or change the port in `.env`:
|
||||
|
||||
```bash
|
||||
# Find what's using the port
|
||||
lsof -i :46941
|
||||
# Or change port
|
||||
echo "DAEMON_RPC_PORT=47941" >> .env
|
||||
docker compose -f docker-compose.pull.yml up -d
|
||||
```
|
||||
|
||||
### Services can't find each other
|
||||
|
||||
**Cause:** Container was created outside of compose (manual `docker run`).
|
||||
|
||||
**Fix:** Remove it and let compose recreate it:
|
||||
|
||||
```bash
|
||||
docker rm -f lthn-trade-api
|
||||
docker compose -f docker-compose.pull.yml up -d trade-api
|
||||
```
|
||||
|
||||
## Reset Everything
|
||||
|
||||
```bash
|
||||
# Stop and remove all containers and volumes
|
||||
docker compose -f docker-compose.pull.yml down -v
|
||||
|
||||
# Start fresh
|
||||
docker compose -f docker-compose.pull.yml up -d
|
||||
```
|
||||
|
||||
This will delete all chain data, wallet files, and databases.
|
||||
Loading…
Add table
Reference in a new issue