מדריך regtest

שלושה מסלולי פיתוח מקומיים, מסודרים לפי רמת החיכוך. כל אחד מעמיד לרשותכם JSON-RPC של TensorCash שאפשר לקרוא לו עם bitcoin-cli או כל לקוח JSON-RPC. חבילת הבדיקות הפונקציונליות של bcore היא המפרט הקנוני, שאפשר גם להריץ, של כל מה שלמטה, וכל מדריך מקשר לבדיקה שממנה הוא נגזר.

Core בלבד · docker compose · בדיקות פונקציונליות

מצבי אימות

TensorCash מוסיף שלב אימות חיצוני לקבלת בלוקים. ‏-validationapi בוחר את ה-backend שמשרת אותו, וזו הבחירה החשובה ביותר בהרצה מקומית: היא קובעת אם צריך GPU, תהליך מאמת, או אף אחד מהם.

דגלמה זהמתי להשתמש
-validationapi=realברירת המחדל. מתקשר עם מאמת חיצוני בערוץ ZMQ PUSH/PULL שבין הצומת למאמת, באמצעות FlatBuffers. ההגדרה של סביבת הייצור.דורש תהליך מאמת אמיתי. בשימוש ב-mainnet, ב-testnet ובכל הרצת regtest שמפעילה שחזור (replay) אמיתי של מודל.
-validationapi=mockבתוך התהליך ודטרמיניסטי. ה-backend המדומה חושף שלושה RPC‏ (validationmockdefault,‏ validationmockclear,‏ validationmockrequests) לתגובות Quick,‏ Full ו-Model מוכנות מראש; עם דגלי ההפעלה -mockval-default-* אפשר לתסרט כל תוצאת אימות.ברירת המחדל של חבילת הבדיקות הפונקציונליות. הבחירה הנכונה להפעלת לוגיקת השרשרת בלי מאמת ובלי הסקה אמיתית.
-validationapi=desktopהיברידי. בדיקות Quick רצות בתוך התהליך; Full ו-Model נשלחות למאמת HTTPS מקומי (הבינארי השולחני המוגדר כברירת מחדל). אין צורך ב-broker של ZMQ.הדגמות על מכונה אחת, כשרוצים מעבר Quick ו-Smell אמיתי בלי להפעיל שירות מאמת נפרד.

למבט ראשון על לוגיקת השרשרת, mock היא התשובה הנכונה. שאר הדף מניח אותה, אלא אם צוין אחרת.

מסלול A · ‏Core בלבד, עם אימות מדומה

הדרך עם הכי מעט חיכוך. דמון C++‎ אחד: בלי docker, בלי GPU, בלי קובצי מודל על הדיסק. מספיק לכל המדריכים בדף הזה.

1. בניית הדמון

עקבו אחר הוראות הבנייה של Bitcoin Core בתיקייה services/core-node/bcore/. הקוד של TensorCash נבנה תחת אותו יעד CMake כמו ה-upstream; אין דגל נפרד.

2. הפעלת צומת regtest

הדגלים האלה משקפים את מה ש-test_framework/test_tensorcash.py מעביר לכל בדיקה פונקציונלית, כך שכל מה שרץ שם רץ גם כאן. תגובות ה-mock המוגדרות כברירת מחדל קבועות על ירוק, ולכן קבלת בלוקים דטרמיניסטית.

./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 · ה-stack המקומי המלא (docker compose)

למקרים שבהם mock לא מספיק: תהליך מאמת אמיתי, מודל אמיתי שמגיש הסקה, ו-API הכורה מחובר. בתיקיית השורש של המאגר יש סקריפטי הפעלה ל-Mac ול-Linux עם CUDA.

ב-Apple silicon, סקריפט ההפעלה מוריד build של llama.cpp ומרים את ה-stack המלא של 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 וארנק ה-repo מבוסס covenant. כל אחת היא תרחיש עצמאי שאפשר לקרוא מההתחלה עד הסוף; המדריכים למטה מפנים לבדיקות המייצגות ביותר.

מדריכים מעשיים

שלושה רצפים קצרים מול צומת ה-mock ממסלול 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. מודל נרשם כך: מפקידים פיקדון בנאמנות, אוספים אימותי 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 מבלוק ה-genesis, במקום מהגובה המדורג של mainnet.
-vdfspvvdfverifyheight=0מפעיל אימות VDF מבלוק ה-genesis.
-maxtipage=999999מקבל חותמות זמן ישנות, כך שהפעלה מחדש על שרשרת מיושנת לא נראית כמו צומת לא מסונכרן.
-spv-asn-min=1מוריד את סף האימות ההדדי לפי ASN; בלעדיו, regtest חוסם את לוגיקת המעבר של VDF SPV.
-spv-hysteresis-base-bps=0מבטל את ההיסטרזיס של מרווח הבסיס, כך ש-reorg בבדיקות מיידי ודטרמיניסטי.
-spv-reorg-sampling-threshold=999למעשה משבית את דגימת גוף הבלוקים ב-reorg עמוק, שאי אפשר להפעיל באופן מעשי בגבהים קטנים.
-useextapi=0משבית את ה-API החיצוני של הכורה: לא נחוץ למדריכים של השרשרת בלבד, ומקצר את זמן ההפעלה.
-debug=net,validationרושם ביומן את השורות השימושיות ביותר לסשן regtest: תקשורת רשת וצינור האימות.
-par=1אימות בתהליכון יחיד. מסלק סוג שלם של חוסר יציבות שמופיע רק בבדיקות, בלי לפגוע בנכונות.

לאן עכשיו

  • תיעוד JSON-RPCאינדקס המתודות המלא, מאורגן לפי קטגוריות, עם תגיות יציבות ודוגמאות curl.
  • REST API של המאמתכשעוברים מ--validationapi=mock לתהליך מאמת אמיתי.
  • סכמות FlatBufferIDL של FlatBuffer ו-JSON Schema למטעני ה-ZMQ שבין הצומת למאמת.
  • bcore/test/functional/לקרוא את הבדיקות כמפרט.
  • ברז testnetהמקבילה המקוונת: מימון ארנק ב-testnet המשותף, כשרוצים שרשרת חיה במקום סביבת ניסוי מקומית.