feat: update README and configuration files for Bitcoin full node setup, add Testnet3 support, and remove Bitcoin Knots template

nipiQ · nipiQ · commit 236e89b39f67 · 2025-05-16T00:20:33.000+09:00
diff --git a/README.md b/README.md
@@ -1,11 +1,12 @@
-# Bitcoin Full Node on macOS with Lima VM
+# Bitcoin Development Toolkit for macOS with Lima VMs (Core Nodes, Layer 2, BTCFi)
 
-This repository provides Lima VM templates to run a Bitcoin full node on macOS (Apple Silicon) using either Bitcoin Core (v29.0), Bitcoin Knots (v28.1.knots20250305), or Bitcoin Core Testnet4. Using Lima VM allows running Bitcoin Core mainnet and testnet4 conflict-free simultaneously, ideal for development environments. All templates automate installation, verify binary signatures and checksums for security, generate a random RPC password, and configure the node as a systemd service with a dedicated storage path. Bitcoin Knots, a fork of Bitcoin Core, includes additional features like enhanced mempool policies. The Testnet4 template supports development and testing on the testnet4 network.
+This repository provides Lima VM templates to run Bitcoin full nodes on macOS (Apple Silicon) using Bitcoin Core (v29.0) for mainnet, testnet3, and testnet4. Each template runs in its own isolated Lima VM, allowing you to operate multiple networks simultaneously without conflicts. All templates automate installation, verify binary signatures and checksums for security, generate a random RPC password, and configure the node as a systemd service with a dedicated storage path. The macOS host never runs any bitcoind instances directly; all nodes run inside their respective Lima VMs for maximum isolation and safety.
 
 ## Prerequisites
 
 - Lima (`brew install lima`)
 - Storage path with ~600GB+ free space (e.g., `/Volumes/MyDrive`)
+- `bitcoin-cli` installed on macOS host (`brew install bitcoin`)
 
 ## Setup
 
