BTX Node

BTX is a post-quantum, AI-infrastructure-friendly blockchain derived from Bitcoin Knots v29.2. It replaces Bitcoin's SHA-256d proof of work with MatMul PoW — a novel consensus mechanism based on matrix multiplication over a finite field — adds post-quantum transaction signatures via witness v2 P2MR outputs, provides a shielded transaction pool with lattice-based confidential transactions active from genesis, enforces reduced-data transaction constraints (BIP 110-style) from genesis, and implements Dandelion++ transaction relay (BIP 156) for network-layer anonymity.

This repository contains the full node implementation, wallet, mining infrastructure, and test suites.

BTX extends the upstream Bitcoin Knots codebase with:

MatMul proof of work for AI-oriented compute hardware
witness v2 P2MR outputs for post-quantum signatures
a native shielded transaction pool
reduced-data transaction constraints from genesis
Dandelion++ transaction relay for network-layer privacy

For the current source of truth, start with:

doc/README.md for the curated documentation index
doc/security/README.md for security status, hard-fork boundaries, and follow-on work
doc/btx-matmul-pow-spec.md for the PoW design
doc/btx-pqc-spec.md for the post-quantum script model
doc/btx-shielded-pool-guide.md for shielded wallet and operator guidance

This public repository keeps the documentation surface intentionally curated. Historical working notes, internal validation journals, and private operator artifacts are not part of this export.

Chain Parameters

Parameter	Value
PoW Algorithm	MatMul PoW (matrix multiplication over F_{2^31 - 1})
Block Time	90 s target spacing from genesis
Block Limits	24 MB serialized, 24 MWU weight, 480k sigops cost
Max Supply	21 000 000 BTX
Initial Block Reward	20 BTX
Halving Interval	525 000 blocks
Difficulty Adjustment	ASERT (aserti3-2d), per-block, active from block 0
Address Format	Bech32m witness v2 P2MR: `btx1z...` (HRP `btx`)
Shielded Address Format	`btxs1...` (Bech32m shielded)
Mainnet P2P Port	19335
Mainnet RPC Port	19334
Consensus Outputs	P2MR-only witness v2 `OP_2 <32>` + `OP_RETURN` (mainnet/testnet/testnet4)
Consensus Features	Reduced-data limits from genesis (BIP 110-style)
PQ Signatures	ML-DSA-44 (primary) + SLH-DSA-SHAKE-128s (backup) via witness v2 P2MR
Shielded Pool	Lattice-based confidential transactions, active from genesis
Default Shielded Ring Size	8
Supported Shielded Ring Sizes	8..32 on the current wire / consensus surface
Dandelion++ Relay	Stem-then-fluff privacy relay, activates at block 250 000

Block Reward Schedule

Block Range	Reward
0 -- 524 999	20 BTX
525 000 -- 1 049 999	10 BTX
1 050 000 -- 1 574 999	5 BTX
1 575 000 -- 2 099 999	2.5 BTX
...	halves every 525 000 blocks until 0

MatMul Proof of Work

MatMul PoW is an AI-infrastructure-friendly proof of work based on the paper "Proofs of Useful Work from Arbitrary Matrix Multiplication" (Komargodski, Schen, Weinstein — arXiv:2504.09971, April 2025).

Instead of brute-force hashing, miners perform matrix multiplications over a Mersenne prime field (q = 2^31 - 1). The core work unit — large dense matrix multiplication — is the same operation that dominates GPU and TPU workloads for AI/ML training and inference, making the mining hardware directly reusable for productive computation.

How It Works

Seed derivation: Two deterministic seeds (seed_a, seed_b) are derived from the previous block hash and current height. Miners cannot choose favorable matrices.
Matrix generation: Seeds expand into two n x n matrices (A, B) over F_q.
Noise injection: A low-rank noise perturbation (rank r) is generated from the block header and nonce, producing A' = A + E and B' = B + F. This prevents precomputation.
Matrix multiplication: The miner computes C' = A' x B' — a standard dense matrix product.
Transcript hashing: The result is canonicalized into block-sized chunks, compressed with a deterministic vector, and hashed with SHA-256.
Difficulty check: If the transcript hash meets the target, the block is valid.

Two-Phase Validation

