Regtest guide

Three local development paths, ordered by friction. Each one puts a TensorCash JSON-RPC in front of you to call with bitcoin-cli or any JSON-RPC client. The bcore functional test suite is the canonical, executable spec for everything below, and every walkthrough links the test it was distilled from.

Core only · docker compose · functional tests

Validation modes

TensorCash adds an external validation step to block acceptance. -validationapi selects the backend that serves it, and it is the most important choice for a local run: it decides whether you need a GPU, a verifier process, or neither.

FlagWhat it isWhen to use it
-validationapi=realThe default. Talks to an external verifier over the node-to-verifier ZMQ PUSH/PULL channel using FlatBuffers. The production setting.Needs a real verifier process. Used on mainnet, testnet, and any regtest run that exercises real model replay.
-validationapi=mockIn-process and deterministic. The mock backend exposes three RPCs (validationmockdefault, validationmockclear, validationmockrequests) for canned Quick, Full and Model responses; with the -mockval-default-* startup flags, every verification outcome is scriptable.The default for the functional test suite. The right choice for driving the chain logic without a verifier or real inference.
-validationapi=desktopHybrid. Quick checks run in-process; Full and Model are sent to a local HTTPS verifier (the default desktop binary). No ZMQ broker needed.Single-machine demos that want a real Quick and Smell pass without operating a separate verifier service.

For a first look at the chain logic, mock is the right answer. The rest of this page assumes it unless stated.

Path A · core only, with mock validation

The lowest friction. One C++ daemon: no docker, no GPU, no model files on disk. Enough for every walkthrough on this page.

1. Build the daemon

Follow the Bitcoin Core build instructions against services/core-node/bcore/. The TensorCash code builds under the same CMake target as upstream; there is no separate flag.

2. Start a regtest node

These flags mirror what test_framework/test_tensorcash.py passes to every functional test, so anything that runs there runs here too. The default mock responses are pinned to green, so block acceptance is deterministic.

./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. Talk to it

Authentication uses the cookie file at $HOME/.tensorcash-regtest/regtest/.cookie, which bitcoin-cli reads automatically when you pass -datadir. The RPC port is the upstream regtest default, 18443.

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

Path B · the full local stack (docker compose)

For when mock is not enough: a real verifier process, a real model serving inference, and the miner API wired in. The repository root has launch scripts for Macs and for Linux with CUDA.

On Apple silicon the launcher pulls a llama.cpp build and brings up the full core-node + miner-api + verification-api compose stack:

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

On Linux with NVIDIA GPUs, launch_linux.sh does the same with the vLLM-based verifier instead of 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

The compose file binds host ports 8333 (P2P), 8050 (the core-node REST API) and 7067 (ZMQ). The verifier serves its Verifier REST API on its own container port.

Path C · run the functional test suite

Once the daemon is built (Path A, step 1), the test runner starts throwaway nodes for you. Useful when you want a known-good sequence to copy from rather than a daemon to poke at.

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)

The TensorCash tests group by surface: model lifecycle, native assets, fair-sign adaptors and the covenant repo wallet. Each is a self-contained scenario you can read top to bottom; the walkthroughs below point at the most representative ones.

Walkthroughs

Three short sequences against the mock node from Path A. Each one is a sketch; the linked functional test is the full, executable scenario.

Mine your first block

Canonical test: wallet_basic.py

Unchanged from Bitcoin Core. A smoke test before any TensorCash-specific surface: it confirms the daemon is up and the wallet is funded.

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

Register a model end to end

Canonical test: feature_model_registration.py

TensorCash-specific. A model is registered by escrowing a deposit, collecting successful Quick and Model verifications across N commits, then moving to registered once the verification window closes. With -validationapi=mock you can drive every step from RPCs, without a real verifier or GPU. This is an outline; the linked test is the full scenario.

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

Issue a native asset

Canonical test: feature_assets_basic_highlevel.py

TensorCash-specific. registerasset is the high-level wallet RPC that builds the bond and ICU outputs, attaches the issuer registration TLV and broadcasts. After one confirmation the asset can be queried by id or ticker. The full lifecycle (mint, transfer, burn) is in the linked test.

Touches: 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 reference

The flags from Path A that differ from a plain bitcoind -regtest session. Source of truth: test_framework/test_tensorcash.py and init.cpp.

FlagWhy it matters in regtest
-regtestSelects the regtest chain (block subsidy, immediate maturity rules and the local-only ports 18443/18444).
-vdfspvcommitmentheight=0Activates VDF/SPV from genesis instead of the staged mainnet height.
-vdfspvvdfverifyheight=0Activates VDF verification from genesis.
-maxtipage=999999Accepts old timestamps, so restarting on a stale chain does not look like an unsynced node.
-spv-asn-min=1Lowers the ASN corroboration floor; without it, regtest blocks the VDF SPV switching logic.
-spv-hysteresis-base-bps=0Removes the base-margin hysteresis, so reorgs in tests are immediate and deterministic.
-spv-reorg-sampling-threshold=999Effectively disables deep-reorg body sampling, which is impractical to drive at small heights.
-useextapi=0Disables the external miner API: not needed for chain-only walkthroughs, and it shortens startup.
-debug=net,validationLogs the most useful lines for a regtest session: networking and the validation pipeline.
-par=1Single-threaded validation. Removes a class of test-only flakiness without affecting correctness.

Where next

  • JSON-RPC referenceThe full method index, organised by bucket, with stability tags and curl examples.
  • Verifier REST APIWhen you move from -validationapi=mock to a real verifier process.
  • FlatBuffer schemasFlatBuffer IDL and JSON Schema for the node-to-verifier ZMQ payloads.
  • bcore/test/functional/Read the tests as the spec.
  • Testnet faucetThe online counterpart: fund a wallet on the shared testnet when you want a live chain instead of a local sandbox.