Regtest ガイド

手軽な順に並べた、3 つのローカル開発の方法です。どれを選んでも、bitcoin-cli や任意の JSON-RPC クライアントから呼び出せる TensorCash の JSON-RPC が手元に用意されます。以下のすべての内容について、bcore の機能テストスイートが正となる実行可能な仕様であり、各ウォークスルーには元になったテストへのリンクがあります。

Core 単体 · docker compose · 機能テスト

検証モード

TensorCash は、ブロックの受け入れに外部の検証ステップを加えています。-validationapi はそれを担うバックエンドを選ぶフラグで、ローカル実行では最も重要な選択です。GPU が要るのか、検証者プロセスが要るのか、どちらも要らないのかが、これで決まります。

フラグ内容使いどころ
-validationapi=realデフォルト。ノードと検証者の間の ZMQ PUSH/PULL チャネルを通じ、FlatBuffers で外部の検証者と通信します。本番環境の設定です。実際の検証者プロセスが必要です。メインネット、テストネット、そして実際のモデルリプレイを行う regtest 実行で使われます。
-validationapi=mockプロセス内で動作し、決定論的です。モックバックエンドは 3 つの RPC(validationmockdefault、validationmockclear、validationmockrequests)を公開し、Quick、Full、Model の応答をあらかじめ用意できます。起動フラグ -mockval-default-* を使えば、あらゆる検証結果をスクリプトで制御できます。機能テストスイートのデフォルト。検証者や実際の推論なしにチェーンのロジックを動かすなら、これが適しています。
-validationapi=desktopハイブリッド。Quick チェックはプロセス内で実行し、Full と Model はローカルの HTTPS 検証者(デフォルトのデスクトップ版バイナリ)に送ります。ZMQ ブローカーは不要です。別の検証サービスを運用せずに、実際の Quick と Smell の検証を通したい、1 台のマシンでのデモ。

チェーンのロジックを初めて試すなら、mock が正解です。このページの残りの部分は、特に断りがない限りこのモードを前提としています。

方法 A · Core 単体(モック検証)

最も手軽な方法です。C++ のデーモンが 1 つだけで、docker も GPU も、ディスク上のモデルファイルも不要です。このページのウォークスルーはすべてこれで実行できます。

1. デーモンをビルドする

services/core-node/bcore/ を対象に、Bitcoin Core のビルド手順に従ってください。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 が同じ処理を行います。検証者には llama.cpp ではなく vLLM ベースのものを使います。

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)をバインドします。検証者は 検証者 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 のモックノードに対する 3 つの短い手順です。どれも概略で、完全に実行できるシナリオはリンク先の機能テストにあります。

最初のブロックをマイニングする

基準となるテスト: 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 を使えば、実際の検証者や GPU なしに、すべてのステップを RPC から進められます。ここでは概要のみを示し、完全なシナリオはリンク先のテストにあります。

関係する機能: 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 で、デポジット(bond)と ICU の出力を構築し、発行体登録の TLV を添付してブロードキャストします。1 回の承認後、その資産は 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 で重要な理由
-regtestregtest チェーンを選択します(ブロック報酬、即時成熟ルール、ローカル専用ポート 18443/18444)。
-vdfspvcommitmentheight=0メインネットの段階的な有効化高ではなく、ジェネシスから VDF/SPV を有効にします。
-vdfspvvdfverifyheight=0ジェネシスから VDF 検証を有効にします。
-maxtipage=999999古いタイムスタンプを受け入れるため、古いチェーンで再起動しても、未同期のノードとして扱われません。
-spv-asn-min=1ASN による裏付けの下限を下げます。これがないと、regtest では VDF の SPV 切り替えロジックがブロックされます。
-spv-hysteresis-base-bps=0ベースマージンのヒステリシスを取り除き、テストでのリオーグを即時かつ決定論的にします。
-spv-reorg-sampling-threshold=999深いリオーグ時のブロック本体のサンプリングを実質的に無効にします。小さなブロック高では、これを動かすのは現実的ではありません。
-useextapi=0外部マイナー API を無効にします。チェーンだけのウォークスルーには不要で、起動も速くなります。
-debug=net,validationregtest セッションで最も役立つログ、つまりネットワーク処理と検証パイプラインを出力します。
-par=1シングルスレッドで検証します。正しさに影響を与えずに、テスト特有の不安定さの一部を取り除きます。

次に読む

  • JSON-RPC リファレンスバケットごとに整理された全メソッドの索引。安定性タグと curl の例付き。
  • 検証者 REST API-validationapi=mock から実際の検証者プロセスに移行するときに。
  • FlatBuffer スキーマノードと検証者の間の ZMQ ペイロード用の FlatBuffer IDL と JSON Schema。
  • bcore/test/functional/テストを仕様として読む。
  • テストネット・フォーセットオンラインで使う代替手段。ローカルのサンドボックスではなく稼働中のチェーンを使いたいときに、共有テストネット上のウォレットに資金を入れられます。