Phase 1 (O(1)): Checks header fields, dimension bounds, seed validity, and that the digest meets the target. Every node runs this on every block.
Phase 2 (O(n^3)): Reconstructs matrices, performs the full multiplication, and verifies the transcript hash. Rate-limited to 8 verifications per peer per minute. Only applied to recent blocks (last 1000 on mainnet).

From block 61000, mainnet validation switches to the product-committed digest path for MatMul proof-of-work hardening. The historical bootstrap/ASERT/pre-hash mainnet schedule remains frozen at 50000; only the newer post-launch hardening activations live at 61000. Current protocol and activation details live in doc/security/hardfork-61000.md and doc/btx-matmul-pow-spec.md.

Parameters by Network

Parameter	Mainnet	Testnet	Regtest
Matrix dimension (n)	512	256	64
Transcript block size (b)	16	8	8
Noise rank (r)	8	4	4
Pre-hash epsilon bits	10 (18 from block 50 000)	10	10
Validation window	1000	500	10
Phase 2 ban threshold	3	unlimited	unlimited

Block Header

The BTX block header extends Bitcoin's 80-byte header:

nVersion        (4 bytes)      Block version
hashPrevBlock   (32 bytes)     Previous block hash
hashMerkleRoot  (32 bytes)     Transaction merkle root
nTime           (4 bytes)      Block timestamp
nBits           (4 bytes)      Difficulty target (compact)
nNonce64        (8 bytes)      64-bit mining nonce
matmul_digest   (32 bytes)     SHA-256 of MatMul transcript
matmul_dim      (2 bytes)      Matrix dimension used
seed_a          (32 bytes)     Deterministic seed for matrix A
seed_b          (32 bytes)     Deterministic seed for matrix B

Total serialized header: ~182 bytes.

For the full MatMul PoW specification, see doc/btx-matmul-pow-spec.md.

Post-Quantum Cryptography

BTX implements NIST-standardized post-quantum digital signatures through a new output type called P2MR (Pay-to-Merkle-Root), activated as witness version 2.

Algorithms

Algorithm	Role	Pubkey	Signature	Type
ML-DSA-44 (Dilithium)	Primary	1312 bytes	2420 bytes	Lattice-based
SLH-DSA-SHAKE-128s (SPHINCS+)	Backup	32 bytes	7856 bytes	Hash-based

BTX keeps ML-DSA-44 as the active primary algorithm today. Falcon-512 is not enabled yet, but this branch reserves P2MR soft-fork slots for a future Falcon activation path once implementations, audits, and operational tooling are mature enough to ship safely.

P2MR Design

P2MR uses a hybrid two-leaf Merkle tree:

Primary leaf: <1312-byte-pubkey> OP_CHECKSIG_MLDSA — lattice-based ML-DSA-44 signature for everyday transactions.
Backup leaf: <32-byte-pubkey> OP_CHECKSIG_SLHDSA — stateless hash-based SLH-DSA signature for key-compromise recovery.

The witness program is a 32-byte Merkle root: OP_2 <merkle-root>. Addresses use Bech32m encoding with witness version 2, giving the prefix btx1z....

Script Opcodes

Opcode	Function
`OP_CHECKSIG_MLDSA`	Verify ML-DSA-44 signature against P2MR sighash
`OP_CHECKSIG_SLHDSA`	Verify SLH-DSA-SHAKE-128s signature against P2MR sighash
`OP_CHECKSIGADD_MLDSA`	Accumulate ML-DSA signature result for threshold multisig
`OP_CHECKSIGADD_SLHDSA`	Accumulate SLH-DSA signature result for threshold multisig
`OP_CHECKTEMPLATEVERIFY`	Enforce CTV template hash in P2MR leaves
`OP_CHECKSIGFROMSTACK`	Verify externally provided message signatures in P2MR leaves

Reserved for future P2MR soft forks and intentionally left inactive today:

Reserved Opcode	Current Meaning
`OP_CHECKSIG_FALCON`	P2MR `OP_SUCCESS` reservation for future Falcon checksig
`OP_CHECKSIGADD_FALCON`	P2MR `OP_SUCCESS` reservation for future Falcon multisig
`OP_CHECKSIGFROMSTACK_FALCON`	P2MR `OP_SUCCESS` reservation for future Falcon CSFS/oracle paths

Wallet Integration

