Regtest-Guide

Drei lokale Entwicklungswege, geordnet nach Aufwand. Jeder stellt dir eine TensorCash-JSON-RPC-Schnittstelle bereit, die du mit bitcoin-cli oder einem beliebigen JSON-RPC-Client aufrufen kannst. Die funktionale Testsuite von bcore ist die maßgebliche, ausführbare Spezifikation für alles Folgende, und jeder Walkthrough verlinkt den Test, aus dem er abgeleitet ist.

Nur Core · docker compose · funktionale Tests

Validierungsmodi

TensorCash ergänzt die Annahme von Blöcken um einen externen Validierungsschritt. -validationapi wählt das Backend, das ihn ausführt, und das ist die wichtigste Entscheidung für einen lokalen Lauf: Sie bestimmt, ob du eine GPU, einen Verifizierer-Prozess oder keins von beidem brauchst.

FlagWas er istWann du ihn nutzt
-validationapi=realDer Standard. Spricht über den ZMQ-PUSH/PULL-Kanal zwischen Node und Verifizierer mit einem externen Verifizierer, per FlatBuffers. Die Einstellung für den Produktivbetrieb.Erfordert einen echten Verifizierer-Prozess. Wird im Mainnet, im Testnet und bei jedem Regtest-Lauf genutzt, der echtes Modell-Replay durchspielt.
-validationapi=mockIm Prozess und deterministisch. Das Mock-Backend stellt drei RPCs bereit (validationmockdefault, validationmockclear, validationmockrequests) für vorgefertigte Quick-, Full- und Model-Antworten; mit den Start-Flags -mockval-default-* lässt sich jedes Verifikationsergebnis skripten.Standard für die funktionale Testsuite. Die richtige Wahl, um die Chain-Logik ohne Verifizierer oder echte Inferenz anzusteuern.
-validationapi=desktopHybrid. Quick-Prüfungen laufen im Prozess; Full und Model gehen an einen lokalen HTTPS-Verifizierer (das Standard-Desktop-Binary). Kein ZMQ-Broker nötig.Demos auf einem einzelnen Rechner, die einen echten Quick- und Smell-Durchlauf wollen, ohne einen separaten Verifizierer-Dienst zu betreiben.

Für einen ersten Blick auf die Chain-Logik ist mock die richtige Wahl. Der Rest dieser Seite geht davon aus, sofern nicht anders angegeben.

Weg A · nur Core, mit Mock-Validierung

Der Weg mit der geringsten Hürde. Ein einziger C++-Daemon: kein Docker, keine GPU, keine Modelldateien auf der Platte. Reicht für jeden Walkthrough auf dieser Seite.

1. Den Daemon bauen

Folge den Build-Anleitungen von Bitcoin Core für services/core-node/bcore/. Der TensorCash-Code baut unter demselben CMake-Target wie Upstream; ein separates Flag gibt es nicht.

2. Einen Regtest-Node starten

Diese Flags entsprechen dem, was test_framework/test_tensorcash.py jedem funktionalen Test übergibt. Was dort läuft, läuft also auch hier. Die Standard-Mock-Antworten sind auf Grün festgelegt, die Annahme von Blöcken ist daher 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. Mit dem Node sprechen

Die Authentifizierung nutzt die Cookie-Datei unter $HOME/.tensorcash-regtest/regtest/.cookie, die bitcoin-cli automatisch liest, wenn du -datadir übergibst. Der RPC-Port ist der Upstream-Regtest-Standard, 18443.

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

Weg B · der komplette lokale Stack (docker compose)

Für den Fall, dass Mock nicht reicht: ein echter Verifizierer-Prozess, ein echtes Modell, das Inferenz ausliefert, und die angebundene Miner-API. Im Wurzelverzeichnis des Repositorys liegen Startskripte für Macs und für Linux mit CUDA.

Auf Apple Silicon lädt das Startskript einen llama.cpp-Build und fährt den kompletten Compose-Stack core-node + miner-api + verification-api hoch:

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

Unter Linux mit NVIDIA-GPUs macht launch_linux.sh dasselbe, aber mit dem vLLM-basierten Verifizierer statt 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

Die Compose-Datei bindet die Host-Ports 8333 (P2P), 8050 (die core-node REST-API) und 7067 (ZMQ). Der Verifizierer stellt seine Verifizierer-REST-API auf einem eigenen Container-Port bereit.

Weg C · die funktionale Testsuite ausführen

Sobald der Daemon gebaut ist (Weg A, Schritt 1), startet der Test-Runner Wegwerf-Nodes für dich. Praktisch, wenn du eine bewährte Abfolge zum Abschreiben suchst statt eines Daemons zum Herumprobieren.

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)

