Guia de regtest

Três caminhos de desenvolvimento local, do mais simples ao mais trabalhoso. Cada um coloca à sua disposição um JSON-RPC da TensorCash para chamar com o bitcoin-cli ou qualquer cliente JSON-RPC. A suíte de testes funcionais do bcore é a especificação canônica e executável de tudo o que vem abaixo, e cada passo a passo indica o teste do qual foi extraído.

Só o Core · docker compose · testes funcionais

Modos de validação

A TensorCash adiciona uma etapa de validação externa à aceitação de blocos. -validationapi seleciona o backend que a executa, e é a escolha mais importante para uma execução local: define se você precisa de uma GPU, de um processo verificador ou de nenhum dos dois.

FlagO que éQuando usar
-validationapi=realO padrão. Comunica-se com um verificador externo pelo canal ZMQ PUSH/PULL entre nó e verificador, usando FlatBuffers. A configuração de produção.Exige um processo verificador real. Usado na mainnet, na testnet e em qualquer execução regtest que exercite o replay real de modelos.
-validationapi=mockNo próprio processo e determinístico. O backend simulado expõe três RPCs (validationmockdefault, validationmockclear, validationmockrequests) para respostas Quick, Full e Model predefinidas; com as flags de inicialização -mockval-default-*, todo resultado de verificação pode ser programado.O padrão da suíte de testes funcionais. A escolha certa para exercitar a lógica da cadeia sem verificador nem inferência real.
-validationapi=desktopHíbrido. As verificações Quick rodam no próprio processo; Full e Model são enviadas a um verificador HTTPS local (o binário desktop padrão). Não precisa de broker ZMQ.Demonstrações em uma única máquina que querem uma passada real de Quick e Smell sem operar um serviço verificador separado.

Para um primeiro contato com a lógica da cadeia, mock é a resposta certa. O restante desta página parte desse modo, salvo indicação em contrário.

Caminho A · só o core, com validação simulada

O caminho mais simples. Um único daemon em C++: sem docker, sem GPU, sem arquivos de modelo no disco. Suficiente para todos os passo a passo desta página.

1. Compile o daemon

Siga as instruções de compilação do Bitcoin Core em services/core-node/bcore/. O código da TensorCash compila no mesmo alvo CMake do upstream; não há flag separada.

2. Inicie um nó regtest

Essas flags reproduzem o que test_framework/test_tensorcash.py passa para cada teste funcional, então tudo o que roda lá roda aqui também. As respostas simuladas padrão estão fixadas em verde, então a aceitação de blocos é determinística.

./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. Converse com o nó

A autenticação usa o arquivo de cookie em $HOME/.tensorcash-regtest/regtest/.cookie, que o bitcoin-cli lê automaticamente quando você passa -datadir. A porta RPC é a padrão do regtest upstream, 18443.

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

Caminho B · o stack local completo (docker compose)

Para quando a simulação não basta: um processo verificador real, um modelo real servindo inferência e a API do minerador integrada. A raiz do repositório tem scripts de inicialização para Mac e para Linux com CUDA.

No Apple Silicon, o inicializador baixa uma build do llama.cpp e sobe o 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

No Linux com GPUs NVIDIA, launch_linux.sh faz o mesmo com o verificador baseado em vLLM em vez do 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

O arquivo compose vincula as portas do host 8333 (P2P), 8050 (a API REST do core-node) e 7067 (ZMQ). O verificador serve a sua API REST do Verificador em uma porta própria do contêiner.

Caminho C · rode a suíte de testes funcionais

Depois que o daemon estiver compilado (Caminho A, passo 1), o executor de testes sobe nós descartáveis para você. Útil quando você quer uma sequência que sabidamente funciona para copiar, e não um daemon para explorar.

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)

Os testes da TensorCash são agrupados por interface: ciclo de vida de modelos, ativos nativos, adaptadores fair-sign e a carteira de repo com covenant. Cada um é um cenário autocontido que pode ser lido do início ao fim; os passo a passo abaixo apontam para os mais representativos.

Passo a passo

Três sequências curtas contra o nó simulado do Caminho A. Cada uma é um esboço; o teste funcional indicado é o cenário completo e executável.

Minere seu primeiro bloco

Teste canônico: wallet_basic.py

Igual ao Bitcoin Core. Um smoke test antes de qualquer interface específica da TensorCash: confirma que o daemon está no ar e que a carteira tem saldo.

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

Registre um modelo de ponta a ponta

Teste canônico: feature_model_registration.py

Específico da TensorCash. Um modelo é registrado depositando uma caução em escrow, acumulando verificações Quick e Model bem-sucedidas ao longo de N commits e passando para registered quando a janela de verificação se fecha. Com -validationapi=mock, você conduz cada etapa por RPCs, sem verificador real nem GPU. Este é um resumo; o teste indicado traz o cenário completo.

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

Emita um ativo nativo

Teste canônico: feature_assets_basic_highlevel.py

Específico da TensorCash. registerasset é a RPC de carteira de alto nível que monta as saídas de caução e ICU, anexa o TLV de registro do emissor e transmite a transação. Após uma confirmação, o ativo pode ser consultado por id ou ticker. O ciclo de vida completo (mint, transferência, burn) está no teste indicado.

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

Referência de flags

As flags do Caminho A que diferem de uma sessão simples de bitcoind -regtest. Fonte da verdade: test_framework/test_tensorcash.py e init.cpp.

FlagPor que importa no regtest
-regtestSeleciona a cadeia regtest (subsídio de bloco, regras de maturidade imediata e as portas apenas locais 18443/18444).
-vdfspvcommitmentheight=0Ativa VDF/SPV desde o bloco gênese, em vez da altura escalonada da mainnet.
-vdfspvvdfverifyheight=0Ativa a verificação de VDF desde o bloco gênese.
-maxtipage=999999Aceita timestamps antigos, para que reiniciar sobre uma cadeia desatualizada não pareça um nó fora de sincronia.
-spv-asn-min=1Reduz o mínimo de corroboração por ASN; sem ela, o regtest bloqueia a lógica de troca VDF/SPV.
-spv-hysteresis-base-bps=0Remove a histerese da margem base, para que os reorgs nos testes sejam imediatos e determinísticos.
-spv-reorg-sampling-threshold=999Na prática, desativa a amostragem de corpos em reorgs profundos, inviável de acionar em alturas pequenas.
-useextapi=0Desativa a API externa do minerador: não é necessária nos passo a passo que usam só a cadeia, e encurta a inicialização.
-debug=net,validationRegistra as linhas mais úteis para uma sessão de regtest: rede e pipeline de validação.
-par=1Validação em uma única thread. Elimina uma classe de instabilidade exclusiva de testes sem afetar a correção.

Próximos passos

  • Referência JSON-RPCO índice completo de métodos, organizado por grupo, com tags de estabilidade e exemplos em curl.
  • API REST do VerificadorQuando você passar de -validationapi=mock para um processo verificador real.
  • Schemas FlatBufferIDL FlatBuffer e JSON Schema para os payloads ZMQ entre nó e verificador.
  • bcore/test/functional/Leia os testes como especificação.
  • Faucet da testnetA contrapartida online: abasteça uma carteira na testnet compartilhada quando quiser uma cadeia ativa em vez de um sandbox local.