راهنمایِ regtest

سه مسیر توسعهٔ محلی، به ترتیب میزان دردسر. هر کدام یک JSON-RPC ‏TensorCash در اختیارتان می‌گذارد تا با bitcoin-cli یا هر کلاینت JSON-RPC فراخوانی‌اش کنید. مجموعهٔ تست‌های عملکردی در bcore مشخصات مرجع و اجرایی همهٔ موارد زیر است، و هر راهنما به تستی که از آن برگرفته شده پیوند می‌دهد.

فقط Core · docker compose · تست‌های عملکردی

حالت‌های اعتبارسنجی

TensorCash یک گام اعتبارسنجی خارجی به پذیرش بلاک اضافه می‌کند. ‏-validationapi بک‌اندی را که این گام را انجام می‌دهد انتخاب می‌کند، و مهم‌ترین انتخاب برای یک اجرای محلی است: تعیین می‌کند به GPU نیاز دارید، به یک فرایند تأییدکننده، یا به هیچ‌کدام.

پرچمچیستچه زمانی استفاده شود
-validationapi=realپیش‌فرض. از طریق کانال ZMQ PUSH/PULL نود به تأییدکننده و با FlatBuffers با یک تأییدکنندهٔ خارجی ارتباط می‌گیرد. تنظیم محیط production.به یک فرایند تأییدکنندهٔ واقعی نیاز دارد. در مین‌نت، تست‌نت و هر اجرای regtest که بازپخش واقعی مدل را آزمایش می‌کند استفاده می‌شود.
-validationapi=mockدرون فرایند و قطعی. بک‌اند mock سه RPC در اختیار می‌گذارد (validationmockdefault، validationmockclear، validationmockrequests) برای پاسخ‌های از پیش تعیین‌شدهٔ Quick، Full و Model؛ با پرچم‌های راه‌اندازی -mockval-default-*، نتیجهٔ هر تأیید قابل اسکریپت‌نویسی است.پیش‌فرض مجموعهٔ تست‌های عملکردی. گزینهٔ درست برای به‌کار انداختن منطق زنجیره بدون تأییدکننده یا استنتاج واقعی.
-validationapi=desktopترکیبی. بررسی‌های Quick درون فرایند اجرا می‌شوند؛ Full و Model به یک تأییدکنندهٔ محلی HTTPS (باینری پیش‌فرض دسکتاپ) فرستاده می‌شوند. نیازی به broker ‏ZMQ نیست.نمایش‌های تک‌دستگاهی که یک گذر واقعی Quick و Smell می‌خواهند، بدون اداره کردن یک سرویس تأییدکنندهٔ جداگانه.

برای نگاه اول به منطق زنجیره، mock پاسخ درست است. بقیهٔ این صفحه همین را فرض می‌کند، مگر خلافش گفته شود.

مسیر A · فقط core، با اعتبارسنجی mock

کم‌دردسرترین مسیر. یک daemon ‏C++‎: بدون docker، بدون GPU، بدون فایل مدل روی دیسک. برای همهٔ راهنماهای گام‌به‌گام این صفحه کافی است.

1. ساختن daemon

دستورالعمل‌های ساخت در Bitcoin Core را روی services/core-node/bcore/ دنبال کنید. کد TensorCash زیر همان هدف CMake نسخهٔ بالادستی ساخته می‌شود؛ هیچ پرچم جداگانه‌ای وجود ندارد.

2. راه‌اندازی یک نود regtest

این پرچم‌ها دقیقاً همان چیزی است که test_framework/test_tensorcash.py به هر تست عملکردی می‌دهد، پس هر چه آن‌جا اجرا شود این‌جا هم اجرا می‌شود. پاسخ‌های پیش‌فرض 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 بالادستی، یعنی 18443، است.

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

مسیر B · استک کامل محلی (docker compose)

برای وقتی که mock کافی نیست: یک فرایند تأییدکنندهٔ واقعی، یک مدل واقعی که استنتاج ارائه می‌دهد، و API ماینر که به آن‌ها وصل است. ریشهٔ مخزن اسکریپت‌های راه‌اندازی برای Mac و برای Linux با CUDA دارد.

روی Apple silicon، اسکریپت راه‌انداز یک build از 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 (API REST core-node) و 7067 (ZMQ) را bind می‌کند. تأییدکننده API REST تأییدکننده خود را روی پورت کانتینر خودش ارائه می‌دهد.