@@ -18,9 +19,9 @@ This repository provides Lima VM templates to run a Bitcoin full node on macOS (
 
 2. Choose a template:
 
-   - For Bitcoin Core: Use `bitcoin-core.yaml`.
-   - For Bitcoin Knots: Use `bitcoin-knots.yaml`.
-   - For Bitcoin Core Testnet4: Use `bitcoin-testnet4.yaml`.
+   - For Bitcoin Core mainnet: Use `bitcoin-core.yaml`.
+   - For Bitcoin Core testnet3: Use `bitcoin-testnet3.yaml`.
+   - For Bitcoin Core testnet4: Use `bitcoin-testnet4.yaml`.
 
 3. Update the template:
 
@@ -29,7 +30,7 @@ This repository provides Lima VM templates to run a Bitcoin full node on macOS (
      ```bash
      sed -i '' 's|/Volumes/Storage|/Volumes/MyDrive|g' <template-file>
      ```
-     Replace `<template-file>` with `bitcoin-core.yaml`, `bitcoin-knots.yaml`, or `bitcoin-testnet4.yaml`.
+     Replace `<template-file>` with `bitcoin-core.yaml`, `bitcoin-testnet3.yaml`, or `bitcoin-testnet4.yaml`.
    - Ensure your storage path exists and has sufficient space.
 
 4. Create and start VM:
@@ -39,9 +40,7 @@ This repository provides Lima VM templates to run a Bitcoin full node on macOS (
    limactl start <vm-name>
    ```
 
-   Replace `<vm-name>` with `bitcoin-core`, `bitcoin-knots`, or `bitcoin-testnet4`, and `<template-file>` with the chosen template.
-
-   - Note: Bitcoin Knots downloads may be slow; allow extra time for `limactl start` to complete.
+   Replace `<vm-name>` with `bitcoin-core`, `bitcoin-testnet3`, or `bitcoin-testnet4`, and `<template-file>` with the chosen template.
 
 5. Verify:
 
@@ -50,9 +49,41 @@ This repository provides Lima VM templates to run a Bitcoin full node on macOS (
    bitcoin-cli getblockchaininfo
    ```
 
+## Example bitcoin.conf for bitcoin-cli and development
+
+The macOS host never runs bitcoind directly. Instead, you can use `bitcoin-cli` (installed via Homebrew) to interact with your nodes running inside the Lima VMs. For development or scripting, you may want a `~/.bitcoin/bitcoin.conf` file on your macOS host to define multiple networks and RPC credentials. Here is an example:
+
+```ini
+[main]
+rpcuser=bitcoinuser
+rpcpassword=your_mainnet_rpc_password
+rpcconnect=127.0.0.1
+rpcport=8332
+
+[test]
+testnet=1
+rpcuser=bitcoinuser
+rpcpassword=your_testnet3_rpc_password
+rpcconnect=127.0.0.1
+rpcport=18332
+
+[testnet4]
+testnet=4
+rpcuser=bitcoinuser
+rpcpassword=your_testnet4_rpc_password
+rpcconnect=127.0.0.1
+rpcport=28332
+```
+
+Adjust the `rpcpassword` and `rpcport` values to match those generated in your VM's `bitcoin.conf` files. This setup allows you to use `bitcoin-cli` on your macOS host to connect to any of your running nodes for mainnet, testnet3, or testnet4.
+
 ## Usage
 
-- Run `bitcoin-cli getblockchaininfo` inside the VM to check node status.
+- Run one of the following inside the VM to check node status:
+  - `bitcoin-cli getblockchaininfo` (mainnet)
+  - `bitcoin-cli -testnet getblockchaininfo` (testnet3)
+  - `bitcoin-cli -testnet4 getblockchaininfo` (testnet4)
+- Or, use `bitcoin-cli` from your macOS host with the appropriate `-conf` or `-rpc*` flags to connect to your VM nodes.
 - Ensure storage path is accessible before starting VM.
 
 ## Connect
diff --git a/bitcoin-testnet3.yaml b/bitcoin-testnet3.yaml
@@ -1,4 +1,5 @@
-# lima.yaml for bitcoin-knots VM
+# filepath: /Users/user/dev/bitcoin/bitcoin-lima/bitcoin-testnet3.yaml
+# lima.yaml for bitcoin-core Testnet3 VM
 images:
   - location: "https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-arm64.img"
     arch: "aarch64"
@@ -9,7 +10,7 @@ mounts:
     9p:
       securityModel: none
       cache: mmap
-  - location: "/Volumes/Storage/bitcoin"
+  - location: "/Volumes/Storage/bitcoin-testnet"
     writable: true
     9p:
       securityModel: none
@@ -25,86 +26,91 @@ provision:
       set -x
       sudo apt update
       sudo apt install -y wget tar openssl gnupg coreutils
-      VERSION="28.1.knots20250305"
-      # Download Bitcoin Knots files with retries
+      VERSION="29.0"
+
+      # Download Bitcoin Core files
+      wget https://bitcoincore.org/bin/bitcoin-core-${VERSION}/bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz
+      wget https://bitcoincore.org/bin/bitcoin-core-${VERSION}/SHA256SUMS
+      wget https://bitcoincore.org/bin/bitcoin-core-${VERSION}/SHA256SUMS.asc
+
+      # Import keys (fanquake, achow101) with retries
       for i in {1..3}; do
-        wget -O bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz https://bitcoinknots.org/files/28.x/${VERSION}/bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz && break
-        echo "Download tarball attempt $i failed. Retrying..." >&2
+        gpg --keyserver keyserver.ubuntu.com --recv-keys 0x0CCBAAFD76A2ECE2CCD3141DE2FFD5B1D88CA97D 0x152812300785C96444D3334D17565732E08E5E41 && break
+        echo "Keyserver attempt $i failed. Retrying..." >&2
         sleep 2
       done
-      for i in {1..3}; do
-        wget -O SHA256SUMS https://bitcoinknots.org/files/28.x/${VERSION}/SHA256SUMS && break
-        echo "Download SHA256SUMS attempt $i failed. Retrying..." >&2
-        sleep 2
-      done
-      for i in {1..3}; do
-        wget -O SHA256SUMS.asc https://bitcoinknots.org/files/28.x/${VERSION}/SHA256SUMS.asc && break
-        echo "Download SHA256SUMS.asc attempt $i failed. Retrying..." >&2
-        sleep 2
-      done
-      # Import Luke Dashjr's key with retries and fallback keyserver
-      for i in {1..3}; do
-        gpg --keyserver keyserver.ubuntu.com --recv-keys 0x0CCBAAFD76A2ECE2CCD3141DE2FFD5B1D88CA97D && break
-        echo "Keyserver attempt $i failed (keyserver.ubuntu.com). Trying keys.openpgp.org..." >&2
-        gpg --keyserver keys.openpgp.org --recv-keys 0x0CCBAAFD76A2ECE2CCD3141DE2FFD5B1D88CA97D && break
-        echo "Keyserver attempt $i failed (keys.openpgp.org). Retrying..." >&2
-        sleep 2
-      done
-      # Verify signature (fallback to checksum if no key)
+
+      # Verify signature (fallback to checksum if no keys)
       if gpg --verify SHA256SUMS.asc SHA256SUMS 2> gpg-verify.log && grep -q "Good signature" gpg-verify.log; then
         echo "Signature verified successfully."
       else
-        echo "Warning: Signature verification failed or no key imported. Proceeding with checksum only." >&2
+        echo "Warning: Signature verification failed or no keys imported. Proceeding with checksum only." >&2
         cat gpg-verify.log >&2
       fi
+
       # Verify checksum
       if ! sha256sum --ignore-missing --check --strict SHA256SUMS; then
         echo "Error: Checksum verification failed." >&2
         exit 1
       fi
-      # Install Bitcoin Knots
+
+      # Install Bitcoin Core
       tar -xzf bitcoin-${VERSION}-aarch64-linux-gnu.tar.gz
       sudo mv bitcoin-${VERSION} /usr/local/bitcoin
       sudo ln -s /usr/local/bitcoin/bin/bitcoind /usr/local/bin/bitcoind
       sudo ln -s /usr/local/bitcoin/bin/bitcoin-cli /usr/local/bin/bitcoin-cli
-      # Configure Bitcoin Knots
+
+      # Configure Bitcoin Core
       sudo mkdir -p /home/user.linux/.bitcoin
+
       cat > /home/user.linux/.bitcoin/bitcoin.conf <<EOF
-      datadir=/Volumes/Storage/bitcoin
-      txindex=1
+      [test]
+      testnet=1
+      datadir=/Volumes/Storage/bitcoin-testnet/testnet
+      rpcuser=bitcoinuser
+      rpcpassword=$(openssl rand -base64 12)
       rpcbind=127.0.0.1
-      rpcport=8332
       rpcallowip=127.0.0.1
+      rpcport=18332
       server=1
-      rpcuser=bitcoinuser
-      rpcpassword=$(openssl rand -base64 12)
+      txindex=1
       EOF
+
       sudo chown -R user:user /home/user.linux/.bitcoin
       sudo chmod -R 755 /home/user.linux/.bitcoin
       sudo chmod 600 /home/user.linux/.bitcoin/bitcoin.conf
+
       # Fix home permissions
       sudo chown -R user:user /home/user.linux
       sudo chmod 755 /home/user.linux
+
       # Set up PATH
       echo 'export PATH=$PATH:/usr/local/bin' > /home/user.linux/.bashrc
       sudo chown user:user /home/user.linux/.bashrc
       sudo chmod 644 /home/user.linux/.bashrc
+
       # Set up storage mount
-      sudo chown -R user:user /Volumes/Storage/bitcoin || echo "Warning: Failed to chown /Volumes/Storage/bitcoin"
-      sudo chmod -R 755 /Volumes/Storage/bitcoin || echo "Warning: Failed to chmod /Volumes/Storage/bitcoin"
-      if ! mount | grep -q /Volumes/Storage/bitcoin; then
-        echo "Error: /Volumes/Storage/bitcoin not mounted" >&2
+      sudo chown -R user:user /Volumes/Storage/bitcoin-testnet || echo "Warning: Failed to chown /Volumes/Storage/bitcoin-testnet"
+      sudo chmod -R 755 /Volumes/Storage/bitcoin-testnet || echo "Warning: Failed to chmod /Volumes/Storage/bitcoin-testnet"
+      if ! mount | grep -q /Volumes/Storage/bitcoin-testnet; then
+        echo "Error: /Volumes/Storage/bitcoin-testnet not mounted" >&2
         exit 1
       fi
+
+      # Ensure testnet directory exists and has proper permissions
+      sudo mkdir -p /Volumes/Storage/bitcoin-testnet/testnet
+      sudo chown -R user:user /Volumes/Storage/bitcoin-testnet/testnet
+      sudo chmod -R 755 /Volumes/Storage/bitcoin-testnet/testnet
+
       # Create systemd service
       cat > /etc/systemd/system/bitcoind.service <<EOF
       [Unit]
-      Description=Bitcoin Knots daemon
+      Description=Bitcoin daemon (Testnet3)
       After=network.target
       [Service]
       User=user
       Group=user
-      ExecStart=/usr/local/bin/bitcoind -conf=/home/user.linux/.bitcoin/bitcoin.conf
+      ExecStart=/usr/local/bin/bitcoind -testnet -conf=/home/user.linux/.bitcoin/bitcoin.conf
       Restart=always
       TimeoutStopSec=60s
       TimeoutStartSec=60s
@@ -119,13 +125,9 @@ provision:
     script: |
       #!/bin/bash
       set -x
-      sleep 10
+      sleep 5
       if ! pgrep bitcoind >/dev/null; then
         echo "Error: bitcoind not running" >&2
         exit 1
       fi
-      # Run bitcoin-cli with timeout to avoid hanging
-      timeout 30 bitcoin-cli getblockchaininfo || {
-        echo "Warning: bitcoin-cli getblockchaininfo timed out or failed." >&2
-        exit 1
-      }
+      bitcoin-cli -testnet getblockchaininfo
diff --git a/bitcoin-testnet4.yaml b/bitcoin-testnet4.yaml
@@ -63,14 +63,15 @@ provision:
       sudo mkdir -p /home/user.linux/.bitcoin
       cat > /home/user.linux/.bitcoin/bitcoin.conf <<EOF
       [testnet4]
-      datadir=/Volumes/Storage/bitcoin-testnet
+      testnet4=1
+      datadir=/Volumes/Storage/bitcoin-testnet/testnet4
       rpcuser=bitcoinuser
       rpcpassword=$(openssl rand -base64 12)
-      txindex=1
-      server=1
-      rpcport=18443
       rpcbind=127.0.0.1
       rpcallowip=127.0.0.1
+      rpcport=18443
+      server=1
+      txindex=1
       EOF
 
       sudo chown -R user:user /home/user.linux/.bitcoin
@@ -94,6 +95,11 @@ provision:
         exit 1
       fi
 
+      # Ensure testnet4 directory exists and has proper permissions
+      sudo mkdir -p /Volumes/Storage/bitcoin-testnet/testnet4
+      sudo chown -R user:user /Volumes/Storage/bitcoin-testnet/testnet4
+      sudo chmod -R 755 /Volumes/Storage/bitcoin-testnet/testnet4
+
       # Create systemd service
       cat > /etc/systemd/system/bitcoind.service <<EOF
       [Unit]
diff --git a/example.bitcoin.conf b/example.bitcoin.conf
@@ -0,0 +1,27 @@
+[main]
+txindex=1
+server=1
+rpcport=8332
+rpcuser=bitcoinuser
+rpcconnect=127.0.0.1
+rpcpassword=strongpassword
+
+[test]
+txindex=1
+server=1
+rpcport=18332
+rpcbind=127.0.0.1
+rpcallowip=127.0.0.1
+rpcuser=bitcoinuser
+rpcpassword=strongpassword
+testnet=1
+
+[testnet4]
+txindex=1
+server=1
+rpcbind=127.0.0.1
+rpcport=18443
+rpcallowip=127.0.0.1
+rpcuser=bitcoinuser
+rpcpassword=strongpassword
+testnet4=1