Descriptor format: mr(<mldsa-key>,pk_slh(<slhdsa-key>)), plus CTV/CSFS leaf forms ctv(...), ctv_pk(...), csfs(...), and csfs_pk(...)
Multisig descriptors: mr(multi_pq(...)) and mr(sortedmulti_pq(...))
Timelocked multisig descriptors: mr(cltv_multi_pq(...)), mr(csv_multi_pq(...)), mr(ctv_multi_pq(...)), plus sorted variants
Miniscript integration: P2MR context supports PQ key and threshold fragments
HD derivation: Purpose 87h for P2MR descriptors
Relay policy: P2MR-only enforcement with watch-only guardrails

For the full PQ specification and tutorials, see:

Shielded Pool

BTX includes a shielded transaction pool active from genesis on all networks. Shielded transactions hide sender, receiver, and amount using lattice-based zero-knowledge proofs, while coinbase rewards are automatically moved into the shielded pool by default.

Production Status

The current production architecture is:

DIRECT_SMILE as the default direct z_sendmany backend,
default direct ring size 8, configurable up to 32 on the current wire surface via -shieldedringsize,
wallet-built transparent deposit (z_shieldcoinbase and compatible coinbase-only z_shieldfunds sweeps after 61000), fully shielded direct send, note merge, and mixed shielded-to-transparent unshield all running on the v2_send transaction family,
shared-ring BATCH_SMILE ingress on the live bridge-in path,
full account-leaf payloads committed in registry state so future spend reconstruction comes from authenticated consensus data,
lean consumed-leaf transaction witnesses on wire (leaf_index + account_leaf_commitment + sibling_path),
egress, rebalance, and settlement flows aligned with the same shielded state model,
legacy MatRiCT and receipt-backed ingress retained only as non-launch residual tooling.

The hard-fork launch protocol is final for this chain. Larger recursive CT anonymity sets are not part of that protocol and are explicitly rejected by prover and verifier instead of falling back to the old prototype multi-level CT branch.

Current operator guidance lives in doc/btx-shielded-pool-guide.md and doc/security/README.md.

The shielded pool is built on lattice-based confidential transaction protocols providing:

Confidential amounts: Pedersen-style commitments hide transaction values
Ring signatures: Each spend references a ring of decoy commitments, hiding the true input among decoys
Range proofs: Prove output values are non-negative without revealing them
Balance proofs: Cryptographic guarantee that inputs equal outputs plus fees
Nullifier-based double-spend prevention: Each note produces a unique nullifier; the global nullifier set prevents replay

Transaction Types

Type	Description
Shield (transparent -> shielded)	Prefork compatibility deposit on proofless `v2_send`; post-`61000` general public-flow `V2_SEND` is retired, with mature-coinbase compatibility retained for miner shielding
Unshield (shielded -> transparent)	Prefork compatibility unshield on mixed `v2_send`; post-`61000` transparent settlement moves to explicit bridge/egress surfaces
Fully shielded (shielded -> shielded)	Transfer within the pool on post-fork `DIRECT_SMILE` `v2_send`

Auto-Shield Coinbase

When enabled (default: on), the wallet automatically shields mature coinbase outputs into the shielded pool on each new block.

# Disable auto-shielding (opt-out)
btxd -autoshieldcoinbase=0

# Manual shielding
btx-cli z_shieldcoinbase

Shielded RPCs

RPC	Description
`z_getnewaddress`	Generate a new shielded address
`z_listaddresses`	List all shielded addresses in the wallet
`z_getbalance`	Shielded balance with optional minimum confirmations
`z_gettotalbalance`	Combined transparent + shielded balance
`z_listunspent`	List unspent shielded notes
`z_sendmany`	Send to shielded recipients and, before `61000`, optionally transparent recipients
`z_shieldcoinbase`	Shield mature coinbase outputs into the pool
`z_shieldfunds`	Shield transparent UTXOs with automatic chunking; after `61000`, limited to mature coinbase compatibility sweeps
`z_mergenotes`	Consolidate many small notes into one
`z_viewtransaction`	Decode shielded transaction details (with viewing keys)
`z_exportviewingkey`	Export KEM viewing key for auditors
`z_importviewingkey`	Import viewing key for watch-only monitoring

Selective Disclosure (View Grants)

Transactions can include CViewGrant entries that encrypt viewing keys to designated auditors using ML-KEM. This allows selective transparency for compliance or audit workflows without compromising privacy for other participants. Up to 8 view grants per transaction.

For detailed setup and operations, see doc/btx-shielded-pool-guide.md.

Dandelion++ Transaction Relay

