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 factory
initializeMessages();

// Create a peer manager
final peerManager = PeerManager(
  network: BitcoinNetwork.regtest,
  logger: Logger('MyApp'),
);

// Connect to a Bitcoin node
final 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 headers
class MyWalletHandler implements PeerHandlerI {
  @override
  Future<void> handleHeaders(WireMessage msg, PeerI peer) async {
    final headers = msg as MsgHeaders;
    print('Received ${headers.headers.length} headers');
    // Store headers for SPV validation
  }
  
  // ... implement other required methods
}

// Configure for efficient SPV synchronization
const spvConfig = PeerConfig(
  startHeight: 50000,  // Your current chain tip
  userAgent: '/my-spv-wallet:1.0/',
  enablePingPong: true,
);

// Option 1: Default handler for all peers
final 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 override
await 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