Przewodnik regtest

Trzy ścieżki lokalnego developmentu, od najprostszej. Każda daje ci JSON-RPC TensorCash, który wywołasz przez bitcoin-cli lub dowolnego klienta JSON-RPC. Zestaw testów funkcjonalnych bcore to kanoniczna, wykonywalna specyfikacja wszystkiego, co opisano poniżej, a każdy przykład odsyła do testu, na podstawie którego powstał.

Sam Core · docker compose · testy funkcjonalne

Tryby walidacji

TensorCash dodaje do akceptacji bloków zewnętrzny krok walidacji. -validationapi wybiera backend, który go obsługuje, i to najważniejsza decyzja przy lokalnym uruchomieniu: od niej zależy, czy potrzebujesz GPU, procesu weryfikatora, czy żadnego z nich.

FlagaNa czym polegaKiedy go używać
-validationapi=realTryb domyślny. Komunikuje się z zewnętrznym weryfikatorem przez kanał ZMQ PUSH/PULL między węzłem a weryfikatorem, z użyciem FlatBuffers. Ustawienie produkcyjne.Wymaga prawdziwego procesu weryfikatora. Używany w mainnecie, testnecie i każdym uruchomieniu regtest, które sprawdza prawdziwe odtwarzanie modelu.
-validationapi=mockW procesie i deterministycznie. Backend mock udostępnia trzy RPC (validationmockdefault, validationmockclear, validationmockrequests) z gotowymi odpowiedziami Quick, Full i Model; dzięki flagom startowym -mockval-default-* każdy wynik weryfikacji można zaskryptować.Domyślny tryb zestawu testów funkcjonalnych. Właściwy wybór, gdy chcesz sterować logiką łańcucha bez weryfikatora i prawdziwej inferencji.
-validationapi=desktopTryb hybrydowy. Kontrole Quick działają w procesie; Full i Model trafiają do lokalnego weryfikatora HTTPS (domyślnej binarki desktopowej). Broker ZMQ nie jest potrzebny.Dema na jednej maszynie, które mają przejść prawdziwą kontrolę Quick i Smell bez obsługi osobnej usługi weryfikatora.

Do pierwszego zapoznania się z logiką łańcucha najlepiej nadaje się mock. Dalsza część strony zakłada ten tryb, o ile nie zaznaczono inaczej.

Ścieżka A · sam Core z mockowaną walidacją

Najmniej zachodu. Jeden demon C++: bez dockera, bez GPU, bez plików modeli na dysku. Wystarczy do każdego przykładu na tej stronie.

1. Skompiluj demona

Postępuj zgodnie z instrukcjami kompilacji Bitcoin Core dla services/core-node/bcore/. Kod TensorCash kompiluje się w tym samym celu CMake co upstream; nie ma osobnej flagi.

2. Uruchom węzeł regtest

Te flagi odpowiadają temu, co test_framework/test_tensorcash.py przekazuje każdemu testowi funkcjonalnemu, więc wszystko, co działa tam, zadziała też tutaj. Domyślne odpowiedzi mocka są ustawione na zielony wynik, więc akceptacja bloków jest deterministyczna.

./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. Połącz się z nim

Uwierzytelnianie korzysta z pliku cookie $HOME/.tensorcash-regtest/regtest/.cookie, który bitcoin-cli odczytuje automatycznie, gdy podasz -datadir. Port RPC to domyślny port regtest z upstreamu, 18443.

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

Ścieżka B · pełny stos lokalny (docker compose)

Gdy mock nie wystarcza: prawdziwy proces weryfikatora, prawdziwy model obsługujący inferencję i podłączone API górnika. W katalogu głównym repozytorium są skrypty uruchomieniowe dla Maców oraz dla Linuksa z CUDA.

Na Apple silicon skrypt pobiera build llama.cpp i uruchamia pełny stos 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

Na Linuksie z GPU NVIDIA launch_linux.sh robi to samo, ale z weryfikatorem opartym na vLLM zamiast 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

Plik compose wiąże porty hosta 8333 (P2P), 8050 (core-node REST API) i 7067 (ZMQ). Weryfikator udostępnia swoje Verifier REST API na własnym porcie kontenera.

Ścieżka C · uruchom zestaw testów funkcjonalnych

