Skip to content

Latest commit

 

History

History
523 lines (397 loc) · 10.1 KB

GUIDE.md

File metadata and controls

523 lines (397 loc) · 10.1 KB
Raw

Token Validator User Guide

Table of Contents

  1. Installation
  2. Configuration
  3. Network Support
  4. Working with Wallets
  5. Transaction Management
  6. UTXO Management
  7. Token Management
  8. Backup and Recovery
  9. Troubleshooting

Installation

Docker Installation (Recommended)

The simplest way to get started is using Docker:

  1. Clone the repository:
git clone https://github.com/yourusername/token-validator.git
cd token-validator
  1. Create environment file:
cat > .env << EOL
BITCOIN_RPC_USER=your_username
BITCOIN_RPC_PASSWORD=your_password
SECRET_KEY=your-secret-key-here
EOL
  1. Start services:
docker-compose up -d
  1. Verify installation:
# Check service status
docker-compose ps

# View logs
docker-compose logs -f

Docker Benefits

  • Pre-configured Bitcoin Core node
  • Automatic service orchestration
  • Built-in health monitoring
  • Data persistence
  • Automatic restarts
  • Isolated environment

Manual Installation

Prerequisites

  • Python 3.11 or higher
  • Bitcoin Core node (optional for mainnet/testnet)
  • SQLite3 (included in Python)

Setup Steps

  1. Clone the repository:
git clone https://github.com/yourusername/token-validator.git
cd token-validator
  1. Create virtual environment:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies:
pip install -r requirements.txt

Configuration

Docker Configuration

  1. Environment Setup: Edit .env file with your settings:
# Bitcoin RPC Configuration
BITCOIN_RPC_USER=your_username
BITCOIN_RPC_PASSWORD=your_password
SECRET_KEY=your-secret-key-here

# Optional overrides
BITCOIN_RPC_HOST=bitcoin
BITCOIN_RPC_PORT=18443
  1. Service Configuration: The docker-compose.yml file provides:
  • Validator service configuration
  • Bitcoin Core setup
  • Network settings
  • Volume management
  • Health checks
  1. Accessing Services:
# Execute validator commands
docker-compose exec validator python -m validator [command]

# Access Bitcoin Core
docker-compose exec bitcoin bitcoin-cli -regtest [command]

Manual Configuration

Environment Setup

Create a .env file with your network settings:

# Network Selection (mainnet, testnet, regtest)
BITCOIN_NETWORK=testnet

# Bitcoin RPC Configuration
BITCOIN_RPC_HOST=localhost
BITCOIN_RPC_PORT=18332  # Port varies by network
BITCOIN_RPC_USER=your_username
BITCOIN_RPC_PASSWORD=your_password

# Application Settings
APP_SECRET_KEY=your_secret_key
DATABASE_URL=sqlite:///validator.db

Network-Specific Ports

  • Mainnet: 8332
  • Testnet: 18332
  • Regtest: 18443

Network Support

Working with Docker Networks

Mainnet

# Update docker-compose.yml bitcoin service
services:
  bitcoin:
    command:
      -server=1
      -rpcallowip=0.0.0.0/0
      # ... other settings ...

# Start services
docker-compose up -d

# Execute commands
docker-compose exec validator python -m validator wallet create mainnet_wallet --network mainnet

Testnet

# Update docker-compose.yml bitcoin service
services:
  bitcoin:
    command:
      -testnet=1
      -server=1
      # ... other settings ...

# Start services
docker-compose up -d

# Execute commands
docker-compose exec validator python -m validator wallet create testnet_wallet --network testnet

Regtest (Default)

# Default configuration works with regtest
docker-compose up -d

# Execute commands
docker-compose exec validator python -m validator wallet create regtest_wallet --network regtest

Manual Network Setup

Working with Mainnet

# Configure for mainnet
export BITCOIN_NETWORK=mainnet
export BITCOIN_RPC_PORT=8332

# Create mainnet wallet
python -m validator wallet create mainnet_wallet --network mainnet

# Generate mainnet address
python -m validator wallet address mainnet_wallet

Working with Testnet

# Configure for testnet
export BITCOIN_NETWORK=testnet
export BITCOIN_RPC_PORT=18332

# Create testnet wallet
python -m validator wallet create testnet_wallet --network testnet

# Generate testnet address
python -m validator wallet address testnet_wallet

Working with Regtest

# Configure for regtest
export BITCOIN_NETWORK=regtest
export BITCOIN_RPC_PORT=18443

# Create regtest wallet
python -m validator wallet create regtest_wallet --network regtest

# Generate regtest address
python -m validator wallet address regtest_wallet

Working with Wallets

Docker Wallet Commands

  1. Create Wallet:
docker-compose exec validator python -m validator wallet create <name> [--network <network>] [--type <address_type>]
  1. List Wallets:
docker-compose exec validator python -m validator wallet list
  1. Generate Address:
docker-compose exec validator python -m validator wallet generate <name> [--count <number>]
  1. Get Balance:
docker-compose exec validator python -m validator wallet balance <name>
  1. View Network Info:
docker-compose exec validator python -m validator wallet network <name>
  1. Export Wallet:
docker-compose exec validator python -m validator wallet export <name> <path>
  1. Import Wallet:
docker-compose exec validator python -m validator wallet import <path>

Manual Wallet Commands

  1. Create Wallet:
python -m validator wallet create <name> [--network <network>] [--type <address_type>]
  1. List Wallets:
python -m validator wallet list
  1. Generate Address:
python -m validator wallet generate <name> [--count <number>]
  1. Get Balance:
python -m validator wallet balance <name>
  1. View Network Info:
python -m validator wallet network <name>
  1. Export Wallet:
python -m validator wallet export <name> <path>
  1. Import Wallet:
python -m validator wallet import <path>

Network-Specific Features

  • Each wallet is network-aware
  • Addresses are automatically formatted for the correct network
  • Separate storage for each network's wallets
  • Network-specific backup files

Transaction Management

Sending Bitcoin

  1. Basic Send:
python -m validator wallet send <wallet_name> <recipient_address> <amount>
  1. Send with Custom Fee Rate:
python -m validator wallet send <wallet_name> <recipient_address> <amount> --fee-rate <sat/vB>
  1. Send with Memo:
python -m validator wallet send <wallet_name> <recipient_address> <amount> --memo "Payment description"

Fee Rate Guidelines

  • Regtest: Default 5 sat/vB
  • Testnet/Mainnet: Dynamic fee estimation
  • Custom fee rates: 1-100 sat/vB recommended

Transaction Features

  • Automatic UTXO selection
  • Change address generation
  • Memo support
  • Custom fee rates
  • Transaction tracking

UTXO Management

Freezing UTXOs

  1. Create and Freeze UTXO:
python -m validator wallet freeze-utxo <wallet_name> <amount> [--memo "Purpose of freeze"]
  1. View Frozen UTXOs:
python -m validator wallet balance <wallet_name>
# Shows both available and frozen UTXOs

UTXO Features

  • Create specific value UTXOs
  • Freeze UTXOs to prevent spending
  • Add memos for tracking
  • Automatic UTXO tracking
  • Balance segregation (available vs frozen)

Best Practices

  1. UTXO Creation:

    • Use meaningful memos
    • Consider fee implications
    • Plan UTXO values carefully

  2. UTXO Management:

    • Regular balance checks
    • Document frozen UTXOs
    • Monitor UTXO states

Token Management

Token Commands

  1. Create Token:
python -m validator token create <name> <supply> [--decimals <decimals>] [--network <network>]
  1. List Tokens:
python -m validator token list [--network <network>]
  1. Transfer Token:
python -m validator token transfer <token_id> <recipient> <amount>
  1. Get Token Info:
python -m validator token info <token_id>

Network Considerations

  • Tokens are bound to their creation network
  • Cross-network transfers are not supported
  • Each network maintains its own token registry

Backup and Recovery

Backup Commands

  1. Create Backup:
python -m validator backup create [--network <network>]
  1. List Backups:
python -m validator backup list
  1. Restore from Backup:
python -m validator backup restore <backup_id>

Network-Specific Backups

  • Separate backup files for each network
  • Network information included in backup metadata
  • Restore validates network compatibility

Troubleshooting

Docker-Specific Issues

  1. Service Status:
# Check service status
docker-compose ps

# View detailed status
docker-compose ps validator
docker-compose ps bitcoin
  1. Logs:
# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f validator
docker-compose logs -f bitcoin
  1. Service Management:
# Restart services
docker-compose restart

# Rebuild services
docker-compose up -d --build

# Reset environment
docker-compose down -v
docker-compose up -d
  1. Common Docker Issues:
  • Port conflicts: Check if ports 5000 or 18443 are in use
  • Volume permissions: Ensure proper ownership of mounted volumes
  • Network connectivity: Verify services can communicate
  • Resource constraints: Monitor container resource usage

General Issues

  1. Network Connection:
# Test network connection
python -m validator network test
  1. Address Validation:
# Validate address format
python -m validator wallet validate <address>
  1. Network Status:
# Check network status
python -m validator network status

Network-Specific Problems

  1. Mainnet Issues:
  • Check Bitcoin Core sync status
  • Verify RPC credentials
  • Confirm network port (8332)
  1. Testnet Issues:
  • Ensure testnet node is running
  • Check testnet port (18332)
  • Verify testnet faucet access
  1. Regtest Issues:
  • Confirm regtest mode is active
  • Check regtest port (18443)
  • Verify block generation