Guida regtest

Tre percorsi di sviluppo locale, dal più semplice al più impegnativo. Ognuno ti mette a disposizione un JSON-RPC TensorCash da chiamare con bitcoin-cli o con qualsiasi client JSON-RPC. La suite di test funzionali di bcore è la specifica canonica ed eseguibile di tutto ciò che segue, e ogni procedura guidata rimanda al test da cui è stata ricavata.

Solo Core · docker compose · test funzionali

Modalità di validazione

TensorCash aggiunge un passaggio di validazione esterna all'accettazione dei blocchi. -validationapi seleziona il backend che lo esegue, ed è la scelta più importante per un'esecuzione locale: stabilisce se ti serve una GPU, un verificatore in esecuzione o nessuno dei due.

FlagChe cos'èQuando usarla
-validationapi=realLa modalità predefinita. Comunica con un verificatore esterno sul canale ZMQ PUSH/PULL tra nodo e verificatore, usando FlatBuffers. È l'impostazione di produzione.Richiede un verificatore reale in esecuzione. Si usa su mainnet, su testnet e in ogni esecuzione regtest che prevede il replay reale del modello.
-validationapi=mockNel processo stesso e deterministica. Il backend simulato espone tre RPC (validationmockdefault, validationmockclear, validationmockrequests) per risposte Quick, Full e Model preimpostate; con i flag di avvio -mockval-default-*, ogni esito della verifica è programmabile.La modalità predefinita della suite di test funzionali. La scelta giusta per provare la logica della blockchain senza un verificatore né un'inferenza reale.
-validationapi=desktopIbrida. I controlli Quick girano nel processo stesso; Full e Model vengono inviati a un verificatore HTTPS locale (il binario desktop predefinito). Non serve un broker ZMQ.Demo su una sola macchina, quando vuoi un vero passaggio Quick e Smell senza gestire un servizio di verifica separato.

Per un primo approccio alla logica della blockchain, mock è la scelta giusta. Salvo indicazione contraria, il resto della pagina presuppone questa modalità.

Percorso A · solo Core, con validazione simulata

La strada più semplice. Un solo daemon C++: niente docker, niente GPU, nessun file di modello su disco. Basta per tutte le procedure guidate di questa pagina.

1. Compila il daemon

Segui le istruzioni di compilazione di Bitcoin Core applicandole a services/core-node/bcore/. Il codice TensorCash si compila con lo stesso target CMake dell'upstream; non c'è un flag separato.

2. Avvia un nodo regtest

Questi flag riproducono quelli che test_framework/test_tensorcash.py passa a ogni test funzionale, quindi tutto ciò che gira lì gira anche qui. Le risposte simulate predefinite sono fissate su green, così l'accettazione dei blocchi è deterministica.

./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. Interroga il nodo

L'autenticazione usa il file cookie in $HOME/.tensorcash-regtest/regtest/.cookie, che bitcoin-cli legge automaticamente quando passi -datadir. La porta RPC è quella predefinita della regtest upstream, 18443.

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

Percorso B · lo stack locale completo (docker compose)

Per quando la simulazione non basta: un verificatore reale in esecuzione, un vero modello che esegue l'inferenza e l'API del miner collegata. Nella root del repository trovi gli script di avvio per Mac e per Linux con CUDA.

Su Apple silicon lo script di avvio scarica una build di llama.cpp e avvia lo stack compose completo 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

Su Linux con GPU NVIDIA, launch_linux.sh fa lo stesso, ma con il verificatore basato su vLLM al posto di 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

Il file compose espone sull'host le porte 8333 (P2P), 8050 (l'API REST core-node) e 7067 (ZMQ). Il verificatore espone la sua API REST del verificatore su una porta del proprio container.

Percorso C · esegui la suite di test funzionali

Una volta compilato il daemon (Percorso A, passo 1), è il test runner ad avviare per te nodi usa e getta. Utile quando vuoi una sequenza collaudata da cui copiare, più che un daemon da esplorare a mano.

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)