BTX implements Dandelion++ (BIP 156), a privacy-enhancing protocol for transaction relay that prevents adversaries from linking transactions to their originating IP addresses.

How It Works

Stem phase: The originating node sends the transaction to one randomly chosen peer. That peer forwards it to one more peer, creating a random walk (~10 hops expected).
Fluff phase: After stem relaying, a node probabilistically (10% per hop) transitions the transaction to standard diffusion relay, making it appear to originate from the fluff point.

Parameter	Value
Activation Height	Block 250 000
Service Flag	`NODE_DANDELION` (bit 30)
Epoch Interval	~600 s
Stem Probability	90% per hop
Relay Destinations	2 outbound peers per epoch
Embargo Timer	Exponential, mean 39 s

# Disable Dandelion++ (opt-out, default: enabled)
btxd -dandelion=0

For the full protocol specification, see doc/dandelion-pp-implementation-spec-v2.md.

CTV + CSFS Covenants

P2MR includes covenant and oracle primitives:

CTV (OP_CHECKTEMPLATEVERIFY): Template-constrained spends for vaults and payment trees.
CSFS (OP_CHECKSIGFROMSTACK): Message-based oracle signatures (ML-DSA-44 or SLH-DSA-128s) with optional spender CHECKSIG.
DoS hardening: Explicit validation-weight charging for ML-DSA, SLH-DSA, and CSFS; 10,000-byte consensus caps for P2MR script elements.

L2 profile: Supported constructions include CTV vaults/payment trees and CSFS delegation closes. SIGHASH_ANYPREVOUT (APO) is not implemented.

Building from Source

Requirements

C++ compiler: GCC 11.1+ or Clang 16.0+
CMake: 3.22+
Boost: 1.73.0+
libevent: 2.1.8+
Python: 3.10+ (for functional tests)

Optional: SQLite 3.7.17+ (descriptor wallets), Qt 5.11+/6.2+ (GUI), ZeroMQ 4.0+ (notifications).

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y build-essential cmake pkg-config \
  libboost-dev libevent-dev libsqlite3-dev python3 python3-zmq

cmake -B build
cmake --build build -j$(nproc)

macOS

brew install cmake boost libevent sqlite pkg-config

cmake -B build
cmake --build build -j$(sysctl -n hw.logicalcpu)

Convenience Script

scripts/build_btx.sh build-btx

For native CLI release assembly without Guix, see scripts/release/cut_local_release.py together with doc/btx-github-release-automation.md.

Build Options

Option	Default	Description
`BUILD_DAEMON`	ON	Build `btxd`
`BUILD_CLI`	ON	Build `btx-cli`
`BUILD_GUI`	OFF	Build `btx-qt` (requires Qt)
`BUILD_WALLET_TOOL`	auto	Build `btx-wallet`
`BUILD_TESTS`	ON	Build unit test suite
`BUILD_BENCH`	OFF	Build benchmark binary
`ENABLE_WALLET`	ON	Enable wallet support
`WITH_SQLITE`	auto	SQLite wallet backend

Platform-Specific Guides

Running a Node

Fast-Start Validating Nodes

BTX releases are designed to support a fast-start validating-node workflow for binary users: install a precompiled archive, load the matching rollback snapshot, and begin using wallet, mining, and service RPCs before a full historical sync finishes.

The shortest operator path is:

export GH_TOKEN="$(<github.key)"  # only needed for private GitHub releases

python3 contrib/faststart/btx-agent-setup.py \
  --repo btxchain/btx \
  --release-tag v29.2-btx1 \
  --preset service \
  --datadir="$HOME/.btx"

That installer consumes the published btx-release-manifest.json, selects the correct platform archive, verifies the advertised assets, and can immediately chain into the assumeutxo bootstrap flow. Use --preset miner for a pruned, mining-oriented setup, or --preset service for an RPC-oriented node that is ready to issue easy / normal / hard / idle MatMul service challenges through listmatmulservicechallengeprofiles, getmatmulservicechallengeplan, and issuematmulservicechallengeprofile. The planner and profile RPCs now return issue_defaults / profile_issue_defaults so agents can round-trip directly into getmatmulservicechallenge or issuematmulservicechallengeprofile without re-deriving difficulty math by hand. Service operators can also watch getdifficultyhealth.service_challenge_registry for shared-registry health, run solvematmulservicechallenge with explicit time_budget_ms / solver_threads limits for background clients, and use the stateless final flag on verifymatmulserviceproof / verifymatmulserviceproofs when they need pure verification without local registry lookups. In --json mode, the installer now keeps bootstrap progress on stderr and returns a machine-readable summary that includes the installed btxd / btx-cli paths, the generated fast-start config, and miner-preset handoff commands for contrib/mining/start-live-mining.sh. For private GitHub releases, export one of BTX_GITHUB_TOKEN, GITHUB_TOKEN, or GH_TOKEN first so the installer can authenticate the release-asset downloads.

