Documentation

Developers - Testnet-guide

Supernova Testnet: Complete Testing Guide

This guide provides detailed instructions for testing the Supernova blockchain on the testnet environment. Follow these steps to build, deploy, and interact with the testnet for development and validation purposes.

Table of Contents

Overview

The Supernova testnet provides a sandbox environment for testing and development without using real tokens or affecting the main network. The testnet is functionally identical to the mainnet but operates with test tokens (tSNOVA) that have no real-world value. This allows developers to experiment freely with application development, transaction testing, and node operation.

Prerequisites

Before beginning, ensure you have the following installed:

  • Docker Engine v20.10 or newer
  • Docker Compose v2.0 or newer
  • Git
  • Rust toolchain (for building from source)
  • 16GB RAM minimum (32GB recommended)
  • 100GB free disk space
  • Open ports: 8545 (RPC), 8080 (Faucet), 26656-26657 (P2P/Tendermint)

Simplified Docker Setup

For the easiest and most reliable testnet deployment, use our new streamlined Docker setup:

# Clone the repository
git clone https://github.com/Carbon-Twelve-C12/supernova.git
cd supernova

# Make the Docker setup script executable
chmod +x docker_setup.sh

# Run the Docker setup script
./docker_setup.sh

This script automates the entire setup process by:

  • Building the necessary Docker images
  • Setting up the testnet configuration
  • Launching all required services
  • Creating a default wallet
  • Funding it with test tokens

After running the script, your testnet will be fully operational and ready for testing. The script also generates a summary of available endpoints and credentials.

For more details on the Docker setup, refer to the TESTNET_FIXES_UPDATED.md document.

Quick Start

For those who want to get up and running quickly with the standard approach:

# Clone repository
git clone https://github.com/Carbon-Twelve-C12/supernova.git
cd supernova

# Build the Docker image
docker build -t supernova:latest -f docker/Dockerfile .

# Deploy testnet environment
cd deployments/testnet
docker-compose up -d

# Create a wallet
docker exec -it supernova-seed-1 supernova wallet create --network testnet

# Request tokens from faucet (visit website)
# https://testnet.supernovanetwork.xyz

# Test a transaction
docker exec -it supernova-seed-1 supernova wallet send --address RECIPIENT_ADDRESS --amount 10 --fee 0.001

Detailed Setup Instructions

Environment Preparation

  1. Clone the Repository

    git clone https://github.com/Carbon-Twelve-C12/supernova.git
cd supernova

  2. Check Configuration (Optional)

    Review the testnet configuration files:

    cat deployments/testnet/docker-compose.yml
cat deployments/testnet/config/genesis.json
cat deployments/testnet/README.md

  3. Apply Required Fixes

    The repository includes fixes for common issues. Review these before proceeding:

    cat TESTNET_FIXES_UPDATED.md
cat FINAL_SOLUTION.md

    These documents contain solutions to common deployment issues and optimizations for the testnet environment.

Building the Docker Image

  1. Build the Supernova Image

    docker build -t supernova:latest -f docker/Dockerfile .

    This process compiles the Supernova blockchain code and creates a Docker image with all necessary dependencies.

  2. Verify the Image

    docker images | grep supernova

    Alternatively, you can build from source:

    cargo build --release

Deploying the Testnet

  1. Navigate to the Testnet Directory

    cd deployments/testnet

  2. Start the Testnet Environment

    docker-compose up -d

    This command launches:

    • Seed nodes (initial validators)
    • Regular nodes
    • An RPC server
    • Testnet explorer
    • Faucet service

  3. Check for Additional Services (Optional)

    # Verify all services are running
docker-compose ps

Verifying Deployment

  1. Check Container Status

    docker-compose ps

    All containers should show a status of "Up".

  2. View Node Logs

    # View logs for the seed node
docker-compose logs -f supernova-seed-1

# View logs for a specific component
docker-compose logs -f supernova-rpc

  3. Verify Network Connectivity

    # Check if nodes are communicating
docker exec -it supernova-seed-1 supernova node peers

  4. Verify Block Production

    # Check if blocks are being created
