คู่มือ regtest

เส้นทางพัฒนาในเครื่องสามแบบ เรียงจากยุ่งยากน้อยไปมาก ทุกแบบให้ JSON-RPC ของ TensorCash ที่คุณเรียกได้ด้วย bitcoin-cli หรือไคลเอนต์ JSON-RPC ใดก็ได้ ชุด functional test ของ bcore คือสเปกหลักที่รันได้จริงของทุกอย่างด้านล่าง และทุก walkthrough ลิงก์ไปยังเทสต์ที่เป็นต้นแบบ

Core อย่างเดียว · docker compose · functional test

โหมดการตรวจสอบ

TensorCash เพิ่มขั้นตอนการตรวจสอบจากภายนอกเข้าไปในการยอมรับบล็อก -validationapi ใช้เลือก backend ที่ให้บริการขั้นตอนนี้ และเป็นตัวเลือกที่สำคัญที่สุดสำหรับการรันในเครื่อง เพราะเป็นตัวกำหนดว่าคุณต้องใช้ GPU, process ผู้ตรวจสอบ หรือไม่ต้องใช้ทั้งสองอย่าง

แฟล็กคืออะไรควรใช้เมื่อใด
-validationapi=realค่าเริ่มต้น สื่อสารกับผู้ตรวจสอบภายนอกผ่านช่องทาง ZMQ PUSH/PULL ระหว่างโหนดกับผู้ตรวจสอบโดยใช้ FlatBuffers เป็นการตั้งค่าสำหรับ productionต้องมี process ผู้ตรวจสอบจริง ใช้บน mainnet, testnet และการรัน regtest ใด ๆ ที่ทดสอบการ replay โมเดลจริง
-validationapi=mockทำงานภายใน process และให้ผลแน่นอน backend แบบ mock เปิด RPC สามตัว (validationmockdefault, validationmockclear, validationmockrequests) สำหรับ response สำเร็จรูปของ Quick, Full และ Model เมื่อใช้ร่วมกับ flag ตอนเริ่มต้น -mockval-default-* ผลการตรวจสอบทุกแบบจะกำหนดด้วยสคริปต์ได้ค่าเริ่มต้นของชุด functional test เป็นตัวเลือกที่เหมาะสำหรับขับเคลื่อนตรรกะของเชนโดยไม่ต้องมีผู้ตรวจสอบหรือการอนุมานจริง
-validationapi=desktopแบบผสม การตรวจ Quick รันภายใน process ส่วน Full และ Model ถูกส่งไปยังผู้ตรวจสอบ HTTPS ในเครื่อง (ไบนารีเดสก์ท็อปตามค่าเริ่มต้น) ไม่ต้องใช้ ZMQ brokerเดโมบนเครื่องเดียวที่ต้องการให้มีการตรวจ Quick และ Smell จริง โดยไม่ต้องดูแลบริการผู้ตรวจสอบแยกต่างหาก

หากต้องการดูตรรกะของเชนเป็นครั้งแรก mock คือคำตอบที่ถูกต้อง เนื้อหาที่เหลือในหน้านี้ถือว่าใช้โหมดนี้ เว้นแต่จะระบุไว้เป็นอย่างอื่น

เส้นทาง A · Core อย่างเดียว พร้อม mock validation

ยุ่งยากน้อยที่สุด daemon C++ ตัวเดียว ไม่ต้องใช้ docker ไม่ต้องใช้ GPU ไม่ต้องมีไฟล์โมเดลบนดิสก์ เพียงพอสำหรับทุก walkthrough ในหน้านี้

1. บิลด์ daemon

ทำตาม คำแนะนำการบิลด์ ของ Bitcoin Core กับ services/core-node/bcore/ โค้ด TensorCash บิลด์ภายใต้ CMake target เดียวกับ upstream ไม่มี flag แยกต่างหาก

2. เริ่มโหนด regtest

flag เหล่านี้ตรงกับที่ test_framework/test_tensorcash.py ส่งให้ functional test ทุกตัว ดังนั้นอะไรที่รันที่นั่นได้ก็รันที่นี่ได้ response ของ mock ตามค่าเริ่มต้นถูกตรึงไว้ที่ 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. สื่อสารกับโหนด

การยืนยันตัวตนใช้ไฟล์ cookie ที่ $HOME/.tensorcash-regtest/regtest/.cookie ซึ่ง bitcoin-cli อ่านให้อัตโนมัติเมื่อคุณส่ง -datadir พอร์ต RPC เป็นค่าเริ่มต้นของ regtest ใน upstream คือ 18443

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

เส้นทาง B · สแต็กในเครื่องเต็มรูปแบบ (docker compose)

สำหรับกรณีที่ mock ไม่พอ: มี process ผู้ตรวจสอบจริง โมเดลจริงที่ให้บริการการอนุมาน และ miner API ที่ต่อเข้าด้วยกัน ที่ root ของ repository มีสคริปต์เปิดใช้งานสำหรับ Mac และ Linux ที่มี CUDA

บน Apple silicon ตัวเปิดใช้งานจะดึงบิลด์ llama.cpp มาแล้วเปิดสแต็ก compose 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

บน Linux ที่มี GPU ของ NVIDIA launch_linux.sh ทำแบบเดียวกัน แต่ใช้ผู้ตรวจสอบที่ใช้ vLLM แทน 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

ไฟล์ compose ผูกพอร์ตของโฮสต์ 8333 (P2P), 8050 (core-node REST API) และ 7067 (ZMQ) ผู้ตรวจสอบให้บริการ Verifier REST API บนพอร์ตคอนเทนเนอร์ของตัวเอง

