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

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

final peer = Peer(
  address: 'bitcoin-node.example.com',
  port: 8333,
  network: BitcoinNetwork.mainnet,
  config: spvConfig,
  handler: MyWalletHandler(),
);

await peer.connect();

📚 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 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
• Discussions: GitHub Discussions
• Documentation: API Docs

---

Built with ❤️ for the Bitcoin ecosystem