Regtest 指南

三種本機開發路徑,依上手難度排序。每一種都會給你一個 TensorCash JSON-RPC,可用 bitcoin-cli 或任何 JSON-RPC 用戶端呼叫。bcore 的功能測試套件是以下所有內容的權威、可執行規格,每篇逐步教學也都附上其所依據的測試連結。

只跑 Core · docker compose · 功能測試

驗證模式

TensorCash 在區塊接受流程中加入了一道外部驗證步驟。-validationapi 選擇提供這項驗證的後端,這也是本機執行時最重要的選擇:它決定你需要 GPU、驗證器程序,還是兩者都不需要。

旗標說明使用時機
-validationapi=real預設值。透過節點至驗證器的 ZMQ PUSH/PULL 通道,以 FlatBuffers 與外部驗證器溝通。這是生產環境的設定。需要真實的驗證器程序。用於主網、測試網,以及任何需要真實模型重播的 regtest 執行。
-validationapi=mock在程序內執行且結果確定。模擬後端提供三個 RPC(validationmockdefault、validationmockclear、validationmockrequests),用來設定預先準備好的 Quick、Full 與 Model 回應;搭配 -mockval-default-* 啟動旗標,每一種驗證結果都能以腳本控制。功能測試套件的預設值。想在沒有驗證器、也沒有真實推論的情況下操作鏈的邏輯時,這是正確的選擇。
-validationapi=desktop混合模式。Quick 檢查在程序內執行;Full 與 Model 則送往本機的 HTTPS 驗證器(預設的桌面版執行檔)。不需要 ZMQ broker。單機示範:想要真實的 Quick 與 Smell 檢查,又不想另外維運一個驗證服務。

若是第一次接觸鏈的邏輯,mock 就是正確答案。除非另有說明,本頁其餘內容都以此為前提。

路徑 A · 只跑 Core,搭配模擬驗證

門檻最低。只有一個 C++ 守護程式:不需要 docker、不需要 GPU,磁碟上也不需要模型檔案。足以完成本頁所有的逐步教學。

1. 編譯守護程式

依照 Bitcoin Core 的編譯說明,在 services/core-node/bcore/ 下編譯。TensorCash 的程式碼與上游使用相同的 CMake 目標建置,沒有額外的旗標。

2. 啟動 regtest 節點

這些旗標與 test_framework/test_tensorcash.py 傳給每個功能測試的旗標相同,因此在那裡能跑的,在這裡也能跑。預設的模擬回應固定為綠燈,因此區塊是否被接受是確定的。

./bitcoind \
  -datadir=$HOME/.tensorcash-regtest \
  -regtest \
  -vdfspvcommitmentheight=0 \
  -vdfspvvdfverifyheight=0 \
  -maxtipage=999999 \
  -spv-asn-min=1 \
  -spv-hysteresis-base-bps=0 \
  -spv-reorg-sampling-threshold=999 \
  -useextapi=0 \
  -par=1 \
  -debug=net -debug=validation \
  -validationapi=mock \
  -mockval-force-external=1 \
  -mockval-default-quick=quick_ok_smell_ok \
  -mockval-default-full=full_green \
  -mockval-default-model=model_ok \
  -daemon

3. 與節點互動

身分驗證使用位於 $HOME/.tensorcash-regtest/regtest/.cookie 的 cookie 檔案;只要傳入 -datadir,bitcoin-cli 就會自動讀取。RPC 連接埠沿用上游 regtest 的預設值 18443。

alias bcli='bitcoin-cli -regtest -datadir=$HOME/.tensorcash-regtest'
bcli getblockchaininfo | jq '{chain, blocks, verificationprogress}'

路徑 B · 完整的本機堆疊(docker compose)

當模擬不夠用時:真實的驗證器程序、真實提供推論服務的模型,再接上礦工 API。儲存庫根目錄提供 Mac 與搭配 CUDA 之 Linux 的啟動腳本。

在 Apple 晶片上,啟動器會取得 llama.cpp 建置版本,並啟動完整的 core-node + miner-api + verification-api compose 堆疊:

export GITHUB_TOKEN="ghp_..."
export MODEL_FILE="$HOME/models/Qwen_Qwen3_8B.gguf"
./launch_macbook.sh
# brings up: core-node (RPC 18443, REST 8050) + miner-api + verification-api

在搭載 NVIDIA GPU 的 Linux 上,launch_linux.sh 做的是同樣的事,只是驗證器改用 vLLM 而非 llama.cpp:

export API_KEY=super-secret-token
export MODEL_API_KEY=super-secret-token
sudo ./launch_linux.sh
# uses deployments/docker-compose/core-miner-validation-api/docker-compose.yaml

compose 檔案綁定主機連接埠 8333(P2P)、8050(core-node REST API)與 7067(ZMQ)。驗證器在自己的容器連接埠上提供Verifier REST API。

路徑 C · 執行功能測試套件

守護程式編譯完成後(路徑 A,步驟 1),測試執行器會替你啟動用完即丟的節點。當你想要一段可直接照抄、確定能運作的流程,而不是一個讓你自己摸索的守護程式時,這很好用。

cd services/core-node/bcore

# Single test
build/test/functional/test_runner.py feature_model_registration.py

# All TensorCash-specific tests
build/test/functional/test_runner.py 'feature_model_*' 'feature_asset*' 'feature_fairsign_*'

# All tests, parallelised
build/test/functional/test_runner.py --jobs=$(nproc)

