Hướng dẫn regtest

Ba hướng phát triển cục bộ, sắp xếp theo mức độ phức tạp. Hướng nào cũng cho bạn một JSON-RPC TensorCash để gọi bằng bitcoin-cli hoặc bất kỳ client JSON-RPC nào. Mọi nội dung bên dưới đều lấy bộ kiểm thử chức năng của bcore làm đặc tả chuẩn, có thể thực thi, và mỗi hướng dẫn đều liên kết tới test làm cơ sở cho nó.

Chỉ Core · docker compose · kiểm thử chức năng

Chế độ kiểm chứng

TensorCash thêm một bước kiểm chứng bên ngoài vào quá trình chấp nhận khối. -validationapi chọn backend phục vụ bước này, và đó là lựa chọn quan trọng nhất khi chạy cục bộ: nó quyết định bạn cần GPU, cần tiến trình verifier, hay không cần gì cả.

CờLà gìKhi nào dùng
-validationapi=realMặc định. Giao tiếp với một verifier bên ngoài qua kênh ZMQ PUSH/PULL từ node tới verifier, dùng FlatBuffers. Đây là thiết lập production.Cần một tiến trình verifier thật. Dùng trên mainnet, testnet và mọi lần chạy regtest có replay mô hình thật.
-validationapi=mockChạy trong tiến trình và tất định. Backend giả lập cung cấp ba RPC (validationmockdefault, validationmockclear, validationmockrequests) cho các phản hồi Quick, Full và Model dựng sẵn; với các cờ khởi động -mockval-default-*, mọi kết quả kiểm chứng đều có thể lập trình trước.Mặc định của bộ kiểm thử chức năng. Lựa chọn phù hợp để vận hành logic chuỗi mà không cần verifier hay suy luận thật.
-validationapi=desktopKết hợp. Kiểm tra Quick chạy ngay trong tiến trình; Full và Model được gửi tới một verifier HTTPS cục bộ (binary desktop mặc định). Không cần ZMQ broker.Bản demo trên một máy muốn có lượt kiểm tra Quick và Smell thật mà không phải vận hành một dịch vụ verifier riêng.

Để làm quen với logic chuỗi, mock là lựa chọn đúng. Phần còn lại của trang này mặc định dùng nó, trừ khi có ghi chú khác.

Hướng A · chỉ Core, với xác thực giả lập

Ít trở ngại nhất. Một daemon C++ duy nhất: không docker, không GPU, không tệp mô hình trên đĩa. Đủ cho mọi hướng dẫn trên trang này.

1. Build daemon

Làm theo hướng dẫn build của Bitcoin Core với thư mục services/core-node/bcore/. Mã TensorCash build dưới cùng target CMake với upstream; không có cờ riêng.

2. Khởi động một node regtest

Các cờ này giống hệt những gì test_framework/test_tensorcash.py truyền cho mọi functional test, nên thứ gì chạy được ở đó cũng chạy được ở đây. Phản hồi giả lập mặc định được cố định ở kết quả xanh, nên việc chấp nhận khối là tất định.

./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. Gọi node

Xác thực dùng tệp cookie tại $HOME/.tensorcash-regtest/regtest/.cookie, được bitcoin-cli tự động đọc khi bạn truyền -datadir. Cổng RPC là cổng regtest mặc định của upstream, 18443.

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

Hướng B · toàn bộ stack cục bộ (docker compose)

Khi xác thực giả lập là chưa đủ: một tiến trình verifier thật, một mô hình thật phục vụ suy luận, và miner API được kết nối sẵn. Thư mục gốc của repository có script khởi chạy cho Mac và cho Linux có CUDA.

Trên Apple silicon, trình khởi chạy tải một bản build llama.cpp và dựng toàn bộ 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

Trên Linux với GPU NVIDIA, launch_linux.sh làm điều tương tự nhưng dùng verifier dựa trên vLLM thay cho 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

Tệp compose bind các cổng host 8333 (P2P), 8050 (REST API core-node) và 7067 (ZMQ). Verifier phục vụ REST API Verifier trên cổng container riêng của nó.

Hướng C · chạy bộ kiểm thử chức năng

Khi daemon đã được build (Hướng A, bước 1), trình chạy test sẽ khởi động các node dùng một lần cho bạn. Hữu ích khi bạn muốn sao chép một trình tự đã được kiểm chứng là chạy đúng, thay vì tự mò mẫm với 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)

