@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

   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:

npx @sonr.io/join-testnet

Install as Global Package

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

Usage

Interactive Setup

Start the interactive setup process:

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:

# 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:

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

# 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

# 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
• Discord: Join our community
• GitHub: sonr-io/sonr
• Testnet Faucet: Available on Discord

License

MIT - See the LICENSE file for details.

Support

For help and support:

• GitHub Issues: Report issues
• Discord: Get real-time help from the community
• Documentation: Check the official docs

Changelog

See CHANGELOG.md for version history and updates.