synor/docs/TESTNET.md

# Synor Testnet Deployment Guide

This guide covers deploying and running the Synor testnet.

## Quick Start (Docker)

The fastest way to run a local testnet is with Docker Compose:

```bash
# Build images
./scripts/testnet-deploy.sh build

# Start testnet (3 seed nodes + faucet)
./scripts/testnet-deploy.sh start

# View logs
./scripts/testnet-deploy.sh logs

# Check status
./scripts/testnet-deploy.sh status

# Stop testnet
./scripts/testnet-deploy.sh stop
```

## Services

After starting, these services are available:

| Service | URL | Description |
|---------|-----|-------------|
| Seed Node 1 RPC | http://localhost:17110 | Primary JSON-RPC endpoint |
| Seed Node 2 RPC | http://localhost:17120 | Secondary JSON-RPC endpoint |
| Seed Node 3 RPC | http://localhost:17130 | Tertiary JSON-RPC endpoint |
| Faucet | http://localhost:8080 | Get test tokens |
| Seed Node 1 P2P | tcp://localhost:17511 | P2P network port |

## Testnet Parameters

| Parameter | Value |
|-----------|-------|
| Network Name | `testnet` |
| Chain ID | `1` |
| Block Time | 100ms |
| GHOSTDAG K | 18 |
| P2P Port | 17511 |
| HTTP RPC Port | 17110 |
| WebSocket RPC Port | 17111 |

## Using the Faucet

### Web Interface

Visit http://localhost:8080 and enter your Synor address.

### API

```bash
curl -X POST http://localhost:8080/faucet \
  -H "Content-Type: application/json" \
  -d '{"address": "synor1your_address_here"}'
```

Response:
```json
{
  "success": true,
  "message": "Sent 10.00000000 SYNOR to synor1...",
  "tx_hash": "0x...",
  "amount": "10.00000000 SYNOR"
}
```

### Rate Limits

- 10 SYNOR per request
- 1 hour cooldown between requests per address
- 10 requests per minute per IP

## Running Without Docker

### Prerequisites

- Rust 1.75+
- OpenSSL development libraries

### Build

```bash
cargo build --release
```

### Run a Single Node

```bash
./target/release/synord \
  --network testnet \
  --data-dir ./data \
  --p2p-addr 0.0.0.0:17511 \
  --rpc-http-addr 0.0.0.0:17110 \
  --rpc-ws-addr 0.0.0.0:17111
```

### Run with Mining

```bash
./target/release/synord \
  --network testnet \
  --data-dir ./data \
  --mining-enabled \
  --coinbase-address synor1your_mining_address
```

## Connecting to Testnet

### Bootstrap Peers

When connecting a new node, use these bootstrap peers:

```
/ip4/seed1.testnet.synor.cc/tcp/17511
/ip4/seed2.testnet.synor.cc/tcp/17511
/ip4/seed3.testnet.synor.cc/tcp/17511
```

For local Docker testnet:
```
/ip4/172.20.0.10/tcp/17511
/ip4/172.20.0.11/tcp/17511
/ip4/172.20.0.12/tcp/17511
```

### SDK Connection

```typescript
import { SynorClient } from '@synor/sdk';

const client = new SynorClient({
  rpcUrl: 'http://localhost:17110',
  network: 'testnet'
});
```

## RPC API

### Get Node Info

```bash
curl -X POST http://localhost:17110 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"synor_getNodeInfo","params":[],"id":1}'
```

### Get Block by Hash

```bash
curl -X POST http://localhost:17110 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"synor_getBlock","params":["0x..."],"id":1}'
```

### Get Balance

```bash
curl -X POST http://localhost:17110 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"synor_getBalance","params":["synor1..."],"id":1}'
```

### Submit Transaction

```bash
curl -X POST http://localhost:17110 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"synor_sendRawTransaction","params":["0x..."],"id":1}'
```

## Production Deployment

For production testnet deployment:

### 1. Generate Node Keys

```bash
./scripts/generate-node-keys.sh ./keys seed1 seed2 seed3
```

### 2. Configure DNS

Set up DNS records:
- `seed1.testnet.synor.cc` -> Seed Node 1 IP
- `seed2.testnet.synor.cc` -> Seed Node 2 IP
- `seed3.testnet.synor.cc` -> Seed Node 3 IP

### 3. Deploy with Docker Compose

```bash
# On each server, copy the appropriate keys
scp -r keys/seed1/* user@seed1.synor.cc:~/synor/keys/

# Start the node
docker-compose -f docker-compose.testnet.yml up -d seed1
```

### 4. Verify Network

```bash
# Check peer connections
curl http://seed1.testnet.synor.cc:17110 \
  -d '{"jsonrpc":"2.0","method":"synor_getPeers","params":[],"id":1}'
```

## Monitoring

### Health Checks

All nodes expose a `/health` endpoint:

```bash
curl http://localhost:17110/health
```

### Logs

```bash
# All services
./scripts/testnet-deploy.sh logs

# Specific service
./scripts/testnet-deploy.sh logs seed1
./scripts/testnet-deploy.sh logs faucet
```

### Metrics

Prometheus metrics are available at `/metrics` (when enabled).

## Troubleshooting

### Node Not Syncing

1. Check peer connections:
   ```bash
   curl -X POST http://localhost:17110 \
     -d '{"jsonrpc":"2.0","method":"synor_getPeers","params":[],"id":1}'
   ```

2. Verify bootstrap peers are reachable:
   ```bash
   nc -zv seed1.testnet.synor.cc 17511
   ```

### Faucet Not Working

1. Check faucet logs:
   ```bash
   ./scripts/testnet-deploy.sh logs faucet
   ```

2. Verify RPC connection:
   ```bash
   curl http://localhost:8080/health
   ```

### Out of Disk Space

```bash
# Check disk usage
docker system df

# Clean up old images
docker system prune -a
```

## Reset Testnet

To reset all testnet data and start fresh:

```bash
./scripts/testnet-deploy.sh clean
./scripts/testnet-deploy.sh start
```

**Warning**: This deletes all blockchain data and transaction history.