เส้นทาง C · รันชุด functional test

เมื่อบิลด์ daemon แล้ว (เส้นทาง A ขั้นตอนที่ 1) ตัวรันเทสต์จะเริ่มโหนดแบบใช้แล้วทิ้งให้คุณ เหมาะเมื่อคุณต้องการลำดับขั้นที่รู้ว่าทำงานถูกต้องไว้คัดลอก มากกว่า daemon ไว้ลองเล่น

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 adaptor และวอลเล็ต covenant repo แต่ละตัวเป็นสถานการณ์ที่สมบูรณ์ในตัวซึ่งอ่านได้ตั้งแต่ต้นจนจบ walkthrough ด้านล่างชี้ไปยังตัวที่เป็นตัวแทนได้ดีที่สุด

Walkthrough

ลำดับขั้นสั้น ๆ สามชุดที่รันกับโหนด mock จากเส้นทาง A แต่ละชุดเป็นเพียงภาพร่าง functional test ที่ลิงก์ไว้คือสถานการณ์เต็มรูปแบบที่รันได้จริง

ขุดบล็อกแรกของคุณ

เทสต์หลัก: wallet_basic.py

เหมือนกับ Bitcoin Core ทุกประการ เป็น smoke test ก่อนเข้าสู่ส่วนที่เฉพาะของ TensorCash เพื่อยืนยันว่า daemon ทำงานอยู่และวอลเล็ตมีเงินแล้ว

เกี่ยวข้องกับ: 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 การลงทะเบียนโมเดลทำโดยวางเงินมัดจำไว้ใน escrow สะสมผลการตรวจสอบ Quick และ Model ที่สำเร็จตลอด N commit แล้วเปลี่ยนเป็น registered เมื่อหน้าต่างการตรวจสอบปิดลง เมื่อใช้ -validationapi=mock คุณขับเคลื่อนทุกขั้นตอนผ่าน RPC ได้โดยไม่ต้องมีผู้ตรวจสอบจริงหรือ GPU นี่เป็นเพียงโครงร่าง เทสต์ที่ลิงก์ไว้คือสถานการณ์เต็มรูปแบบ

เกี่ยวข้องกับ: 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 คือ RPC ระดับสูงของวอลเล็ตที่สร้าง output ของ bond และ ICU แนบ TLV การลงทะเบียนผู้ออกสินทรัพย์ แล้ว broadcast หลังได้รับหนึ่ง confirmation จะ query สินทรัพย์ได้ด้วย id หรือ ticker วงจรชีวิตเต็มรูปแบบ (mint, transfer, burn) อยู่ใน test ที่ลิงก์ไว้

เกี่ยวข้องกับ: 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

flag จากเส้นทาง A ที่ต่างจากเซสชัน bitcoind -regtest ธรรมดา แหล่งอ้างอิงหลัก: test_framework/test_tensorcash.py และ init.cpp

แฟล็กความสำคัญใน regtest
-regtestเลือกเชน regtest (block subsidy, กฎ maturity ทันที และพอร์ตเฉพาะในเครื่อง 18443/18444)
-vdfspvcommitmentheight=0เปิดใช้ VDF/SPV ตั้งแต่ genesis แทนความสูงที่กำหนดเป็นขั้นบน mainnet
-vdfspvvdfverifyheight=0เปิดใช้การตรวจสอบ VDF ตั้งแต่ genesis
-maxtipage=999999ยอมรับ timestamp เก่า เพื่อให้การรีสตาร์ตบนเชนที่ค้างอยู่ไม่ดูเหมือนโหนดที่ยังไม่ซิงก์
-spv-asn-min=1ลดเกณฑ์ขั้นต่ำของการยืนยันซ้ำด้วย ASN หากไม่ใส่ regtest จะบล็อกตรรกะการสลับ VDF SPV
-spv-hysteresis-base-bps=0ตัด hysteresis ของ base margin ออก ทำให้ reorg ในเทสต์เกิดขึ้นทันทีและให้ผลแน่นอน
-spv-reorg-sampling-threshold=999แทบจะปิดการสุ่มตรวจ body ของ deep reorg ซึ่งทดสอบได้ยากเมื่อความสูงของเชนยังน้อย
-useextapi=0ปิด miner API ภายนอก ซึ่งไม่จำเป็นสำหรับ walkthrough ที่ใช้แค่เชน และช่วยให้เริ่มต้นเร็วขึ้น
-debug=net,validationบันทึก log บรรทัดที่มีประโยชน์ที่สุดสำหรับเซสชัน regtest คือ networking และ validation pipeline
-par=1validation แบบเธรดเดียว ขจัดความไม่เสถียรประเภทที่เกิดเฉพาะในเทสต์ โดยไม่กระทบความถูกต้อง

ไปต่อที่ไหนดี

  • เอกสารอ้างอิง JSON-RPCดัชนี method ทั้งหมด จัดตาม bucket พร้อมแท็กระดับความเสถียรและตัวอย่าง curl
  • Verifier REST APIเมื่อคุณเปลี่ยนจาก -validationapi=mock ไปใช้ process ผู้ตรวจสอบจริง
  • สคีมา FlatBufferFlatBuffer IDL และ JSON Schema สำหรับ payload ZMQ ระหว่างโหนดกับผู้ตรวจสอบ
  • bcore/test/functional/อ่านเทสต์ในฐานะสเปก
  • Faucet ของ testnetทางเลือกแบบออนไลน์: เติมเงินเข้าวอลเล็ตบน testnet ที่ใช้ร่วมกัน เมื่อคุณต้องการเชนจริงแทน sandbox ในเครื่อง