Net signed obligations first. Move only the remainder. Deliver both assets or deliver neither.
BNNS is an application-layer protocol for Bitcoin-native clearing and Delivery versus Payment (DvP). Participants agree exact integer amounts, calculate the same net positions, and sign the same settlement plan. No clearing operator can rewrite the result or take custody of their funds.
Status: research prototype. Deterministic clearing, a durable local orchestrator, and the existing upstream Taproot Assets bilateral swap are executable today. BNNS has reproduced that swap on isolated regtest; it did not invent it. Real net-only settlement after multiple trades, multi-party settlement, and Lightning settlement are not implemented. Do not use with real funds.
| Current pain | BNNS result |
|---|---|
| Every gross trade consumes liquidity | Compatible obligations are netted; only final deficits move |
| Payment can settle while delivery fails | Both asset legs share one atomic Bitcoin transaction in phase 1 |
| A clearing house owns the authoritative ledger | Every participant recomputes and signs the exact result |
| Margin engines depend on manipulable market prices | Exact quantities are signed; there is no mark-to-market or liquidation |
| A scheduler or operator can halt settlement | Block heights define sessions; any peer can reproduce a proposal |
| Payment and acknowledgement live in separate databases | A payment agent may add an optional receipt asset to the DvP exchange |
| Internal reconciliation is hard to audit | Trades, clearing results, plans, and evidence are content-addressed |
The core use case is repeated trading or payment flow where gross turnover is large but each participant's final obligation is small. BNNS preserves the signed trade history while transferring only the net result.
This is a narrow market condition, not an assumed market. Taproot Assets and USDt-on-Lightning announcements are encouraging ecosystem signals, but public evidence of dense offsetting flows that need a separate clearing layer is still insufficient. BNNS must validate demand against existing asset payments, swaps, Spark, custodial internal netting, and legal netting arrangements. See Adoption and commercial boundaries.
Five Bells publicly described a Bitcoin-native institutional DvP settlement layer in March 2026, before the first BNNS research commit on 20 August 2026. Its public materials also describe trade compression, clearing, and bilateral acceptance of final net movements. BNNS therefore does not claim priority for Bitcoin-native DvP, clearing, trade compression, or netting as broad ideas.
The narrower BNNS research delta is participant-recomputed clearing of exact signed obligations into one participant-approved net vector and, eventually, net-only BTC/Taproot Asset DvP without a fiat leg or authoritative clearing operator. Five Bells publicly describes a commercial institutional platform using Taproot FROST escrow and bank or custodian integrations for BTC against fiat or stablecoin settlement. These are overlapping problems with different published trust and execution boundaries, not proof that either implementation is equivalent to the other.
See Five Bells and the BNNS priority boundary and References and related work.
Netting may also avoid unnecessary on-chain transactions and therefore disclose fewer new settlement graph edges than gross settlement. This is not UTXO "cleansing": BNNS does not erase provenance, remove risk labels, guarantee anonymity, or mix unrelated coins. See Pain points and benefits.
The bilateral primitive can also support a market narrower than Bisq or RoboSats: BTC for Taproot Assets only, with no fiat leg. Since wallet software can verify both transferred assets, settlement does not need a trusted coordinator, fiat-payment evidence, or human arbitrator. Offers can be copied across replaceable relays while counterparties verify and settle directly.
See BNNS Market for the product profile, comparison, failure behavior, and implementation limits. It is a design and regtest prototype, not a production exchange.
The repository contains four independently testable layers:
- Deterministic clearing: integer accounting, solvency checks, netting, and a minimal transfer plan.
- Durable orchestration: a SQLite-backed lifecycle for sessions, trades, clearing commitments, settlement evidence, and aborts.
- Upstream bilateral on-chain DvP: a pinned Taproot Assets v0.8.1 regtest case that minted 5,000 units and exchanged them for 69,420 satoshis in one Bitcoin transaction. A tampered offer was rejected. This proves the reused settlement primitive, not a BNNS-specific invention.
- Local MVP: a localhost wallet and market with test-only BIP-340 signed offers, bilateral trade signatures, participant-signed clearing plans, actual/reserved/planned balances, session netting, a minimal transfer plan, simulated DvP, the real pinned regtest harness, and an audit log.
python3 -m unittest discover -s tests -v
scripts/verify-environment.sh
scripts/run-upstream-dvp-itest.sh all
scripts/run-mvp.shThe integration harness is isolated from the user's Bitcoin node and keeps all
mutable data under /Volumes/Storage/Projects/bnns-runtime by default. See
regtest evidence and limitations.
A separate repeated-trade vector proves the clearing arithmetic reduces two opposing bilateral trades to one BTC transfer and one asset transfer. It does not yet construct that net-only plan as a real Taproot Assets PSBT. See the claims and maturity matrix.
flowchart LR
A[Exact signed trades] --> B[Block-height session]
B --> C[Deterministic net positions]
C --> D[Participant-signed plan]
D --> E[Atomic BTC / Taproot Asset DvP]
D --> F[No broadcast if incomplete]
- A trade identifies the assets and exact integer amounts. Price discovery happens between participants, not inside BNNS.
- A session opens and closes at Bitcoin block heights.
- Every peer sorts the same trade IDs and independently calculates the same net positions and transfer plan.
- A settlement component becomes final only when every affected participant signs its exact commitment.
- The reused Taproot Assets phase-1 primitive uses one Bitcoin PSBT. The asset seller commits to the exact BTC payment output; the buyer supplies BTC and replaces the asset destination with the buyer's key. Both legs confirm together or the offer is never broadcast.
There is no leverage or negative balance. Incoming value inside the same atomic component may fund outgoing value, but every final per-asset balance must remain non-negative. This is liquidity-saving net settlement, not credit.
BNNS treats a Taproot Asset ID as an identifier, not as a promise about value. Subject to the issuer's terms and applicable law, a token can represent:
- a currency or stable-value claim such as USDT where supported;
- a bank-money or digital-ruble claim issued by an authorized party;
- a security, commodity, fund unit, ticket, entitlement, or warehouse receipt;
- a claim on any other underlying asset the issuer defines.
BNNS makes delivery of the token atomic with payment. It does not prove the issuer's reserves, authority, solvency, redemption performance, or legal status. A private token referring to a digital ruble is not the official digital ruble.
A Settlement Receipt Asset (SRA) is a separate, optional profile for payment services. It may have zero nominal monetary value and bind an invoice hash, merchant key, terms version, and service event to a payment. This can serve as a portable receipt or workflow trigger.
Ordinary BNNS assets are not expected to have zero nominal value. An SRA is useful only when a wallet-held token adds value; otherwise a signed message is cheaper. See asset model and Settlement Receipt Assets.
The BNNS core uses no market-price oracle:
- counterparties sign exact asset quantities;
- Bitcoin supplies block height and transaction finality;
- there is no mark-to-market, margin call, liquidation, or price-triggered transfer;
- the current DvP transaction needs no external factual attestation.
An application exchanging a token for a physical delivery or another external event may separately require an attestor, dispute process, or legal enforcement. That mechanism is outside BNNS core and must not be described as oracle-free. Issuer redemption risk is also outside the protocol.
Version 0.1 requires no Bitcoin consensus change and no privileged clearing server. It does not create a global permissionless consensus: a known set of counterparties signs each affected component. Relays, matchers, and proposal nodes are replaceable. They may harm liveness by withholding data, but they cannot create participant signatures, change a signed trade, or spend participant funds.
This is a safety guarantee, not an execution guarantee. A participant may refuse to sign after seeing a clearing result. The affected component then aborts and loses its netting benefit; BNNS cannot compel settlement without a separate pre-commitment, collateral, covenant, or legal mechanism. Remaining participants may approve a new smaller commitment, but no proposer may silently remove trades from an existing signed trade-set root.
This holdout also creates a temporary free option: after market conditions move, the economically losing participant may prefer not to sign while honest peers lose time and reserved liquidity. Epoch Netting is therefore most plausible for bounded groups with repeated relationships, admission policy, and reputational or contractual consequences outside the protocol. BNNS trades permanent operator/custody risk for this explicit liveness risk; it does not eliminate risk.
An optional Bonded Channel Netting Profile is proposed for repeated counterparties. Trades and state updates remain off-chain; a trade becomes committed only when the resulting state is fully authorized for cooperative or unilateral exit. Successful close still moves only final net positions. The required trade reserve is the outgoing net deficit, not gross turnover; a fixed performance bond and close-fee reserve are separate.
The bond is not magic insurance. Silence cannot be blamed objectively, so core BNNS does not confiscate a deposit merely because a deadline passed. Penalties require a cryptographic predicate such as a conflicting signature or a revoked state. See Holdout and bonded sessions.
Re-clearing without an unavailable participant is a fresh opt-in lineage, not a finding of fault. Retries must be bounded to prevent a near-zero-cost recompute-and-resign griefing loop. BNNS is also not an RFQ replacement or an ordinary asset channel: its delta is deterministic netting of many signed obligations into one net vector and DvP plan; channel machinery is a possible enforcement layer for that result.
When enabled, re-clearing uses a SessionPolicy bound through session_id with
max_reclear_attempts, signing_window_blocks, and fallback_policy. Omitting
the policy disables re-clearing, so the current non-retrying v0.1 path remains
unchanged.
The implemented on-chain phase uses existing PSBT, Taproot, Schnorr sighash, and Taproot Assets mechanisms. Lightning HTLC/time-lock settlement and bounded multi-party components are future work, not claims about the current prototype.
export BNNS_DB=/Volumes/Storage/Projects/bnns-runtime/orchestrator/demo.sqlite
rm -f "$BNNS_DB"
python3 reference/orchestrator.py --db "$BNNS_DB" create-session \
examples/orchestrator-session.json
python3 reference/orchestrator.py --db "$BNNS_DB" add-trade \
examples/orchestrator-trade.json
python3 reference/orchestrator.py --db "$BNNS_DB" clear \
bnns-demo-session --height 110See orchestrator scope. Public tapd, lnd, and Bitcoin
Core RPC integration is the next engineering milestone; the current coordinator
does not hold keys or pretend to verify a transaction it has not queried.
The product MVP is available at http://127.0.0.1:8765 after running
scripts/run-mvp.sh. It explicitly labels its built-in settlement as a
simulation and hard-blocks mainnet. See MVP guide.
- Architecture
- Claims and implementation maturity
- Adoption and commercial boundaries
- Pain points and benefits
- Five Bells and the BNNS priority boundary
- Holdout and bonded sessions
- Asset model
- Threat model
- BNNS-0001 draft specification
- Development orchestrator
- Bilateral DvP regtest
- Coordinator-free P2P market
- Local product MVP
- Roadmap
- References
- Community review strategy
BNNS v0.1 is not a custodial exchange, lending protocol, oracle, stablecoin issuer, proof of off-chain delivery, or production-ready financial system.
MIT. See LICENSE.