For the full operator flow, see doc/btx-download-and-go.md, doc/assumeutxo.md, and contrib/faststart/README.md.

Starting the Daemon

# Foreground
./build/bin/btxd

# Background daemon
./build/bin/btxd -daemon

# Testnet
./build/bin/btxd -testnet -daemon

# Regtest (local testing)
./build/bin/btxd -regtest -daemon

Configuration

Create ~/.btx/btx.conf:

server=1
listen=1
port=19335

rpcuser=btxrpc
rpcpassword=your_secure_password
rpcport=19334

dbcache=4096
maxmempool=300

# Fast node (recommended):
prune=4096
# Archival node:
# prune=0

# Bootstrap peers
minimumchainwork=0
dnsseed=1
fixedseeds=1
addnode=node.btx.tools:19335
addnode=146.190.179.86:19335
addnode=164.90.246.229:19335

Or generate a profile automatically:

# Fast node (recommended default)
./contrib/devtools/gen-btx-node-conf.sh fast > ~/.btx/btx.conf

# Archival node
./contrib/devtools/gen-btx-node-conf.sh archival > ~/.btx/btx.conf

Checking Status

btx-cli getblockchaininfo     # Chain state, sync progress
btx-cli getpeerinfo           # Connected peers
btx-cli getmininginfo         # Mining parameters
btx-cli getmempoolinfo        # Memory pool status

Data Directory

