Regtest-handleiding

Drie routes voor lokale ontwikkeling, van eenvoudig naar uitgebreid. Elke route geeft je een TensorCash-JSON-RPC die je kunt aanroepen met bitcoin-cli of een andere JSON-RPC-client. De functionele testsuite van bcore is de canonieke, uitvoerbare specificatie voor alles hieronder, en bij elk voorbeeld staat een link naar de test waaruit het is afgeleid.

Alleen Core · docker compose · functionele tests

Validatiemodi

TensorCash voegt een externe validatiestap toe aan de acceptatie van blokken. -validationapi kiest de backend die deze stap uitvoert, en dat is de belangrijkste keuze voor een lokale run: die bepaalt of je een GPU nodig hebt, een verifierproces, of geen van beide.

FlagWat het isWanneer gebruiken
-validationapi=realDe standaard. Communiceert met een externe verifier via het ZMQ PUSH/PULL-kanaal tussen node en verifier, met FlatBuffers. De instelling voor productie.Vereist een echt verifierproces. Wordt gebruikt op mainnet, testnet en bij elke regtest-run die echte replay van modellen test.
-validationapi=mockIn het proces zelf en deterministisch. De mock-backend biedt drie RPC's (validationmockdefault, validationmockclear, validationmockrequests) voor vooraf ingestelde Quick-, Full- en Model-responses; met de startflags -mockval-default-* is elke verificatie-uitkomst te scripten.De standaard voor de functionele testsuite. De juiste keuze om de blockchainlogica aan te sturen zonder verifier of echte inferentie.
-validationapi=desktopHybride. Quick-controles draaien in het proces zelf; Full en Model gaan naar een lokale HTTPS-verifier (de standaard desktopbinary). Geen ZMQ-broker nodig.Demo's op één machine waarbij je een echte Quick- en Smell-controle wilt, zonder een aparte verifierdienst te beheren.

Voor een eerste blik op de blockchainlogica is mock de juiste keuze. De rest van deze pagina gaat daarvan uit, tenzij anders vermeld.

Route A · alleen Core, met gesimuleerde validatie

De eenvoudigste route. Eén C++-daemon: geen Docker, geen GPU, geen modelbestanden op schijf. Genoeg voor elk voorbeeld op deze pagina.

1. Bouw de daemon

Volg de build-instructies van Bitcoin Core en pas ze toe op services/core-node/bcore/. De TensorCash-code wordt gebouwd met hetzelfde CMake-target als upstream; er is geen aparte flag.

2. Start een regtest-node

Deze flags komen overeen met wat test_framework/test_tensorcash.py aan elke functionele test meegeeft, dus alles wat daar draait, draait hier ook. De standaard mock-responses staan vast op GREEN, dus blokacceptatie is deterministisch.

./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. Maak verbinding

Authenticatie gaat via het cookiebestand in $HOME/.tensorcash-regtest/regtest/.cookie, dat bitcoin-cli automatisch leest als je -datadir meegeeft. De RPC-poort is de standaardpoort van upstream voor regtest, 18443.

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

Route B · de volledige lokale stack (docker compose)

Voor als gesimuleerde validatie niet genoeg is: een echt verifierproces, een echt model dat inferentie levert, en de miner-API aangesloten. In de root van de repository staan startscripts voor Macs en voor Linux met CUDA.

Op Apple silicon haalt het startscript een build van llama.cpp binnen en start het de volledige 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

Op Linux met NVIDIA-GPU's doet launch_linux.sh hetzelfde, met de verifier op basis van vLLM in plaats van 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

Het compose-bestand bindt de hostpoorten 8333 (P2P), 8050 (de REST-API van de core-node) en 7067 (ZMQ). De verifier biedt de REST-API van de verifier aan op een eigen containerpoort.

Route C · draai de functionele testsuite

Zodra de daemon gebouwd is (route A, stap 1), start de testrunner wegwerpnodes voor je. Handig als je een bewezen werkende reeks wilt om van over te nemen, in plaats van een daemon om mee te experimenteren.

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)

