Посібник 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У самому процесі й детерміновано. Імітований бекенд надає три 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, що й upstream; окремого прапорця немає.

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 \
  -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)

Коли імітації замало: справжній процес верифікатора, справжня модель, що виконує інференс, і підключений 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 (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 і гаманець covenant-репо. Кожен — самодостатній сценарій, який можна читати згори донизу; покрокові приклади нижче посилаються на найпоказовіші з них.

Покрокові приклади

Три короткі послідовності для імітованого вузла зі шляху 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. Модель реєструють так: блокують депозит, збирають успішні верифікації Quick і Model у N комітах, після чого модель переходить у стан 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 реєстрації емітента й розсилає транзакцію в мережу. Після одного підтвердження актив можна запитати за ідентифікатором або тікером. Повний життєвий цикл (випуск, переказ, спалення) — у тесті за посиланням.

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