Introduction

Welcome to the Bitcoin-PoCX documentation. This guide covers Linux command-line setup for running nodes and mining on the Bitcoin-PoCX network.

What is Bitcoin-PoCX?

Bitcoin-PoCX is a Bitcoin fork that replaces Proof of Work with Proof of Capacity (PoCX) consensus. Instead of continuously computing hashes, miners pre-compute hashes once during plotting and store them on disk. Mining then simply reads from these plots, resulting in significantly lower power consumption.

Quick Start

Use the guided installer to get up and running quickly:

curl -sSL https://raw.githubusercontent.com/PoC-Consortium/bitcoin-pocx-docs/main/scripts/install.sh | bash

See Quick Start for details and options.

Choose Your Path

Network Status

Note: Bitcoin-PoCX is currently in testnet phase. All examples default to testnet. Mainnet instructions are provided for future reference.

Requirements

All guides assume:

• Linux operating system (Debian/Ubuntu, Fedora, Arch)
• Command-line familiarity
• Basic understanding of blockchain concepts

Getting Help

• Discord
• Telegram
• GitHub Issues

Quick Start

Get up and running with the guided installer.

One-Line Install

curl -sSL https://raw.githubusercontent.com/PoC-Consortium/bitcoin-pocx-docs/main/scripts/install.sh | bash

Or download and review first:

curl -LO https://raw.githubusercontent.com/PoC-Consortium/bitcoin-pocx-docs/main/scripts/install.sh
less install.sh  # review the script
bash install.sh

What the Installer Does

The guided installer will:

1. Detect your OS (Debian/Ubuntu, Fedora, Arch)
2. Install dependencies (curl, tar, etc.)
3. Ask your role:
   • Node Operator (network support only)
   • Solo Miner (mine to your own wallet)
   • Pool Miner (mine through a pool)
4. Download latest releases from GitHub
5. Configure based on your choices:
   • Testnet or Mainnet
   • Create dedicated bitcoin user (optional)
   • Install systemd services (optional)
6. Start services and verify

Installer Options

# Interactive mode (default)
bash install.sh

# Specify role directly
bash install.sh --role node-operator
bash install.sh --role solo-miner
bash install.sh --role pool-miner

# Specify network
bash install.sh --testnet
bash install.sh --mainnet

# Non-interactive with defaults
bash install.sh --role solo-miner --testnet --yes

Manual Installation

Prefer to do it yourself? See the manual guides:

• Node Operator
• Solo Miner
• Pool Miner

Node Operator Guide

Run a Bitcoin-PoCX full node to support network decentralization, validate transactions, and relay blocks.

Prefer automated setup? Use the Quick Start installer.

Overview

Prerequisites

System Requirements

Network Ports

Install Dependencies

# Debian/Ubuntu
sudo apt update && sudo apt install -y curl tar

# Fedora
sudo dnf install -y curl tar

# Arch
sudo pacman -S --noconfirm curl tar

Installation

Download Latest Release

Network Selection

Bitcoin-PoCX is currently in testnet phase. All examples default to testnet.

# Create directory
mkdir -p ~/bitcoin-pocx && cd ~/bitcoin-pocx

# Get latest release URL from GitHub API
LATEST=$(curl -s https://api.github.com/repos/PoC-Consortium/bitcoin/releases/latest \
  | grep "browser_download_url.*x86_64-linux-gnu.tar.gz" \
  | cut -d '"' -f 4)

# Download
curl -LO "$LATEST"

# Extract
tar -xzf *.tar.gz

# Find and add to PATH
BINDIR=$(find . -type d -name "bin" | head -1)
export PATH="$PWD/$BINDIR:$PATH"
echo "export PATH=\"$PWD/$BINDIR:\$PATH\"" >> ~/.bashrc

Verify Installation

# Note: -testnet required until mainnet launch
bitcoind -testnet -?

You should see version info: Bitcoin PoCX daemon version v30.x.x

Configuration

Create Data Directory

mkdir -p ~/.bitcoin-pocx-pocx

Create Configuration File

