BTX Node

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

A shielded transaction pool with lattice-based confidential transactions operated from genesis and was closed at height 199300. The remaining shielded balance is treated as burned. Nodes past that height do not maintain shielded state. Do not read this tree as shipping a live shielded pool.

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

v0.34.1 is the base reference implementation. Further enhancements, features, and releases are expected to come from community forks and modifications, not from this repository. That is a handover, not a roadmap.

The two documents that make the handover real, rather than a slogan:

• doc/btx-fork-golden-self-sufficiency.md — how a fork adds its own ExactReplay golden, reseals against its own freeze, and mines without asking this line to bless a device.
• doc/release-process.md — how a third party cuts the next seal, corpus, and tarballs from this code without the original machines or keys.

1. A consensus node validates independently. With no pin, no signers, and no threshold configured, it accepts a block because this node ExactReplay'd it, never because a key signed it.
2. Archives are ADDR-only pointers. They run -matmulvalidation=relay, report chain_oracle=false, and refuse to start if handed a pin, a key, a serve flag, a blocklist, or open attestors.
3. Mining admission is a byte-exact TensorOps self-test, not a device-name string. Any hardware that proves byte-exact INT8→INT32 GEMM qualifies, regardless of vendor.
4. The golden manifest is a local mining-admission belt, not a network blessing. A fork adds its own row, rebuilds, reseals against its freeze, and other nodes ExactReplay the resulting blocks regardless of whose manifest produced them. Do not ask this repository to bless a golden.
5. -miningpeermesh means the mining peer set is no longer hardcoded to operator domains. When set, it replaces the compiled list entirely.
6. Observed in production: the network produced and accepted blocks up to 199328 while both operator nodes sat at 199300. Consensus formed without us.

A handover document that hides remaining dependencies is not a handover.

• Bootstrap still depends on operator-run hosts. The three DNS seeds (node.btx.dev, node.btxchain.org, node.btx.tools) and both compiled fixed seeds in src/chainparamsseeds.h resolve to operator-run machines. New-node introduction currently goes through us. The fix is community-run seeds across distinct ASNs, regenerated into chainparamsseeds.h. That is an invitation, not a future operator deliverable from this repo.
• Trusted-mode nodes follow a pin they configured, not a compiled-in key. That mode is opt-in and only for CPU-only machines that cannot ExactReplay. After v0.34.1 the original operator does not commit to running signers; see Notice to trusted-mirror operators. Consensus miners and GPU full nodes do not use it.

If you run -matmulvalidation=trusted, read this before upgrading.

The pin is your choice, not ours. There is no compiled-in signer key anywhere in this tree — grep chainparams.cpp and you will not find one. Your -matmultrustedpubkey entries and your -matmultrustedthreshold are config lines you own. They point at whichever GPU nodes you decided to trust. If that is currently the original operator's keys, it is because those were the keys that existed, not because the software prefers them.

We are stepping back. After v0.34.1 the original operator no longer commits to running attestation signers. Nodes in trusted mode follow a pin; if the keys you have listed stop signing, your node stops advancing. That is not a defect, it is what delegated validation means.

Your options, in order of preference:

1. Move to -matmulvalidation=consensus. This is the real fix. A consensus node needs no pin, no signers, and no threshold — it accepts a block because this node ExactReplay'd it. It requires a GPU that passes the byte-exact TensorOps self-test. No permission from anyone is involved.
2. Repoint the pin at signers you actually trust. Any GPU node running a local signing key can attest. Configure two independent ones and keep -matmultrustedthreshold=2. Mainnet refuses a 1-of-1 quorum for good reason: a single stolen key would be sole proof-of-work authority for your node.
3. Revoke specific keys without changing your pin using -matmulattestationblocklist=<hex>. Attestations from a blocked key are never counted, even if the key is still listed. It is fail-closed: a block that would leave you below your own threshold is refused.

What a trusted mirror is not. The startup banner says it plainly — a trusted mirror performs ordinary block, body, and script validation but delegates the Profile-1 ExactReplay verdict to a configured quorum. It is not an independently validating full node. That is a reasonable trade for a CPU-only machine. It should be a deliberate choice, not an inherited default.