docker exec -it supernova-seed-1 supernova blockchain info

  5. Verify Endpoint Connectivity

    According to the FINAL_SOLUTION.md document, you should verify that all endpoints are accessible:

    # Check RPC endpoint
curl -s http://localhost:8545 -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":1}'

# Check Faucet endpoint
curl -s http://localhost:8080/health

# Check Explorer endpoint
curl -s http://localhost:8081/api/status

Node Startup with ASCII Art

Supernova includes ASCII art animations that can be displayed during node startup:

# Start node with ASCII animation
./run_node.sh --with-animation

# Or use the standalone banner tool
cargo run --bin supernova-banner -- static
cargo run --bin supernova-banner -- slide-in
cargo run --bin supernova-banner -- dissolve-out
cargo run --bin supernova-banner -- complete
cargo run --bin supernova-banner -- testnet

The different animation modes provide various visual effects:

  • static: Display a static ASCII logo
  • slide-in: Animate the logo sliding in from the left
  • dissolve-out: Animate the logo dissolving away
  • complete: Run a full animation sequence
  • testnet: Show the testnet-specific animation

Wallet Operations

Creating Wallets

  1. Create Your First Wallet

    docker exec -it supernova-seed-1 supernova wallet create --network testnet

    You'll receive output containing:

    • Wallet address
    • Recovery phrase (mnemonic)
    • Public key

    IMPORTANT: Save the recovery phrase securely!

  2. Create Additional Wallets (Optional)

    docker exec -it supernova-seed-1 supernova wallet create --network testnet --name test_wallet_2

  3. List Your Wallets

    docker exec -it supernova-seed-1 supernova wallet list

  4. Import Existing Wallet

    If you have an existing wallet mnemonic, you can import it:

    docker exec -it supernova-seed-1 supernova wallet import \
  --mnemonic "your twelve word mnemonic phrase here" \
  --name imported_wallet

Obtaining Test Tokens

  1. Request Tokens from Faucet

    Visit the testnet faucet at https://testnet.supernovanetwork.xyz and:

    • Enter your wallet address
    • Complete the verification
    • Submit your request

    Alternatively, use the command line:

    curl -X POST -H "Content-Type: application/json" \
  -d '{"address":"YOUR_WALLET_ADDRESS","amount":100}' \
  https://testnet.supernovanetwork.xyz/api/faucet/send

    When using the Docker setup method, your wallet is automatically funded with test tokens.

  2. Verify Token Receipt

    docker exec -it supernova-seed-1 supernova wallet balance --address YOUR_ADDRESS

    It may take a few moments for tokens to arrive.

Checking Balances

# Check by wallet name (if you created with --name)
docker exec -it supernova-seed-1 supernova wallet balance --name main

# Check by address
docker exec -it supernova-seed-1 supernova wallet balance --address YOUR_ADDRESS

# See detailed UTXO information
docker exec -it supernova-seed-1 supernova wallet list-utxos

Quantum-Resistant Addresses

Supernova supports post-quantum cryptography for enhanced security:

# Generate a quantum-resistant address
docker exec -it supernova-seed-1 supernova wallet new-address --type quantum

# Generate with specific quantum algorithm
docker exec -it supernova-seed-1 supernova wallet new-address --type quantum --algorithm dilithium

# List all addresses including quantum-resistant ones
docker exec -it supernova-seed-1 supernova wallet list-addresses

Testing Transactions

Basic Transfer

  1. Send a Simple Transaction

    docker exec -it supernova-seed-1 supernova wallet send \
  --address RECIPIENT_ADDRESS \
  --amount 10 \
  --fee 0.001

    The command returns a transaction ID (txid) that can be used to track the transaction.

  2. Verify Transaction Success

    # Check sender balance
docker exec -it supernova-seed-1 supernova wallet balance --address SENDER_ADDRESS

# Check recipient balance
docker exec -it supernova-seed-1 supernova wallet balance --address RECIPIENT_ADDRESS

