Avian Stratum Proxy

A dual-algorithm stratum mining proxy for Avian (AVN) blockchain supporting both X16RT (GPU) and MinotaurX (CPU) proof-of-work algorithms.

Features

• ✅ Dual Algorithm Support: X16RT for GPU mining and MinotaurX for CPU mining
• ✅ Dual Port Operation: Separate ports for each algorithm with unified dashboard
• ✅ ZMQ Support: Instant new block notifications
• ✅ Notifications: Discord and Telegram alerts for blocks found and miner connections
• ✅ Web Dashboard (optional): Real-time monitoring of all miners, hashrates, and blocks
• ✅ SQLite Database (optional): Historical statistics and block history
• ✅ Variable Difficulty (optional): Auto-adjustment per algorithm and per miner
• ✅ Docker Ready: Complete docker compose setup with health checks
• ✅ Flexible Difficulty: Algorithm-specific difficulty configuration

Algorithm Support

X16RT (GPU Mining)

• Port: 54321 (default)
• Recommended For: NVIDIA/AMD GPUs
• Default Difficulty: 1.0
• Hash Library: avian-x16rt-hash

MinotaurX (CPU Mining)

• Port: 54322 (default)
• Recommended For: CPU miners
• Default Difficulty: 0.001
• Hash Library: avian-minotaurx-hash

Quick Start

Choose your setup method:

Option 1: Docker Compose (Recommended)

Prerequisites: Docker and Docker Compose installed

The Docker setup automatically builds Avian from source - no need to download binaries!

1. Configure environment:

   Linux/macOS:

   # Copy example configuration
   cp .env.example.gpu .env
   
   # Edit .env - set a secure RPC password
   nano .env

   Windows (PowerShell):

   # Copy example configuration
   Copy-Item .env.example.gpu .env
   
   # Edit .env - set a secure RPC password
   notepad .env