Create ~/.bitcoin-pocx-pocx/bitcoin.conf:

Testnet (Current)

# Network
testnet=1

# Disable wallet (node operator only)
disablewallet=1

# RPC Settings (cookie auth - no password needed)
server=1

# Node Settings
listen=1
maxconnections=40
dbcache=450

[test]
rpcport=18332

Mainnet (After Launch)

# Disable wallet (node operator only)
disablewallet=1

# RPC Settings (cookie auth - no password needed)
server=1

# Node Settings
listen=1
maxconnections=40
dbcache=450
rpcport=8332

Cookie Authentication: With disablewallet=1, cookie auth is simpler and more secure. Bitcoin Core automatically creates a .cookie file for local RPC access. No password configuration needed.

Running the Node

Start Manually

bitcoind -daemon

Check Status

# Wait ~30 seconds for initial startup, then check blockchain info
bitcoin-cli -testnet getblockchaininfo

Note: During the first few seconds after startup, you may see a JSON parsing error. This is normal - wait for the initial block download to begin.

Monitor Sync Progress

watch bitcoin-cli -testnet getblockchaininfo

When blocks equals headers and initialblockdownload is false, sync is complete.

Systemd Service (Recommended)

Create Service User

sudo useradd -r -m -d /var/lib/bitcoin-pocx -s /sbin/nologin bitcoin
sudo mkdir -p /var/lib/bitcoin-pocx/.bitcoin-pocx
sudo chown -R bitcoin:bitcoin /var/lib/bitcoin-pocx

Copy Configuration

sudo cp ~/.bitcoin-pocx/bitcoin.conf /var/lib/bitcoin-pocx/.bitcoin-pocx/
sudo chown bitcoin:bitcoin /var/lib/bitcoin-pocx/.bitcoin-pocx/bitcoin.conf

Install Binaries System-Wide

