SpiffyNode

A high-performance BitcoinSV P2P client library written in Dart, designed for building Bitcoin applications, SPV wallets, and blockchain infrastructure.

Features

• Full Bitcoin P2P Protocol - Complete implementation of BitcoinSV wire protocol
• SPV Node Support - Efficient Simplified Payment Verification with configurable chain tips
• Custom Message Handlers - Install per-peer or default handlers to capture and process Bitcoin protocol messages
• High-Performance Networking - Asynchronous message handling with priority queuing
• Peer Management - Automatic peer discovery, connection management, and health monitoring
• Message Framework - Extensible wire message system supporting all Bitcoin protocol messages
• Chain Tip Tracking - Built-in SPV chain synchronization and block header management
• Production Ready - Comprehensive error handling, logging, and connection resilience

Architecture

SpiffyNode is built with a layered architecture:

┌─────────────────────────────────────┐
│ Application Layer │ Your Bitcoin App
├─────────────────────────────────────┤
│ Peer Management │ PeerManager, PeerHandler
├─────────────────────────────────────┤
│ Protocol Layer │ Handshake, Message Processing
├─────────────────────────────────────┤
│ Wire Protocol │ Bitcoin Messages (version, block, tx, etc.)
├─────────────────────────────────────┤
│ Network Layer │ TCP Connections, Message Queue
└─────────────────────────────────────┘

Use Cases

• SPV Wallets - Lightweight Bitcoin wallets for mobile/desktop apps
• Blockchain Explorers - Real-time Bitcoin network monitoring
• Mining Pool Software - Pool management and block distribution
• Payment Processors - Bitcoin payment verification and processing
• Research Tools - Bitcoin network analysis and monitoring
• IoT Devices - Minimal footprint Bitcoin nodes for embedded systems

Quick Start

Installation

Add to your pubspec.yaml:

dependencies:
spiffynode: ^0.1.0

Basic Usage

import'package:spiffynode/spiffy_node.dart';
// Initialize the message factoryinitializeMessages();
// Create a peer managerfinal peerManager =PeerManager(
network:BitcoinNetwork.regtest,
logger:Logger('MyApp'),
);
// Connect to a Bitcoin nodefinal peer =await peerManager.addPeerByAddress(
'127.0.0.1', 18444,
peerConfig:PeerConfig(
startHeight:1000, // For SPV: sync from block 1000
userAgent:'/MyApp:1.0/',
),
);
await peer.connect();
print('Connected to Bitcoin network! 🎉');

SPV Node Example

// Custom handler for capturing block headersclassMyWalletHandlerimplementsPeerHandlerI {
@overrideFuture<void> handleHeaders(WireMessage msg, PeerI peer) async {
final headers = msg asMsgHeaders;
print('Received ${headers.headers.length} headers');
// Store headers for SPV validation
}
// ... implement other required methods
}
// Configure for efficient SPV synchronizationconst spvConfig =PeerConfig(
startHeight:50000, // Your current chain tip
userAgent:'/my-spv-wallet:1.0/',
enablePingPong:true,
);
// Option 1: Default handler for all peersfinal peerManager =PeerManager(
network:BitcoinNetwork.mainnet,
handler:MyWalletHandler(), // All peers use this handler
);
await peerManager.addPeerByAddress(
'bitcoin-node.example.com', 8333,
peerConfig: spvConfig,
);
// Option 2: Per-peer handler overrideawait peerManager.addPeerByAddress(
'special-node.example.com',
8333,
peerConfig: spvConfig,
handler:MySpecialHandler(), // This peer uses a different handler
);

Documentation

• API Documentation - Comprehensive API reference
• Examples - Working code examples
• Implementation Roadmap - Development status

🛠️ Development

Running Tests

dart test

Running Examples

# Start a local BitcoinSV regtest node first
dart run example/simple_peer_example.dart

Bitcoin SV Networks Supported

• Mainnet - Production Bitcoin network
• Testnet - Bitcoin test network
• Regtest - Local regression testing
• Simnet - Simulation network

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: API Docs