Guide regtest

Trois voies de développement local, classées par niveau de friction. Chacune vous met face à un JSON-RPC TensorCash à appeler avec bitcoin-cli ou n’importe quel client JSON-RPC. La suite de tests fonctionnels de bcore est la spécification canonique et exécutable de tout ce qui suit, et chaque tutoriel renvoie au test dont il est tiré.

Core seul · docker compose · tests fonctionnels

Modes de validation

TensorCash ajoute une étape de validation externe à l’acceptation des blocs. -validationapi choisit le backend qui la fournit ; c’est le choix le plus important pour une exécution locale, car il détermine si vous avez besoin d’un GPU, d’un processus vérificateur, ou de rien du tout.

OptionCe que c’estQuand l’utiliser
-validationapi=realLe mode par défaut. Communique avec un vérificateur externe par le canal ZMQ PUSH/PULL entre nœud et vérificateur, en FlatBuffers. Le réglage de production.Nécessite un vrai processus vérificateur. Utilisé sur le mainnet, le testnet et toute session regtest qui met en œuvre un vrai rejeu de modèle.
-validationapi=mockDans le processus et déterministe. Le backend simulé expose trois RPC (validationmockdefault, validationmockclear, validationmockrequests) pour des réponses Quick, Full et Model préenregistrées ; avec les options de démarrage -mockval-default-*, chaque résultat de vérification est scriptable.Le mode par défaut de la suite de tests fonctionnels. Le bon choix pour piloter la logique de la chaîne sans vérificateur ni inférence réelle.
-validationapi=desktopHybride. Les vérifications Quick s’exécutent dans le processus ; Full et Model sont envoyées à un vérificateur HTTPS local (le binaire desktop par défaut). Aucun broker ZMQ nécessaire.Démos sur une seule machine qui nécessitent une vraie passe Quick et Smell, sans exploiter de service vérificateur séparé.

Pour une première exploration de la logique de la chaîne, mock est le bon choix. Sauf mention contraire, la suite de cette page part de ce mode.

Voie A · Core seul, avec validation simulée

Le moins de friction possible. Un seul daemon C++ : pas de docker, pas de GPU, aucun fichier de modèle sur le disque. Suffisant pour tous les tutoriels de cette page.

1. Compiler le daemon

Suivez les instructions de compilation de Bitcoin Core dans services/core-node/bcore/. Le code TensorCash se compile avec la même cible CMake qu’en amont ; il n’y a pas d’option séparée.

2. Démarrer un nœud regtest

Ces options reprennent celles que test_framework/test_tensorcash.py passe à chaque test fonctionnel : tout ce qui tourne là-bas tourne aussi ici. Les réponses simulées par défaut sont fixées au vert, donc l’acceptation des blocs est déterministe.

./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. Interagir avec le nœud

L’authentification utilise le fichier cookie $HOME/.tensorcash-regtest/regtest/.cookie, que bitcoin-cli lit automatiquement quand vous passez -datadir. Le port RPC est le port regtest par défaut de Bitcoin Core, 18443.

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

Voie B · la stack locale complète (docker compose)

Quand la simulation ne suffit plus : un vrai processus vérificateur, un vrai modèle qui sert l’inférence, et l’API du mineur branchée. La racine du dépôt contient des scripts de lancement pour Mac et pour Linux avec CUDA.

Sur Apple silicon, le lanceur récupère une build de llama.cpp et démarre la stack compose complète 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

Sous Linux avec des GPU NVIDIA, launch_linux.sh fait la même chose avec le vérificateur basé sur vLLM au lieu de 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

Le fichier compose expose les ports hôte 8333 (P2P), 8050 (l’API REST core-node) et 7067 (ZMQ). Le vérificateur sert son API REST du vérificateur sur son propre port de conteneur.

Voie C · lancer la suite de tests fonctionnels