Consensus miners and GPU full nodes are unaffected by any of this. They never consult a pin.

v0.34.1 is the reference cut of this tree. Seal and freeze hashes are written when the tag is sealed (see doc/release-process.md). The previous tag is v0.34 (seal dc46dee2, freeze ecfaa6c9). Epoch A Profile 1 ExactReplay is live on mainnet at height 185000. EncDr stall recovery at height 199299 is withdrawn. The shielded pool is closed at height 199300. The compiled assumeutxo pin is height 201500 (the 199299 and 199300 pins were on the withdrawn 0.34.1 branch and are removed; see #127). Nodes that already loaded assumeutxo-199300 or assumeutxo-199299 must resync from an empty datadir.

• Release notes
• 0.34.5 convergence notes
• GitHub releases — Linux CPU, Linux CUDA, macOS arm64 Metal
• AssumeUTXO snapshot 201500 (btx-assumeutxo-201500.dat SHA256 08c52c8b34e878c4d48546cfec066bc48fceed51d7287b4ff7ec7b5727cf52c7)

Catch-up on a fresh chainstate (loadtxoutset of assumeutxo-199300 / assumeutxo-199299 is rejected; wipe that datadir and start empty):

btx-cli -rpcclienttimeout=0 loadtxoutset snapshot.dat

Use loadtxoutset, not loadtxoutsetattested. Do not mine on parent ff80e629… — that hash is not on the majority chain.

A node that has fallen behind the majority — inherited datadir, frozen tip, or a parked deep fork — recovers on binary upgrade with no operator action, no invalidateblock, and no snapshot surgery. Header sync walks forward from the batch terminal. GPU ExactReplay budget is spent on the lowest unverified body whose parent is connectable. A stale node (default 600s) may acquire at most two strictly-heavier competing towers out to tip+2048.

Switching onto an acquired deep fork stays gated. A parked deep majority fork is un-parked only once its entire suffix is locally ExactReplay-verified (BLOCK_HAVE_DATA + BLOCK_EXACT_REPLAY_VERIFIED, a bit set only by a local byte-exact re-execution of the block's MatMul PoW). A forged or header-only tower fails that re-execution and stays parked. The depth-6 dump-and-run park is intact.

Recovery is permissionless: the node re-derives majority truth by re-running the GPU-native proof of work, not by trusting a peer, a signed checkpoint, a quorum shortcut, or a CPU oracle. Details: 0.34.5 release notes.

Mainnet Epoch A uses one atomic nMatMulV4Height = nMatMulBMX4CHeight = nMatMulRCHeight = 185000 tuple. Testnet and signet heights remain disabled, as do Epochs B–D, DRLT, and coupled RC. EncDr ExactReplay digest is unchanged (b4777985…).

The transition deliberately separates verification authority from workload size:

1. Epoch A: Profile 1 mining with epsilon-zero ExactReplay required for every claimed block; succinct proofs may run only as optional shadow data.
2. Epoch B: Profile 1 with both a mandatory durable proof and ExactReplay.
3. Epoch C: Profile 1 with the succinct proof as consensus authority; ExactReplay becomes an optional audit.
4. Epoch D: Profile 2 with succinct-proof authority, activated at a separate height with its own workload/difficulty calibration.

Profile 1 is the live ExactReplay epoch. Profile 2 is retained for the later proof-authoritative workload; it is not a routine-replay requirement for Epoch A. The 182-byte digest-only header and header-derived work statement are preserved across the transition. See the canonical transition roadmap and ExactReplay launch-candidate gates.

While Epoch A still uses ExactReplay as consensus authority, public CPU archives follow GPU attestors so the seed layer does not need a GPU on every host. Continuing that topology is community-fork work; this repository is the 0.34.1 reference, not a schedule of further operator releases. Historical notes live in doc/btx-gpu-verified-network-transition.md.

Shielded pool (closed). The pool operated from genesis. At height 199300 it is closed in both directions: no new shielded credits, no shielded spends, remaining balance treated as burned. Nodes past that height do not maintain shielded state. Pre-close history (125000/128000 sunset rules, Smile v2 launch figures, ring-size notes) is documentation of a finished feature, not a live surface. See Shielded Pool.

• 0.34.1 is the base reference. This is a handover.
• Notice to trusted-mirror operators: repoint or move to consensus
• Current release — v0.34.1
• Automatic convergence (0.34.5)
• GPU-verified network (three-phase)
• Chain Parameters
• MatMul Proof of Work
• Post-Quantum Cryptography
• Shielded Pool
• Dandelion++ Transaction Relay
• CTV + CSFS Covenants
• Building from Source
• Running a Node
• Wallet Operations
• Key Management
• Shielded Transfer Builder
• Mining
• Running Tests
• RPC Interface
• Network Configuration
• Architecture
• Contributing
• License

That three-phase topology is community-fork work. This repository is the 0.34.1 reference, not a schedule of further operator releases.

Profile 1 ExactReplay is the Epoch-A consensus check. It needs a qualified GPU. Public IBD/RPC seeds can stay on ordinary VPS hardware only by trusting signed ExactReplay verdicts from GPU attestors. That is an explicit operator-trust topology, not independent validation.

The project is moving that seed layer to GPU ExactReplay in three releases so the public network does not take on unsustainable GPU infra before difficulty, peering, and attestor diversity can carry it:

1. Consensus dump floor + CPU seeds still follow one attestor. Mainnet nBits cannot go easier than compact 0x1f0a3d70 from height 191714 (ASERT half-life 14400 at 191715). P2P catch-up is fixed so CPU archives can pull headers and attestations from the GPU. Still 1-of-1.
2. Add GPU attestors (M-of-N). Repeat -matmultrustedpubkey, raise -matmultrustedthreshold. Archives stay CPU. Independent miners keep talking to seeds. Adding N with M=1 is only availability; M≥2 is what removes a single key as PoW authority.

The live mainnet pin (1-of-2) is published below. GPU attestors and the CPU archives that follow them return the same set from getmatmultrustedstatus / getfinalityinfo (trusted_signer_pubkeys, threshold). P2P seed connect does not push keys — miners pin this set at bootstrap, then confirm it on local RPC after joining node.btx.dev / node.btxchain.org / node.btx.tools.

# Mainnet ExactReplay attestors. Public keys only — never a signer WIF.
matmultrustedpubkey=03d90c148db37da28ce47ce15bade88a177728d663da4bc9ba765943b7d4e4f0aa
matmultrustedpubkey=0224e80df33697385b54b3c69bae1f097f533c0c43e93c29f73ee97319d4a5e04c
matmultrustedthreshold=1

btx-cli getmatmultrustedstatus
# configured=true, threshold=1, trusted_signer_pubkeys = the two hex keys above

A miner that omits this pin cannot see getmatmulattestedtip and getblocktemplate may extend an unattested orphan. Do not load -matmulattestationsignerkeyfile on a miner. 3. Convert public seeds to discovery relays. Each public DNS/addnode host runs -matmulvalidation=relay: ADDR only, no pin, no GETMMATTEST, no NODE_NETWORK. Archives follow GPU attestors via the pin; GPU attestors stay off DNS (-discover=0). See doc/design/0.34-discovery-relay.md.

Full contract, roll order, and what is not dropped (Epochs B–D, light clients, nBits as difficulty): doc/btx-gpu-verified-network-transition.md. Trusted-mirror mechanics: doc/btx-matmul-trusted-rpc-mirrors.md.

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.

MatMul v4.7 Resident Curriculum — Epoch A is live at height 185000. The implementation preserves the 182-byte digest-only header and a header-derived work statement, but divides the consensus change into four separately activated epochs:

• A: Profile 1 with epsilon-zero ExactReplay authority and optional shadow proofs.
• B: Profile 1 with a mandatory durable proof and ExactReplay.
• C: Profile 1 with the succinct proof as authority; ExactReplay becomes optional audit policy.
• D: Profile 2 with proof authority and an atomic workload/difficulty recalibration.

Profile 1 is four sequential rounds, 16 FFN layers, b_seq=16,384, and T_leaf=1,024. Profile 2 is approximately 16 times heavier and is not a routine validator requirement at launch. Sampled/Freivalds carriers and unfinished GKR/FRI machinery are never allowed to silently become authority. Mainnet schedules Epoch A at the release-selected atomic H_A (v4 = BMX4C = RC, with a final-binary RC ASERT rescale); testnet and signet heights remain disabled, and Epochs B–D require separate future activation heights. See the canonical roadmap and Epoch-A launch gates.

The Epoch-A consensus oracle is full Profile 1 ExactReplay. Accelerated implementations must be byte-identical to the portable reference. In production strict-device mode, a device mismatch is a local accelerator failure: the block remains retryable and the announcing peer is neither punished nor given a cached invalid verdict. It does NOT quarantine the provider -- a sole device disagreement cannot take a healthy provider out of service (IsUnconfirmedMismatch); only an ExecutionFailure is quarantinable (IsQuarantinableExecutionFailure, src/matmul/matmul_v4_rc_gkr.cpp). The portable oracle is available only through the explicit pre-activation auto-fallback or offline cpu-diagnostic policies; it is not an automatic inline production retry.

Build with full acceleration. The portable CPU path remains the deterministic oracle, not the Epoch-A performance baseline:

# CUDA (e.g. sm_120 / Blackwell-class; see src/CMakeLists.txt for native MXFP4 recipes)
cmake -B build -DBTX_ENABLE_CUDA_EXPERIMENTAL=ON -DBTX_CUDA_ARCHITECTURES=120
# AMD ROCm/HIP and Apple Metal are selected the same way via their backend TUs.
cmake --build build -j

Select the mining backend (auto-detects the best admissible device by default; override per run):

BTX_MATMUL_V4_BACKEND=auto   # developer convenience; may resolve to CPU
BTX_MATMUL_V4_BACKEND=cuda   # request a specific backend
BTX_MATMUL_V4_BACKEND=cpu    # force the portable scalar path

Production qualification must additionally require the requested backend and fail on any fallback; selecting a backend name without checking device coverage telemetry is not certification.

Benchmark Profile 1 end to end:

cmake --build build --target matmul-v4-rc-harness
BTX_MATMUL_V4_BACKEND=metal \
  build/bin/matmul-v4-rc-harness \
  --base-production --episodes 100 --backend metal \
  --source-revision "$(git rev-parse --short=12 HEAD)" \
  --out profile1-metal-loaded-100.json

Use the strict CUDA equivalent on NVIDIA. Activation review requires at least 100 continuous dimension-bound samples, frozen cross-machine digest parity, and actual-consensus back-to-back/reorg scenarios—not a toy run, sampled carrier timing, or a Profile 2 replay.

1. Seed derivation: Two deterministic seeds (seed_a, seed_b) are derived from the previous block hash and current height. Miners cannot choose favorable matrices.

2. Matrix generation: Seeds expand into two n x n matrices (A, B) over F_q.

3. 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.

4. Matrix multiplication: The miner computes C' = A' x B' — a standard dense matrix product.

5. Transcript hashing: The result is canonicalized into block-sized chunks, compressed with a deterministic vector, and hashed with SHA-256.

6. Difficulty check: If the transcript hash meets the target, the block is valid.

• 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. The current source of truth for that transition and its regression coverage is doc/btx-matmul-product-digest-mining-fix-2026-04-03.md.

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.

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

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 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....

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

• 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:

• doc/btx-pqc-spec.md
• doc/btx-pq-multisig-spec.md
• doc/btx-pq-multisig-tutorial.md
• doc/btx-key-management-guide.md
• doc/falcon-softfork-readiness-analysis-2026-03-29.md

BTX had a shielded transaction pool, active from genesis, using lattice-based zero-knowledge proofs. As of height 199300 the pool is closed in both directions. The remaining shielded balance is treated as burned. Nodes past that height do not maintain shielded state, do not accept shielded transactions, and do not run shielded proving or verification as live work. Coinbase auto-shielding is inert on mainnet past the close (-autoshieldcoinbase does not reopen the pool).

The shielded pool's value soundness is covered by a tiered formal-verification suite — an accounting firewall (turnstile / supply floor / velocity cap), the C-002 verifier-relation bindings (serial↔key and value/inflation), and a reduction of forgery hardness to Module-SIS — with 21 machine-checked obligations plus paper-rigorous proofs per tier. See formal-verification/PLAN.md (run python3 formal-verification/run_all.py).

As of 2026-03-23, the pre-sunset reset-chain launch architecture was:

• 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 pre-sunset 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.

Those pre-close sunset rules (block 125000 / 128000) are historical. Height 199300 is the close: both directions disabled, remaining balance burned, no shielded state on nodes past that height.

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 measured launch-surface figures on the pre-61000 baseline surface are:

• headline mixed-L1 throughput at a 50/50 block-space split between direct 1x2 v2_send and a canonical transparent 1-in/2-out P2MR send: 3,263 tx/block, about 36.26 TPS at 90 s (199 shielded + 3,064 transparent)
• proofless deposit v2_send (prefork compatibility only; not part of the post-61000 direct-send readiness surface): 19,172 bytes, 221 ms sample build, 1,251 tx/block (13.90 TPS at 90 s)
• live wallet 1x2 v2_send: 60,218 bytes, 22.71 s sample wallet first-prove, 398 tx/block at the 24 MB serialized cap.
• canonical redesign-report 1x2 v2_send: 60,110 bytes, 51,099 proof bytes, 10.20 s build, 304.26 ms verify, 399 tx/block.
• 2x2 v2_send: 70,272 bytes, 61,091 proof bytes, 7.29 s build, 481.09 ms verify, 341 tx/block.
• 2x4 v2_send: 101,918 bytes, 84,111 proof bytes, 5.09 s build, 538.55 ms verify, 235 tx/block.
• mixed unshield v2_send (prefork compatibility only; post-61000 unshield moves to bridge/egress): 44,330 bytes, 10.88 s sample build, 541 tx/block (6.01 TPS)
• Smile ingress 63 leaves / 8 spends / 8 proof shards / 1 reserve: 312,364 bytes, 281,622 proof bytes, 109.86 s build, 5.69 s verify, 76 tx/block (4,788 represented ingress leaves / block at the proven launch ceiling).
• 32-output v2_egress: 470,168 bytes, 433 proof bytes, 463.14 ms full pipeline, 9.99 ms verify, 51 tx/block (1,632 represented outputs / block).
• representative rebalance / settlement capacity from the live netting report:
  • 32x95: rebalance 38,073 bytes / 6,880 proof bytes / 2.63 ms build / 0.36 ms validate / 630 tx/block
  • 64x99: rebalance 75,753 bytes / 13,760 proof bytes / 6.22 ms build / 0.63 ms validate / 316 tx/block
  • settlement anchors remain 433 proof bytes and scale to 2,400 tx/block by shielded verify units

These are the current measured launch-surface figures for the reset-chain Smile-default protocol. For the current architecture, readiness report, and benchmark details, see doc/btx-shielded-production-status-2026-03-20.md. For the completed genesis-reset launch checklist, see doc/btx-smile-v2-genesis-readiness-tracker-2026-03-20.md. For the post-launch proof-size / TPS optimization workstream built on that baseline, see doc/btx-smile-v2-optimization-tracker-2026-03-21.md and doc/btx-postlaunch-optimization-roadmap.md. For the shielded hardening fork at 61000, audit closeout, and remaining security roadmap, see doc/security/README.md. For the transaction-family migration and mixed send benchmark details, see doc/btx-smile-v2-transaction-family-transition-2026-03-23.md. The mixed headline assumes a 24 MB serialized block cap, 90 s target block time, 12 MB reserved for direct 1x2 v2_send at 60,218 bytes, and 12 MB reserved for a measured transparent witness_v2_p2mr send at 3,916 bytes.

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

Automatic coinbase shielding is disabled by default. If an operator explicitly starts a pre-sunset test or compatibility node with -autoshieldcoinbase=1, the wallet may sweep mature coinbase outputs before shielded pool credits are disabled. At and after the configured pool-credit disable height (125000 on mainnet), the wallet auto-shield path is inert to avoid building transactions consensus will reject.

# Default production behavior: leave auto-shield off.
btxd

# Historical/pre-sunset compatibility only.
btx-cli z_shieldcoinbase

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. For the focused bridge view-grant production gate, see doc/btx-bridge-view-grants-readiness.md.

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

1. 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).

2. 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.

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

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

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.

• 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).

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)