Gdy demon jest już skompilowany (Ścieżka A, krok 1), runner testów sam uruchamia jednorazowe węzły. Przydatne, gdy chcesz skopiować sprawdzoną sekwencję, a nie eksperymentować z demonem.

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)

Testy TensorCash są pogrupowane według obszaru: cykl życia modeli, aktywa natywne, adaptory fair-sign i portfel repo z kowenantami. Każdy to samodzielny scenariusz, który można przeczytać od początku do końca; przykłady poniżej wskazują te najbardziej reprezentatywne.

Przykłady krok po kroku

Trzy krótkie sekwencje na węźle z mockiem ze Ścieżki A. Każda to tylko szkic; pełnym, wykonywalnym scenariuszem jest podlinkowany test funkcjonalny.

Wydobądź pierwszy blok

Test kanoniczny: wallet_basic.py

Bez zmian względem Bitcoin Core. Test dymny przed jakimkolwiek interfejsem specyficznym dla TensorCash: potwierdza, że demon działa, a portfel ma środki.

Dotyczy: 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)

Zarejestruj model od początku do końca

Test kanoniczny: feature_model_registration.py

Specyficzne dla TensorCash. Model rejestruje się, deponując kaucję, zbierając udane weryfikacje Quick i Model w N commitach, a następnie przechodząc do stanu registered po zamknięciu okna weryfikacji. Z -validationapi=mock każdy krok wykonasz przez RPC, bez prawdziwego weryfikatora i GPU. To tylko zarys; pełny scenariusz zawiera podlinkowany test.

Dotyczy: 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, ...}

Wyemituj aktywo natywne

Test kanoniczny: feature_assets_basic_highlevel.py

Specyficzne dla TensorCash. registerasset to wysokopoziomowe RPC portfela, które buduje wyjścia kaucji i ICU, dołącza TLV rejestracji emitenta i rozgłasza transakcję. Po jednym potwierdzeniu aktywo można odpytać po identyfikatorze lub tickerze. Pełny cykl życia (mint, transfer, burn) znajdziesz w podlinkowanym teście.

Dotyczy: 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

Opis flag

Flagi ze Ścieżki A, które różnią się od zwykłej sesji bitcoind -regtest. Źródło prawdy: test_framework/test_tensorcash.py i init.cpp.

FlagaDlaczego ma znaczenie w regtest
-regtestWybiera łańcuch regtest (subsydium bloku, reguły natychmiastowej dojrzałości i lokalne porty 18443/18444).
-vdfspvcommitmentheight=0Aktywuje VDF/SPV od bloku genesis zamiast od wysokości przewidzianej dla mainnetu.
-vdfspvvdfverifyheight=0Aktywuje weryfikację VDF od bloku genesis.
-maxtipage=999999Akceptuje stare znaczniki czasu, więc restart na nieaktualnym łańcuchu nie wygląda jak niezsynchronizowany węzeł.
-spv-asn-min=1Obniża próg potwierdzeń ASN; bez tej flagi regtest blokuje logikę przełączania VDF SPV.
-spv-hysteresis-base-bps=0Usuwa histerezę marginesu bazowego, dzięki czemu reorganizacje w testach są natychmiastowe i deterministyczne.
-spv-reorg-sampling-threshold=999W praktyce wyłącza próbkowanie zawartości bloków przy głębokich reorganizacjach, którego nie da się sensownie wywołać na małych wysokościach.
-useextapi=0Wyłącza zewnętrzne API górnika: niepotrzebne w przykładach dotyczących samego łańcucha, a skraca start.
-debug=net,validationLoguje najprzydatniejsze linie w sesji regtest: sieć i potok walidacji.
-par=1Walidacja jednowątkowa. Eliminuje klasę niestabilności występujących tylko w testach, bez wpływu na poprawność.

Dokąd dalej

  • Dokumentacja JSON-RPCPełny indeks metod, pogrupowany w kategorie, z oznaczeniami stabilności i przykładami curl.
  • Verifier REST APIGdy przechodzisz z -validationapi=mock na prawdziwy proces weryfikatora.
  • Schematy FlatBufferIDL FlatBuffer i JSON Schema dla ładunków ZMQ przesyłanych między węzłem a weryfikatorem.
  • bcore/test/functional/Traktuj testy jak specyfikację.
  • Faucet testnetuOdpowiednik online: zasil portfel we współdzielonym testnecie, gdy zamiast lokalnego sandboxa potrzebujesz żywego łańcucha.