Transaction Index (txindex)

什麼是 TxIndex？

Transaction Index（txindex）是 Bitcoin Core 的可選功能，建立一個從交易 ID (txid) 到區塊位置的索引。啟用後，你可以透過 txid 快速查詢區塊鏈中的任何歷史交易。

有無 TxIndex 的差異

無 TxIndex（預設）

• 只能查詢 UTXO 相關交易
• 只能查詢錢包交易
• 只能查詢 mempool 交易
• getrawtransaction 受限

有 TxIndex

• 可查詢任何歷史交易
• 支援區塊瀏覽器功能
• 完整的 getrawtransaction
• 需要額外磁碟空間

配置方式

啟用 TxIndex

# 方法 1: 命令行參數
bitcoind -txindex=1

# 方法 2: 配置文件 (~/.bitcoin/bitcoin.conf)
echo "txindex=1" >> ~/.bitcoin/bitcoin.conf

# 重新啟動節點
bitcoin-cli stop
bitcoind

# 檢查索引狀態
bitcoin-cli getindexinfo
# {
#   "txindex": {
#     "synced": true,
#     "best_block_height": 820000
#   }
# }

注意： 如果在已同步的節點上啟用 txindex，需要重新索引整個區塊鏈。這可能需要幾個小時到一天，取決於硬體。

重新索引

# 如果已有區塊數據，需要重新索引
bitcoind -txindex=1 -reindex

# 或者只重建索引（不重新驗證區塊）
bitcoind -txindex=1 -reindex-chainstate

# 查看進度
bitcoin-cli getblockchaininfo | jq '{blocks, headers, verificationprogress}'

使用方式

getrawtransaction

# 查詢任意交易（需要 txindex）
bitcoin-cli getrawtransaction 

# 解碼交易
bitcoin-cli getrawtransaction  true

# 包含區塊資訊
bitcoin-cli getrawtransaction  true 

# 示例輸出
{
  "txid": "abc123...",
  "hash": "abc123...",
  "version": 2,
  "size": 225,
  "vsize": 144,
  "weight": 573,
  "locktime": 0,
  "vin": [...],
  "vout": [...],
  "blockhash": "000000000...",
  "confirmations": 12345,
  "time": 1234567890,
  "blocktime": 1234567890
}

gettxout（不需要 txindex）

# 查詢未花費輸出（不需要 txindex）
bitcoin-cli gettxout  

# 包含 mempool
bitcoin-cli gettxout   true

# 示例輸出
{
  "bestblock": "000000000...",
  "confirmations": 100,
  "value": 0.01000000,
  "scriptPubKey": {
    "asm": "0 abc123...",
    "hex": "0014abc123...",
    "type": "witness_v0_keyhash",
    "address": "bc1q..."
  },
  "coinbase": false
}

存儲需求

磁碟空間估算

組件	大小	說明
區塊數據	~600 GB	完整區塊鏈
UTXO 集合	~8 GB	chainstate
TxIndex	~35 GB	交易索引
總計	~643 GB	完整節點 + txindex

索引位置

~/.bitcoin/
├── blocks/           # 區塊數據
│   ├── blk00000.dat
│   └── ...
├── chainstate/       # UTXO 集合
├── indexes/          # 索引目錄
│   └── txindex/      # 交易索引 (LevelDB)
│       ├── 000001.log
│       ├── CURRENT
│       ├── LOCK
│       └── ...
└── ...

實現細節

索引結構

// TxIndex 條目結構
interface TxIndexEntry {
  txid: Buffer;        // 32 bytes - 交易 ID
  blockHash: Buffer;   // 32 bytes - 區塊雜湊
  blockHeight: number; // 4 bytes - 區塊高度
  txOffset: number;    // 4 bytes - 交易在區塊文件中的偏移
}

// LevelDB Key-Value
// Key: 't' + txid (33 bytes)
// Value: blockHash + blockHeight + txOffset

// 查詢流程
async function getTransaction(txid: string): Promise {
  // 1. 查詢索引
  const entry = await txindex.get(txid);
  if (!entry) {
    return null;
  }

  // 2. 從區塊文件讀取交易
  const blockFile = getBlockFile(entry.blockHash);
  const rawTx = await blockFile.read(entry.txOffset);

  // 3. 解碼交易
  return Transaction.decode(rawTx);
}

// 索引建立
async function indexBlock(block: Block): Promise {
  const batch = txindex.batch();

  for (let i = 0; i < block.transactions.length; i++) {
    const tx = block.transactions[i];
    batch.put(tx.txid, {
      blockHash: block.hash,
      blockHeight: block.height,
      txOffset: calculateOffset(block, i),
    });
  }

  await batch.commit();
}

使用場景

區塊瀏覽器

建立區塊瀏覽器需要 txindex 來快速查詢任意交易。

分析工具

鏈上分析需要追蹤交易歷史，txindex 提供快速查詢。

開發調試

開發者需要查詢交易細節來調試應用程式。

支付驗證

驗證歷史付款需要查詢交易詳情。

替代方案

不使用 TxIndex

# 如果知道區塊雜湊，可以不用 txindex
bitcoin-cli getrawtransaction  true 

# 查詢錢包交易（不需要 txindex）
bitcoin-cli gettransaction 

# 查詢 mempool 交易（不需要 txindex）
bitcoin-cli getmempoolentry

其他索引

# 區塊過濾器索引（用於輕客戶端）
blockfilterindex=1

# Coinstats 索引（用於 UTXO 統計）
coinstatsindex=1

# 查看所有索引狀態
bitcoin-cli getindexinfo

兼容性

TxIndex 與 Pruning 不兼容

修剪節點會刪除舊區塊數據，而 txindex 需要完整的區塊數據來定位交易。因此，txindex 和 pruning 不能同時使用。

# 這會報錯
bitcoind -txindex=1 -prune=550
# Error: -txindex is incompatible with -prune mode

最佳實踐

✓ 推薦使用 TxIndex

• 運行區塊瀏覽器
• 進行鏈上分析
• 開發和調試應用
• 需要查詢歷史交易

⚠ 可以不用 TxIndex

• 只運行個人錢包
• 只驗證區塊鏈
• 磁碟空間有限
• 使用修剪模式

總結

✓ 快速查詢：TxIndex 允許透過 txid 快速查詢任何歷史交易
✓ 可選功能：預設禁用，需要手動啟用並重建索引
⚠ 額外空間：需要約 35 GB 額外磁碟空間
✗ 不兼容修剪：TxIndex 不能與 pruning 模式同時使用