spiffynode 1.1.0

A Dart library for connecting to the BitcoinSV P2P network

Changelog

All notable changes to the SpiffyNode project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.1.0 - 2026-03-22

Added

• Custom Handler Support: Added per-peer handler support to PeerManager.addPeerByAddress() method
  • New optional handler parameter allows overriding the default handler for individual peers
  • Handler priority: per-peer handler > default PeerManager handler > chain tip tracking only
  • Enables SPV wallets to capture MsgHeaders responses for block header validation
  • Updated addPeersByAddresses() extension method to support handler parameter
  • All custom handlers are automatically wrapped with chain tip tracking for SPV support
• Documentation: Added comprehensive handler usage examples in API-DOCS.md
  • Three handler patterns: default handler, per-peer override, and LibSpiffy SPV pattern
  • New example file: example/custom_handler_example.dart demonstrating all handler patterns
  • Updated SPV wallet examples to show handler integration

Changed

• PeerManager.addPeerByAddress() now accepts optional handler parameter for per-peer customization
• Updated internal _createCompositeHandler() method to support handler priority system

1.0.0 - 2025-01-27

🎉 Initial Release - Full BitcoinSV P2P Client

SpiffyNode 1.0.0 represents a complete, production-ready BitcoinSV P2P networking library for Dart.

Core Features Implemented

P2P Protocol Foundation:

• Complete Bitcoin P2P protocol handshake (version/verack)
• Network magic number support (Mainnet, Testnet, RegTest, SimNet)
• Priority-based message queue with overflow protection
• Robust connection management with health monitoring
• Peer discovery and management system

Message Types:

• MsgVersion - Protocol handshake with configurable startHeight for SPV sync
• MsgVerAck - Handshake acknowledgment
• MsgPing/MsgPong - Connection keepalive and latency measurement
• MsgHeaders - Block header synchronization (supports large 162KB+ payloads)
• MsgGetHeaders - Request block headers with locator support
• MsgSendHeaders - BIP 130 direct header delivery preference
• MsgInv - Inventory announcements for blocks and transactions
• MsgGetData - Request specific data items
• MsgAddr - Peer address sharing
• MsgTx - Transaction messages
• MsgBlock - Full block data
• MsgMemPool - Memory pool requests
• MsgReject - Error reporting

Block Header Client:

• Complete block header synchronization from genesis or specific height
• In-memory block header storage and management
• Real-time block announcements via sendheaders protocol
• Automatic pagination for large header sets (2000+ headers)
• RegTest network compatibility for development

Network Layer:

• TCP connection management with timeout handling
• Message serialization/deserialization with checksum verification
• Large message support (tested with 162KB+ payloads)
• Graceful handling of unsupported protocol extensions
• Background send/receive loops with error recovery

🔧 Critical Bug Fixes

Message Processing Pipeline:

• Fixed critical deserialization bug in MessageProcessor where immutable messages (like MsgHeaders) were being parsed as empty despite receiving large payloads
• Corrected checksum calculation to use raw byte arrays instead of integers (endianness fix)
• Resolved "Future already completed" error in message queue processing
• Fixed priority queue ordering and completion handling

Protocol Compliance:

• Corrected network magic number mappings for BitcoinSV networks
• Implemented proper sendheaders timing per BIP 130 specification
• Fixed getheaders message format to include locator hashes for genesis sync
• Added proper handling of protocol extensions (protoconf, sendcmpct, feefilter)

📚 Documentation & Examples

API Documentation:

• Comprehensive API-DOCS.md with usage examples
• Updated README.md with project overview and quick start guide
• Inline code documentation for all public APIs

Example Applications:

• simple_peer_example.dart - Basic P2P connection demo
• block_header_client_example.dart - Full SPV block header sync client

🧪 Testing & Quality

Test Coverage:

• Unit tests for all message types and serialization
• Integration tests for peer connections and handshakes
• Message queue and priority handling tests
• Block header parsing and validation tests

Development Tools:

• Proper error handling and logging throughout
• Debug output for protocol troubleshooting
• Performance monitoring and statistics

📦 Project Metadata

• License: MIT License (Copyright 2025 Stephan M. February)
• Dart SDK: Compatible with Dart 3.0.0+
• Dependencies: Minimal (crypto, logging, meta)
• Homepage: https://github.com/twostack/spiffynode

Current Status: ✅ PRODUCTION READY

SpiffyNode 1.0.0 is a complete, tested, and production-ready BitcoinSV P2P networking library.

What Works:

• ✅ Full P2P handshake and connection management
• ✅ Block header synchronization (tested with 2100+ RegTest blocks)
• ✅ All major Bitcoin protocol messages
• ✅ Large message handling (162KB+ payloads)
• ✅ Priority message queuing and flow control
• ✅ Real-time block announcements
• ✅ SPV client capabilities with configurable sync points

Use Cases:

• SPV (Simplified Payment Verification) clients
• Blockchain explorers and analytics tools
• BitcoinSV network monitoring applications
• Custom wallet implementations
• Research and educational projects

Ready for integration into production BitcoinSV applications!