Руководство по regtest

Три пути локальной разработки — от самого простого к самому сложному. Каждый даёт вам JSON-RPC TensorCash, к которому можно обращаться через bitcoin-cli или любой JSON-RPC-клиент. Набор функциональных тестов bcore — каноническая исполняемая спецификация всего, что описано ниже, и каждый сценарий ссылается на тест, из которого он взят.

Только Core · docker compose · функциональные тесты

Режимы валидации

TensorCash добавляет к приёму блока шаг внешней валидации. -validationapi выбирает бэкенд, который его выполняет, и это самый важный выбор для локального запуска: от него зависит, нужен ли вам GPU, процесс верификатора или ни то ни другое.

ФлагЧто этоКогда использовать
-validationapi=realРежим по умолчанию. Общается с внешним верификатором по каналу ZMQ PUSH/PULL между узлом и верификатором с использованием FlatBuffers. Продакшен-настройка.Нужен настоящий процесс верификатора. Используется в mainnet, testnet и в любом regtest-запуске с реальным воспроизведением модели.
-validationapi=mockВнутри процесса и детерминированно. Mock-бэкенд предоставляет три RPC (validationmockdefault, validationmockclear, validationmockrequests) для заготовленных ответов Quick, Full и Model; с флагами запуска -mockval-default-* любой результат верификации задаётся сценарием.Режим по умолчанию для набора функциональных тестов. Правильный выбор, чтобы гонять логику цепочки без верификатора и реального инференса.
-validationapi=desktopГибридный режим. Проверки Quick выполняются внутри процесса; Full и Model отправляются локальному HTTPS-верификатору (десктопный бинарник по умолчанию). Брокер ZMQ не нужен.Демо на одной машине, где нужен настоящий проход Quick и Smell без отдельного сервиса верификатора.

Для первого знакомства с логикой цепочки правильный ответ — mock. Если не сказано иное, остальная часть страницы исходит из него.

Путь A · только Core, с mock-валидацией

Самый простой путь. Один демон на C++: без docker, без GPU, без файлов моделей на диске. Этого хватает для всех сценариев на этой странице.

1. Соберите демон

Следуйте инструкциям по сборке Bitcoin Core для services/core-node/bcore/. Код TensorCash собирается в той же цели CMake, что и upstream; отдельного флага нет.

2. Запустите regtest-узел

Эти флаги повторяют то, что test_framework/test_tensorcash.py передаёт каждому функциональному тесту, поэтому всё, что работает там, работает и здесь. Ответы mock по умолчанию закреплены на 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. Подключитесь к узлу

Аутентификация идёт через cookie-файл $HOME/.tensorcash-regtest/regtest/.cookie, который bitcoin-cli читает автоматически, если передать -datadir. Порт RPC — стандартный для regtest в upstream: 18443.

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

Путь B · полный локальный стек (docker compose)

Когда mock недостаточно: настоящий процесс верификатора, настоящая модель, обслуживающая инференс, и подключённый API майнера. В корне репозитория есть скрипты запуска для Mac и для Linux с CUDA.

На Apple silicon лаунчер скачивает сборку llama.cpp и поднимает полный compose-стек core-node + miner-api + verification-api:

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

На Linux с GPU NVIDIA 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 (REST API core-node) и 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 и covenant-кошелёк для репо. Каждый — самостоятельный сценарий, который читается сверху вниз; сценарии ниже ссылаются на самые показательные из них.

Пошаговые сценарии

Три короткие последовательности для mock-узла из пути 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 с генезиса, а не с поэтапной высоты mainnet.
-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-примерами.
  • REST API верификатораКогда вы переходите с -validationapi=mock на настоящий процесс верификатора.
  • FlatBuffer-схемыFlatBuffer IDL и JSON Schema для ZMQ-сообщений между узлом и верификатором.
  • bcore/test/functional/Читайте тесты как спецификацию.
  • Кран testnetОнлайн-аналог: пополните кошелёк в общем testnet, когда нужна живая цепочка, а не локальная песочница.