Knotsday

Install Claude Code

# Install via npm (requires Node.js 18+)
npm install -g @anthropic-ai/claude-code

# Or if you don't have Node.js:
sudo apt-get install -y nodejs npm
npm install -g @anthropic-ai/claude-code

You will need an Anthropic API key. Get one at console.anthropic.com, then set it:

export ANTHROPIC_API_KEY="your-api-key-here"

Download the Knotsday skill file

# Download the skill file to your project
mkdir -p ~/.claude
wget -O ~/.claude/SKILL.md https://knotsday.com/SKILL.md

This file teaches Claude Code how Bitcoin Knots, ckpool, and Bitaxe work together. It knows the correct configuration, common errors, and how to fix them.

Run Claude Code

# Start Claude Code in your home directory
cd ~
claude

Then tell it what is wrong. Examples:

# Example prompts:
"My Bitcoin Knots node won't start, check the debug log"
"My Bitaxe can't connect to ckpool"
"Set up my node from scratch following the Knotsday guide"
"Check if my drive is ext4 and migrate if needed"
"My node shows 'Failed to read block' errors"
"Configure my Bitaxe at 192.168.1.50 to point to my node"

#!/bin/bash
# Knotsday diagnostic script - run and share the output

echo "=== Bitcoin Knots ==="
bitcoind --version 2>/dev/null | head -1 || echo "NOT INSTALLED"

echo ""
echo "=== Node Status ==="
bitcoin-cli getblockchaininfo 2>&1 | head -10 || echo "NODE NOT RUNNING"

echo ""
echo "=== Peer Connections ==="
bitcoin-cli getconnectioncount 2>&1 || echo "CANNOT CONNECT"

echo ""
echo "=== Drive Filesystem ==="
df -Th /media/$USER/bitcoin 2>/dev/null || \
  df -Th $(grep datadir ~/.bitcoin/bitcoin.conf 2>/dev/null | cut -d= -f2) 2>/dev/null || \
  echo "DATADIR NOT FOUND"

echo ""
echo "=== ckpool ==="
systemctl --user status ckpool 2>&1 | head -5 || echo "NOT A SERVICE"
pgrep -a ckpool || echo "NOT RUNNING"

echo ""
echo "=== Recent Errors ==="
DATADIR=$(grep datadir ~/.bitcoin/bitcoin.conf 2>/dev/null | cut -d= -f2)
if [ -f "$DATADIR/debug.log" ]; then
  grep -i "error\|fatal\|failed" "$DATADIR/debug.log" | tail -10
else
  echo "NO DEBUG LOG FOUND"
fi

echo ""
echo "=== Disk Space ==="
df -h / /media/$USER/bitcoin 2>/dev/null

echo ""
echo "=== Network Interfaces ==="
ip addr show | grep "inet " | grep -v 127.0.0.1

wget -O /tmp/knotsday-diag.sh https://knotsday.com/scripts/diagnose.sh
chmod +x /tmp/knotsday-diag.sh
/tmp/knotsday-diag.sh

Check the debug log

# Find your datadir
grep datadir ~/.bitcoin/bitcoin.conf

# Read the last 50 lines of the debug log
tail -50 /path/to/datadir/debug.log

Common causes:

• "Failed to load database path" — A wallet reference in settings.json points to a wallet that no longer exists. Edit the file and clear the "wallet" array:

  # Edit settings.json in your datadir
  nano /path/to/datadir/settings.json
  
  # Change "wallet": ["old_wallet"] to "wallet": []

• "Cannot obtain a lock" — Another instance is already running, or a previous instance did not shut down cleanly:

  # Check for running instances
  pgrep -a bitcoin
  
  # Remove stale lock file (only if no instance is running!)
  rm /path/to/datadir/.lock