مسیر C · اجرای مجموعهٔ تست‌های عملکردی

وقتی 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 بر اساس سطح دسترسی دسته‌بندی شده‌اند: چرخهٔ عمر مدل، دارایی‌های بومی، adaptorهای fair-sign و کیف پول repo مبتنی بر covenant. هر کدام سناریویی مستقل است که می‌توانید از اول تا آخر بخوانید؛ راهنماهای زیر به نماینده‌ترین آن‌ها اشاره می‌کنند.

راهنماهای گام‌به‌گام

سه توالی کوتاه روی نود mock از مسیر A. هر کدام یک طرح اولیه است؛ تست عملکردی پیوندشده سناریوی کامل و قابل اجرا است.

نخستین بلاک خود را ماین کنید

تست مرجع: wallet_basic.py

بدون تغییر نسبت به Bitcoin Core. یک تست اولیه پیش از هر سطح ویژهٔ 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 کامیت جمع‌آوری می‌شوند، و پس از بسته شدن پنجرهٔ تأیید، مدل به وضعیت 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 سطح‌بالای کیف پول است که خروجی‌های bond و ICU را می‌سازد، TLV ثبت ناشر را پیوست می‌کند و تراکنش را پخش می‌کند. پس از یک تأیید، دارایی را می‌توان با شناسه یا ticker جست‌وجو کرد. چرخهٔ عمر کامل (mint، انتقال، burn) در تست پیوندشده آمده است.

بخش‌های درگیر: 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
-regtestزنجیرهٔ regtest را انتخاب می‌کند (یارانهٔ بلاک، قواعد بلوغ فوری و پورت‌های فقط محلی 18443/18444).
-vdfspvcommitmentheight=0VDF/SPV را از بلاک genesis فعال می‌کند، به‌جای ارتفاع مرحله‌بندی‌شدهٔ مین‌نت.
-vdfspvvdfverifyheight=0تأیید VDF را از بلاک genesis فعال می‌کند.
-maxtipage=999999timestampهای قدیمی را می‌پذیرد تا راه‌اندازی دوباره روی یک زنجیرهٔ کهنه مثل یک نود همگام‌نشده به نظر نرسد.
-spv-asn-min=1کف تأیید متقابل ASN را پایین می‌آورد؛ بدون آن، regtest منطق سوئیچ VDF SPV را مسدود می‌کند.
-spv-hysteresis-base-bps=0هیسترزیس حاشیهٔ پایه را حذف می‌کند تا reorgها در تست‌ها فوری و قطعی باشند.
-spv-reorg-sampling-threshold=999نمونه‌برداری از بدنهٔ بلاک در reorgهای عمیق را عملاً غیرفعال می‌کند، چون در ارتفاع‌های کم به‌کار انداختن آن عملی نیست.
-useextapi=0API خارجی ماینر را غیرفعال می‌کند: برای راهنماهایی که فقط با زنجیره کار دارند لازم نیست، و راه‌اندازی را کوتاه‌تر می‌کند.
-debug=net,validationمفیدترین خطوط لاگ را برای یک جلسهٔ regtest ثبت می‌کند: شبکه و خط لولهٔ اعتبارسنجی.
-par=1اعتبارسنجی تک‌نخی. دسته‌ای از ناپایداری‌های مخصوص تست را بدون اثر بر درستی حذف می‌کند.

قدم بعدی

  • مرجعِ JSON-RPCفهرست کامل متدها، دسته‌بندی‌شده در bucketها، با برچسب‌های پایداری و نمونه‌های curl.
  • API REST تأییدکنندهوقتی از -validationapi=mock به یک فرایند تأییدکنندهٔ واقعی می‌روید.
  • طرح‌واره‌های FlatBufferIDL ‏FlatBuffer و JSON Schema برای payloadهای ZMQ نود به تأییدکننده.
  • bcore/test/functional/تست‌ها را به‌عنوان مشخصات بخوانید.
  • فاست تست‌نتهمتای آنلاین: وقتی به‌جای یک محیط آزمایشی محلی یک زنجیرهٔ زنده می‌خواهید، کیف پولی را روی تست‌نت مشترک شارژ کنید.