Regtest 가이드

로컬 개발 경로 세 가지를 진입 장벽이 낮은 순서로 정리했습니다. 어느 경로든 bitcoin-cli나 아무 JSON-RPC 클라이언트로 호출할 수 있는 TensorCash JSON-RPC가 준비됩니다. 아래 모든 내용의 기준이 되는 실행 가능한 명세는 bcore 기능 테스트 스위트이며, 각 워크스루는 그 바탕이 된 테스트로 연결됩니다.

Core 단독 · docker compose · 기능 테스트

검증 모드

TensorCash는 블록 수락 과정에 외부 검증 단계를 추가합니다. -validationapi는 이 단계를 처리할 백엔드를 선택하며, 로컬 실행에서 가장 중요한 선택입니다. GPU가 필요한지, 검증자 프로세스가 필요한지, 둘 다 필요 없는지가 이 값으로 정해집니다.

플래그설명사용 시점
-validationapi=real기본값입니다. 노드-검증자 간 ZMQ PUSH/PULL 채널을 통해 FlatBuffers로 외부 검증자와 통신합니다. 프로덕션 설정입니다.실제 검증자 프로세스가 필요합니다. 메인넷, 테스트넷, 그리고 실제 모델 재실행을 검증하는 모든 regtest 실행에서 사용합니다.
-validationapi=mock프로세스 내에서 결정론적으로 동작합니다. 모의 백엔드는 미리 정해 둔 Quick, Full, Model 응답을 위한 RPC 세 개(validationmockdefault, validationmockclear, validationmockrequests)를 제공하며, -mockval-default-* 시작 플래그를 쓰면 모든 검증 결과를 스크립트로 지정할 수 있습니다.기능 테스트 스위트의 기본값입니다. 검증자나 실제 추론 없이 체인 로직을 구동할 때 알맞은 선택입니다.
-validationapi=desktop하이브리드입니다. Quick 검사는 프로세스 내에서 실행되고, Full과 Model은 로컬 HTTPS 검증자(기본 데스크톱 바이너리)로 전송됩니다. ZMQ 브로커가 필요 없습니다.별도의 검증자 서비스를 운영하지 않고 실제 Quick 및 Smell 검사를 거치고 싶은 단일 머신 데모.

체인 로직을 처음 살펴본다면 mock을 쓰면 됩니다. 이 페이지의 나머지 부분은 따로 언급하지 않는 한 모의 모드를 가정합니다.

경로 A · 모의 검증을 사용하는 Core 단독

가장 간단한 방법입니다. C++ 데몬 하나면 되며, docker도 GPU도 디스크의 모델 파일도 필요 없습니다. 이 페이지의 모든 워크스루를 따라 하기에 충분합니다.

1. 데몬 빌드

services/core-node/bcore/에서 Bitcoin Core 빌드 안내를 따르세요. TensorCash 코드는 업스트림과 같은 CMake 타깃으로 빌드되며, 별도 플래그는 없습니다.

2. regtest 노드 시작

이 플래그들은 test_framework/test_tensorcash.py가 모든 기능 테스트에 넘기는 값과 같으므로, 거기서 실행되는 것은 여기서도 실행됩니다. 기본 모의 응답이 green으로 고정되어 있어 블록 수락 결과가 결정론적입니다.

./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. 노드와 통신

인증에는 $HOME/.tensorcash-regtest/regtest/.cookie 쿠키 파일을 사용하며, -datadir을 넘기면 bitcoin-cli가 자동으로 읽습니다. RPC 포트는 업스트림 regtest 기본값인 18443입니다.

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

경로 B · 전체 로컬 스택(docker compose)

모의 검증으로는 부족할 때: 실제 검증자 프로세스, 실제로 추론을 서빙하는 모델, 그리고 연결된 채굴자 API를 사용합니다. 저장소 루트에 Mac용과 CUDA가 있는 Linux용 실행 스크립트가 있습니다.

Apple silicon에서는 실행 스크립트가 llama.cpp 빌드를 받아 전체 core-node + miner-api + verification-api compose 스택을 띄웁니다:

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

NVIDIA GPU가 있는 Linux에서는 launch_linux.sh가 llama.cpp 대신 vLLM 기반 검증자로 같은 작업을 수행합니다:

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

compose 파일은 호스트 포트 8333(P2P), 8050(core-node REST API), 7067(ZMQ)을 바인딩합니다. 검증자는 자체 컨테이너 포트에서 Verifier REST API를 제공합니다.

경로 C · 기능 테스트 스위트 실행

데몬을 빌드하고 나면(경로 A, 1단계) 테스트 러너가 일회용 노드를 대신 띄워 줍니다. 직접 만져 볼 데몬보다, 그대로 가져다 쓸 수 있는 검증된 실행 순서가 필요할 때 유용합니다.

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)

