Network

Publish and resolve large verified UHRP content with CHIRP, or connect to Teranode's P2P network and subscribe to real-time blockchain events.

Packages in this Domain

Package	Purpose
@bsv/chirp	Progressively publish and resiliently resolve BRC-167 chunked Merkle content over UHRP
@bsv/teranode-listener	Subscribe to Teranode P2P topics via libp2p DHT with gossipsub pub/sub messaging

What You Can Do

• Listen for new blocks — Real-time block solution events from Teranode
• Monitor subtree updates — Track subtree creation and validation
• Track mining status — Subscribe to mining enabled/disabled events
• Monitor peer connections — Handshake messages from connecting peers
• Detect rejected transactions — Receive txid of transactions rejected by network
• Custom topic subscription — Dynamic add/remove of topic callbacks at runtime
• PNET-compatible DHT participation — Join mainnet with its public compatibility value or configure a private network PSK

Key Concepts

• PNET DHT — Uses a 32-byte PNET value for network compatibility; the published mainnet value is not authentication
• Gossipsub — Efficient pub/sub messaging layer for blockchain event distribution
• Topic-based subscriptions — Subscribe to specific events (bitcoin/mainnet-block, bitcoin/mainnet-subtree, etc.)
• Bootstrap peers — Known entry points for discovering other peers in the network
• Static peers — Explicitly configured peers maintained for reliable connectivity
• Peer discovery — libp2p Kademlia DHT discovers peers dynamically
• Callbacks — Each topic has own async message handler for processing events
• Message format — Events arrive as raw Uint8Array; caller deserializes (typically BSV transactions/blocks)
• Trust boundary — Topic messages, sender names, and propagation peers are untrusted until application claims are independently verified

When to Use

Use network packages when you need to:

• Monitor real-time blockchain events
• React to new blocks as they arrive
• Track peer connectivity and network health
• Run an overlay service that listens for transactions
• Build applications that need live blockchain state updates

When NOT to Use

• For transaction broadcasting — use transaction submission endpoints
• For historical queries — use indexers or explorer APIs
• For UTXO lookups — use full-node RPC or @bsv/overlay lookup services
• Without requirement for real-time updates — use batch query APIs

Architecture Overview

Topics Available

Topic	Event
bitcoin/mainnet-bestblock	Best block message
bitcoin/mainnet-block	Block solution found
bitcoin/mainnet-subtree	Subtree created
bitcoin/mainnet-mining_on	Mining enabled
bitcoin/mainnet-handshake	Peer connects
bitcoin/mainnet-rejected_tx	Transaction rejected
bitcoin/testnet-*	Testnet equivalents

Next Steps

• @bsv/teranode-listener — Real-time blockchain event subscription
• @bsv/overlay — Indexing service integration
• @bsv/sdk — Transaction/block deserialization