Tracking Transactions

  1. Check Transaction Status

    docker exec -it supernova-seed-1 supernova tx info --txid YOUR_TRANSACTION_ID

  2. View Transaction in Explorer

    Visit https://explorer.testnet.supernovanetwork.xyz and search for your transaction ID.

    If using the local Docker setup, the explorer is available at http://localhost:8081.

  3. View Transaction History

    docker exec -it supernova-seed-1 supernova wallet history

Advanced Transaction Options

  1. Send with Memo

    docker exec -it supernova-seed-1 supernova wallet send \
  --address RECIPIENT_ADDRESS \
  --amount 5 \
  --fee 0.001 \
  --memo "Test payment"

  2. Multiple Outputs

    docker exec -it supernova-seed-1 supernova wallet send-many \
  --outputs "ADDRESS1:5,ADDRESS2:10,ADDRESS3:15" \
  --fee 0.002

  3. Custom Fee Level

    # Low priority
docker exec -it supernova-seed-1 supernova wallet send \
  --address RECIPIENT_ADDRESS \
  --amount 1 \
  --fee-rate low

# High priority
docker exec -it supernova-seed-1 supernova wallet send \
  --address RECIPIENT_ADDRESS \
  --amount 1 \
  --fee-rate high

  4. Label Transactions

    docker exec -it supernova-seed-1 supernova wallet label-tx \
  --txid YOUR_TRANSACTION_ID \
  --label "Test payment"

Quantum-Protected Transactions

Send transactions using quantum-resistant signatures:

# Send funds using quantum-resistant signatures
docker exec -it supernova-seed-1 supernova wallet send \
  --address RECIPIENT_ADDRESS \
  --amount 5 \
  --quantum-protected

# Specify quantum algorithm
docker exec -it supernova-seed-1 supernova wallet send \
  --address RECIPIENT_ADDRESS \
  --amount 5 \
  --quantum-protected \
  --algorithm dilithium

Lightning Network Testing

Opening Channels

  1. Start Lightning Node

    docker exec -it supernova-seed-1 supernova lightning start

  2. Create a New Channel

    docker exec -it supernova-seed-1 supernova lightning open-channel \
  --peer NODE_ID@IP_ADDRESS:PORT \
  --local-amount 1000000 \
  --push-amount 200000

  3. List Open Channels

    docker exec -it supernova-seed-1 supernova lightning list-channels

Creating and Paying Invoices

  1. Create an Invoice

    docker exec -it supernova-seed-1 supernova lightning create-invoice \
  --amount 50000 \
  --memo "Test Invoice"

  2. Pay an Invoice

    docker exec -it supernova-seed-1 supernova lightning pay \
  --invoice LIGHTNING_INVOICE

  3. List Invoices

    docker exec -it supernova-seed-1 supernova lightning list-invoices

Managing Channels

  1. Close a Channel

    docker exec -it supernova-seed-1 supernova lightning close-channel \
  --channel-id CHANNEL_ID

  2. Force Close (if needed)

    docker exec -it supernova-seed-1 supernova lightning force-close-channel \
  --channel-id CHANNEL_ID

  3. Check Channel Status

    docker exec -it supernova-seed-1 supernova lightning channel-info \
  --channel-id CHANNEL_ID

Environmental Impact Monitoring

Green Mining Registration

  1. Register as Green Miner

    docker exec -it supernova-seed-1 supernova env register-green \
  --power-source solar \
  --percentage 100 \
  --location "San Francisco, CA" \
  --proof-url "https://example.com/solar-certificate.pdf"

    Available power sources: solar, wind, hydro, geothermal, nuclear, carbon-offset

  2. Verify Registration

    docker exec -it supernova-seed-1 supernova env status

Environmental Reporting

  1. Submit Monthly Report

    docker exec -it supernova-seed-1 supernova env submit-report \
  --month 2023-06 \
  --kwh-consumed 120.5 \
  --kwh-offset 120.5 \
  --proof-url "https://example.com/june-energy-bill.pdf"

  2. View Environmental Impact

    docker exec -it supernova-seed-1 supernova env impact-report

    This command displays:

    • Total estimated carbon offset
    • Energy efficiency rating
    • Comparison to network average

Fee Discounts for Green Mining

Verified green miners receive transaction fee discounts:

# Check your current fee discount
docker exec -it supernova-seed-1 supernova env fee-discount

# Apply fee discount to a transaction
docker exec -it supernova-seed-1 supernova wallet send \
  --address RECIPIENT_ADDRESS \
  --amount 10 \
  --apply-green-discount

Security Feature Testing

Network Security Metrics

  1. View Security Status

    docker exec -it supernova-seed-1 supernova security status

    This displays:

    • Network health score
    • Active security incidents
    • Threat assessment level
    • Recommended security settings

  2. Run Security Scan

    docker exec -it supernova-seed-1 supernova security scan

Peer Reputation System

  1. Check Peer Reputation

    docker exec -it supernova-seed-1 supernova security peer-reputation \
  --peer-id PEER_NODE_ID

  2. List Banned Peers

    docker exec -it supernova-seed-1 supernova security list-banned

  3. Report Malicious Activity

    docker exec -it supernova-seed-1 supernova security report-peer \
  --peer-id PEER_NODE_ID \
  --reason "Spamming transactions" \
  --evidence "Transaction logs at 2023-06-15T14:30:00Z"

Security Configuration

  1. Update Security Settings

    docker exec -it supernova-seed-1 supernova security config \
  --auto-ban true \
  --max-banned-peers 100 \
  --ban-threshold 50

  2. Enable Enhanced Security Mode

    docker exec -it supernova-seed-1 supernova security enhanced-mode \
  --level high

    Security levels: standard, enhanced, high, paranoid

Disaster Recovery Testing

Creating Backups

  1. Create Full Node Backup

    docker exec -it supernova-seed-1 supernova backup create \
  --output /backups/full-node-backup.zip

  2. Create Wallet-Only Backup

    docker exec -it supernova-seed-1 supernova wallet backup \
  --output /backups/wallet-backup.zip \
  --encrypt

  3. Schedule Automated Backups

    docker exec -it supernova-seed-1 supernova backup schedule \
  --interval daily \
  --output-dir /backups/ \
  --retain 7

    Intervals: hourly, daily, weekly, monthly

Integrity Verification

  1. Verify Backup Integrity

    docker exec -it supernova-seed-1 supernova backup verify \
  --input /backups/full-node-backup.zip

  2. Test Recovery Process

    docker exec -it supernova-seed-1 supernova backup test-recovery \
  --input /backups/full-node-backup.zip \
  --target /tmp/recovery-test

Restoring from Backup

  1. Restore Full Node

    docker exec -it supernova-seed-1 supernova backup restore \
  --input /backups/full-node-backup.zip \
  --force

  2. Restore Wallet Only

    docker exec -it supernova-seed-1 supernova wallet restore \
  --input /backups/wallet-backup.zip

  3. Verify Restored Data

    docker exec -it supernova-seed-1 supernova blockchain verify
docker exec -it supernova-seed-1 supernova wallet verify

API Testing

RESTful API

  1. Test RESTful API Endpoints

    # Get blockchain status
curl http://localhost:8080/api/v1/status

# Get block by height
curl http://localhost:8080/api/v1/blocks/1000

# Get transaction by ID
curl http://localhost:8080/api/v1/transactions/TRANSACTION_ID

  2. Create Transaction via API

    curl -X POST http://localhost:8080/api/v1/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "from": "SENDER_ADDRESS",
    "to": "RECIPIENT_ADDRESS",
    "amount": 1.5,
    "fee": 0.001,
    "signature": "VALID_SIGNATURE"
  }'

JSON-RPC API

  1. Test JSON-RPC API

    # Get node info
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "supernova_getNodeInfo",
    "params": [],
    "id": 1
  }'

# Get balance
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "supernova_getBalance",
    "params": ["ADDRESS"],
    "id": 1
  }'

  2. Create New Block (Validator Only)

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

Explorer and Network Status

  1. Access Testnet Explorer

    Visit the explorer at:

    The explorer provides:

    • Real-time block information
    • Transaction history
    • Network statistics
    • Validator performance

  2. Check Network Status Dashboard

    Visit the status page at:

    The status page shows:

    • Network uptime
    • Transaction throughput
    • Active validators
    • Error rates
    • Environmental impact metrics

