دليل regtest

ثلاثة مسارات للتطوير المحلي، مرتّبة من الأبسط إلى الأعقد. كلّ منها يضع أمامك واجهة JSON-RPC لـ TensorCash تستدعيها بـ bitcoin-cli أو بأيّ عميل JSON-RPC. ‏مجموعة الاختبارات الوظيفية في bcore هي المواصفة المرجعية القابلة للتنفيذ لكلّ ما يلي، وكلّ شرح عملي يربط بالاختبار الذي استُخلص منه.

Core وحده · docker compose · اختبارات وظيفية

أنماط التحقّق

يضيف TensorCash خطوة تحقّق خارجية إلى قبول الكتل. يختار -validationapi الواجهة الخلفية التي تتولّاها، وهو أهمّ قرار في التشغيل المحلي: فهو يحدّد ما إذا كنت تحتاج إلى GPU، أو إلى عملية مُحقِّق، أو إلى لا شيء منهما.

الخيارما هومتى تستخدمه
-validationapi=realالخيار الافتراضي. يتواصل مع مُحقِّق خارجي عبر قناة ZMQ PUSH/PULL بين العقدة والمُحقِّق باستخدام FlatBuffers. إعداد بيئة الإنتاج.يتطلّب عملية مُحقِّق حقيقية. يُستخدَم على الشبكة الرئيسية والشبكة التجريبية وفي أيّ تشغيل regtest يختبر إعادة تشغيل النموذج فعليًا.
-validationapi=mockداخل العملية وحتمي. توفّر الواجهة الخلفية الوهمية ثلاث دوال RPC ‏(validationmockdefault وvalidationmockclear وvalidationmockrequests) لاستجابات Quick وFull وModel مُعدّة مسبقًا؛ ومع خيارات الإقلاع -mockval-default-* يصبح كلّ ناتج تحقّق قابلًا للبرمجة.الخيار الافتراضي لمجموعة الاختبارات الوظيفية. الخيار الصحيح لتشغيل منطق السلسلة دون مُحقِّق أو استدلال حقيقي.
-validationapi=desktopهجين. تعمل فحوص Quick داخل العملية؛ أمّا Full وModel فتُرسَل إلى مُحقِّق HTTPS محلي (الملف التنفيذي الافتراضي لسطح المكتب). لا حاجة إلى وسيط ZMQ.عروض على جهاز واحد تحتاج إلى تمريرة Quick وSmell حقيقية دون تشغيل خدمة مُحقِّق منفصلة.

لإلقاء نظرة أولى على منطق السلسلة، mock هو الخيار الصحيح. وتفترضه بقية هذه الصفحة ما لم يُذكر خلاف ذلك.

المسار A · Core وحده، مع تحقّق وهمي

أقلّ المسارات تعقيدًا. خادم C++ واحد: بلا docker، وبلا GPU، وبلا ملفات نماذج على القرص. يكفي لكلّ الشروح العملية في هذه الصفحة.

1. ابنِ الخادم

اتّبع تعليمات البناء الخاصة بـ Bitcoin Core على services/core-node/bcore/. تُبنى شيفرة TensorCash ضمن هدف CMake نفسه المعتمد في المصدر الأصلي؛ ولا يوجد خيار منفصل.

2. شغّل عقدة regtest

تطابق هذه الخيارات ما يمرّره test_framework/test_tensorcash.py إلى كلّ اختبار وظيفي، فكلّ ما يعمل هناك يعمل هنا أيضًا. الاستجابات الوهمية الافتراضية مثبّتة على الأخضر، لذا يكون قبول الكتل حتميًا.

./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، الذي يقرؤه bitcoin-cli تلقائيًا عند تمرير -datadir. منفذ RPC هو المنفذ الافتراضي لـ regtest في المصدر الأصلي، 18443.

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

المسار B · الحزمة المحلية الكاملة (docker compose)

حين لا يكفي التحقّق الوهمي: عملية مُحقِّق حقيقية، ونموذج حقيقي يقدّم الاستدلال، وواجهة API للمُعدِّن موصولة. يحتوي جذر المستودع على سكربتات تشغيل لأجهزة 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 مع وحدات NVIDIA GPU، يقوم 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 (واجهة REST API لـ core-node) و7067 (ZMQ). ويقدّم المُحقِّق واجهة 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، ومحفظة اتفاقيات إعادة الشراء القائمة على covenant. كلّ منها سيناريو مكتفٍ بذاته تقرؤه من أوّله إلى آخره؛ والشروح العملية أدناه تشير إلى أكثرها تمثيلًا.

شروح عملية

ثلاثة تسلسلات قصيرة على العقدة الوهمية من المسار 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. يُسجَّل النموذج بحجز إيداع في حساب ضمان (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 عالية المستوى في المحفظة، تبني مخرجات الضمان وICU، وترفق TLV تسجيل المُصدِر، ثمّ تذيع المعاملة. بعد تأكيد واحد يمكن الاستعلام عن الأصل بمعرّفه أو برمزه. دورة الحياة الكاملة (السكّ، والتحويل، والحرق) موجودة في الاختبار المرتبط.

يشمل: 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=0يفعّل VDF/SPV منذ كتلة التكوين بدلًا من الارتفاع المرحلي المعتمد على الشبكة الرئيسية.
-vdfspvvdfverifyheight=0يفعّل التحقّق من VDF منذ كتلة التكوين.
-maxtipage=999999يقبل الطوابع الزمنية القديمة، فلا تبدو إعادة التشغيل على سلسلة متقادمة كأنّها عقدة غير متزامنة.
-spv-asn-min=1يخفّض الحدّ الأدنى لتأكيد ASN؛ ودونه، تعطّل regtest منطق تبديل VDF SPV.
-spv-hysteresis-base-bps=0يزيل تخلّف الهامش الأساسي (hysteresis)، فتصبح إعادات التنظيم في الاختبارات فورية وحتمية.
-spv-reorg-sampling-threshold=999يعطّل فعليًا أخذ عيّنات من متون الكتل عند إعادات التنظيم العميقة، وهو أمر يصعب تشغيله عمليًا عند ارتفاعات صغيرة.
-useextapi=0يعطّل واجهة API الخارجية للمُعدِّن: لا حاجة إليها في الشروح المقتصرة على السلسلة، ويختصر وقت الإقلاع.
-debug=net,validationيسجّل أكثر الأسطر فائدةً في جلسة regtest: الشبكات ومسار التحقّق.
-par=1تحقّق بخيط تنفيذ واحد. يزيل فئة من عدم الاستقرار الخاص بالاختبارات دون المساس بالصحّة.

الخطوة التالية

  • مرجع JSON-RPCفهرس الدوال الكامل، مرتّبًا حسب الفئة، مع وسوم الاستقرار وأمثلة curl.
  • واجهة REST API للمُحقِّقحين تنتقل من -validationapi=mock إلى عملية مُحقِّق حقيقية.
  • مخطّطات FlatBufferلغة FlatBuffer IDL وJSON Schema لحمولات ZMQ بين العقدة والمُحقِّق.
  • bcore/test/functional/اقرأ الاختبارات بوصفها المواصفة.
  • صنبور الشبكة التجريبيةالنظير المتّصل بالإنترنت: موّل محفظة على الشبكة التجريبية المشتركة حين تريد سلسلة حيّة بدلًا من بيئة معزولة محلية.