Die TensorCash-Tests sind nach Schnittstelle gruppiert: Modell-Lebenszyklus, native Assets, Fair-Sign-Adaptoren und die Covenant-Repo-Wallet. Jeder ist ein in sich geschlossenes Szenario, das du von oben nach unten lesen kannst; die Walkthroughs unten verweisen auf die repräsentativsten.

Schritt-für-Schritt-Anleitungen

Drei kurze Abfolgen gegen den Mock-Node aus Weg A. Jede ist eine Skizze; der verlinkte funktionale Test ist das vollständige, ausführbare Szenario.

Deinen ersten Block minen

Maßgeblicher Test: wallet_basic.py

Unverändert gegenüber Bitcoin Core. Ein Smoke-Test vor jeder TensorCash-spezifischen Schnittstelle: Er bestätigt, dass der Daemon läuft und die Wallet Guthaben hat.

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

Ein Modell von Anfang bis Ende registrieren

Maßgeblicher Test: feature_model_registration.py

TensorCash-spezifisch. Ein Modell wird registriert, indem eine Kaution hinterlegt wird, über N Commits erfolgreiche Quick- und Model-Verifikationen gesammelt werden und es nach Ablauf des Verifikationsfensters in den Status registered wechselt. Mit -validationapi=mock kannst du jeden Schritt per RPC steuern, ohne echten Verifizierer oder GPU. Dies ist eine Skizze; das vollständige Szenario steht im verlinkten Test.

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

Ein natives Asset emittieren

Maßgeblicher Test: feature_assets_basic_highlevel.py

TensorCash-spezifisch. registerasset ist der High-Level-Wallet-RPC, der die Bond- und ICU-Outputs baut, das TLV für die Emittenten-Registrierung anhängt und die Transaktion sendet. Nach einer Bestätigung lässt sich das Asset per ID oder Ticker abfragen. Den vollständigen Lebenszyklus (Mint, Transfer, Burn) zeigt der verlinkte Test.

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

Flag-Referenz

Die Flags aus Weg A, die sich von einer einfachen bitcoind -regtest-Sitzung unterscheiden. Maßgebliche Quelle: test_framework/test_tensorcash.py und init.cpp.

FlagWarum es in Regtest wichtig ist
-regtestWählt die Regtest-Chain (Blocksubvention, Regeln für sofortige Reife und die rein lokalen Ports 18443/18444).
-vdfspvcommitmentheight=0Aktiviert VDF/SPV ab dem Genesis-Block statt ab der gestaffelten Mainnet-Höhe.
-vdfspvvdfverifyheight=0Aktiviert die VDF-Verifikation ab dem Genesis-Block.
-maxtipage=999999Akzeptiert alte Zeitstempel, damit ein Neustart auf einer veralteten Chain nicht wie ein nicht synchronisierter Node aussieht.
-spv-asn-min=1Senkt die Mindestzahl an ASN-Bestätigungen; ohne das Flag blockiert Regtest die VDF-SPV-Umschaltlogik.
-spv-hysteresis-base-bps=0Entfernt die Base-Margin-Hysterese, sodass Reorgs in Tests sofort und deterministisch erfolgen.
-spv-reorg-sampling-threshold=999Deaktiviert praktisch das Body-Sampling bei tiefen Reorgs, das sich bei geringen Blockhöhen kaum sinnvoll ansteuern lässt.
-useextapi=0Deaktiviert die externe Miner-API: für reine Chain-Walkthroughs nicht nötig, und der Start geht schneller.
-debug=net,validationProtokolliert die nützlichsten Zeilen für eine Regtest-Sitzung: Netzwerk und Validierungspipeline.
-par=1Validierung in einem einzigen Thread. Beseitigt eine Klasse rein testbedingter Instabilität, ohne die Korrektheit zu beeinträchtigen.

Wie geht’s weiter

  • JSON-RPC-ReferenzDer vollständige Methodenindex, nach Bereichen geordnet, mit Stabilitäts-Tags und curl-Beispielen.
  • Verifizierer-REST-APIWenn du von -validationapi=mock zu einem echten Verifizierer-Prozess wechselst.
  • FlatBuffer-SchemasFlatBuffer-IDL und JSON-Schema für die ZMQ-Payloads zwischen Node und Verifizierer.
  • bcore/test/functional/Lies die Tests als Spezifikation.
  • Testnet-FaucetDas Online-Gegenstück: Lade eine Wallet im gemeinsamen Testnet auf, wenn du statt einer lokalen Sandbox eine echte Chain willst.