• Drive not mounted — Your external drive may not have auto-mounted:

  # Check if mounted
  mount | grep bitcoin
  
  # Mount manually
  sudo mount /dev/sda1 /media/$USER/bitcoin
  
  # Or remount all fstab entries
  sudo mount -a

Diagnose block file corruption

# Count zero-byte block files
DATADIR=$(grep datadir ~/.bitcoin/bitcoin.conf | cut -d= -f2)
echo "Zero-byte block files:"
find "$DATADIR/blocks/" -name "blk*.dat" -size 0 | wc -l

echo "Total block files:"
find "$DATADIR/blocks/" -name "blk*.dat" | wc -l

echo "Filesystem type:"
df -Th "$DATADIR" | tail -1 | awk '{print $2}'

If you see zero-byte files and the filesystem is exFAT or NTFS, you need to migrate to ext4. See the migration script.

If the filesystem is already ext4, a simple reindex will re-download the missing blocks:

bitcoin-qt -reindex &

Diagnose sync performance

# Check current sync progress
bitcoin-cli getblockchaininfo | grep -E "blocks|headers|verificationprogress"

# Check disk I/O (high iowait = disk bottleneck)
iostat -x 1 5

# Check if dbcache is set high enough
grep dbcache ~/.bitcoin/bitcoin.conf

# Check available RAM
free -h

# Check disk type (SSD vs HDD)
lsblk -d -o NAME,ROTA,SIZE,MODEL
# ROTA=0 means SSD (good), ROTA=1 means HDD (slow)

Fixes:

• Increase dbcache to 4000-8000 during initial sync
• Use an SSD, not an HDD — HDDs are 10-50x slower for sync
• Close other disk-heavy applications
• Check your internet speed: curl -s https://speed.cloudflare.com/__down?bytes=25000000 > /dev/null

Debug ckpool connection

# Check if ckpool is running
systemctl --user status ckpool

# Check ckpool logs
tail -20 ~/.local/var/log/ckpool/ckpool.log

# Test RPC credentials manually
RPC_USER=$(grep rpcuser ~/.bitcoin/bitcoin.conf | cut -d= -f2)
RPC_PASS=$(grep rpcpassword ~/.bitcoin/bitcoin.conf | cut -d= -f2)
bitcoin-cli -rpcuser=$RPC_USER -rpcpassword=$RPC_PASS getblockcount

# Verify ckpool config matches bitcoin.conf
echo "=== ckpool config ==="
cat ~/.local/etc/ckpool.conf | grep -E "auth|pass"
echo "=== bitcoin.conf ==="
grep -E "rpcuser|rpcpassword" ~/.bitcoin/bitcoin.conf

Common causes:

• Mismatched credentials — The auth and pass in ckpool.conf must match rpcuser and rpcpassword in bitcoin.conf.
• Cookie auth changed — If you are using cookie authentication, the cookie changes every time the node restarts. Switch to static rpcuser/rpcpassword.
• Node not fully started — ckpool starts before the node is ready. It will retry automatically.

Debug Bitaxe connectivity

# Step 1: Find the Bitaxe on your network
# If it's in AP mode, connect to its WiFi (Bitaxe_XXXX)
# and access it at 192.168.4.1

# Step 2: Check Bitaxe status via API
curl -s http://BITAXE_IP/api/system/info | python3 -c "
import sys, json
d = json.load(sys.stdin)
print(f'WiFi: {d[\"ssid\"]} ({d[\"wifiStatus\"]})')
print(f'Stratum: {d[\"stratumURL\"]}:{d[\"stratumPort\"]}')
print(f'Fallback: {d[\"isUsingFallbackStratum\"]}')
print(f'Hashrate: {d[\"hashRate\"]:.0f} GH/s')
print(f'Shares: {d[\"sharesAccepted\"]} ok, {d[\"sharesRejected\"]} bad')
"

