Bitcoin CLI

bitcoin-cli 是 Bitcoin Core 提供的命令行界面工具，用於與 bitcoind 節點進行 RPC 通訊。 它是開發者和節點運營者最常用的交互方式。

基本用法

# 基本語法
bitcoin-cli [選項] <命令> [參數...]

# 獲取幫助
bitcoin-cli help
bitcoin-cli help <命令>

# 示例
bitcoin-cli getblockchaininfo
bitcoin-cli getblockcount
bitcoin-cli getbestblockhash

連接配置

# 使用配置文件（默認）
# 自動讀取 ~/.bitcoin/bitcoin.conf

# 指定數據目錄
bitcoin-cli -datadir=/path/to/data getblockcount

# 指定網路
bitcoin-cli -testnet getblockcount
bitcoin-cli -signet getblockcount
bitcoin-cli -regtest getblockcount

# 指定 RPC 連接
bitcoin-cli -rpcconnect=192.168.1.100 -rpcport=8332 \
            -rpcuser=user -rpcpassword=pass getblockcount

# 使用 cookie 認證（推薦）
bitcoin-cli -rpccookiefile=/path/to/.cookie getblockcount

常用命令分類

區塊鏈信息

# 區塊鏈狀態
bitcoin-cli getblockchaininfo

# 當前區塊數
bitcoin-cli getblockcount

# 最佳區塊雜湊
bitcoin-cli getbestblockhash

# 獲取區塊
bitcoin-cli getblock <blockhash>
bitcoin-cli getblock <blockhash> 2  # 詳細信息

# 獲取區塊頭
bitcoin-cli getblockheader <blockhash>

# 按高度獲取區塊雜湊
bitcoin-cli getblockhash 840000

交易相關

# 獲取原始交易
bitcoin-cli getrawtransaction <txid>
bitcoin-cli getrawtransaction <txid> true  # 解碼

# 解碼原始交易
bitcoin-cli decoderawtransaction <hex>

# 發送原始交易
bitcoin-cli sendrawtransaction <hex>

# 測試交易是否會被接受
bitcoin-cli testmempoolaccept '["<hex>"]'

Mempool

# Mempool 信息
bitcoin-cli getmempoolinfo

# 獲取 mempool 中所有交易
bitcoin-cli getrawmempool
bitcoin-cli getrawmempool true  # 詳細

# 獲取特定交易在 mempool 中的信息
bitcoin-cli getmempoolentry <txid>

# 獲取交易的祖先/後代
bitcoin-cli getmempoolancestors <txid>
bitcoin-cli getmempooldescendants <txid>

網路

# 網路信息
bitcoin-cli getnetworkinfo

# 節點連接
bitcoin-cli getpeerinfo
bitcoin-cli getconnectioncount

# 添加/移除節點
bitcoin-cli addnode "192.168.1.100:8333" "add"
bitcoin-cli disconnectnode "192.168.1.100:8333"

# 封禁節點
bitcoin-cli setban "192.168.1.100" "add" 86400
bitcoin-cli listbanned

錢包

# 創建/載入錢包
bitcoin-cli createwallet "mywallet"
bitcoin-cli loadwallet "mywallet"
bitcoin-cli unloadwallet "mywallet"

# 指定錢包執行命令
bitcoin-cli -rpcwallet=mywallet getbalance

# 獲取新地址
bitcoin-cli getnewaddress
bitcoin-cli getnewaddress "" "bech32m"  # Taproot

# 發送比特幣
bitcoin-cli sendtoaddress <address> <amount>

# 列出交易
bitcoin-cli listtransactions
bitcoin-cli listunspent

輸出格式化

# 使用 jq 處理 JSON 輸出
bitcoin-cli getblockchaininfo | jq '.blocks'
bitcoin-cli getpeerinfo | jq '.[].addr'

# 只獲取特定欄位
bitcoin-cli getblockchaininfo | jq '{height: .blocks, chain: .chain}'

# 格式化輸出
bitcoin-cli getblock $(bitcoin-cli getbestblockhash) | jq '.'

# 獲取 mempool 中費率最高的交易
bitcoin-cli getrawmempool true | jq 'to_entries | sort_by(-.value.fees.ancestor) | .[0:5]'

批量命令

# 使用 -stdin 讀取參數
echo '["<txhex>"]' | bitcoin-cli -stdin testmempoolaccept

# 批量 RPC 調用
bitcoin-cli <<EOF
[
  {"method": "getblockcount", "params": []},
  {"method": "getbestblockhash", "params": []}
]
EOF

# 腳本中使用
for height in {0..10}; do
  hash=$(bitcoin-cli getblockhash $height)
  echo "Block $height: $hash"
done

調試和診斷

# 節點狀態
bitcoin-cli getinfo  # 已棄用，使用下面的命令
bitcoin-cli -getinfo  # 組合信息

# 日誌控制
bitcoin-cli logging '["net", "mempool"]'
bitcoin-cli logging '[]' '["net"]'  # 禁用 net 日誌

# 手續費估算
bitcoin-cli estimatesmartfee 6
bitcoin-cli estimatesmartfee 1 "ECONOMICAL"

# 驗證區塊鏈
bitcoin-cli verifychain 4 1000  # 驗證最近 1000 個區塊

常用選項

命名參數

# 使用 -named 選項可以明確指定參數名
bitcoin-cli -named sendtoaddress \
  address="bc1q..." \
  amount=0.1 \
  fee_rate=10 \
  replaceable=true

# 對比位置參數
bitcoin-cli sendtoaddress "bc1q..." 0.1 "" "" false true 10

錯誤處理

# 檢查退出碼
bitcoin-cli getblockcount
if [ $? -eq 0 ]; then
  echo "Success"
else
  echo "Failed"
fi

# 常見錯誤碼
# -1: 一般錯誤
# -3: 錢包錯誤
# -5: 無效地址或密鑰
# -6: 資金不足
# -8: 無效參數
# -25: 交易已在鏈上
# -26: 交易被拒絕

安全建議