OS	Default Path
Linux	`~/.btx/`
macOS	`~/Library/Application Support/BTX/`
Windows	`%APPDATA%\BTX\`

Wallet Operations

Creating a Wallet

# Create a new descriptor wallet
btx-cli createwallet "mywallet"

Descriptor wallets are required. Default address type is p2mr (btx1z...).

Receiving and Sending

# Get a new receiving address
btx-cli -rpcwallet=mywallet getnewaddress
# Returns: btx1z...

# Check balance
btx-cli -rpcwallet=mywallet getbalance

# Send BTX
btx-cli -rpcwallet=mywallet sendtoaddress "btx1z..." 1.5

# Shielded balance
btx-cli -rpcwallet=mywallet z_gettotalbalance

# Send to shielded address
btx-cli -rpcwallet=mywallet z_sendmany '[{"address":"btxs1...","amount":1.0}]'

Backup

# Verify integrity before taking a production backup
btx-cli -rpcwallet=mywallet z_verifywalletintegrity

# Backup wallet file
btx-cli -rpcwallet=mywallet backupwallet "/path/to/backup.dat"

# Preferred: full encrypted bundle archive
btx-cli -rpcwallet=mywallet \
  -stdinwalletpassphrase \
  -stdinbundlepassphrase \
  backupwalletbundlearchive "/path/to/mywallet.bundle.btx"

# Restore from archive
btx-cli -stdinbundlepassphrase \
  restorewalletbundlearchive "restored" "/path/to/mywallet.bundle.btx"

Wallet Encryption

btx-cli -rpcwallet=mywallet encryptwallet "your_passphrase"
btx-cli -rpcwallet=mywallet walletpassphrase "your_passphrase" 60
btx-cli -rpcwallet=mywallet walletlock

For BTX-native treasury, multisig, timelocked recovery, backup, restore, and AI-safe operating guidance, see doc/btx-key-management-guide.md.

Key Management

BTX's recommended operational model is:

descriptor wallets only
P2MR receive/change descriptors
watch-only coordinators for planning and accounting
isolated signer wallets or external signers for authorization
bundle archive backups plus restore drills

Use these docs together:

Shielded Transfer Builder

BTX includes a deterministic operator tool for multisig-to-shielded transfer bundles at:

contrib/shielded_transfer_builder.py

The builder exposes four explicit phases:

plan
simulate
execute
release

It is intended for large or operationally sensitive transfers where operators want:

a canonical JSON bundle containing the exact unsigned PSBT plan
deterministic destination ordering and transaction ordering
authoritative fee convergence through z_fundpsbt
exact finalized mempool preflight before broadcast
controlled input locking during review and execution

After the post-61000 privacy fork, z_fundpsbt remains suitable for mature-coinbase compatibility deposits but not for arbitrary transparent ingress; general transparent deposits should use the bridge-ingress surface.

Example:

python3 contrib/shielded_transfer_builder.py plan \
  --datadir=/path/to/datadir \
  --chain=main \
  --rpcwallet=signer-1 \
  --signer-wallet=signer-1 \
  --signer-wallet=signer-2 \
  --signer-wallet=signer-3 \
  --destination=btxs1...=1000.00000000 \
  --destination=btxs1...=500.00000000 \
  --bundle=/tmp/transfer-bundle.json

The builder reports and consumes the following fee-analysis fields from the daemon:

fee_authoritative
required_mempool_fee
estimated_vsize
estimated_sigop_cost

For the full operator workflow, lock behavior, auth/config lookup order, and artifact model, see doc/shielded-transfer-builder.md.

Mining

Overview

BTX uses MatMul PoW for mining. The built-in solver is available through RPC for regtest/testnet mining. For production mainnet mining, use getblocktemplate / submitblock.

Regtest Mining (Testing)

./build/bin/btxd -regtest -daemon
./build/bin/btx-cli -regtest createwallet "miner"
ADDR=$(./build/bin/btx-cli -regtest -rpcwallet=miner getnewaddress)
./build/bin/btx-cli -regtest generatetoaddress 10 "$ADDR"
./build/bin/btx-cli -regtest -rpcwallet=miner getbalance
# -> 200.00000000 (10 blocks x 20 BTX)

Production Mining (getblocktemplate)

./build/bin/btx-cli getblocktemplate '{"rules": ["segwit"]}'

The template includes MatMul-specific fields (matmul_dim, seed_a, seed_b, target). External miners should:

Fetch the template via getblocktemplate
Generate matrices A, B from seed_a, seed_b
Iterate nonces, applying noise and computing the MatMul transcript
When the transcript hash meets the target, submit via submitblock

Mining Best Practices

Keep the node healthy and near tip before mining. getmininginfo exposes a chain_guard section that reports peer count, near-tip peers, and whether mining should be paused.
The chain guard stays conservative around recently active lagging peers, but it discounts long-idle stale peers so a few dead outbound connections do not pause otherwise healthy mining sessions.
For normal operation, avoid connect=-only peer islands. Prefer normal peer discovery plus optional addnode= hints so the node can recover from stale peer sets on its own.
If you use the bundled solo-mining helpers, keep enough automatic peer capacity available for discovery; the helper restart path now uses -maxconnections=32 by default instead of a tiny connection budget.
Back up the mining reward wallet together with its descriptors, not just the wallet database file.
Prefer btxd / btx-cli in scripts and service files.
If you intentionally drive local solo mining through generatetoaddress, use a health-aware supervisor instead of a blind shell loop so the miner can react to repeated RPC failures or prolonged chain_guard pauses.
For actual idle-time mining, give that supervisor an explicit local idleness probe via --should-mine-command='...' so chain health alone is not treated as permission to keep mining while the machine is busy.

Portable helper scripts for that workflow live in contrib/mining:

# Start a supervised solo-mining loop
contrib/mining/start-live-mining.sh \
  --datadir="$HOME/.btx" \
  --wallet=miner \
  --should-mine-command='/usr/local/bin/btx-should-mine-now' \
  --address-file=/path/to/miner-address.txt

# Back up the mining wallet + descriptors
contrib/mining/backup-wallet.sh \
  --datadir="$HOME/.btx" \
  --wallet=miner

Mining RPCs

Command	Description
`getmininginfo`	Current mining state, difficulty, algorithm
`getblocktemplate`	Block template for external mining
`submitblock`	Submit a solved block
`generatetoaddress`	Mine N blocks (regtest/testnet)
`getnetworkhashps`	Estimated network hash rate

Genesis Block Generator

./build/bin/btx-genesis --timestamp "BTX genesis" --max-tries 200000 --backend cpu
./build/bin/btx-genesis --timestamp "BTX genesis" --max-tries 200000 --backend metal

Backend selection: BTX_MATMUL_BACKEND (cpu|metal|mlx|cuda).

Running Tests

Unit Tests

ctest --test-dir build
./build/bin/test_btx --log_level=warning
./build/bin/test_btx --run_test=matmul_tests

Functional Tests

build/test/functional/test_runner.py
build/test/functional/test_runner.py --jobs=4
build/test/functional/test_runner.py wallet_basic.py

BTX-Specific Test Gates

# Consensus rules verification
scripts/test_btx_consensus.sh build-btx

# Full parallel gate (unit + functional + BTX scripts)
scripts/test_btx_parallel.sh build-btx

# Dual-node P2P connectivity check
scripts/m12_dual_node_p2p_readiness.sh --build-dir build-btx

# Single-node lifecycle smoke
scripts/m15_single_node_wallet_lifecycle.sh \
  --build-dir build-btx \
  --artifact /tmp/btx-m15-single-node.json \
  --node-label mac-host

Full CI Matrix (Local)

scripts/ci/run_local_mac_matrix.sh all

RPC Interface

BTX exposes a Bitcoin-style JSON-RPC interface. Connect using btx-cli or any compatible Bitcoin-family RPC client library.

Category	Description
Blockchain	Block queries, chain state, UTXO info
Mining	Block templates, generation, submission
Wallet	Address management, sending, receiving, backup
Shielded	z_sendmany, z_shieldcoinbase, z_getbalance, viewing keys
Network	Peer management, banning, network info
Raw Transactions	Transaction creation, signing, decoding

ZeroMQ Notifications

btxd -zmqpubhashtx=tcp://127.0.0.1:28332 \
     -zmqpubhashblock=tcp://127.0.0.1:28332

Network Configuration

Networks

Network	P2P Port	Chain ID	Purpose
Mainnet	19335	`main`	Production network
Testnet	29335	`test`	Public test network
Testnet4	48333	`testnet4`	Updated test network
Signet	38333	`signet`	Custom-challenge test network
Regtest	18444	`regtest`	Local development and testing

DNS Seeds (Mainnet)

node.btx.tools

Current fixed public fallback peers compiled into chainparamsseeds.h:

146.190.179.86:19335
164.90.246.229:19335

Custom Regtest / Devnet Identity

./build/bin/btxd -regtest \
  -regtestmsgstart=0a0b0c0d \
  -regtestport=19444 \
  -regtestgenesisntime=1700001234 \
  -regtestgenesisnonce=42 \
  -regtestgenesisbits=2070ffff \
  -regtestgenesisversion=4

All nodes in a devnet must use the same override tuple.

Architecture

Source Layout

src/
  matmul/               MatMul PoW implementation
    matmul_pow.h/cpp      Solve and verify functions
    field.h/cpp           Finite field arithmetic (F_{2^31 - 1})
    matrix.h/cpp          Matrix operations
    noise.h/cpp           Low-rank noise generation
    transcript.h/cpp      Canonical transcript and compression
  shielded/             Shielded pool core
    bundle.h/cpp          Shielded transaction bundles
    note.h/cpp            Note commitment and nullifier
    validation.h/cpp      Shielded proof verification
    ringct/               MatRiCT direct-spend fallback / failover proof system
    smile2/               SMILE v2 proving stack and launch-hardening work
    v2_bundle.h/cpp       Shielded v2 bundle implementation
    v2_ingress.h/cpp      Shielded v2 ingress proofs
    v2_egress.h/cpp       Shielded v2 egress proofs
    v2_proof.h/cpp        Shielded v2 proof verification
    bridge.h/cpp          Bridge operator helpers
  dandelion.h/cpp       Dandelion++ privacy relay
  libbitcoinpqc/        Post-quantum crypto library (ML-DSA + SLH-DSA)
  pqkey.h/cpp           PQ key generation, signing, verification
  script/pqm.h/cpp      P2MR Merkle hashing, proofs, script building
  consensus/params.h    Consensus parameters (MatMul, ASERT, P2MR, monetary)
  kernel/chainparams.cpp  Network-specific chain parameters
  primitives/block.h    Block header (extended for MatMul fields)
  pow.cpp/h             PoW verification and solving entry points
  validation.cpp        Block and transaction validation
  node/miner.cpp        Block template assembly
  wallet/
    shielded_wallet.h/cpp   Shielded key management, note scanning
    shielded_rpc.cpp        z_* RPC implementations
test/
  functional/           Python functional tests
  fuzz/                 Fuzz testing
scripts/
  build_btx.sh          Convenience build script
  test_btx_consensus.sh Consensus test gate
  test_btx_parallel.sh  Parallel test gate
doc/
  btx-matmul-pow-spec.md    MatMul PoW specification
  btx-pqc-spec.md           Post-quantum script profile
  btx-shielded-pool-guide.md Shielded pool operations guide
  btx-mining-ops.md          Mining operations runbook

Key Differences from Bitcoin

PoW: MatMul PoW replaces SHA-256d. Block headers carry nNonce64, matmul_digest, matmul_dim, seed_a, seed_b.
Post-quantum signatures: Witness v2 P2MR outputs with ML-DSA-44 and SLH-DSA via OP_CHECKSIG_MLDSA / OP_CHECKSIG_SLHDSA.
Shielded pool: Lattice-based confidential transactions active from genesis. Coinbase auto-shield, z_* RPCs, ML-KEM note encryption.
Block time: 90 s (vs. Bitcoin's 600 s).
Difficulty: ASERT per-block adjustment from block 0.
Data limits: BIP 110-style constraints restrict OP_RETURN to 83 bytes and scriptPubKey to 34 bytes, preventing inscription-style data.
Halving: Every 525 000 blocks with 20 BTX initial reward (same 21M cap).
Address format: HRP btx; P2MR btx1z...; shielded btxs1....
Dandelion++ relay: Stem-then-fluff privacy relay (BIP 156) from block 250 000.

Upstream Reference

BTX was forked from Bitcoin Knots v29.2: Bitcoin Knots

Using BTX As A Service Primitive

The RPC surface also supports:

Difficulty and challenge introspection for external products
Useful-work rate limiting
Spam prevention and abuse pricing
AI endpoint admission control
Layered "proof of AI" architectures where BTX gates access and a separate verifiable inference layer proves model execution

Contributing

See CONTRIBUTING.md for development guidelines, coding style, and the PR review process.

Fork the repository
Create a feature branch
Make changes with tests
Run scripts/test_btx_parallel.sh build-btx to verify
Submit a pull request

License

Released under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github		.github
.tx		.tx
ci		ci
cmake		cmake
contrib		contrib
depends		depends
doc		doc
scripts		scripts
share		share
src		src
test		test
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.python-version		.python-version
.style.yapf		.style.yapf
CMakeLists.txt		CMakeLists.txt
CMakePresets.json		CMakePresets.json
CONTRIBUTING.md		CONTRIBUTING.md
COPYING		COPYING
INSTALL.md		INSTALL.md
README.md		README.md
SECURITY.md		SECURITY.md
libbitcoinconsensus.pc.in		libbitcoinconsensus.pc.in
libbitcoinkernel.pc.in		libbitcoinkernel.pc.in
lief.pyi		lief.pyi
vcpkg.json		vcpkg.json

Folders and files

Latest commit

History

Repository files navigation

BTX Node

Table of Contents

Chain Parameters

Block Reward Schedule

MatMul Proof of Work

How It Works

Two-Phase Validation

Parameters by Network

Block Header

Post-Quantum Cryptography

Algorithms

P2MR Design

Script Opcodes

Wallet Integration

Shielded Pool

Production Status

Transaction Types

Auto-Shield Coinbase

Shielded RPCs

Selective Disclosure (View Grants)

Dandelion++ Transaction Relay

How It Works

CTV + CSFS Covenants

Building from Source

Requirements

Linux (Ubuntu/Debian)

macOS

Convenience Script

Build Options

Platform-Specific Guides

Running a Node

Fast-Start Validating Nodes

Starting the Daemon

Configuration

Checking Status

Data Directory

Wallet Operations

Creating a Wallet

Receiving and Sending

Backup

Wallet Encryption

Key Management

Shielded Transfer Builder

Mining

Overview

Regtest Mining (Testing)

Production Mining (getblocktemplate)

Mining Best Practices

Mining RPCs

Genesis Block Generator

Running Tests

Unit Tests

Functional Tests

BTX-Specific Test Gates

Full CI Matrix (Local)

RPC Interface

ZeroMQ Notifications

Network Configuration

Networks

DNS Seeds (Mainnet)

Custom Regtest / Devnet Identity

Architecture

Source Layout

Key Differences from Bitcoin

Upstream Reference

Using BTX As A Service Primitive

Contributing

License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Packages