Průvodce regtestem

Tři cesty k lokálnímu vývoji, seřazené podle náročnosti. Každá ti zpřístupní JSON-RPC TensorCash, které můžeš volat přes bitcoin-cli nebo jakýkoli JSON-RPC klient. Kanonickou, spustitelnou specifikací všeho níže je sada funkčních testů bcore a každý návod odkazuje na test, ze kterého vychází.

Jen Core · docker compose · funkční testy

Režimy validace

TensorCash přidává k přijetí bloku externí validační krok. -validationapi vybírá backend, který ho obsluhuje, a pro lokální běh je to nejdůležitější volba: rozhoduje, zda potřebuješ GPU, proces ověřovatele, nebo ani jedno.

PřepínačCo to jeKdy ho použít
-validationapi=realVýchozí režim. Komunikuje s externím ověřovatelem přes ZMQ PUSH/PULL kanál mezi uzlem a ověřovatelem pomocí FlatBuffers. Produkční nastavení.Vyžaduje skutečný proces ověřovatele. Používá se na mainnetu, testnetu a v každém regtest běhu, který zkouší skutečný replay modelu.
-validationapi=mockV procesu a deterministický. Mock backend nabízí tři RPC (validationmockdefault, validationmockclear, validationmockrequests) pro předpřipravené odpovědi Quick, Full a Model; se startovacími přepínači -mockval-default-* lze naskriptovat každý výsledek ověření.Výchozí režim sady funkčních testů. Správná volba, když chceš řídit logiku řetězce bez ověřovatele a bez skutečné inference.
-validationapi=desktopHybridní. Kontroly Quick běží v procesu; Full a Model se posílají lokálnímu HTTPS ověřovateli (výchozí desktopová binárka). ZMQ broker není potřeba.Ukázky na jednom stroji, které chtějí skutečný průchod Quick a Smell bez provozování samostatné ověřovací služby.

Pro první seznámení s logikou řetězce je správnou odpovědí mock. Zbytek stránky s ním počítá, pokud není uvedeno jinak.

Cesta A · jen Core, s mock validací

Nejméně překážek. Jediný démon v C++: žádný docker, žádná GPU, žádné soubory modelů na disku. Stačí na všechny návody na této stránce.

1. Sestav démona

Postupuj podle návodu k sestavení Bitcoin Core nad services/core-node/bcore/. Kód TensorCash se sestavuje pod stejným CMake targetem jako upstream; žádný zvláštní přepínač není potřeba.

2. Spusť regtest uzel

Tyto přepínače odpovídají tomu, co test_framework/test_tensorcash.py předává každému funkčnímu testu, takže co běží tam, poběží i tady. Výchozí mock odpovědi jsou napevno nastavené na green, takže přijetí bloku je deterministické.

./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. Komunikuj s ním

Autentizace používá cookie soubor $HOME/.tensorcash-regtest/regtest/.cookie, který bitcoin-cli načte automaticky, když předáš -datadir. RPC port je výchozí upstream port pro regtest, 18443.

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

Cesta B · kompletní lokální stack (docker compose)

Pro chvíle, kdy mock nestačí: skutečný proces ověřovatele, skutečný model obsluhující inferenci a zapojené miner API. V kořeni repozitáře jsou spouštěcí skripty pro Macy a pro Linux s CUDA.

Na Apple Silicon spouštěč stáhne build llama.cpp a spustí celý compose stack 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 Linuxu s GPU NVIDIA dělá totéž launch_linux.sh, jen místo llama.cpp používá ověřovatele postaveného na 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 soubor váže hostitelské porty 8333 (P2P), 8050 (core-node REST API) a 7067 (ZMQ). Ověřovatel poskytuje své Verifier REST API na vlastním portu kontejneru.

Cesta C · spusť sadu funkčních testů