brew install cmake boost libevent sqlite pkg-config

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

scripts/build_btx.sh build-btx

Use the BTX Windows wrapper for a native Windows 11 build:

powershell -ExecutionPolicy Bypass -File .\contrib\devtools\build-btx-windows.ps1 `
  -InstallDependencies

That wrapper bootstraps a short-path standalone vcpkg, builds a wallet-enabled headless node, and runs a regtest smoke test. See doc/btx-windows-11-compile-handbook.md for the step-by-step handbook and doc/build-windows-msvc.md for the full Windows build walkthrough.

For native CLI release assembly without Guix, see scripts/release/cut_local_release.py together with doc/btx-github-release-automation.md. For the prepackaged Linux CPU/CUDA release matrix, supported GPU hardware, and target-host driver requirements, see doc/linux-release-builds.md.

If you only need the generic precompiled Windows x64 CLI archive from this branch, use the files in contrib/prebuilt/windows/.

• Linux/Unix
• macOS
• Windows (MinGW)
• Windows (MSVC)
• Windows 11 Step-by-Step Handbook
• FreeBSD

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

Fast-start support in the current tree:

• main: supported; compiled assumeutxo heights through 201500 (3dd0fa67…). Load https://github.com/btxchain/btx/releases/download/assumeutxo-201500/btx-assumeutxo-201500.dat with loadtxoutset on a fresh chainstate. Do not load assumeutxo-199300 (ff80e629…) or assumeutxo-199299 (f12a27d0…); those bases are on the withdrawn 0.34.1 branch and 0.34.5 rejects them. A node that already loaded one of those pins must resync from an empty datadir.
• regtest: supported for default-consensus development and CI flows
• testnet, testnet4, and signet: snapshot tooling exists, but there are no compiled assumeutxo entries yet, so fast-start bootstrap is not currently supported there

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 v0.33.4.2 \
  --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.

# Foreground
./build/bin/btxd

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

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

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

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
retainshieldedcommitmentindex=1
dnsseed=1
fixedseeds=1
addnode=node.btx.dev:19335
addnode=node.btxchain.org:19335
addnode=node.btx.tools: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

The baseline config keeps retainshieldedcommitmentindex=1 so shielded wallets and assumeutxo-backed nodes restart without rebuilding the commitment lookup index from historical shielded data. Set it to 0 only if you intentionally want the slower externalized-retention posture.

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

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

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

For the separately deployed browser wallet, public gateway, and detached document-signing security boundary, see doc/browser-wallet-backend.md. Node JSON-RPC must remain private; browser code never receives RPC credentials.

# 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}]'

# 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"

# Restore a browser self-custody .btxwallet JSON bundle
btx-cli restorewalletbundle "webwallet" "/path/to/btx-wallet.btxwallet.json"

# Or import that browser bundle into an existing blank descriptor wallet
btx-cli -rpcwallet=webwallet importwalletbundle "/path/to/btx-wallet.btxwallet.json"

# Export a native descriptor wallet as a browser-compatible .btxwallet file
# This file contains plaintext PQ master seed material.
btx-cli -rpcwallet=mywallet exportwalletbundle "/path/to/mywallet.btxwallet.json"

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.

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:

• doc/btx-key-management-guide.md
• doc/btx-pq-multisig-tutorial.md
• doc/managing-wallets.md
• doc/btx-shielded-pool-guide.md
• doc/external-signer.md

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

• contrib/shielded_transfer_builder.py

The builder exposes four explicit phases:

1. plan
2. simulate
3. execute
4. 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

This flow is historical/pre-sunset only. After the v0.32 sunset, new shielded credits are disabled by consensus; do not use z_fundpsbt or bridge ingress as current production shielded ingress.

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.

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.

./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)

After the node is up and peering with the public seed/archive mesh, treat the attestor set as a normal bootstrap check — same class of pin as DNS seeds, not a secret:

1. Join the published seeds (dnsseed=1, addnode=node.btx.dev:19335, …).
2. Have the two -matmultrustedpubkey lines and -matmultrustedthreshold=1 in btx.conf (miner fast-start writes them).
3. Ping local RPC: getmatmultrustedstatus must show configured=true and the same trusted_signer_pubkeys / threshold the archives and GPU attestors return. getfinalityinfo repeats the pubs.
4. Then call getblocktemplate. A unique attested child of tip means follow getmatmulattestedtip instead of grinding an unattested twin.

P2P addnode / DNS seeds do not serve RPC. You confirm the pin on your btx-cli, or on an archive/attestor RPC you already control. Do not take signer pubs from a random remote RPC.

contrib/faststart --preset miner writes this pin and checks it after RPC is ready. contrib/devtools/gen-btx-node-conf.sh writes it too.

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

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

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

• Keep the node healthy and near tip before mining. getmininginfo exposes a chain_guard section that reports peer count, near-tip peers, freshness windows, mesh refresh settings, and a recommended action for operators.
• 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 warnings.
• 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

./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).

To run btxd with CUDA selected as the MatMul backend on a CUDA-enabled build:

BTX_MATMUL_BACKEND=cuda ./build/bin/btxd \
  -datadir="$HOME/.btx" \
  -server=1

CUDA builds automatically detect all supported visible NVIDIA devices and use them for host-prepared MatMul digest batches. For multi-GPU selection, weighting, and per-device pool-slot tuning, see doc/btx-cuda-multi-device.md.

To verify that the local CUDA backend is compiled and runtime-ready:

./build/bin/btx-matmul-backend-info --backend cuda

Prepackaged Linux releases include separate CPU-only, CUDA 12, and CUDA 13 archives. See doc/linux-release-builds.md for the archive names, supported GPU targets, and NVIDIA driver requirements.

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

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

# 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 lifecycle matrix smoke
scripts/m15_full_lifecycle_matrix.sh \
  --build-dir build-btx \
  --centos-build-dir build-btx-centos \
  --artifact /tmp/btx-m15-matrix.json \
  --log-dir /tmp/btx-m15-matrix-logs

Typical pass markers: M15 single-node lifecycle checks passed (mac-host): Overall status: pass

scripts/ci/run_local_mac_matrix.sh all

For changes touching src/libbitcoinpqc/**, also run the local fuzz smoke recipe before merge:

cd src/libbitcoinpqc/fuzz
make fuzz-smoke

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

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

node.btx.tools

Current fixed public fallback peers compiled into chainparamsseeds.h:

146.190.179.86:19335
164.90.246.229:19335

./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.

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

1. PoW: MatMul PoW replaces SHA-256d. Block headers carry nNonce64, matmul_digest, matmul_dim, seed_a, seed_b.
2. Post-quantum signatures: Witness v2 P2MR outputs with ML-DSA-44 and SLH-DSA via OP_CHECKSIG_MLDSA / OP_CHECKSIG_SLHDSA.
3. Shielded pool: Lattice-based confidential transactions active from genesis, with new shielded credits disabled at the v0.32 sunset. Auto-shield is default-off and inert after the pool-credit disable height.
4. Block time: 90 s (vs. Bitcoin's 600 s).
5. Difficulty: ASERT per-block adjustment from block 0.
6. Data limits: BIP 110-style constraints restrict OP_RETURN to 83 bytes and scriptPubKey to 34 bytes, preventing inscription-style data.
7. Halving: Every 525 000 blocks with 20 BTX initial reward (same 21M cap).
8. Address format: HRP btx; P2MR btx1z...; shielded btxs1....
9. Dandelion++ relay: Stem-then-fluff privacy relay (BIP 156) from block 250 000.

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

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

v0.34.1 is the reference. Further features and releases are expected from community forks, not from this repository. See the handover at the top of this file, then doc/btx-fork-golden-self-sufficiency.md and doc/release-process.md.

Do not open a PR against this repository whose purpose is “please bless our golden” or “please ship our next feature as an official release.” Fork, measure, seal, ship.

Coding style for anyone working in a fork still lives in CONTRIBUTING.md.

Released under the MIT License.

Copyright (c) 2009-2025 The Bitcoin Core developers Copyright (c) 2026 The BTX developers