文件 Regtest 指南 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 \
-daemon3. 與節點互動 身分驗證使用位於 $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.yamlcompose 檔案綁定主機連接埠 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單執行緒驗證。消除一類只在測試中出現的不穩定問題,且不影響正確性。