I test TensorCash sono raggruppati per area: ciclo di vita dei modelli, asset nativi, adaptor fair-sign e wallet per i pronti contro termine basati su covenant. Ognuno è uno scenario autonomo che puoi leggere dall'inizio alla fine; le procedure guidate qui sotto rimandano ai più rappresentativi.

Procedure guidate

Tre brevi sequenze sul nodo simulato del Percorso A. Ognuna è solo una traccia; il test funzionale collegato è lo scenario completo ed eseguibile.

Mina il tuo primo blocco

Test di riferimento: wallet_basic.py

Identico a Bitcoin Core. Un test di base prima di toccare qualsiasi funzione specifica di TensorCash: conferma che il daemon è attivo e che il wallet ha fondi.

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

Registra un modello dall'inizio alla fine

Test di riferimento: feature_model_registration.py

Specifico di TensorCash. Un modello si registra vincolando un deposito, raccogliendo verifiche Quick e Model andate a buon fine su N commit e passando poi allo stato registered alla chiusura della finestra di verifica. Con -validationapi=mock puoi pilotare ogni passaggio tramite RPC, senza un verificatore reale né una GPU. Questa è una traccia; lo scenario completo è nel test collegato.

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

Emetti un asset nativo

Test di riferimento: feature_assets_basic_highlevel.py

Specifico di TensorCash. registerasset è la RPC di alto livello del wallet che costruisce gli output del bond e dell'ICU, allega il TLV di registrazione dell'emittente e trasmette la transazione. Dopo una conferma, l'asset si può interrogare per id o per ticker. Il ciclo di vita completo (creazione, trasferimento e distruzione di unità) è nel test collegato.

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

Elenco dei flag

I flag del Percorso A che differiscono da una normale sessione bitcoind -regtest. Fonti di riferimento: test_framework/test_tensorcash.py e init.cpp.

FlagPerché serve in regtest
-regtestSeleziona la blockchain regtest (sussidio di blocco, regole di maturazione immediata e le porte solo locali 18443/18444).
-vdfspvcommitmentheight=0Attiva VDF/SPV dal blocco genesi, invece che all'altezza prevista per l'attivazione graduale su mainnet.
-vdfspvvdfverifyheight=0Attiva la verifica VDF dal blocco genesi.
-maxtipage=999999Accetta timestamp vecchi, così un riavvio su una blockchain ferma da tempo non sembra un nodo non sincronizzato.
-spv-asn-min=1Abbassa la soglia minima di conferma tra ASN diversi; senza questo flag, la regtest blocca la logica di commutazione VDF SPV.
-spv-hysteresis-base-bps=0Elimina l'isteresi sul margine di base, così le riorganizzazioni nei test sono immediate e deterministiche.
-spv-reorg-sampling-threshold=999Disattiva di fatto il campionamento dei corpi dei blocchi nelle riorganizzazioni profonde, difficile da gestire ad altezze ridotte.
-useextapi=0Disattiva l'API esterna del miner: non serve per le procedure guidate che riguardano solo la blockchain e accorcia l'avvio.
-debug=net,validationRegistra nei log le righe più utili per una sessione regtest: rete e pipeline di validazione.
-par=1Validazione a thread singolo. Elimina una classe di instabilità che si presenta solo nei test, senza incidere sulla correttezza.

Prossimi passi

  • Riferimento JSON-RPCL'indice completo dei metodi, organizzato per categoria, con livello di stabilità ed esempi curl.
  • API REST del verificatorePer quando passi da -validationapi=mock a un verificatore reale in esecuzione.
  • Schemi FlatBufferIDL FlatBuffer e JSON Schema per i payload ZMQ tra nodo e verificatore.
  • bcore/test/functional/Leggi i test come se fossero la specifica.
  • Faucet testnetLa controparte online: carica un wallet sulla testnet condivisa quando ti serve una blockchain attiva invece di un ambiente di prova locale.