Jakmile máš démona sestaveného (Cesta A, krok 1), spouštěč testů za tebe nastartuje jednorázové uzly. Hodí se, když chceš ověřenou sekvenci, ze které můžeš opisovat, místo démona, do kterého bys šťouchal.

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 jsou seskupené podle rozhraní: životní cyklus modelů, nativní aktiva, fair-sign adaptory a covenantová repo peněženka. Každý je samostatný scénář, který se dá číst odshora dolů; návody níže odkazují na ty nejreprezentativnější.

Návody krok za krokem

Tři krátké sekvence proti mock uzlu z Cesty A. Každá je jen náčrt; úplný spustitelný scénář je v odkazovaném funkčním testu.

Vytěž svůj první blok

Kanonický test: wallet_basic.py

Beze změny oproti Bitcoin Core. Smoke test před jakýmkoli rozhraním specifickým pro TensorCash: potvrdí, že démon běží a peněženka má prostředky.

Používá: 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)

Zaregistruj model od začátku do konce

Kanonický test: feature_model_registration.py

Specifické pro TensorCash. Model se registruje tak, že se do úschovy složí záloha, během N commitů se nasbírají úspěšná ověření Quick a Model a po uzavření ověřovacího okna model přejde do stavu registered. S -validationapi=mock můžeš každý krok řídit přes RPC, bez skutečného ověřovatele i GPU. Tohle je jen nástin; celý scénář je v odkazovaném testu.

Používá: 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, ...}

Vydej nativní aktivum

Kanonický test: feature_assets_basic_highlevel.py

Specifické pro TensorCash. registerasset je vysokoúrovňové RPC peněženky, které sestaví výstupy kauce a ICU, připojí TLV s registrací emitenta a transakci odvysílá. Po jednom potvrzení lze aktivum dohledat podle id nebo tickeru. Celý životní cyklus (mint, převod, burn) je v odkazovaném testu.

Používá: 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

Přehled přepínačů

Přepínače z Cesty A, které se liší od obyčejné session bitcoind -regtest. Zdroj pravdy: test_framework/test_tensorcash.py a init.cpp.

PřepínačProč na tom v regtestu záleží
-regtestVybírá regtest řetězec (odměna za blok, pravidla okamžité zralosti a čistě lokální porty 18443/18444).
-vdfspvcommitmentheight=0Aktivuje VDF/SPV od genesis bloku místo postupné aktivace na výšce jako na mainnetu.
-vdfspvvdfverifyheight=0Aktivuje ověřování VDF od genesis bloku.
-maxtipage=999999Přijímá staré časové značky, takže restart na zastaralém řetězci nevypadá jako nesynchronizovaný uzel.
-spv-asn-min=1Snižuje minimální práh potvrzení ASN; bez něj regtest zablokuje logiku přepínání VDF SPV.
-spv-hysteresis-base-bps=0Odstraňuje hysterezi základní marže, takže reorgy v testech jsou okamžité a deterministické.
-spv-reorg-sampling-threshold=999Prakticky vypíná vzorkování těl bloků při hlubokých reorzích, které se na malých výškách nedá rozumně řídit.
-useextapi=0Vypíná externí miner API: pro návody pracující jen s řetězcem není potřeba a zkracuje start.
-debug=net,validationLoguje nejužitečnější řádky pro regtest session: síťovou komunikaci a validační pipeline.
-par=1Jednovláknová validace. Odstraňuje jednu třídu nestability, která se projevuje jen v testech, aniž by ovlivnila správnost.

Kam dál

  • Reference JSON-RPCÚplný přehled metod rozdělený do skupin, se štítky stability a ukázkami curl.
  • Verifier REST APIAž přejdeš od -validationapi=mock ke skutečnému procesu ověřovatele.
  • FlatBuffer schémataFlatBuffer IDL a JSON Schema pro ZMQ zprávy mezi uzlem a ověřovatelem.
  • bcore/test/functional/Čti testy jako specifikaci.
  • Testnetový faucetOnline protějšek: naplň si peněženku na sdíleném testnetu, když místo lokálního sandboxu chceš živý řetězec.