Advanced Testing

Performance Testing

  1. Run Benchmarks

    docker exec -it supernova-seed-1 supernova benchmark all

    This runs comprehensive benchmarks for:

    • Transaction processing
    • Block validation
    • Consensus algorithms
    • Network communication

  2. Test Transaction Throughput

    docker exec -it supernova-seed-1 supernova benchmark transactions \
  --count 10000 \
  --threads 4 \
  --size small

    Transaction sizes: small, medium, large

Stress Testing

  1. Network Flood Test

    docker exec -it supernova-seed-1 supernova test flood \
  --tx-per-second 1000 \
  --duration 300

  2. Validator Failover Test

    docker exec -it supernova-seed-1 supernova test validator-failover \
  --validators 3 \
  --fail-count 1

  3. Network Partition Test

    docker exec -it supernova-seed-1 supernova test network-partition

Node Statistics

  1. View Detailed Stats

    docker exec -it supernova-seed-1 supernova stats --detailed

  2. Export Performance Metrics

    docker exec -it supernova-seed-1 supernova stats export \
  --format json \
  --output /tmp/node-stats.json

    Export formats: json, csv, prometheus

Using Utility Scripts

The testnet includes several utility scripts to simplify common tasks:

# Reset testnet environment
./scripts/reset_testnet.sh

# Generate test transactions
./scripts/generate_transactions.sh --count 100

# Monitor node performance
./scripts/monitor_performance.sh --interval 10

Additional scripts available:

  1. Network Visualization

    ./scripts/visualize_network.sh --output network.html

  2. Quick Environment Setup

    ./scripts/quick_setup.sh --nodes 3 --with-explorer

  3. Automated Testing

    ./scripts/run_tests.sh --suite complete

Known Issues and Fixes

The testnet may encounter the following known issues. Here are the solutions:

  1. Docker Network Conflicts

    Issue: Docker network conflicts with existing networks.

    Solution:

    docker network prune
# Then modify the docker-compose.yml to use a different subnet:
# networks:
#   supernova_net:
#     ipam:
#       config:
#         - subnet: 172.20.0.0/16

  2. Node Synchronization Issues

    Issue: Nodes fail to synchronize properly.

    Solution:

    # Reset the node data
docker exec -it supernova-seed-1 supernova node reset-data

# Restart with specified seed node
docker-compose restart

  3. Transaction Processing Delays

    Issue: Transactions take too long to process.

    Solution: Adjust block parameters in the configuration:

    docker exec -it supernova-seed-1 supernova config set \
  --max-block-size 2048576 \
  --block-time 5

Troubleshooting

If you encounter issues not listed above, try these general troubleshooting steps:

  1. Check Logs

    docker-compose logs -f

  2. Verify Network Connectivity

    docker exec -it supernova-seed-1 ping supernova-node-1

  3. Inspect Container Health

    docker inspect --format='{{.State.Health.Status}}' supernova-seed-1

  4. Check Resource Usage

    docker stats

  5. Restart Services

    docker-compose restart

  6. Reset Environment

    If all else fails, reset the entire environment:

    docker-compose down -v
docker-compose up -d

Testnet Reset Procedure

The testnet is periodically reset to ensure optimal performance. To prepare for a reset:

  1. Export Your Wallets

    docker exec -it supernova-seed-1 supernova wallet export \
  --output /backups/wallets.json

  2. Save Important Data

    docker exec -it supernova-seed-1 supernova data export \
  --output /backups/important-data.json

  3. Monitor Reset Announcements

    Reset announcements are posted on:

    • Discord #testnet channel
    • GitHub repository issues
    • Status page banner

Getting Help

If you need assistance with the testnet:

  1. Join Discord Community

    Join our Discord server and ask questions in the #testnet-support channel.

  2. GitHub Issues

    Report bugs or suggest improvements on our GitHub repository.

  3. Documentation

    Refer to the complete documentation for detailed information.

  4. Developer Office Hours

    Attend our weekly developer office hours every Wednesday at 2:00 PM UTC on Discord.

Edit this page on GitHub