# Step 3: Verify ckpool is reachable from the Bitaxe's network
YOUR_IP=$(ip addr show | grep "inet " | grep -v 127.0.0.1 | head -1 | awk '{print $2}' | cut -d/ -f1)
echo "Your IP: $YOUR_IP"
nc -zv $YOUR_IP 3333

# Step 4: Check if ckpool sees the Bitaxe
grep "Authorised" ~/.local/var/log/ckpool/ckpool.log | tail -5

Common causes:

• Different networks — The Bitaxe and your computer must be on the same network (same subnet).
• 5 GHz WiFi — The Bitaxe only supports 2.4 GHz. If your router only broadcasts 5 GHz, use a phone hotspot as a bridge (see Bitaxe guide).
• Wrong IP — If you switched networks or your DHCP lease changed, update the Bitaxe stratum URL:

  curl -X PATCH http://BITAXE_IP/api/system \
    -H "Content-Type: application/json" \
    -d '{"stratumURL":"YOUR_NEW_IP","stratumPort":3333}'
  curl -X POST http://BITAXE_IP/api/system/restart

• Firewall — Ensure port 3333 is open:

  sudo ufw allow 3333/tcp

Prevent node sync over mobile data

# Check which interface has the default route
ip route show | grep default

# If your phone hotspot interface has a default route, remove it
# Find the gateway and interface name first:
ip route show | grep default

# Remove the hotspot default route (keep the main WiFi route)
sudo ip route del default via HOTSPOT_GATEWAY dev HOTSPOT_INTERFACE

# Verify only your main WiFi has internet routing
ip route show | grep default
# Should show only one line with your main WiFi interface

Check and migrate filesystem

# Check filesystem type
DATADIR=$(grep datadir ~/.bitcoin/bitcoin.conf | cut -d= -f2)
df -Th "$DATADIR" | tail -1

# If it shows fuseblk, exfat, or ntfs, you need to migrate
# Download and run the migration script:
wget https://knotsday.com/scripts/migrate-to-ext4.sh
chmod +x migrate-to-ext4.sh

# Stop the node first!
bitcoin-cli stop
sleep 10

# Run the migration
./migrate-to-ext4.sh

# Check current version
bitcoind --version | head -1

# Check latest version
curl -s https://bitcoinknots.org | grep -oP 'bitcoin-\K[0-9.]+knots[0-9]+' | head -1

# Stop the node
bitcoin-cli stop
sleep 10

# Download and install (replace version as needed)
KNOTS_VERSION="29.3.knots20260508"
cd /tmp
wget "https://bitcoinknots.org/files/29.x/${KNOTS_VERSION}/bitcoin-${KNOTS_VERSION}-x86_64-linux-gnu.tar.gz"
tar xzf "bitcoin-${KNOTS_VERSION}-x86_64-linux-gnu.tar.gz"
cp "bitcoin-${KNOTS_VERSION}/bin/"* ~/.local/bin/

# Restart
bitcoind
bitcoind --version | head -1

# If ckpool won't build, ensure all dependencies are installed
sudo apt-get install -y build-essential autoconf automake \
  libtool pkg-config libssl-dev

# Clean build
cd /tmp
rm -rf ckpool
git clone https://bitbucket.org/ckolivas/ckpool.git
cd ckpool
./autogen.sh
./configure
make -j$(nproc)

# Install
cp src/ckpool src/notifier ~/.local/bin/

# Restart service
systemctl --user restart ckpool
systemctl --user status ckpool

# Stop everything
bitcoin-cli stop 2>/dev/null
systemctl --user stop ckpool 2>/dev/null
sleep 10

# Back up your wallet and config
cp ~/.bitcoin/bitcoin.conf ~/bitcoin.conf.backup

# Wipe and re-sync (keeps your config)
DATADIR=$(grep datadir ~/.bitcoin/bitcoin.conf | cut -d= -f2)
rm -rf "$DATADIR/blocks" "$DATADIR/chainstate" "$DATADIR/indexes"

# Start fresh
bitcoin-qt &