xpowermine/miner repository overview

⁠XPower Miner - Docker Deployment Guide

Containerized Deno-based cryptocurrency mining service for XPower tokens on the Avalanche blockchain.

⁠Overview

This Docker container runs the XPower cryptocurrency miner, which:

• Mines XPower tokens on the Avalanche C-Chain
• Uses multiple workers for parallel proof-of-work computation
• Restarts the mining session hourly via the Supercronic scheduler
• Automatically or manually configures gas parameters
• Integrates with Avalanche smart contracts (v10a, v10b, etc.)

Technology Stack:

• Debian-based container image (bookworm-slim)
• Supercronic scheduler
• Avalanche blockchain integration

⁠Quick Start

⁠Build

./docker/xpowermine/miner/build.sh

Or directly:

docker build -t xpowermine/miner -f docker/xpowermine/miner/Dockerfile .

⁠Configuration

⁠Required Environment Variables

Blockchain Configuration:

CONTRACT_RUN=v11b # Optional: Smart contract version (v11a, v11b, etc.)

Minting Configuration:

INIT_ADDRESS_PK=0x... # Optional: Private key for init transaction signing
MINT_ADDRESS_PK=0x... # Required: Private key for mint transaction signing
MINT_ADDRESS=0x...    # Required: Beneficiary address for minted tokens

⁠Optional Environment Variables

Blockchain Connection(s):

PROVIDER_URL=https://avalanche.drpc.org,https://avalanche-c-chain-rpc.publicnode.com,https://api.avax.network/ext/bc/C/rpc

Mining Parameters:

MINT_LEVEL=8   # Default: 8 (proof-of-work difficulty, 2^8-1=255 XPOW minimum)
MINE_WORKERS=7 # Default: 7 (number of mining workers, set to cores-1)
MINT_BATCH=1   # Default: 1 (nonces per mint-batch transaction)

Gas Parameters (Optional):

MAX_PRIORITY_FEE_PER_GAS=0 # Default: auto (0 recommended to avoid extra fees)
MAX_FEE_PER_GAS=500000000  # Default: auto (0.5 Gwei recommended)
GAS_LIMIT=100000           # Default: auto (0.1 Mwei recommended)

⁠Running the Container

⁠With Automatic Gas Parameters (Recommended)

docker run --rm -ti \
-e PROVIDER_URL="$PROVIDER_URL" \
-e CONTRACT_RUN="$CONTRACT_RUN" \
-e INIT_ADDRESS_PK="$INIT_ADDRESS_PK" \
-e MINT_ADDRESS_PK="$MINT_ADDRESS_PK" \
-e MINT_ADDRESS="$MINT_ADDRESS" \
-e MINT_LEVEL="$MINT_LEVEL" \
-e MINE_WORKERS="$MINE_WORKERS" \
-e MINT_BATCH="$MINT_BATCH" \
xpowermine/miner

⁠With Custom Gas Parameters

# Set custom gas parameters
export MAX_PRIORITY_FEE_PER_GAS=0 # 0.0 gwei
export MAX_FEE_PER_GAS=500000000  # 0.5 gwei
export GAS_LIMIT=100000           # 0.1 mwei

# Run with custom gas settings
docker run --rm -ti \
-e PROVIDER_URL="$PROVIDER_URL" \
-e CONTRACT_RUN="$CONTRACT_RUN" \
-e INIT_ADDRESS_PK="$INIT_ADDRESS_PK" \
-e MINT_ADDRESS_PK="$MINT_ADDRESS_PK" \
-e MINT_ADDRESS="$MINT_ADDRESS" \
-e MINT_LEVEL="$MINT_LEVEL" \
-e MINE_WORKERS="$MINE_WORKERS" \
-e MINT_BATCH="$MINT_BATCH" \
-e MAX_PRIORITY_FEE_PER_GAS="$MAX_PRIORITY_FEE_PER_GAS" \
-e MAX_FEE_PER_GAS="$MAX_FEE_PER_GAS" \
-e GAS_LIMIT="$GAS_LIMIT" \
xpowermine/miner

⁠Scheduling

The container runs mine.sh once at startup and then every hour via the Supercronic scheduler (mine.cron). Each run kills the previous mining session and starts a fresh one, ensuring workers always mine against a recent block hash. Supercronic inherits the container environment, so variables passed with docker run -e ... remain available to every hourly run — no extra setup is required.

⁠Providing Secrets via Files (Alternative)

Instead of passing MINT_ADDRESS and {MINT,INIT}_ADDRESS_PK as environment variables, mine.sh can read them from files (e.g. Docker / Swarm secrets). If the corresponding environment variable is unset, mine.sh falls back to:

Example with bind-mounted secret files:

docker run --rm -ti \
-e CONTRACT_RUN="$CONTRACT_RUN" \
-v /path/to/mint-address:/var/run/secrets/mint-address:ro \
-v /path/to/mint-address-pk:/var/run/secrets/mint-address-pk:ro \
-v /path/to/init-address-pk:/var/run/secrets/init-address-pk:ro \
xpowermine/miner

⁠Configuration Guide

⁠PROVIDER_URL

Default: https://api.avax.network/ext/bc/C/rpc