TensorCash 的測試依介面分組:模型生命週期、原生資產、fair-sign 適配器簽章,以及契約式附買回錢包。每一組都是獨立完整的情境,可以從頭讀到尾;下方的逐步教學會指向最具代表性的幾個。

逐步教學

針對路徑 A 的模擬節點所做的三段簡短流程。每段都只是概要;連結中的功能測試才是完整、可執行的情境。

挖出你的第一個區塊

權威測試: wallet_basic.py

與 Bitcoin Core 完全相同。在動到任何 TensorCash 專屬介面之前先做個冒煙測試:確認守護程式已啟動、錢包已有資金。

涉及: createwallet, getnewaddress, generatetoaddress, getbalance

# bitcoin-cli speaks to the regtest daemon over the cookie file.
ALIAS="bitcoin-cli -regtest -datadir=$HOME/.tensorcash-regtest"

$ALIAS createwallet sandbox
ADDR=$($ALIAS -rpcwallet=sandbox getnewaddress)
$ALIAS -rpcwallet=sandbox generatetoaddress 101 "$ADDR"
$ALIAS -rpcwallet=sandbox getbalance
# 50.00000000  (block 1's coinbase, mature after 100 confirmations)

從頭到尾註冊一個模型

權威測試: feature_model_registration.py

TensorCash 專屬。註冊模型的流程是:託管一筆押金,在 N 次提交中累積成功的 Quick 與 Model 驗證,待驗證視窗結束後轉為 registered。使用 -validationapi=mock 時,每一步都能透過 RPC 驅動,不需要真實的驗證器或 GPU。這裡只是概要,連結中的測試才是完整情境。

涉及: validationmockdefault, createmodeldeposit, createmodelcommit, getmodelstatus, generatetoaddress

# Pin every mock rung to the green response.
$ALIAS validationmockdefault quick quick_ok_smell_ok
$ALIAS validationmockdefault model model_ok
$ALIAS validationmockdefault full  full_green

# Lay down 101 spendable coinbase outputs.
$ALIAS -rpcwallet=sandbox generatetoaddress 101 "$ADDR"

# 1. Escrow the deposit (1_000_000 sats == 0.01 BTC).
DEPOSIT=$($ALIAS -rpcwallet=sandbox createmodeldeposit \
  tensor/registration-success success-commit 1000000)
TXID=$(echo "$DEPOSIT" | jq -r .txid)
VOUT=$(echo "$DEPOSIT" | jq -r .deposit_vout)
HASH=$(echo "$DEPOSIT" | jq -r .model_hash)
$ALIAS -rpcwallet=sandbox generatetoaddress 1 "$ADDR"

# 2. Accumulate 50 commits — feature_model_registration.py shows the funding
#    plumbing in detail. Then mine to the verification window's close height.
# 3. Poll status.
$ALIAS getmodelstatus "$HASH"
# {"status": "registered", "verification_code": 0, ...}

發行原生資產

權威測試: feature_assets_basic_highlevel.py

TensorCash 專屬。registerasset 是高階的錢包 RPC,會建立保證金與 ICU 輸出、附上發行方註冊 TLV 並廣播。經過一次確認後,即可依 ID 或 ticker 查詢該資產。完整的生命週期(鑄造、轉移、銷毀)請見連結中的測試。

涉及: registerasset, getassetpolicy, getassetbyticker, getassetbalance

ADDR=$($ALIAS -rpcwallet=sandbox getnewaddress)
ASSET_ID=$(printf 'my-first-asset' | shasum -a 256 | cut -d' ' -f1)

$ALIAS -rpcwallet=sandbox registerasset \
  "$ADDR"          `# ICU address` \
  5.1              `# bond (BTC)` \
  "$ASSET_ID"      `# 32-byte asset id` \
  3                `# policy bits: MINT | BURN` \
  28               `# allowed families: P2WPKH | P2WSH | P2TR` \
  510000000        `# unlock fees (sats)` \
  TST              `# ticker` \
  8                `# decimals` \
  '{"autofund":true,"broadcast":true,"fee_rate":10}'

$ALIAS -rpcwallet=sandbox generatetoaddress 1 "$ADDR"
$ALIAS getassetpolicy "$ASSET_ID"
$ALIAS getassetbyticker TST

旗標參考

路徑 A 中與一般 bitcoind -regtest 工作階段不同的旗標。以 test_framework/test_tensorcash.py 與 init.cpp 為準。

旗標在 regtest 中的作用
-regtest選用 regtest 鏈(區塊補貼、立即成熟規則,以及僅限本機的連接埠 18443/18444)。
-vdfspvcommitmentheight=0從創世區塊起即啟用 VDF/SPV,而不是等到主網的分階段啟用高度。
-vdfspvvdfverifyheight=0從創世區塊起即啟用 VDF 驗證。
-maxtipage=999999接受舊的時間戳記,讓在過時的鏈上重新啟動時,不會被當成尚未同步的節點。
-spv-asn-min=1降低 ASN 佐證的下限;若不設定,regtest 會擋下 VDF SPV 的切換邏輯。
-spv-hysteresis-base-bps=0移除基礎邊際的遲滯機制,讓測試中的重組立即且確定地發生。
-spv-reorg-sampling-threshold=999實際上停用深度重組的區塊主體抽樣;在低區塊高度下,這項機制難以運作。
-useextapi=0停用外部礦工 API:只操作鏈的教學用不到它,而且可以縮短啟動時間。
-debug=net,validation記錄 regtest 工作階段中最有用的日誌:網路與驗證管線。
-par=1單執行緒驗證。消除一類只在測試中出現的不穩定問題,且不影響正確性。

下一步