Une fois le daemon compilé (voie A, étape 1), le lanceur de tests démarre pour vous des nœuds jetables. Pratique quand vous voulez une séquence éprouvée à copier plutôt qu’un daemon à explorer.

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)

Les tests TensorCash sont regroupés par domaine : cycle de vie des modèles, actifs natifs, adaptateurs fair-sign et wallet repo à covenant. Chacun est un scénario autonome qui se lit de haut en bas ; les tutoriels ci-dessous renvoient aux plus représentatifs.

Tutoriels

Trois courtes séquences à exécuter sur le nœud simulé de la voie A. Chacune n’est qu’une esquisse ; le test fonctionnel associé est le scénario complet et exécutable.

Miner votre premier bloc

Test de référence : wallet_basic.py

Identique à Bitcoin Core. Un test de fumée avant toute fonctionnalité spécifique à TensorCash : il confirme que le daemon tourne et que le wallet est approvisionné.

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

Enregistrer un modèle de bout en bout

Test de référence : feature_model_registration.py

Spécifique à TensorCash. Un modèle s’enregistre en bloquant un dépôt sous séquestre, en accumulant des vérifications Quick et Model réussies sur N commits, puis passe à l’état registered une fois la fenêtre de vérification close. Avec -validationapi=mock, chaque étape se pilote par RPC, sans vrai vérificateur ni GPU. Ceci n’est qu’un aperçu ; le test associé contient le scénario complet.

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

Émettre un actif natif

Test de référence : feature_assets_basic_highlevel.py

Spécifique à TensorCash. registerasset est la RPC de haut niveau du wallet qui construit les sorties de caution et ICU, joint le TLV d’enregistrement de l’émetteur et diffuse la transaction. Après une confirmation, l’actif peut être interrogé par identifiant ou par ticker. Le cycle de vie complet (création, transfert, destruction) se trouve dans le test associé.

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

Référence des options

Les options de la voie A qui diffèrent d’une session bitcoind -regtest classique. Source de référence : test_framework/test_tensorcash.py et init.cpp.

OptionPourquoi c’est important en regtest
-regtestSélectionne la chaîne regtest (subvention de bloc, règles de maturité immédiate et ports locaux 18443/18444).
-vdfspvcommitmentheight=0Active VDF/SPV dès le bloc genesis au lieu de la hauteur échelonnée du mainnet.
-vdfspvvdfverifyheight=0Active la vérification VDF dès le bloc genesis.
-maxtipage=999999Accepte les horodatages anciens : un redémarrage sur une chaîne figée ne fait pas passer le nœud pour non synchronisé.
-spv-asn-min=1Abaisse le seuil de corroboration ASN ; sans cette option, le regtest bloque la logique de bascule VDF/SPV.
-spv-hysteresis-base-bps=0Supprime l’hystérésis de marge de base : les réorganisations dans les tests sont immédiates et déterministes.
-spv-reorg-sampling-threshold=999Désactive en pratique l’échantillonnage des corps de blocs lors des réorganisations profondes, difficile à exercer à faible hauteur.
-useextapi=0Désactive l’API externe du mineur : inutile pour les tutoriels centrés sur la chaîne, et cela accélère le démarrage.
-debug=net,validationJournalise les lignes les plus utiles pour une session regtest : réseau et pipeline de validation.
-par=1Validation sur un seul thread. Élimine une catégorie d’instabilités propres aux tests sans affecter l’exactitude des résultats.

Et ensuite

  • Référence JSON-RPCL’index complet des méthodes, organisé par catégorie, avec niveaux de stabilité et exemples curl.
  • API REST du vérificateurQuand vous passez de -validationapi=mock à un vrai processus vérificateur.
  • Schémas FlatBufferIDL FlatBuffer et JSON Schema des payloads ZMQ entre nœud et vérificateur.
  • bcore/test/functional/Les tests font office de spécification.
  • Faucet testnetL’équivalent en ligne : alimentez un wallet sur le testnet partagé quand vous voulez une chaîne réelle plutôt qu’un bac à sable local.