npm package: @sonr.io/join-testnet
Description: Sonr testnet joining CLI tool
Author: Sonr Team
Latest version: 0.1.2

# @sonr.io/join-testnet

An interactive CLI tool for joining the Sonr blockchain testnet with automated node configuration and setup.

## Overview

`@sonr.io/join-testnet` simplifies the process of joining the Sonr blockchain network by automating node initialization, configuration, and genesis file setup. The tool provides an interactive experience that guides you through selecting a network, configuring your node, and preparing it for operation.

## Features

- **Interactive network selection** - Choose between devnet, testnet, or mainnet (when available)
- **Automated node initialization** - Sets up node configuration with proper chain ID
- **Network-specific configuration** - Automatically configures seeds, peers, and endpoints
- **Genesis file management** - Downloads and installs the correct genesis file
- **Custom start scripts** - Generates ready-to-use scripts for node operation
- **Multiple data directory options** - Use default or custom locations for node data

## Requirements

### System Requirements

- **Node.js**: v20.0.0 or higher
- **Operating System**: macOS or Linux
- **snrd**: Sonr blockchain daemon must be installed

### Prerequisites

Before using this tool, ensure you have:

1. **snrd installed**: The Sonr blockchain daemon
   ```bash
   npx @sonr.io/install
   ```

2. **Internet connection**: Required for downloading genesis files and connecting to network peers

## Installation

### Quick Start

Run the tool directly using npx:

```bash
npx @sonr.io/join-testnet
```

### Install as Global Package

```bash
npm install -g @sonr.io/join-testnet
sonr-join-testnet
```

## Usage

### Interactive Setup

Start the interactive setup process:

```bash
npx @sonr.io/join-testnet
```

The tool guides you through:

1. **Network Selection**:
   - **Development Network** (devnet) - Local development environment
   - **Public Testnet** - Public test network for validators
   - **Mainnet** - Production network (coming soon)

2. **Node Configuration**:
   - **Moniker** - Your node's unique identifier
   - **Data Directory** - Where to store blockchain data
     - Default: `~/.sonr`
     - Custom: Specify your own path

3. **Automatic Setup**:
   - Initializes node with selected chain ID
   - Configures network peers and seeds
   - Downloads appropriate genesis file
   - Creates start script for easy node operation

### Post-Setup Commands

After successful setup, use these commands:

```bash
# Start your node
~/.sonr/start.sh

# Check sync status
snrd status --home ~/.sonr

# View node information
snrd tendermint show-node-id --home ~/.sonr

# Create validator (after sync)
snrd tx staking create-validator --help
```

## Network Configurations

### Development Network (devnet)

- **Chain ID**: `sonrtest_1-1`
- **RPC URL**: `http://localhost:26657`
- **API URL**: `http://localhost:1317`
- **Purpose**: Local development and testing

### Public Testnet

- **Chain ID**: `sonrtest_9000-1`
- **RPC URL**: `https://rpc.testnet.sonr.io`
- **API URL**: `https://api.testnet.sonr.io`
- **Seeds**: Available for network discovery
- **Persistent Peers**: Maintained validator nodes
- **Purpose**: Public testing and validator operations

### Mainnet (Coming Soon)

- **Chain ID**: `sonr_1-1`
- **RPC URL**: `https://rpc.sonr.io`
- **API URL**: `https://api.sonr.io`
- **Purpose**: Production blockchain operations

## API Reference

### Core Functions

#### `checkSnrdInstalled()`

Verifies that the Sonr daemon is installed on the system.

**Returns:**
- `Promise<boolean>`: True if snrd is found in PATH

#### `initializeNode(moniker, chainId, homeDir)`

Initializes a new node with the specified configuration.

**Parameters:**
- `moniker`: String - Node identifier/nickname
- `chainId`: String - Blockchain network identifier
- `homeDir`: String - Directory for node data storage

**Side Effects:**
- Creates node configuration files
- Generates node keys

#### `configureNode(testnet, homeDir)`

Configures node settings for the selected network.

**Parameters:**
- `testnet`: Object - Network configuration object containing:
  - `seeds`: Array of seed node addresses
  - `persistent_peers`: Array of persistent peer addresses
  - `rpcUrl`: RPC endpoint URL
  - `apiUrl`: API endpoint URL
