Guía de regtest

Tres rutas de desarrollo local, ordenadas de menor a mayor complejidad. Cada una te deja un JSON-RPC de TensorCash al que llamar con bitcoin-cli o cualquier cliente JSON-RPC. La suite de tests funcionales de bcore es la especificación canónica y ejecutable de todo lo que sigue, y cada recorrido enlaza el test del que se extrajo.

Solo Core · docker compose · tests funcionales

Modos de validación

TensorCash añade un paso de validación externa a la aceptación de bloques. -validationapi selecciona el backend que lo sirve, y es la decisión más importante en una ejecución local: determina si necesitas una GPU, un proceso verificador o ninguna de las dos cosas.

OpciónQué esCuándo usarlo
-validationapi=realEl predeterminado. Se comunica con un verificador externo por el canal ZMQ PUSH/PULL entre nodo y verificador, usando FlatBuffers. La configuración de producción.Necesita un proceso verificador real. Se usa en mainnet, en testnet y en cualquier ejecución de regtest que reproduzca modelos reales.
-validationapi=mockDentro del proceso y determinista. El backend simulado expone tres RPCs (validationmockdefault, validationmockclear, validationmockrequests) para respuestas Quick, Full y Model predefinidas; con los flags de arranque -mockval-default-*, cada resultado de verificación se puede programar.El predeterminado de la suite de tests funcionales. La opción adecuada para ejercitar la lógica de la cadena sin verificador ni inferencia real.
-validationapi=desktopHíbrido. Las comprobaciones Quick se ejecutan dentro del proceso; Full y Model se envían a un verificador HTTPS local (el binario de escritorio predeterminado). No necesita broker ZMQ.Demos en una sola máquina que quieren una pasada real de Quick y Smell sin operar un servicio verificador aparte.

Para un primer vistazo a la lógica de la cadena, mock es la respuesta correcta. El resto de esta página lo da por supuesto salvo que se indique lo contrario.

Ruta A · solo Core, con validación simulada

La opción más sencilla. Un único daemon en C++: sin docker, sin GPU y sin archivos de modelo en disco. Suficiente para todos los recorridos de esta página.

1. Compila el daemon

Sigue las instrucciones de compilación de Bitcoin Core sobre services/core-node/bcore/. El código de TensorCash se compila con el mismo target de CMake que upstream; no hay ningún flag aparte.

2. Arranca un nodo regtest

Estos flags replican lo que test_framework/test_tensorcash.py pasa a cada test funcional, así que todo lo que funciona allí funciona también aquí. Las respuestas simuladas por defecto están fijadas en verde, de modo que la aceptación de bloques es determinista.

./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. Comunícate con él

La autenticación usa el archivo de cookie en $HOME/.tensorcash-regtest/regtest/.cookie, que bitcoin-cli lee automáticamente cuando pasas -datadir. El puerto RPC es el predeterminado de regtest en upstream, 18443.

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

Ruta B · el stack local completo (docker compose)

Para cuando la simulación no basta: un proceso verificador real, un modelo real sirviendo inferencia y la API del minero conectada. La raíz del repositorio incluye scripts de arranque para Mac y para Linux con CUDA.

En Apple silicon, el lanzador descarga una compilación de llama.cpp y levanta el stack de 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

En Linux con GPUs de NVIDIA, launch_linux.sh hace lo mismo con el verificador basado en vLLM en lugar 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

El archivo de compose expone en el host los puertos 8333 (P2P), 8050 (la API REST del core-node) y 7067 (ZMQ). El verificador sirve su API REST del verificador en su propio puerto de contenedor.

Ruta C · ejecuta la suite de tests funcionales

Una vez compilado el daemon (Ruta A, paso 1), el ejecutor de tests arranca nodos desechables por ti. Útil cuando quieres una secuencia que funciona para copiarla, más que un daemon con el que trastear.

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)

Los tests de TensorCash se agrupan por área: ciclo de vida de modelos, activos nativos, adaptadores fair-sign y la wallet de repos con covenants. Cada uno es un escenario autónomo que puedes leer de principio a fin; los recorridos de abajo apuntan a los más representativos.

Recorridos guiados

Tres secuencias cortas contra el nodo simulado de la Ruta A. Cada una es un esbozo; el test funcional enlazado es el escenario completo y ejecutable.

Mina tu primer bloque

Test canónico: wallet_basic.py

Igual que en Bitcoin Core. Una prueba básica antes de cualquier interfaz específica de TensorCash: confirma que el daemon está en marcha y que la wallet tiene fondos.

Usa: 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 modelo de principio a fin

Test canónico: feature_model_registration.py

Específico de TensorCash. Un modelo se registra depositando una garantía en custodia, reuniendo verificaciones Quick y Model correctas a lo largo de N commits y pasando a registered cuando se cierra la ventana de verificación. Con -validationapi=mock puedes ejecutar cada paso desde RPCs, sin verificador real ni GPU. Esto es un esquema; el test enlazado contiene el escenario completo.

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

Emite un activo nativo

Test canónico: feature_assets_basic_highlevel.py

Específico de TensorCash. registerasset es el RPC de alto nivel de la wallet que construye las salidas de fianza e ICU, adjunta el TLV de registro del emisor y difunde la transacción. Tras una confirmación, el activo se puede consultar por id o por ticker. El ciclo de vida completo (emisión, transferencia, quema) está en el test enlazado.

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

Referencia de flags

Los flags de la Ruta A que difieren de una sesión normal de bitcoind -regtest. Fuente de referencia: test_framework/test_tensorcash.py e init.cpp.

OpciónPor qué importa en regtest
-regtestSelecciona la cadena regtest (subsidio de bloque, reglas de maduración inmediata y los puertos solo locales 18443/18444).
-vdfspvcommitmentheight=0Activa VDF/SPV desde el bloque génesis en lugar de la altura escalonada de mainnet.
-vdfspvvdfverifyheight=0Activa la verificación VDF desde el bloque génesis.
-maxtipage=999999Acepta marcas de tiempo antiguas, para que reiniciar sobre una cadena desactualizada no parezca un nodo sin sincronizar.
-spv-asn-min=1Reduce el umbral mínimo de corroboración por ASN; sin él, regtest bloquea la lógica de conmutación VDF/SPV.
-spv-hysteresis-base-bps=0Elimina la histéresis del margen base, para que las reorganizaciones en los tests sean inmediatas y deterministas.
-spv-reorg-sampling-threshold=999En la práctica desactiva el muestreo de cuerpos en reorganizaciones profundas, que es poco práctico de provocar a alturas pequeñas.
-useextapi=0Desactiva la API externa del minero: no hace falta para recorridos solo de cadena y acorta el arranque.
-debug=net,validationRegistra las líneas más útiles para una sesión de regtest: red y pipeline de validación.
-par=1Validación en un solo hilo. Elimina un tipo de inestabilidad propia de los tests sin afectar a la corrección.

Siguientes pasos

  • Referencia JSON-RPCEl índice completo de métodos, organizado por categorías, con etiquetas de estabilidad y ejemplos de curl.
  • API REST del verificadorCuando pases de -validationapi=mock a un proceso verificador real.
  • Esquemas FlatBufferIDL de FlatBuffers y JSON Schema para los payloads ZMQ entre el nodo y el verificador.
  • bcore/test/functional/Lee los tests como la especificación.
  • Faucet de testnetLa alternativa en línea: financia una wallet en la testnet compartida cuando quieras una cadena real en lugar de un entorno local.