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 \
  -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 或代码查询该资产。完整生命周期(铸造、转账、销毁)见链接中的测试。

涉及: 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单线程验证。消除一类仅在测试中出现的不稳定问题,且不影响正确性。

接下来

  • JSON-RPC 参考完整的方法索引,按类别组织,附带稳定性标签与 curl 示例。
  • Verifier REST API从 -validationapi=mock 切换到真实验证器进程时参考。
  • FlatBuffer 模式节点与验证器之间 ZMQ 载荷的 FlatBuffer IDL 与 JSON Schema。
  • bcore/test/functional/把测试当作规范来读。
  • 测试网水龙头对应的在线方案:当你需要一条实时链而不是本地沙箱时,在共享测试网上为钱包领取资金。