- `homeDir`: String - Node data directory

**Configuration Changes:**
- Updates `config.toml` with network peers
- Enables API endpoints
- Sets pruning strategy
- Configures RPC/API binding addresses

#### `downloadGenesis(testnet, homeDir)`

Downloads and installs the genesis file for the selected network.

**Parameters:**
- `testnet`: Object - Network configuration
- `homeDir`: String - Node data directory

**Behavior:**
- For devnet: Creates minimal genesis file
- For testnet/mainnet: Downloads from GitHub repository

## File Structure

After setup, your node directory contains:

```
~/.sonr/
├── config/
│   ├── app.toml           # Application configuration
│   ├── config.toml        # Tendermint configuration
│   ├── genesis.json       # Network genesis file
│   ├── node_key.json      # Node identity key
│   └── priv_validator_key.json  # Validator private key
├── data/                  # Blockchain data
└── start.sh              # Generated start script
```

## Configuration Details

### app.toml Modifications

- **API**: Enabled for blockchain queries
- **Pruning**: Set to "nothing" for archive nodes
- **API Address**: Bound to 0.0.0.0:1317

### config.toml Modifications

- **Seeds**: Network-specific seed nodes
- **Persistent Peers**: Reliable validator nodes
- **RPC Address**: Bound to 0.0.0.0:26657
- **P2P Settings**: Configured for network discovery

## Troubleshooting

### Common Issues

#### "snrd is not installed"
**Solution**: Install snrd first:
```bash
npx @sonr.io/install
```

#### "Genesis download failed"
**Causes & Solutions**:
- Network connectivity issues - Check internet connection
- GitHub rate limiting - Wait and retry
- Invalid network selection - Ensure network is available

#### Node fails to start
**Check**:
- Port availability (26656, 26657, 1317)
- Sufficient disk space
- Valid genesis file
- Correct permissions on data directory

#### Node not syncing
**Verify**:
- Correct chain ID in config
- Peers are configured
- Firewall allows P2P connections (port 26656)

### Verification Commands

```bash
# Check if node is running
snrd status --home ~/.sonr

# View connected peers
snrd tendermint show-peers --home ~/.sonr

# Check sync status
snrd status --home ~/.sonr | jq .SyncInfo

# View logs (if running with systemd)
journalctl -u sonr-node -f
```

## Development

### Project Structure

```
cli/join-testnet/
├── src/
│   └── index.ts        # Main CLI logic
├── dist/               # Compiled JavaScript
├── package.json        # Package configuration
├── tsconfig.json       # TypeScript configuration
└── CHANGELOG.md        # Version history
```

### Scripts

```bash
# Build TypeScript source
pnpm build

# Development watch mode
pnpm dev

# Clean build artifacts
pnpm clean

# Run linting
pnpm lint

# Format code
pnpm format

# Run tests
pnpm test
```

### Dependencies

- **@clack/prompts**: Interactive CLI prompts
- **picocolors**: Terminal output coloring

## Security Considerations

### Private Keys

**Important**: The tool generates validator private keys during initialization. These keys are stored in:
- `~/.sonr/config/node_key.json`
- `~/.sonr/config/priv_validator_key.json`

**Always**:
- Back up these files securely
- Never share private keys
- Use appropriate file permissions (600)

### Network Security

For production validators:
- Use firewall rules to restrict access
- Enable Tendermint KMS for key management
- Configure sentry nodes for DDoS protection
- Monitor node metrics and alerts

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## Resources

- **Documentation**: [Sonr Docs](https://docs.sonr.io)
- **Discord**: [Join our community](https://discord.gg/sonr)
- **GitHub**: [sonr-io/sonr](https://github.com/sonr-io/sonr)
- **Testnet Faucet**: Available on Discord

## License

MIT - See the [LICENSE](../../LICENSE) file for details.

## Support

For help and support:

- **GitHub Issues**: [Report issues](https://github.com/sonr-io/sonr/issues)
- **Discord**: Get real-time help from the community
- **Documentation**: Check the official docs

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history and updates.