De TensorCash-tests zijn ingedeeld per onderdeel: levenscyclus van modellen, native assets, fair-sign-adaptors en de covenant-repowallet. Elke test is een op zichzelf staand scenario dat je van boven naar beneden kunt lezen; de voorbeelden hieronder verwijzen naar de meest representatieve.

Uitgewerkte voorbeelden

Drie korte reeksen op de mock-node uit route A. Elke reeks is een schets; de gelinkte functionele test is het volledige, uitvoerbare scenario.

Mine je eerste blok

Canonieke test: wallet_basic.py

Ongewijzigd ten opzichte van Bitcoin Core. Een smoketest voordat je iets aanraakt wat specifiek is voor TensorCash: hij bevestigt dat de daemon draait en dat de wallet gevuld is.

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

Een model van begin tot eind registreren

Canonieke test: feature_model_registration.py

Specifiek voor TensorCash. Een model wordt geregistreerd door een deposito in escrow te zetten, over N commits geslaagde Quick- en Model-verificaties te verzamelen en daarna naar registered over te gaan zodra het verificatievenster sluit. Met -validationapi=mock kun je elke stap via RPC's aansturen, zonder echte verifier of GPU. Dit is een schets; de gelinkte test bevat het volledige scenario.

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

Een native asset uitgeven

Canonieke test: feature_assets_basic_highlevel.py

Specifiek voor TensorCash. registerasset is de wallet-RPC op hoog niveau die de borg- en ICU-outputs opbouwt, de TLV met de registratie van de uitgever toevoegt en de transactie naar het netwerk verzendt. Na één bevestiging kun je de asset opvragen op id of ticker. De volledige levenscyclus (aanmaken, overdragen, verbranden) staat in de gelinkte test.

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

Overzicht van de flags

De flags uit route A die afwijken van een gewone bitcoind -regtest-sessie. Bron van waarheid: test_framework/test_tensorcash.py en init.cpp.

FlagWaarom het in regtest uitmaakt
-regtestSelecteert de regtest-blockchain (bloksubsidie, regels voor directe maturity en de poorten 18443/18444, die alleen lokaal bereikbaar zijn).
-vdfspvcommitmentheight=0Activeert VDF/SPV vanaf het genesisblok in plaats van pas op de activeringshoogte van mainnet.
-vdfspvvdfverifyheight=0Activeert VDF-verificatie vanaf het genesisblok.
-maxtipage=999999Accepteert oude timestamps, zodat een herstart op een verouderde blockchain er niet uitziet als een niet-gesynchroniseerde node.
-spv-asn-min=1Verlaagt het minimum voor ASN-bevestiging; zonder deze flag blokkeert regtest de schakellogica voor VDF/SPV.
-spv-hysteresis-base-bps=0Verwijdert de base-margin-hysterese, zodat reorgs in tests direct en deterministisch zijn.
-spv-reorg-sampling-threshold=999Schakelt de body-sampling bij diepe reorgs in de praktijk uit; die is bij lage blokhoogtes nauwelijks aan te sturen.
-useextapi=0Schakelt de externe miner-API uit: niet nodig voor voorbeelden die alleen de blockchain gebruiken, en het opstarten gaat sneller.
-debug=net,validationLogt de nuttigste regels voor een regtest-sessie: netwerkverkeer en de validatiepipeline.
-par=1Validatie op één thread. Neemt een soort instabiliteit weg die alleen in tests voorkomt, zonder de correctheid te beïnvloeden.

Verder lezen

  • JSON-RPC-referentieDe volledige index van methoden, ingedeeld per categorie, met stabiliteitslabels en curl-voorbeelden.
  • REST-API van de verifierVoor als je overstapt van -validationapi=mock naar een echt verifierproces.
  • FlatBuffer-schemasFlatBuffer-IDL en JSON Schema voor de ZMQ-payloads tussen node en verifier.
  • bcore/test/functional/Lees de tests als specificatie.
  • Testnet-faucetDe online tegenhanger: vul een wallet op het gedeelde testnet als je een draaiende blockchain wilt in plaats van een lokale sandbox.