Regtest-guide

Tre vägar för lokal utveckling, ordnade efter friktion. Var och en ger dig en TensorCash-JSON-RPC att anropa med bitcoin-cli eller valfri JSON-RPC-klient. bcores funktionella testsvit är den kanoniska, körbara specifikationen för allt nedan, och varje genomgång länkar till testet den bygger på.

Bara Core · docker compose · funktionella tester

Valideringslägen

TensorCash lägger till ett externt valideringssteg i blockacceptansen. -validationapi väljer backenden som utför det, och det är det viktigaste valet för en lokal körning: det avgör om du behöver en GPU, en verifierarprocess eller ingetdera.

FlaggaVad det ärNär du ska använda det
-validationapi=realStandardläget. Kommunicerar med en extern verifierare över ZMQ-kanalen PUSH/PULL mellan nod och verifierare, med FlatBuffers. Inställningen för produktion.Kräver en riktig verifierarprocess. Används på mainnet, testnet och i varje regtest-körning som testar verklig omkörning av modeller.
-validationapi=mockI processen och deterministiskt. Mock-backenden exponerar tre RPC:er (validationmockdefault, validationmockclear, validationmockrequests) för förberedda svar på Quick, Full och Model; med startflaggorna -mockval-default-* går varje verifieringsutfall att skripta.Standard för den funktionella testsviten. Rätt val för att driva kedjelogiken utan verifierare eller riktig inferens.
-validationapi=desktopHybrid. Quick-kontroller körs i processen; Full och Model skickas till en lokal HTTPS-verifierare (standardbinären för skrivbordet). Ingen ZMQ-broker behövs.Demonstrationer på en enda maskin som vill ha en riktig Quick- och Smell-kontroll utan att driva en separat verifieringstjänst.

För en första titt på kedjelogiken är mock rätt svar. Resten av sidan utgår från det om inget annat anges.

Väg A · bara Core, med mockvalidering

Minst friktion. En C++-daemon: ingen docker, ingen GPU, inga modellfiler på disken. Räcker för varje genomgång på den här sidan.

1. Bygg daemonen

Följ Bitcoin Cores bygginstruktioner mot services/core-node/bcore/. TensorCash-koden byggs under samma CMake-mål som upstream; det finns ingen separat flagga.

2. Starta en regtest-nod

De här flaggorna motsvarar det som test_framework/test_tensorcash.py skickar till varje funktionellt test, så allt som körs där körs här också. Standardsvaren från mocken är låsta till grönt, så blockacceptansen är deterministisk.

./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. Prata med den

Autentiseringen använder cookiefilen $HOME/.tensorcash-regtest/regtest/.cookie, som bitcoin-cli läser automatiskt när du anger -datadir. RPC-porten är upstreams standardport för regtest, 18443.

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

Väg B · hela den lokala stacken (docker compose)

För när mocken inte räcker: en riktig verifierarprocess, en riktig modell som levererar inferens och miner-API:t inkopplat. I repots rot finns startskript för Mac och för Linux med CUDA.

På Apple silicon hämtar startskriptet ett llama.cpp-bygge och startar hela compose-stacken 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

På Linux med NVIDIA-GPU:er gör launch_linux.sh samma sak, men med den vLLM-baserade verifieraren i stället för 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-filen binder värdportarna 8333 (P2P), 8050 (core-node REST-API) och 7067 (ZMQ). Verifieraren exponerar sitt Verifier REST-API på sin egen containerport.

Väg C · kör den funktionella testsviten

När daemonen är byggd (väg A, steg 1) startar testköraren tillfälliga noder åt dig. Användbart när du vill ha en beprövad sekvens att kopiera från snarare än en daemon att peta i.

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-testerna är grupperade efter gränssnitt: modellernas livscykel, nativa tillgångar, fair-sign-adaptrar och covenant-repaplånboken. Varje test är ett fristående scenario som du kan läsa uppifrån och ned; genomgångarna nedan pekar på de mest representativa.

Genomgångar

Tre korta sekvenser mot mocknoden från väg A. Var och en är en skiss; det länkade funktionella testet är det fullständiga, körbara scenariot.

Mina ditt första block

Kanoniskt test: wallet_basic.py

Oförändrat från Bitcoin Core. Ett röktest före alla TensorCash-specifika gränssnitt: det bekräftar att daemonen är uppe och att plånboken har medel.

Berör: 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)

Registrera en modell från början till slut

Kanoniskt test: feature_model_registration.py

TensorCash-specifikt. En modell registreras genom att en deposition låses, lyckade Quick- och Model-verifieringar samlas in över N commits och modellen sedan går över till registered när verifieringsfönstret stängs. Med -validationapi=mock kan du driva varje steg via RPC:er, utan riktig verifierare eller GPU. Det här är en översikt; det länkade testet innehåller hela scenariot.

Berör: 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, ...}

Emittera en nativ tillgång

Kanoniskt test: feature_assets_basic_highlevel.py

TensorCash-specifikt. registerasset är plånbokens högnivå-RPC som bygger bond- och ICU-utgångarna, bifogar emittentens registrerings-TLV och sänder transaktionen. Efter en bekräftelse kan tillgången hämtas via id eller ticker. Hela livscykeln (mint, överföring, bränning) finns i det länkade testet.

Berör: 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

Flaggreferens

Flaggorna från väg A som skiljer sig från en vanlig bitcoind -regtest-session. Auktoritativ källa: test_framework/test_tensorcash.py och init.cpp.

FlaggaVarför det spelar roll i regtest
-regtestVäljer regtest-kedjan (blocksubvention, regler för omedelbar mognad och de lokala portarna 18443/18444).
-vdfspvcommitmentheight=0Aktiverar VDF/SPV från genesis i stället för vid den stegvisa mainnet-höjden.
-vdfspvvdfverifyheight=0Aktiverar VDF-verifiering från genesis.
-maxtipage=999999Accepterar gamla tidsstämplar, så att en omstart på en inaktuell kedja inte ser ut som en osynkad nod.
-spv-asn-min=1Sänker golvet för ASN-bekräftelse; utan den blockerar regtest växlingslogiken för VDF-SPV.
-spv-hysteresis-base-bps=0Tar bort hysteresen för basmarginalen, så att reorganiseringar i tester sker omedelbart och deterministiskt.
-spv-reorg-sampling-threshold=999Stänger i praktiken av stickprov på blockinnehåll vid djupa reorganiseringar, vilket är opraktiskt att driva vid låga höjder.
-useextapi=0Stänger av det externa miner-API:t: det behövs inte för genomgångar som bara rör kedjan, och uppstarten går snabbare.
-debug=net,validationLoggar de mest användbara raderna för en regtest-session: nätverk och valideringspipelinen.
-par=1Entrådig validering. Tar bort en typ av instabilitet som bara uppstår i tester, utan att påverka korrektheten.

Vart härnäst

  • JSON-RPC-referensDet fullständiga metodindexet, ordnat efter kategori, med stabilitetstaggar och curl-exempel.
  • Verifier REST-APINär du går från -validationapi=mock till en riktig verifierarprocess.
  • FlatBuffer-schemanFlatBuffer-IDL och JSON Schema för ZMQ-nyttolasterna mellan nod och verifierare.
  • bcore/test/functional/Läs testerna som specifikationen.
  • Testnet-faucetMotsvarigheten online: fyll på en plånbok på det delade testnet när du vill ha en kedja i drift i stället för en lokal sandlåda.