Các test của TensorCash được nhóm theo giao diện: vòng đời mô hình, tài sản nguyên bản, fair-sign adaptor và ví repo dùng covenant. Mỗi test là một kịch bản độc lập có thể đọc từ đầu đến cuối; các hướng dẫn bên dưới trỏ tới những test tiêu biểu nhất.

Hướng dẫn từng bước

Ba trình tự ngắn chạy trên node giả lập từ Hướng A. Mỗi trình tự chỉ là phác thảo; functional test được liên kết là kịch bản đầy đủ, có thể thực thi.

Khai thác khối đầu tiên

Test chuẩn: wallet_basic.py

Giữ nguyên như Bitcoin Core. Một bước kiểm tra nhanh trước mọi giao diện riêng của TensorCash: xác nhận daemon đang chạy và ví đã có tiền.

Liên quan đến: 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)

Đăng ký mô hình từ đầu đến cuối

Test chuẩn: feature_model_registration.py

Dành riêng cho TensorCash. Một mô hình được đăng ký bằng cách ký quỹ một khoản đặt cọc, thu thập các lượt kiểm chứng Quick và Model thành công qua N commit, rồi chuyển sang registered khi cửa sổ kiểm chứng đóng lại. Với -validationapi=mock, bạn có thể điều khiển mọi bước bằng RPC, không cần verifier hay GPU thật. Đây chỉ là phác thảo; test được liên kết là kịch bản đầy đủ.

Liên quan đến: 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, ...}

Phát hành một tài sản nguyên bản

Test chuẩn: feature_assets_basic_highlevel.py

Dành riêng cho TensorCash. registerasset là RPC ví cấp cao: nó tạo các output đặt cọc và ICU, gắn TLV đăng ký của tổ chức phát hành rồi phát sóng. Sau một xác nhận, có thể truy vấn tài sản theo id hoặc ticker. Toàn bộ vòng đời (mint, chuyển, burn) nằm trong test được liên kết.

Liên quan đến: 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

Tham chiếu cờ

Các cờ trong Hướng A khác với một phiên bitcoind -regtest thông thường. Nguồn chuẩn: test_framework/test_tensorcash.py và init.cpp.

CờVì sao quan trọng trong regtest
-regtestChọn chuỗi regtest (trợ cấp khối, quy tắc trưởng thành tức thì và các cổng chỉ dùng cục bộ 18443/18444).
-vdfspvcommitmentheight=0Kích hoạt VDF/SPV ngay từ genesis thay vì ở độ cao kích hoạt theo giai đoạn của mainnet.
-vdfspvvdfverifyheight=0Kích hoạt kiểm chứng VDF ngay từ genesis.
-maxtipage=999999Chấp nhận timestamp cũ, để khi khởi động lại trên một chuỗi cũ, node không bị coi là chưa đồng bộ.
-spv-asn-min=1Hạ ngưỡng xác nhận chéo ASN; nếu không có cờ này, regtest sẽ chặn logic chuyển đổi VDF SPV.
-spv-hysteresis-base-bps=0Bỏ độ trễ (hysteresis) của biên cơ sở, để reorg trong test diễn ra tức thì và tất định.
-spv-reorg-sampling-threshold=999Trên thực tế tắt việc lấy mẫu thân khối khi reorg sâu, vốn khó vận hành ở độ cao nhỏ.
-useextapi=0Tắt miner API bên ngoài: không cần cho các hướng dẫn chỉ liên quan đến chuỗi, và giúp khởi động nhanh hơn.
-debug=net,validationGhi log những dòng hữu ích nhất cho một phiên regtest: mạng và pipeline kiểm chứng.
-par=1Kiểm chứng đơn luồng. Loại bỏ một nhóm lỗi chập chờn chỉ xuất hiện khi test, mà không ảnh hưởng đến tính đúng đắn.

Tiếp theo

  • Tài liệu JSON-RPCDanh mục đầy đủ các method, sắp xếp theo nhóm, kèm nhãn mức ổn định và ví dụ curl.
  • REST API VerifierKhi bạn chuyển từ -validationapi=mock sang một tiến trình verifier thật.
  • Schema FlatBufferIDL FlatBuffer và JSON Schema cho các payload ZMQ từ node tới verifier.
  • bcore/test/functional/Đọc các test như một bản đặc tả.
  • Faucet testnetPhiên bản trực tuyến: nạp tiền cho ví trên testnet dùng chung khi bạn muốn một chuỗi đang chạy thật thay vì sandbox cục bộ.