文档 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 消息代理。 适合单机演示:希望真正跑一遍 Quick 和 Smell 检查,又不想单独运维验证服务。
如果只是初步了解链逻辑,选 mock 就够了。除非另有说明,本页其余部分均假定使用该模式。
路径 A · 仅运行 Core,使用模拟验证 门槛最低。只需一个 C++ 守护进程:无需 docker、无需 GPU,磁盘上也无需模型文件。足以完成本页的所有演练。
1. 构建守护进程 参照 Bitcoin Core 的构建说明 ,在 services/core-node/bcore/ 下构建。TensorCash 代码与上游使用同一个 CMake 目标构建,没有单独的编译开关。
2. 启动 regtest 节点 这些参数与 test_framework/test_tensorcash.py 传给每个功能测试的参数一致,因此能在那里运行的,在这里也能运行。默认的模拟响应固定为 green,因此区块接受结果是确定的。
./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 或代码查询该资产。完整生命周期(铸造、转账、销毁)见链接中的测试。
涉及: 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单线程验证。消除一类仅在测试中出现的不稳定问题,且不影响正确性。