2. Start services (first build takes ~10-15 minutes to compile Avian):

   docker compose up -d
   docker compose logs -f stratum-proxy  # Watch logs

   Note: First build compiles Avian from source (https://github.com/AvianNetwork/Avian). Subsequent starts are instant since the image is cached.

3. Connect miners:

   For GPU miners (X16RT):

   • Server: localhost:54321
   • Username: Your Avian address
   • Password: anything

   For CPU miners (MinotaurX):

   • Server: localhost:54322
   • Username: Your Avian address
   • Password: anything

Option 2: Native Python (Your Own Node)

Prerequisites: Python 3.10+, running aviand node

1. Configure blockchain node:

   • Edit your avian.conf:

     server=1
     rpcuser=avian_user
     rpcpassword=your_secure_password
     rpcport=7896
     rpcallowip=127.0.0.1
     
     # ZMQ for instant block notifications
     zmqpubhashblock=tcp://127.0.0.1:28332
     

   • Start aviand

2. Install Python dependencies:

   pip install -r requirements.txt

3. Configure proxy:

   Linux/macOS:

   cp .env.example.gpu .env

   Windows (PowerShell):

   Copy-Item .env.example.gpu .env

   Then edit .env to match your node RPC settings.

4. Run proxy:

   python -m avn_proxy.run

5. Connect miners: Same as Docker method above

Configuration

Essential Environment Variables

Variable	Description	Default
AVN_RPC_PORT	Avian RPC port	7896
AVN_RPC_USER / AVN_RPC_PASS	Avian RPC credentials	-
STRATUM_PORT_X16RT	X16RT (GPU) mining port	54321
STRATUM_PORT_MINOTAURX	MinotaurX (CPU) mining port	54322
STATIC_SHARE_DIFFICULTY_X16RT	GPU share difficulty	1.0
STATIC_SHARE_DIFFICULTY_MINOTAURX	CPU share difficulty	0.001
ENABLE_VARDIFF	Enable variable difficulty	true
ENABLE_ZMQ	Enable ZMQ block notifications	true
DISCORD_WEBHOOK_URL	Discord webhook for notifications	(blank = disabled)
TELEGRAM_BOT_TOKEN	Telegram bot token	(blank = disabled)
TELEGRAM_CHAT_ID	Telegram chat ID	(blank = disabled)
ENABLE_DASHBOARD	Enable web dashboard	true
DASHBOARD_PORT	Web dashboard port	8080
ENABLE_DATABASE	Enable statistics database	true

See NOTIFICATIONS.md for notification setup and DASHBOARD.md for dashboard configuration.

Share Difficulty

Share difficulty determines how often miners submit shares:

X16RT (GPU) Default: 1.0

• Frequent shares for hashrate tracking
• Auto-adjusts with VarDiff enabled

MinotaurX (CPU) Default: 0.001

• Very low difficulty for slower CPUs
• Ensures regular share submissions

With VarDiff enabled (recommended), these are only used as starting points.

Variable Difficulty (VarDiff)

VarDiff automatically adjusts difficulty per miner to target ~15 seconds between shares:

GPU Settings (X16RT):

• Min: 0.1, Max: 1,000,000, Start: 1.0

CPU Settings (MinotaurX):

• Min: 0.0001, Max: 10.0, Start: 0.001

Avian Dual Algorithm Mining

How It Works

Avian supports two proof-of-work algorithms:

X16RT (GPU)

Block Header (80 bytes)
    ↓
X16RT hash → Compare with AVN target
    ↓
    └─→ Meets target? → Submit to AVN → Earn AVN rewards

MinotaurX (CPU)

Block Header (80 bytes)
    ↓
MinotaurX hash → Compare with AVN target
    ↓
    └─→ Meets target? → Submit to AVN → Earn AVN rewards

Both algorithms work on the same blockchain - miners choose based on their hardware.

Block Finding

When a share meets or exceeds the network difficulty target:

1. Share submitted by miner
2. Proxy validates hash using algorithm (X16RT or MinotaurX)
3. If hash ≤ network target → Block found!
4. Submit block to Avian node
5. Notification sent (if configured)
6. Dashboard shows block with algorithm tag

Monitoring

Block submissions are logged to ./submit_history/:

• AVN-X16RT_<height>_<job>_<time>.txt - GPU blocks
• AVN-MINOTAURX_<height>_<job>_<time>.txt - CPU blocks

Check logs:

# Docker
docker compose logs -f stratum-proxy

# Native
# Watch console output

Troubleshooting

"Block template not ready": Node still syncing, wait for full sync

Miner can't connect: Check firewall, verify STRATUM_PORT is correct

Low hashrate: Adjust STATIC_SHARE_DIFFICULTY for more frequent feedback

Build fails: Ensure Docker has enough memory (4GB+ recommended for compilation)

Advanced

ZMQ Block Notifications

The proxy uses ZMQ for instant block notifications instead of polling:

• AVN: Port 28332 (hashblock)

Disable with ENABLE_ZMQ=false if needed.

Variable Difficulty

Enable automatic difficulty adjustment per miner:

ENABLE_VARDIFF=true
VARDIFF_TARGET_SHARE_TIME=15.0    # Target seconds between shares
VARDIFF_MIN_DIFFICULTY=100.0      # Minimum difficulty floor
VARDIFF_MAX_DIFFICULTY=10000000.0 # Maximum difficulty ceiling
VARDIFF_START_DIFFICULTY=10000.0  # Initial difficulty for new miners

Additional tuning options (see .env.example.gpu or .env.example.asic for full list):

VARDIFF_RETARGET_SHARES=20        # Shares before retargeting
VARDIFF_RETARGET_TIME=300.0       # Max seconds before retargeting
VARDIFF_UP_STEP=2.0               # Multiplier when increasing difficulty
VARDIFF_DOWN_STEP=0.5             # Multiplier when decreasing difficulty
VARDIFF_STATE_PATH=data/vardiff_state.json  # Persist difficulty between restarts
VARDIFF_CHAIN_HEADROOM=0.9        # Fraction of chain difficulty as upper cap

Project Structure

avn_proxy/
├── consensus/    # Block/transaction building
├── db/           # Database schema and queries
├── rpc/          # RPC client implementations
├── state/        # Template state management
├── stratum/      # Stratum protocol server
├── utils/        # Hashing and encoding
├── web/          # Dashboard web interface
└── zmq/          # ZMQ block listeners

License

MIT License - See LICENSE file

All Environment Variables

Core Settings

Variable	Description	Default
AVN_RPC_USER	Avian RPC username	avian_user
AVN_RPC_PASS	Avian RPC password	-
AVN_RPC_PORT	Avian RPC port	7896
AVN_P2P_PORT	Avian P2P port	7895
STRATUM_PORT_X16RT	Stratum proxy port for X16RT (GPU)	54321
STRATUM_PORT_MINOTAURX	Stratum proxy port for MinotaurX (CPU)	54322
PROXY_SIGNATURE	Custom coinbase signature	/avian-stratum-proxy/
USE_EASIER_TARGET	Enable easier target selection	true
STATIC_SHARE_DIFFICULTY	Static share difficulty (GPU=1, ASIC=512)	512.0
TESTNET	Use testnet	false
LOG_LEVEL	Logging level (DEBUG, INFO, WARNING, ERROR)	INFO
SHOW_JOBS	Show job updates in logs	false
ENABLE_ZMQ	Enable ZMQ block notifications	true
AVN_ZMQ_ENDPOINT	ZMQ endpoint URL	tcp://avian:28332
ENABLE_DASHBOARD	Enable web dashboard	false
DASHBOARD_PORT	Web dashboard port	8080
ENABLE_DATABASE	Enable statistics database	false
DISCORD_WEBHOOK_URL	Discord webhook for notifications	(blank = disabled)
TELEGRAM_BOT_TOKEN	Telegram bot token	(blank = disabled)
TELEGRAM_CHAT_ID	Telegram chat ID	(blank = disabled)

Variable Difficulty Settings

Variable	Description	Default
ENABLE_VARDIFF	Enable variable difficulty per miner	false
VARDIFF_TARGET_SHARE_TIME	Target seconds between shares	15.0
VARDIFF_MIN_DIFFICULTY	Minimum difficulty floor	100.0
VARDIFF_MAX_DIFFICULTY	Maximum difficulty ceiling	10000000.0
VARDIFF_START_DIFFICULTY	Initial difficulty for new miners	10000.0
VARDIFF_RETARGET_SHARES	Shares before retargeting	20
VARDIFF_RETARGET_TIME	Max seconds before retargeting	300.0
VARDIFF_UP_STEP	Multiplier when increasing difficulty	2.0
VARDIFF_DOWN_STEP	Multiplier when decreasing difficulty	0.5
VARDIFF_EMA_ALPHA	EMA smoothing factor	0.3
VARDIFF_INACTIVITY_LOWER	Seconds before inactivity drop	90.0
VARDIFF_INACTIVITY_MULTIPLES	Multiples of target time for inactivity	6.0
VARDIFF_INACTIVITY_DROP_FACTOR	Factor to reduce difficulty on inactivity	0.5
VARDIFF_STATE_PATH	Path to persist difficulty state	data/vardiff_state.json
VARDIFF_WARM_START_MINUTES	Minutes to use saved difficulty on restart	60
VARDIFF_CHAIN_HEADROOM	Fraction of chain difficulty as upper cap	0.9

Building from Source

Docker automatically builds Avian from source using https://github.com/AvianNetwork/Avian (official repository).

Build Configuration

You can specify a different branch or tag by modifying the build arg in docker-compose.yml:

avian:
  build:
    context: .
    dockerfile: Dockerfile.avian
    args:
      AVIAN_VERSION: master  # or a specific tag like v5.1.0

Manual Build (for native installs)

If running without Docker, build Avian manually:

# Install dependencies
sudo apt-get install build-essential cmake ninja-build libboost-all-dev \
    libevent-dev libssl-dev libdb++-dev libminiupnpc-dev libzmq3-dev

# Clone and build
git clone https://github.com/AvianNetwork/Avian.git
cd Avian
mkdir build && cd build
cmake -GNinja .. -DBUILD_AVIAN_QT=OFF
ninja

# Binaries are in build/src/
# - aviand
# - avian-cli

Services

• avian: Avian daemon
  • RPC: localhost:7332
  • P2P: localhost:7333
• stratum-proxy: Mining proxy
  • Stratum: localhost:54321
  • Dashboard: localhost:8080

Customization

Proxy Signature

The proxy includes a customizable signature in coinbase transactions to identify your mining setup.

Configuration Options:

1. Environment Variable (recommended for Docker):

   # In .env file
   PROXY_SIGNATURE=/your-pool-name/

2. Command Line Argument:

   python -m avn_proxy.run --proxy-signature="/my-custom-signature/" [other args...]

Guidelines:

• Keep it short (max 32 bytes recommended)
• Use forward slashes or other characters to make it recognizable
• Examples: /MyPool/, /Solo-Miner-2025/, /AVN-Solo/

Default: /avian-stratum-proxy/

Usage

Native Python Execution (Without Docker)

If you prefer to run the proxy directly with Python instead of using Docker:

Prerequisites

1. Python 3.10+ installed on your system
2. Avian node running separately (either locally or remotely)
3. Python dependencies installed

Setup Steps

1. Install Python dependencies:

   pip install -r requirements.txt

2. Configure your blockchain node (optional):

   Copy config/avian.conf to your Avian data directory:

   Data directory locations:

   • Windows: %APPDATA%\Avian\
   • Linux: ~/.avian/
   • macOS: ~/Library/Application Support/Avian/

3. Ensure your node is running:

   • Avian node accessible via RPC (default: localhost:7332)

4. Run the proxy:

   For localhost testing only:

   python -m avn_proxy.run \
     --ip=127.0.0.1 \
     --port=54321 \
     --rpcuser=your_avn_rpc_user \
     --rpcpass=your_avn_rpc_password \
     --rpcip=127.0.0.1 \
     --rpcport=7332 \
     --use-easier-target \
     --log-level=INFO

   For remote miners:

   python -m avn_proxy.run \
     --ip=0.0.0.0 \
     --port=54321 \
     --rpcuser=your_avn_rpc_user \
     --rpcpass=your_avn_rpc_password \
     --use-easier-target \
     --log-level=INFO

Network Binding Options

IP Address	Use Case	Security	Description
127.0.0.1	Testing/Development	High	Localhost only - miners must run on same machine
0.0.0.0	Production Mining	Medium	All interfaces - remote miners can connect
192.168.1.100	Specific Network	Medium	Bind to specific IP - only that network interface

Available Options

Run python -m avn_proxy.run --help to see all available options:

• --ip: IP address to bind proxy server on (default: 127.0.0.1)
• --port: Stratum port (default: 54321)
• --rpcip/--rpcport: Avian RPC connection
• --proxy-signature: Custom coinbase signature
• --use-easier-target: Enable easier target selection
• --testnet: Use testnet mode
• --log-level: Set logging level (DEBUG, INFO, WARNING, ERROR)
• --jobs: Show job updates

Docker Compose Usage

For a complete containerized setup:

Start All Services

docker compose up -d

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f stratum-proxy
docker compose logs -f avian

Stop Services

docker compose down

Update Configuration

Linux/macOS:

nano .env
docker compose down && docker compose up -d

Windows (PowerShell):

notepad .env
docker compose down; docker compose up -d

Mining

Connect your miner to the stratum proxy:

• Host: Your server IP
• Port: 54321 (or your configured STRATUM_PORT)
• Username: Your Avian address (e.g., RYourAvianAddress.worker1)
• Password: Any value

The first address that connects becomes the payout address for Avian rewards.

Sample Miner Commands

For X16RT (GPU) mining on port 54321:

# For localhost testing
miner.exe --algorithm x16rt --pool localhost:54321 --wallet RYourAvianAddress

# For remote server
miner.exe --algorithm x16rt --pool 192.168.1.100:54321 --wallet RYourAvianAddress.worker1

For MinotaurX (CPU) mining on port 54322:

# For localhost testing
miner.exe --algorithm minotaurx --pool localhost:54322 --wallet RYourAvianAddress

# For remote server
miner.exe --algorithm minotaurx --pool 192.168.1.100:54322 --wallet RYourAvianAddress.worker1

Note: Replace RYourAvianAddress with your actual Avian address.

RPC Command Line Access

You can interact with the blockchain node using RPC commands:

Docker Container RPC Commands

Avian Commands:

Note: The -u avian flag is required to run as the avian user, which has access to the RPC credentials in the configuration file.

# Get mining information
docker compose exec -u avian avian avian-cli getmininginfo

# Get blockchain info
docker compose exec -u avian avian avian-cli getblockchaininfo

# Get wallet info
docker compose exec -u avian avian avian-cli getwalletinfo

# Generate new address
docker compose exec -u avian avian avian-cli getnewaddress

# Get network connections
docker compose exec -u avian avian avian-cli getconnectioncount

Native Installation RPC Commands

# Using configuration file (recommended)
avian-cli getmininginfo

# Using explicit RPC parameters
avian-cli -rpcuser=avian_user -rpcpassword=avian_password -rpcport=7896 getmininginfo

Useful RPC Commands for Mining

Monitor Mining Status:

# Check if mining is active
getmininginfo

# Get current block height
getblockcount

# Get network hash rate
getnetworkhashps

# Check wallet balance
getbalance

# List recent transactions
listtransactions

Wallet Setup

Important: Before generating addresses, you must first create and load a wallet.

1. Create Avian Wallet:

   # Create a new wallet named "default"
   docker compose exec -u avian avian avian-cli createwallet "default"
   
   # Load the wallet
   docker compose exec -u avian avian avian-cli loadwallet "default"

2. Generate Avian Address:

   docker compose exec -u avian avian avian-cli getnewaddress

Monitoring

Check blockchain sync status:

docker compose exec -u avian avian avian-cli getblockchaininfo

Check mining info:

docker compose exec -u avian avian avian-cli getmininginfo

Troubleshooting

Services Won't Start

• Check Docker logs: docker compose logs [service-name]
• Verify .env file configuration
• Ensure ports aren't already in use

Proxy Connection Issues

• Verify daemon is synced
• Check RPC connectivity
• Review proxy logs for errors

Mining Issues

• Ensure miner is pointing to correct host:port
• Verify wallet address format (Avian addresses start with "R" for mainnet)
• Check proxy logs for submission details

Security Notes

• Change default RPC passwords in .env
• Consider using firewall rules for RPC ports
• Keep wallet backups secure
• Monitor for unauthorized access

File Structure

avian-stratum-proxy/
├── docker-compose.yml       # Main compose file
├── .env.example             # Configuration template
├── .gitignore               # Git ignore rules
├── Dockerfile               # Proxy container build
├── Dockerfile.avian         # Avian node container (builds from source)
├── entrypoint.sh            # Proxy entrypoint script
├── entrypoint-avian.sh      # Avian node entrypoint script
├── requirements.txt         # Python dependencies
├── setup.sh / setup.bat     # Setup scripts for different platforms
├── health-check-avian.sh    # Avian node health check
├── config/                  # Configuration templates directory
│   └── avian.conf           # Avian daemon config template
├── avn_proxy/               # Proxy application package
│   ├── consensus/           # Block/transaction building
│   ├── db/                  # Database schema and queries
│   ├── rpc/                 # RPC client implementations
│   ├── state/               # Template state management
│   ├── stratum/             # Stratum protocol server
│   ├── utils/               # Hashing and encoding
│   ├── web/                 # Dashboard web interface
│   └── zmq/                 # ZMQ block listeners
└── submit_history/          # Block submission logs