The public RPC endpoint of the Avalanche network works well most of the time. However, if your container is behind a popular VPN or your minting frequency is high, using your own custom endpoint is recommended.

Recommendation: Use the default unless you experience rate limiting or connectivity issues.

⁠INIT_ADDRESS_PK

Default: MINT_ADDRESS_PK

The private key of an address that holds AVAX to pay for init transaction costs. If not provided, then by default the MINT_ADDRESS_PK is used.

Security Recommendations:

• Do NOT fund this address with large amounts of AVAX
• Regularly refill with small amounts instead
• Keep the private key secure and never commit it to version control
• Consider using a dedicated address only for mining operations

⁠MINT_ADDRESS_PK (required)

The private key of an address that holds AVAX to pay for mint transaction costs.

Security Recommendations:

• Do NOT fund this address with large amounts of AVAX
• Regularly refill with small amounts instead
• Keep the private key secure and never commit it to version control
• Consider using a dedicated address only for mining operations

⁠MINT_ADDRESS (required)

The beneficiary address that will receive the mined and minted XPOW tokens.

Security Recommendations:

• Use a DIFFERENT address from MINT_ADDRESS_PK for operational security
• This address can be your main wallet or a dedicated receiving address
• Does not need to hold any AVAX

⁠MINT_LEVEL

Default: 8

Controls the minimum proof-of-work difficulty. Only work corresponding to 2^MINT_LEVEL - 1 XPOW or more will be minted.

Trade-offs:

• Lower values (e.g., 6-7): Faster mining, more frequent mints, higher total gas costs
• Higher values (e.g., 9-10): Slower mining, less frequent mints, lower total gas costs, higher rewards per mint

Recommendation: 8 or higher for current state-of-the-art CPUs. This provides a good balance between energy consumption and minting costs.

⁠MINE_WORKERS

Default: 7

Number of parallel mining workers (threads) to use.

Recommendation: Set to one LESS than your total CPU cores to avoid system lockup.

Examples:

• 4-core CPU: MINE_WORKERS=3
• 8-core CPU: MINE_WORKERS=7
• 16-core CPU: MINE_WORKERS=15

Check your CPU count: nproc or lscpu

⁠MINT_BATCH

Default: 1

Number of mined nonces that xpow-mint groups into a single mintBatch transaction. With 1, each nonce is minted individually via mint (the historical behavior).

Trade-offs:

• Higher values: fewer transactions (lower total base-fee overhead) and a higher reward per transaction, but each transaction needs more gas, a wider time window (the batch must complete before the block hash expires), and a failure reverts the whole batch.
• Lower values: more frequent transactions, lower per-transaction risk.

Requirements:

• The deployed XPower contract for the selected CONTRACT_RUN must implement mintBatch; otherwise minting reverts.
• Raise GAS_LIMIT accordingly (a mintBatch of N nonces costs more than N individual mint calls). GAS_LIMIT is not scaled automatically.

⁠MAX_PRIORITY_FEE_PER_GAS

Default: Auto (blockchain determines)

Priority fee paid to validators for transaction inclusion.

Recommendation: 0 (zero) to avoid paying extra fees. This seems to work well on Avalanche. Increase to 1000000000 (1 Gwei) only if transactions are regularly rejected.

⁠MAX_FEE_PER_GAS

Default: Auto (blockchain determines)

Maximum total gas fee willing to pay per transaction.

Recommendation: 500000000 (0.5 Gwei) or less. Increase to 1000000000 (1 Gwei) only if transactions are regularly rejected.

⁠GAS_LIMIT

Default: Auto (blockchain determines)

Maximum gas units to use for each transaction.

Recommendation: 100000 (0.1 Mwei). This value seems to work reliably for minting operations.

⁠Security Considerations

Private Key Management:

• Never commit INIT_ADDRESS_PK to version control
• Never commit MINT_ADDRESS_PK to version control
• Use environment variables or secure secrets management
• Keep minimal AVAX in the minting address
• Use a separate beneficiary address (MINT_ADDRESS)

Resource Management:

• Mining is CPU-intensive and can damage hardware over time
• Monitor CPU temperatures and usage
• Ensure adequate cooling
• Consider electricity costs vs mining rewards

Network Security:

• The container only makes outbound connections to the blockchain
• No ports need to be exposed
• All sensitive data is passed via environment variables

⁠Monitoring

Container Logs:

docker logs -f xpowermine-miner

Resource Usage:

docker stats xpowermine-miner

System Temperature (if available):

sensors # Linux with lm-sensors

⁠Troubleshooting

Transactions rejected:

• Increase MAX_FEE_PER_GAS and/or MAX_PRIORITY_FEE_PER_GAS
• Check AVAX balance in MINT_ADDRESS_PK address
• Verify PROVIDER_URL is accessible

Low mining performance:

• Increase MINE_WORKERS (but leave at least 1 core free)
• Verify CPU is not thermal throttling
• Check if other processes are consuming CPU

Container exits:

• Check logs: docker logs xpowermine-miner
• Verify all required environment variables are set
• Ensure MINT_ADDRESS_PK and CONTRACT_RUN are correct

⁠License

GPL-3.0 - See project repository for details.