TensorCash 테스트는 인터페이스별로 묶여 있습니다: 모델 라이프사이클, 네이티브 자산, fair-sign 어댑터, 코버넌트 레포 지갑. 각각은 처음부터 끝까지 읽을 수 있는 독립된 시나리오이며, 아래 워크스루는 가장 대표적인 테스트를 가리킵니다.

워크스루

경로 A의 모의 노드를 대상으로 한 짧은 시퀀스 세 가지입니다. 각각은 개요이며, 링크된 기능 테스트가 완전하고 실행 가능한 시나리오입니다.

첫 블록 채굴하기

기준 테스트: wallet_basic.py

Bitcoin Core와 동일합니다. TensorCash 전용 인터페이스를 쓰기 전의 스모크 테스트로, 데몬이 실행 중이고 지갑에 자금이 있는지 확인합니다.

관련 항목: 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)

모델 등록 처음부터 끝까지

기준 테스트: feature_model_registration.py

TensorCash 전용 기능입니다. 모델은 예치금을 에스크로에 넣고, N번의 커밋에 걸쳐 Quick 및 Model 검증 성공을 모은 뒤, 검증 기간이 끝나면 registered 상태로 전환되는 방식으로 등록됩니다. -validationapi=mock을 쓰면 실제 검증자나 GPU 없이 모든 단계를 RPC로 진행할 수 있습니다. 여기서는 개요만 다루며, 전체 시나리오는 링크된 테스트에 있습니다.

관련 항목: 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, ...}

네이티브 자산 발행

기준 테스트: feature_assets_basic_highlevel.py

TensorCash 전용 기능입니다. registerasset은 예치금(bond) 출력과 ICU 출력을 만들고, 발행자 등록 TLV를 첨부해 브로드캐스트하는 상위 수준 지갑 RPC입니다. 한 번 컨펌되면 ID나 티커로 자산을 조회할 수 있습니다. 전체 라이프사이클(민팅, 전송, 소각)은 링크된 테스트에 있습니다.

관련 항목: 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

플래그 레퍼런스

경로 A의 플래그 중 일반 bitcoind -regtest 세션과 다른 것들입니다. 기준 소스: test_framework/test_tensorcash.py, init.cpp.

플래그regtest에서 중요한 이유
-regtestregtest 체인을 선택합니다(블록 보조금, 즉시 성숙 규칙, 로컬 전용 포트 18443/18444).
-vdfspvcommitmentheight=0단계적으로 적용되는 메인넷 높이 대신 제네시스부터 VDF/SPV를 활성화합니다.
-vdfspvvdfverifyheight=0제네시스부터 VDF 검증을 활성화합니다.
-maxtipage=999999오래된 타임스탬프를 허용해, 오래된 체인에서 재시작해도 동기화되지 않은 노드로 보이지 않게 합니다.
-spv-asn-min=1ASN 교차 확인 하한을 낮춥니다. 이 플래그가 없으면 regtest가 VDF SPV 전환 로직을 막습니다.
-spv-hysteresis-base-bps=0기본 마진 히스테리시스를 제거해, 테스트에서 리오그가 즉시 그리고 결정론적으로 일어나게 합니다.
-spv-reorg-sampling-threshold=999딥 리오그 본문 샘플링을 사실상 비활성화합니다. 낮은 블록 높이에서는 이를 구동하기가 현실적으로 어렵기 때문입니다.
-useextapi=0외부 채굴자 API를 비활성화합니다. 체인만 다루는 워크스루에는 필요 없고, 시작 시간도 줄어듭니다.
-debug=net,validationregtest 세션에 가장 유용한 로그(네트워킹과 검증 파이프라인)를 남깁니다.
-par=1단일 스레드 검증입니다. 정확성에 영향을 주지 않으면서, 테스트에서만 생기는 일부 불안정성을 없앱니다.

다음 단계

  • JSON-RPC 레퍼런스카테고리별로 정리된 전체 메서드 목록으로, 안정성 태그와 curl 예제를 함께 제공합니다.
  • Verifier REST API-validationapi=mock에서 실제 검증자 프로세스로 넘어갈 때 참고하세요.
  • FlatBuffer 스키마노드-검증자 간 ZMQ 페이로드를 위한 FlatBuffer IDL과 JSON Schema.
  • bcore/test/functional/테스트를 명세로 읽어 보세요.
  • 테스트넷 파우셋온라인 대안입니다. 로컬 샌드박스 대신 실제 체인이 필요할 때, 공유 테스트넷에서 지갑에 자금을 받으세요.