sudo install -m 0755 ~/bitcoin-pocx/*/bin/* /usr/local/bin/

Create Service File

Create /etc/systemd/system/bitcoind.service:

[Unit]
Description=Bitcoin PoCX Node
After=network-online.target
Wants=network-online.target

[Service]
Type=forking
User=bitcoin
Group=bitcoin
ExecStart=/usr/local/bin/bitcoind -daemon -datadir=/var/lib/bitcoin-pocx/.bitcoin-pocx
ExecStop=/usr/local/bin/bitcoin-cli -datadir=/var/lib/bitcoin-pocx/.bitcoin-pocx stop
Restart=on-failure
RestartSec=30
TimeoutStartSec=60
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target

Note: With cookie auth, use -datadir= to point to the data directory. The cookie file is read automatically.

Enable and Start

sudo systemctl daemon-reload
sudo systemctl enable bitcoind
sudo systemctl start bitcoind

Check Status

sudo systemctl status bitcoind
sudo journalctl -u bitcoind -f

Verification

Check Peer Connections

# Manual run (as your user)
bitcoin-cli -testnet getpeerinfo | grep -E '"addr"|"subver"'

# Systemd (as bitcoin user)
sudo -u bitcoin bitcoin-cli -datadir=/var/lib/bitcoin-pocx/.bitcoin-pocx getpeerinfo | grep -E '"addr"|"subver"'

Check Block Height

# Manual run
bitcoin-cli -testnet getblockcount

# Systemd
sudo -u bitcoin bitcoin-cli -datadir=/var/lib/bitcoin-pocx/.bitcoin-pocx getblockcount

View Logs

# Manual run
tail -f ~/.bitcoin-pocx/testnet/debug.log

# Systemd
sudo journalctl -u bitcoind -f
# or
sudo tail -f /var/lib/bitcoin-pocx/.bitcoin-pocx/testnet/debug.log

Useful Commands

For manual runs (as your user):

For systemd service:

# Prefix with: sudo -u bitcoin bitcoin-cli -datadir=/var/lib/bitcoin-pocx/.bitcoin-pocx
# Example:
sudo -u bitcoin bitcoin-cli -datadir=/var/lib/bitcoin-pocx/.bitcoin-pocx getblockcount

You’re Done!

Your node is now supporting the Bitcoin-PoCX network by:

• Validating transactions and blocks
• Relaying data to other nodes
• Contributing to network decentralization

Next Steps

Want to start mining? See:

• Solo Miner Guide - Mine directly to your wallet
• Pool Miner Guide - Mine through a pool

Miner Guide

Mine Bitcoin-PoCX using Proof of Capacity. Choose between solo mining (direct rewards) or pool mining (consistent rewards).

Prefer automated setup? Use the Quick Start installer.

Solo vs Pool Mining

Prerequisites

System Requirements

Pool miners don’t need to store the full blockchain permanently - only temporarily for creating assignments.

Install Dependencies

# Debian/Ubuntu
sudo apt update && sudo apt install -y curl tar openssl

# Fedora
sudo dnf install -y curl tar openssl

# Arch
sudo pacman -S --noconfirm curl tar openssl

Step 1: Install Bitcoin Core PoCX

mkdir -p ~/bitcoin-pocx && cd ~/bitcoin-pocx

# Get latest release
LATEST=$(curl -s https://api.github.com/repos/PoC-Consortium/bitcoin/releases/latest \
  | grep "browser_download_url.*x86_64-linux-gnu.tar.gz" \
  | cut -d '"' -f 4)

curl -LO "$LATEST"
tar -xzf *.tar.gz

# Add to PATH
BINDIR=$(find . -type d -name "bin" | head -1)
export PATH="$PWD/$BINDIR:$PATH"
echo "export PATH=\"$PWD/$BINDIR:\$PATH\"" >> ~/.bashrc

Step 2: Configure Node

Generate RPC Password

RPCPASS=$(openssl rand -hex 32)
echo "Save this password: $RPCPASS"

Create Configuration

Create ~/.bitcoin-pocx/bitcoin.conf:

mkdir -p ~/.bitcoin-pocx
cat > ~/.bitcoin-pocx/bitcoin.conf << EOF
testnet=1
server=1
rpcuser=bitcoinrpc
rpcpassword=$RPCPASS
listen=1
maxconnections=40
dbcache=450

[test]
rpcport=18332
# Auto-load mining wallet on startup
wallet=mining
EOF

Note: Miners need RPC password authentication (not cookie auth) for the miner to connect. The wallet=mining line ensures your wallet loads automatically on node restart.

Step 3: Start Node and Create Wallet

# Start node
bitcoind -testnet -daemon

# Wait for startup (~30 seconds)
sleep 30

# Create wallet
bitcoin-cli -testnet createwallet "mining"

# Generate mining address
bitcoin-cli -testnet getnewaddress "mining_rewards"

Save your mining address! You need it for plotting.

⚠️ BACKUP YOUR WALLET - DO THIS NOW ⚠️

# Create backup file
bitcoin-cli -testnet backupwallet ~/mining-wallet-backup.dat

Optional: Export private key for paper backup

# Get private key for your address (KEEP THIS SECRET!)
bitcoin-cli -testnet dumpprivkey "YOUR_MINING_ADDRESS"

Write down this key and store it offline (e.g., safe deposit box, fireproof safe).

For solo mining, wait for the blockchain to sync before mining:

# Check sync progress
bitcoin-cli -testnet getblockchaininfo

Step 4: Install PoCX Framework

cd ~/bitcoin-pocx

# Get latest pocx release (musl build for maximum compatibility)
LATEST=$(curl -s https://api.github.com/repos/PoC-Consortium/pocx/releases/latest \
  | grep "browser_download_url.*x86_64-unknown-linux-musl.tar.gz" \
  | cut -d '"' -f 4)

curl -LO "$LATEST"
tar -xzf pocx-*.tar.gz

Step 5: Create Plots

Plots are pre-computed hashes stored on disk. More capacity = higher rewards.

./pocx_plotter \
  -i YOUR_MINING_ADDRESS \
  -p /path/to/plots \
  -w 100 \
  -x 1

Example for 100 GiB plot:

./pocx_plotter -i tpocx1q... -p /mnt/plots -w 100 -x 1

Plotting takes hours to days depending on size. You can proceed to Step 6 while plotting if you have existing plots.

Step 6: Configure Mining

Choose your mining approach:

6a. Solo Mining

Solo mining submits directly to your local node. You keep 100% of block rewards.

Create ~/bitcoin-pocx/miner.yaml:

chains:
  - name: 'Bitcoin-PoCX Testnet'
    rpc_transport: http
    rpc_host: '127.0.0.1'
    rpc_port: 18332
    rpc_auth:
      type: user_pass
      username: 'bitcoinrpc'
      password: 'YOUR_RPC_PASSWORD'
    block_time_seconds: 120
    submission_mode: wallet

plot_dirs:
  - '/path/to/plots'

Replace YOUR_RPC_PASSWORD with your password from Step 2.

Start mining:

./pocx_miner --config miner.yaml

6b. Pool Mining

Pool mining requires a forging assignment that authorizes the pool to mine on your behalf.

Testnet Pool

Create Forging Assignment

bitcoin-cli -testnet create_assignment \
  "YOUR_MINING_ADDRESS" \
  "tpocx1qp00ljf5sy0kdk4h8x5n4erzdshkzj4cdrhq76k"

• First argument: your mining/plot address
• Second argument: pool’s forging address

Note: Assignments become active after 30 blocks (~1 hour).

Verify your assignment:

bitcoin-cli -testnet get_assignment "YOUR_MINING_ADDRESS"

Revoking Assignments

To switch pools or return to solo mining, you must revoke your current assignment:

bitcoin-cli -testnet revoke_assignment "YOUR_MINING_ADDRESS"

Important timing:

• Revocation takes effect after 720 blocks (~24 hours)
• After revocation completes, wait before creating a new assignment
• New assignments then take another 30 blocks (~1 hour) to activate

So switching pools takes approximately 25 hours total.

Configure Miner for Pool

Create ~/bitcoin-pocx/miner.yaml:

chains:
  - name: 'Testnet Pool'
    rpc_transport: https
    rpc_host: 'pool.testnet.bitcoin-pocx.org'
    rpc_port: 443
    block_time_seconds: 120
    submission_mode: pool

plot_dirs:
  - '/path/to/plots'

Start mining:

./pocx_miner --config miner.yaml

Stop Local Node (Optional)

Once your assignment is confirmed (after 30 blocks), pool miners can stop the local node:

bitcoin-cli -testnet stop

Verification

Check Miner Output

Working miner shows:

[INFO] Connected to local/pool at http://...
[INFO] Scanning plots: /path/to/plots
[INFO] Found X plot files (Y GB capacity)
[INFO] Waiting for new block...

Solo Mining

# Check wallet balance (after finding blocks)
bitcoin-cli -testnet getbalance

Pool Mining

Check your pool’s dashboard for:

• Your address appears as active miner
• Capacity matches your plots
• Submissions being recorded

Block Explorer

Check your address: https://explorer.testnet.bitcoin-pocx.org/

Systemd Services

Miner Service

Create /etc/systemd/system/pocx_miner.service:

[Unit]
Description=PoCX Miner
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=YOUR_USERNAME
ExecStart=/home/YOUR_USERNAME/bitcoin-pocx/pocx_miner --config /home/YOUR_USERNAME/bitcoin-pocx/miner.yaml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

For solo mining, also add After=bitcoind.service and see Node Operator Guide for the bitcoind service.

sudo systemctl daemon-reload
sudo systemctl enable pocx_miner
sudo systemctl start pocx_miner

Troubleshooting

Miner can’t connect

• Solo: Verify bitcoind is running and synced
• Pool: Check pool URL and status
• Verify RPC credentials match

No plots found

• Check plot path in miner.yaml
• Verify plots exist: ls /path/to/plots/*.plot
• Ensure plots match your wallet address

Pool doesn’t see capacity

• Wait for activation - assignments take 30 blocks (~1 hour at 120s/block) to activate
• Verify assignment is confirmed: bitcoin-cli -testnet get_assignment "YOUR_MINING_ADDRESS"
• Check assignment hasn’t expired
• Ensure plots are for correct address

No rewards

• Solo: Normal - depends on capacity vs network
• Pool: Check minimum payout threshold

Maintenance

Renew Pool Assignments

Before expiration, create a new assignment (renewing the same pool doesn’t require revoking):

bitcoind -testnet -daemon  # if stopped
sleep 30
bitcoin-cli -testnet create_assignment \
  "YOUR_MINING_ADDRESS" \
  "tpocx1qp00ljf5sy0kdk4h8x5n4erzdshkzj4cdrhq76k"

Add More Capacity

Create additional plots and add to miner.yaml:

plot_dirs:
  - '/path/to/plots'
  - path: '/path/to/more/plots'

Restart miner to pick up new plots.

Configuration Reference

Complete reference for Bitcoin-PoCX configuration options.

Bitcoin Core PoCX (bitcoin.conf)

Location

Authentication

Cookie Auth (Recommended for Node Operators)

No configuration needed. Bitcoin Core creates a .cookie file automatically:

• Mainnet: ~/.bitcoin-pocx/.cookie
• Testnet: ~/.bitcoin-pocx/testnet/.cookie

RPC Password (Required for Mining)

server=1
rpcuser=bitcoinrpc
rpcpassword=YOUR_SECURE_PASSWORD

Network Options

RPC Options

P2P Network Options

Wallet Options

Performance Options

Example Configurations

Node Operator (Testnet, Cookie Auth)

testnet=1
disablewallet=1
server=1
listen=1
maxconnections=40
dbcache=450

[test]
rpcport=18332

Solo Miner (Testnet, RPC Password)

testnet=1
server=1
rpcuser=bitcoinrpc
rpcpassword=YOUR_PASSWORD
listen=1
maxconnections=40
dbcache=450

[test]
rpcport=18332
wallet=mining

PoCX Miner (miner.yaml)

Location

Typically ~/bitcoin-pocx/miner.yaml or /var/lib/bitcoin/miner.yaml

Chain Configuration

chains:
  - name: 'local'                    # Friendly name
    rpc_transport: http              # Transport type
    rpc_host: '127.0.0.1'            # Node/pool host
    rpc_port: 18332                  # RPC port
    rpc_auth:                        # Auth (required for solo)
      type: user_pass
      username: 'bitcoinrpc'
      password: 'YOUR_PASSWORD'
    block_time_seconds: 120          # Block time
    submission_mode: wallet          # wallet or pool

Plot Configuration

plot_dirs:
  - '/path/to/plots'           # Directory containing plot files

Multiple plot directories:

plot_dirs:
  - '/mnt/disk1/plots'
  - path: '/mnt/disk2/plots'
  - path: '/mnt/disk3/plots'

Full Example (Solo Mining)

chains:
  - name: 'Bitcoin-PoCX Testnet'
    rpc_transport: http
    rpc_host: '127.0.0.1'
    rpc_port: 18332
    rpc_auth:
      type: user_pass
      username: 'bitcoinrpc'
      password: 'your_rpc_password'
    block_time_seconds: 120
    submission_mode: wallet

plot_dirs:
  - '/home/user/plots'
  - path: '/mnt/external/plots'

Full Example (Pool Mining)

chains:
  - name: 'Testnet Pool'
    rpc_transport: https
    rpc_host: 'pool.testnet.bitcoin-pocx.org'
    rpc_port: 443
    block_time_seconds: 120
    submission_mode: pool

plot_dirs:
  - '/home/user/plots'

PoCX Plotter

Command Line Options

Compression Levels

Example

./pocx_plotter \
  -i tpocx1qyouraddress... \
  -p /mnt/plots \
  -w 500 \
  -x 1 \
  -c 4

Network Ports Reference

File Locations Reference

Troubleshooting

Common issues and solutions.

Node Issues

Node won’t start

Symptoms: bitcoind exits immediately or shows errors.

Check logs:

tail -50 ~/.bitcoin-pocx/debug.log        # mainnet
tail -50 ~/.bitcoin-pocx/testnet/debug.log  # testnet

Common causes:

1. Port already in use

   sudo lsof -i :8333   # mainnet
   sudo lsof -i :18333  # testnet
   

2. Corrupt database

   bitcoind -reindex  # takes time
   

3. Insufficient disk space

   df -h ~/.bitcoin-pocx
   

Node not syncing

Symptoms: Block height not increasing, few or no peers.

Check peer connections:

bitcoin-cli -testnet getconnectioncount
bitcoin-cli -testnet getpeerinfo

Solutions:

1. Check firewall

   sudo ufw allow 18333/tcp
   

2. Add peers manually in bitcoin.conf:

   addnode=seed.testnet.bitcoin-pocx.org
   

3. Check internet

   curl -s https://api.github.com | head -1
   

RPC connection refused

Symptoms: bitcoin-cli shows “Could not connect to the server”

Check:

1. Node running?

   pgrep bitcoind
   

2. RPC enabled? Ensure server=1 in bitcoin.conf

3. Correct network flag?

   bitcoin-cli -testnet getblockchaininfo
   

4. Cookie auth working?

   # Check cookie file exists
   ls -la ~/.bitcoin-pocx/testnet/.cookie
   

Miner Issues

Miner can’t connect to node

Symptoms: Connection refused, timeout errors.

Check:

1. Node running and synced?

   bitcoin-cli -testnet getblockchaininfo
   

2. RPC password auth enabled? Mining requires rpcuser/rpcpassword in bitcoin.conf (not cookie auth)

3. Credentials match? Compare bitcoin.conf and miner.yaml

4. Correct URL?

   • Testnet: http://127.0.0.1:18332
   • Mainnet: http://127.0.0.1:8332

No plots found

Symptoms: Miner reports 0 capacity.

Check:

1. Plot path correct?

   ls -la /path/to/plots/*.plot
   

2. Permissions?

   sudo -u bitcoin ls /path/to/plots/
   

3. Plot format valid? Ensure plots created with pocx-plotter

Miner can’t connect to pool

Symptoms: Connection timeout, refused.

Check:

1. Pool URL correct? Verify with pool docs
2. Pool online? Check status page
3. Network access?

   curl -v http://pool-url:port
   

Plotting Issues

Plotting fails or corrupts

Solutions:

1. Check disk space

   df -h /path/to/plots
   

2. Check disk health

   sudo smartctl -a /dev/sdX
   

3. Resume interrupted plots (if supported)

Plotting too slow

Tips:

1. More threads: ./pocx-plotter --threads 8
2. Check I/O: iostat -x 1
3. SSD for temp files if plotter supports it

Pool Mining Issues

Assignment not recognized

Check:

1. Assignment confirmed?

   bitcoin-cli -testnet get_assignment "YOUR_MINING_ADDRESS"
   

2. Correct pool address?

3. Assignment expired?

No pool rewards

Check:

1. Minimum payout threshold - most pools have one
2. Correct payout address in pool dashboard
3. Miner submitting? Check logs for submissions

Systemd Service Issues

Service won’t start

sudo systemctl status bitcoind
sudo journalctl -u bitcoind -n 50

Common issues:

1. Permissions

   sudo chown -R bitcoin:bitcoin /var/lib/bitcoin
   

2. Path issues - verify paths in service file

3. Config errors - check bitcoin.conf syntax

Service starts then stops

Check:

1. Exit code: sudo systemctl status bitcoind
2. Memory limits - service may be OOM killed
3. Logs: sudo journalctl -u bitcoind --since "5 minutes ago"

Getting Help

If stuck:

1. Check debug logs for specific errors
2. Search GitHub issues
3. Discord: https://discord.gg/enQ57bgJdq
4. Telegram: https://t.me/+aqavnqlq2vg0Mzhk

When asking for help, include:

• OS and version
• Config files (redact passwords)
• Full error messages
• Steps to reproduce