mirror of
https://github.com/sonr-io/sonr.git
synced 2026-08-02 17:31:39 +00:00
Prad NukalaandGitHub
ebfa2b062a
* No commit suggestions generated * No commit suggestions generated * No commit suggestions generated
408 lines
10 KiB
Markdown
408 lines
10 KiB
Markdown
# Sonr Testnet
|
|
|
|
Production-ready 3-validator testnet with validator-sentry architecture and Cloudflare tunnel integration via DockFlare.
|
|
|
|
## Overview
|
|
|
|
This testnet provides:
|
|
- **3 Validators** with isolated private networks
|
|
- **3 Sentry Nodes** for public access and DDoS protection
|
|
- **IPFS Node** for distributed storage
|
|
- **Cloudflare Tunnels** for secure, zero-configuration public endpoints
|
|
- **14 Public Endpoints** via `*.sonr.land` domains
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
1. **Docker & Docker Compose**
|
|
```bash
|
|
docker --version
|
|
docker compose version
|
|
```
|
|
|
|
2. **Devbox** (provides snrd binary via Nix)
|
|
```bash
|
|
# Auto-install via Makefile
|
|
make all
|
|
|
|
# Or install manually
|
|
curl -fsSL https://get.jetpack.io/devbox | bash
|
|
```
|
|
|
|
3. **DockFlare** (for Cloudflare tunnels)
|
|
```bash
|
|
docker network create cloudflare-net
|
|
docker run -d \
|
|
--name dockflare \
|
|
--restart unless-stopped \
|
|
--network cloudflare-net \
|
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
|
-e CLOUDFLARE_API_TOKEN=your_token_here \
|
|
-e CLOUDFLARE_ACCOUNT_ID=your_account_id \
|
|
-e CLOUDFLARE_ZONE_ID=your_zone_id \
|
|
ghcr.io/sonr-io/dockflare:latest
|
|
```
|
|
|
|
> Get credentials from: https://dash.cloudflare.com
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# 1. Clone repository
|
|
git clone https://github.com/sonr-io/testnet
|
|
cd testnet
|
|
|
|
# 2. Install devbox (if not already installed)
|
|
make all
|
|
|
|
# 3. Create environment configuration
|
|
make setup
|
|
# Optional: Edit .env to customize
|
|
|
|
# 4. Initialize testnet
|
|
make init
|
|
|
|
# 5. Start testnet
|
|
make start
|
|
|
|
# 6. Verify endpoints
|
|
make test
|
|
```
|
|
|
|
**That's it!** Your testnet is running with Cloudflare tunnels.
|
|
|
|
---
|
|
|
|
## Commands
|
|
|
|
All testnet operations are managed via `make`:
|
|
|
|
```bash
|
|
make all # Check/install devbox
|
|
make setup # Create .env from template
|
|
make init # Initialize validators and sentries
|
|
make start # Start testnet
|
|
make stop # Stop testnet
|
|
make restart # Restart testnet
|
|
make clean # Clean all data (WARNING: destructive)
|
|
make status # Show status and endpoints
|
|
make logs # View logs
|
|
make test # Run basic tests
|
|
make help # Show available commands
|
|
```
|
|
|
|
> **Note:** All commands use devbox under the hood, which provides the `snrd` binary via Nix.
|
|
|
|
---
|
|
|
|
## Public Endpoints
|
|
|
|
All services are accessible via Cloudflare tunnels (no port conflicts):
|
|
|
|
### Sentry Endpoints
|
|
|
|
**Alice:**
|
|
- RPC: `https://alice-rpc.sonr.land`
|
|
- REST: `https://alice-rest.sonr.land`
|
|
- gRPC: `https://alice-grpc.sonr.land`
|
|
- EVM: `https://alice-evm.sonr.land`
|
|
|
|
**Bob:**
|
|
- RPC: `https://bob-rpc.sonr.land`
|
|
- REST: `https://bob-rest.sonr.land`
|
|
- gRPC: `https://bob-grpc.sonr.land`
|
|
- EVM: `https://bob-evm.sonr.land`
|
|
|
|
**Carol:**
|
|
- RPC: `https://carol-rpc.sonr.land`
|
|
- REST: `https://carol-rest.sonr.land`
|
|
- gRPC: `https://carol-grpc.sonr.land`
|
|
- EVM: `https://carol-evm.sonr.land`
|
|
|
|
### IPFS Endpoints
|
|
|
|
- API: `https://ipfs-api.sonr.land`
|
|
- Gateway: `https://ipfs-gateway.sonr.land`
|
|
|
|
### Example Usage
|
|
|
|
```bash
|
|
# Query blockchain status
|
|
curl https://alice-rpc.sonr.land/status | jq
|
|
|
|
# Query account balance
|
|
curl https://alice-rest.sonr.land/cosmos/bank/v1beta1/balances/idx16wx7ye3ce060tjvmmpu8lm0ak5xr7gm2vjyh4k | jq
|
|
|
|
# Send transaction
|
|
snrd tx bank send alice idx1... 1000000usnr \
|
|
--node https://alice-rpc.sonr.land \
|
|
--chain-id sonrtest_1-1 \
|
|
--keyring-backend test \
|
|
--yes
|
|
|
|
# IPFS operations
|
|
curl -X POST https://ipfs-api.sonr.land/api/v0/version | jq
|
|
curl https://ipfs-gateway.sonr.land/ipfs/<CID>
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Cloudflare Tunnel (DockFlare)
|
|
│
|
|
▼
|
|
┌──────────────────────────────────────────────┐
|
|
│ net-public + cloudflare-net │
|
|
│ │
|
|
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────┐
|
|
│ │sentry-alice │◄─►sentry-bob │◄─►sentry-carol │ │ IPFS │
|
|
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────────┘
|
|
└─────────┼──────────────────┼──────────────────┼──────────────────────┘
|
|
│ │ │
|
|
│ Private │ Private │ Private
|
|
│ │ │
|
|
┌─────────▼────────┐ ┌──────▼────────┐ ┌─────▼─────────┐
|
|
│ val-alice │ │ val-bob │ │ val-carol │
|
|
│ (net-alice) │ │ (net-bob) │ │ (net-carol) │
|
|
└──────────────────┘ └───────────────┘ └───────────────┘
|
|
```
|
|
|
|
### Key Features
|
|
|
|
- **Validator Isolation**: Each validator on private network
|
|
- **Sentry Protection**: Public traffic filtered through sentries
|
|
- **No Port Conflicts**: All services via Cloudflare tunnels
|
|
- **Auto-Discovery**: DockFlare automatically creates tunnels
|
|
- **TLS Encryption**: All traffic encrypted via Cloudflare
|
|
|
|
---
|
|
|
|
## Genesis Accounts
|
|
|
|
| Name | Address | Balance | Purpose |
|
|
|------|---------|---------|---------|
|
|
| Alice | `idx140fehngcrxvhdt84x729p3f0qmkmea8n570lrg` | 100M SNR | Validator |
|
|
| Bob | `idx1r6yue0vuyj9m7xw78npspt9drq2tmtvgcrf7sr` | 100M SNR | Validator |
|
|
| Carol | `idx1pe9mc2q72u94sn2gg52ramrt26x5efw6kslflg` | 100M SNR | Validator |
|
|
| Faucet | `idx16wx7ye3ce060tjvmmpu8lm0ak5xr7gm2vjyh4k` | 250M SNR | Faucet |
|
|
|
|
**Total Genesis Supply:** 550M SNR (300M staked + 250M faucet)
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Configuration is managed via `.env` file:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Quick setup:
|
|
```bash
|
|
make setup # Creates .env from .env.example
|
|
```
|
|
|
|
**Key Variables:**
|
|
- `CHAIN_ID=sonrtest_1-1` - Chain identifier
|
|
- `DENOM=usnr` - Native token denomination
|
|
- `BLOCK_TIME=5s` - Target block time
|
|
- `VOTING_PERIOD=30s` - Governance voting period
|
|
- `ALICE_MNEMONIC`, `BOB_MNEMONIC`, `CAROL_MNEMONIC` - Validator keys
|
|
- `FAUCET_MNEMONIC` - Faucet account key
|
|
- `DOCKER_IMAGE=onsonr/snrd:latest` - Container image
|
|
|
|
**⚠️ WARNING:** Default mnemonics in `.env.example` are public. Generate new ones for production!
|
|
|
|
For complete configuration details, see [docs/Environment.md](docs/Environment.md)
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
### Detailed Guides
|
|
|
|
- **[Docker.md](docs/Docker.md)** - Complete container documentation
|
|
- All 7 containers explained
|
|
- Network topology and security
|
|
- Volume management
|
|
- Health checks and troubleshooting
|
|
- Performance tuning
|
|
- Backup procedures
|
|
|
|
- **[Cloudflare.md](docs/Cloudflare.md)** - DockFlare integration guide
|
|
- Complete domain mapping (14 endpoints)
|
|
- DockFlare setup and configuration
|
|
- DNS management
|
|
- Testing all endpoint types
|
|
- Access policies
|
|
- Troubleshooting tunnels
|
|
|
|
- **[Environment.md](docs/Environment.md)** - Environment variable reference
|
|
- Global configuration variables
|
|
- Container-specific variables
|
|
- DockFlare environment variables
|
|
- Runtime overrides
|
|
- Security best practices
|
|
|
|
- **[Architecture.md](docs/Architecture.md)** - Architecture deep dive
|
|
- **[CLAUDE.md](CLAUDE.md)** - Quick reference for AI assistants
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Initialization Takes 1-2 Minutes
|
|
|
|
This is normal. The script initializes 6 nodes, creates genesis, and configures peer connections.
|
|
|
|
**Expected output:**
|
|
- 📋 Initializing validators
|
|
- 🛡️ Initializing sentries
|
|
- 💰 Adding genesis accounts
|
|
- 🔗 Setting up peer connections
|
|
- ✅ Completion with validator addresses
|
|
|
|
**If init fails:**
|
|
```bash
|
|
make clean
|
|
make init
|
|
```
|
|
|
|
### Validators Not Syncing
|
|
|
|
```bash
|
|
# Check logs
|
|
docker compose logs val-alice
|
|
|
|
# Verify peer connections
|
|
docker exec val-alice snrd tendermint show-node-id --home /root/.sonr
|
|
```
|
|
|
|
### Cloudflare Tunnels Not Working
|
|
|
|
Check DockFlare logs:
|
|
```bash
|
|
docker logs dockflare
|
|
```
|
|
|
|
Common issues:
|
|
- Missing `cloudflare-net` network
|
|
- Invalid API token
|
|
- Container not on `cloudflare-net`
|
|
|
|
See [docs/Cloudflare.md#troubleshooting](docs/Cloudflare.md#troubleshooting) for detailed help.
|
|
|
|
### IPFS Port Conflict
|
|
|
|
If IPFS fails with "port 8080 already allocated":
|
|
1. Stop the conflicting service
|
|
2. Or modify `docker-compose.yml` to use different port
|
|
|
|
---
|
|
|
|
## Production Deployment
|
|
|
|
**Before deploying to production:**
|
|
|
|
1. ✅ **Generate new mnemonics** - Never use defaults
|
|
```bash
|
|
snrd keys add test --keyring-backend test --output json | jq -r .mnemonic
|
|
```
|
|
|
|
2. ✅ **Use KMS** for validator key management (e.g., tmkms)
|
|
|
|
3. ✅ **Configure firewall rules** to restrict validator access
|
|
|
|
4. ✅ **Enable monitoring** (Prometheus, Grafana)
|
|
|
|
5. ✅ **Set up backups** of validator keys and state
|
|
```bash
|
|
tar -czf backup.tar.gz val-* sentry-* .env
|
|
```
|
|
|
|
6. ✅ **Rotate Cloudflare API tokens** regularly (every 90 days)
|
|
|
|
7. ✅ **Enable rate limiting** in Cloudflare dashboard
|
|
|
|
8. ✅ **Use persistent volumes** instead of bind mounts (optional)
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
### View Logs
|
|
|
|
```bash
|
|
# All services
|
|
make logs
|
|
|
|
# Specific service
|
|
docker compose logs -f sentry-alice
|
|
|
|
# Search logs
|
|
docker compose logs val-alice | grep -i error
|
|
```
|
|
|
|
### Execute Commands
|
|
|
|
```bash
|
|
# Via docker compose (recommended)
|
|
docker compose exec sentry-alice snrd query bank total
|
|
|
|
# Direct docker exec
|
|
docker exec -it sentry-alice snrd keys list --keyring-backend test
|
|
```
|
|
|
|
### Clean Restart
|
|
|
|
```bash
|
|
make clean # Remove all data (destructive!)
|
|
make init # Reinitialize
|
|
make start # Start fresh
|
|
```
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run basic tests
|
|
make test
|
|
```
|
|
|
|
### Manual Testing
|
|
|
|
```bash
|
|
# RPC
|
|
curl https://alice-rpc.sonr.land/status | jq
|
|
|
|
# REST
|
|
curl https://alice-rest.sonr.land/cosmos/base/tendermint/v1beta1/node_info | jq
|
|
|
|
# EVM JSON-RPC
|
|
curl -X POST https://alice-evm.sonr.land \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' | jq
|
|
|
|
# IPFS
|
|
curl -X POST https://ipfs-api.sonr.land/api/v0/version | jq
|
|
```
|
|
|
|
---
|
|
|
|
## Support
|
|
|
|
- **Documentation**: See [docs/](docs/) directory
|
|
- **Issues**: https://github.com/sonr-io/testnet/issues
|
|
- **Discord**: https://discord.gg/sonr
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Apache 2.0
|