Chia Block Listener

A high-performance Chia blockchain listener for Node.js, built with Rust and NAPI bindings. This library provides real-time monitoring of the Chia blockchain with efficient peer connections and block parsing capabilities.

Features

Real-time Block Monitoring: Listen for new blocks as they're produced on the Chia network
Peer Management: Connect to multiple Chia full nodes simultaneously
Automatic Failover: Intelligent peer failover with automatic retry across multiple peers
Enhanced Error Handling: Automatic disconnection of peers that refuse blocks or have protocol errors
Efficient Parsing: Fast extraction of coin spends, additions, and removals from blocks
Event-Driven Architecture: TypeScript-friendly event system with full type safety
Transaction Analysis: Parse CLVM puzzles and solutions from coin spends
Historical Block Access: Retrieve blocks by height or ranges with automatic load balancing
Connection Pool: ChiaPeerPool provides automatic load balancing and rate limiting for historical queries
Peak Height Tracking: Monitor blockchain sync progress across all connected peers
DNS Peer Discovery: Automatic peer discovery using Chia network DNS introducers with IPv4/IPv6 support
Cross-platform Support: Works on Windows, macOS, and Linux (x64 and ARM64)
TypeScript Support: Complete TypeScript definitions with IntelliSense

Installation

npm install @dignetwork/chia-block-listener

Quick Start

const { ChiaBlockListener, initTracing } = require('@dignetwork/chia-block-listener')

// Initialize tracing for debugging (optional)
initTracing()

// Create a new listener instance
const listener = new ChiaBlockListener()

// Listen for block events
listener.on('blockReceived', (block) => {
  console.log(`New block received: ${block.height}`)
  console.log(`Header hash: ${block.headerHash}`)
  console.log(`Timestamp: ${new Date(block.timestamp * 1000)}`)
  console.log(`Coin additions: ${block.coinAdditions.length}`)
  console.log(`Coin removals: ${block.coinRemovals.length}`)
  console.log(`Coin spends: ${block.coinSpends.length}`)
})

// Listen for peer connection events
listener.on('peerConnected', (peer) => {
  console.log(`Connected to peer: ${peer.peerId} (${peer.host}:${peer.port})`)
})

listener.on('peerDisconnected', (peer) => {
  console.log(`Disconnected from peer: ${peer.peerId}`)
  if (peer.message) {
    console.log(`Reason: ${peer.message}`)
  }
})

// Connect to a Chia full node
const peerId = listener.addPeer('localhost', 8444, 'mainnet')
console.log(`Added peer: ${peerId}`)

// Keep the process running
process.on('SIGINT', () => {
  console.log('Shutting down...')
  listener.disconnectAllPeers()
  process.exit(0)
})

API Reference

ChiaBlockListener Class

Constructor

const listener = new ChiaBlockListener()

Creates a new Chia block listener instance.

Methods

`addPeer(host, port, networkId): string`

Connects to a Chia full node and starts listening for blocks.

Parameters:

host (string): The hostname or IP address of the Chia node
port (number): The port number (typically 8444 for mainnet)
networkId (string): The network identifier ('mainnet', 'testnet', etc.)

Returns: A unique peer ID string for this connection

`disconnectPeer(peerId): boolean`

Disconnects from a specific peer.

Parameters:

peerId (string): The peer ID returned by addPeer()

Returns: true if the peer was successfully disconnected, false otherwise

`disconnectAllPeers(): void`

Disconnects from all connected peers.

`getConnectedPeers(): string[]`

Returns an array of currently connected peer IDs.

`getBlockByHeight(peerId, height): BlockReceivedEvent`

Retrieves a specific block by its height from a connected peer.

Parameters:

peerId (string): The peer ID to query
height (number): The block height to retrieve

Returns: A BlockReceivedEvent object containing the block data

`getBlocksRange(peerId, startHeight, endHeight): BlockReceivedEvent[]`

Retrieves a range of blocks from a connected peer.

Parameters:

peerId (string): The peer ID to query
startHeight (number): The starting block height (inclusive)
endHeight (number): The ending block height (inclusive)

Returns: An array of BlockReceivedEvent objects

ChiaPeerPool Class

The ChiaPeerPool provides a managed pool of peer connections for retrieving historical blocks with automatic load balancing and intelligent failover across multiple peers. When a peer fails to provide a block or experiences protocol errors, the pool automatically tries alternative peers and removes problematic peers from the pool.

Constructor

const pool = new ChiaPeerPool()

Creates a new peer pool instance with built-in rate limiting (500ms per peer).

Methods

`addPeer(host, port, networkId): Promise<string>`

Adds a peer to the connection pool.

Parameters:

host (string): The hostname or IP address of the Chia node
port (number): The port number (typically 8444 for mainnet)
networkId (string): The network identifier ('mainnet', 'testnet', etc.)

Returns: A Promise that resolves to a unique peer ID string

`getBlockByHeight(height): Promise<BlockReceivedEvent>`

Retrieves a specific block by height using automatic peer selection and load balancing.

Parameters:

height (number): The block height to retrieve

Returns: A Promise that resolves to a BlockReceivedEvent object

`removePeer(peerId): Promise<boolean>`

Removes a peer from the pool.

Parameters:

peerId (string): The peer ID to remove

Returns: A Promise that resolves to true if the peer was removed, false otherwise

`shutdown(): Promise<void>`

Shuts down the pool and disconnects all peers.

`getConnectedPeers(): Promise<string[]>`

Gets the list of currently connected peer IDs.

Returns: Array of peer ID strings (format: "host:port")

`getPeakHeight(): Promise<number | null>`

Gets the highest blockchain peak height seen across all connected peers.

Returns: The highest peak height as a number, or null if no peaks have been received yet

`on(event, callback): void`

Registers an event handler for pool events.

Parameters:

event (string): The event name ('peerConnected' or 'peerDisconnected')
callback (function): The event handler function

`off(event, callback): void`

Removes an event handler.

Parameters:

event (string): The event name to stop listening for

Events

The ChiaBlockListener emits the following events:

`blockReceived`

Fired when a new block is received from any connected peer.

Callback: (event: BlockReceivedEvent) => void

`peerConnected`

Fired when a connection to a peer is established.

Callback: (event: PeerConnectedEvent) => void

`peerDisconnected`

Fired when a peer connection is lost.

Callback: (event: PeerDisconnectedEvent) => void

ChiaPeerPool Events

The ChiaPeerPool emits the following events:

`peerConnected`

Fired when a peer is successfully added to the pool.

Callback: (event: PeerConnectedEvent) => void

`peerDisconnected`

Fired when a peer is removed from the pool or disconnects.

Callback: (event: PeerDisconnectedEvent) => void

`newPeakHeight`

Fired when a new highest blockchain peak is discovered.

Callback: (event: NewPeakHeightEvent) => void

DnsDiscoveryClient Class

The DnsDiscoveryClient provides automatic peer discovery using Chia network DNS introducers with full IPv4 and IPv6 support.

Constructor

const client = new DnsDiscoveryClient()

Creates a new DNS discovery client instance.

Methods

`discoverMainnetPeers(): Promise<DiscoveryResultJS>`

Discovers peers for Chia mainnet using built-in DNS introducers.

Returns: Promise resolving to discovery results with separate IPv4 and IPv6 peer lists

`discoverTestnet11Peers(): Promise<DiscoveryResultJS>`

Discovers peers for Chia testnet11 using built-in DNS introducers.

Returns: Promise resolving to discovery results

`discoverPeers(introducers, port): Promise<DiscoveryResultJS>`

Discovers peers using custom DNS introducers.

Parameters:

introducers (string[]): Array of DNS introducer hostnames
port (number): Default port for discovered peers

Returns: Promise resolving to discovery results

`resolveIpv4(hostname): Promise<AddressResult>`

Resolves IPv4 addresses (A records) for a hostname.

Parameters:

hostname (string): Hostname to resolve

Returns: Promise resolving to IPv4 addresses

`resolveIpv6(hostname): Promise<AddressResult>`

Resolves IPv6 addresses (AAAA records) for a hostname.

Parameters:

hostname (string): Hostname to resolve

Returns: Promise resolving to IPv6 addresses

`resolveBoth(hostname, port): Promise<DiscoveryResultJS>`

Resolves both IPv4 and IPv6 addresses for a hostname.

Parameters:

hostname (string): Hostname to resolve
port (number): Port for the peer addresses

Returns: Promise resolving to discovery results

Event Data Types

`BlockReceivedEvent`

interface BlockReceivedEvent {
  peerId: string                    // IP address of the peer that sent this block
  height: number                     // Block height
  weight: string                     // Block weight as string
  headerHash: string               // Block header hash (hex)
  timestamp: number                 // Block timestamp (Unix time)
  coinAdditions: CoinRecord[]      // New coins created in this block
  coinRemovals: CoinRecord[]       // Coins spent in this block
  coinSpends: CoinSpend[]         // Detailed spend information
  coinCreations: CoinRecord[]      // Coins created by puzzles
  hasTransactionsGenerator: boolean // Whether block has a generator
  generatorSize: number            // Size of the generator bytecode
}

`PeerConnectedEvent`

interface PeerConnectedEvent {
  peerId: string  // Peer IP address
  host: string     // Peer hostname/IP
  port: number     // Peer port number
}

`PeerDisconnectedEvent`

interface PeerDisconnectedEvent {
  peerId: string   // Peer IP address
  host: string      // Peer hostname/IP
  port: number      // Peer port number
  message?: string  // Optional disconnection reason
}

`NewPeakHeightEvent`

interface NewPeakHeightEvent {
  oldPeak: number | null  // Previous highest peak (null if first peak)
  newPeak: number        // New highest peak height
  peerId: string         // Peer that discovered this peak
}

`CoinRecord`

interface CoinRecord {
  parentCoinInfo: string  // Parent coin ID (hex)
  puzzleHash: string       // Puzzle hash (hex)
  amount: string            // Coin amount as string
}

`CoinSpend`

interface CoinSpend {
  coin: CoinRecord         // The coin being spent
  puzzleReveal: string    // CLVM puzzle bytecode (hex)
  solution: string         // CLVM solution bytecode (hex)
  offset: number           // Offset in the generator bytecode
}

`DiscoveryResultJS`

interface DiscoveryResultJS {
  ipv4Peers: PeerAddressJS[]    // IPv4 peer addresses
  ipv6Peers: PeerAddressJS[]    // IPv6 peer addresses  
  totalCount: number            // Total peers found
}

`PeerAddressJS`

interface PeerAddressJS {
  host: string           // IP address as string
  port: number           // Port number
  isIpv6: boolean        // Protocol indicator
  displayAddress: string // Formatted for display/URLs
}

`AddressResult`

interface AddressResult {
  addresses: string[]    // List of IP addresses
  count: number          // Number of addresses
}

ChiaPeerPool Usage

The ChiaPeerPool is designed for efficiently retrieving historical blocks with automatic load balancing and intelligent failover across multiple peers. When a peer fails to provide a block or experiences protocol errors, the pool automatically tries alternative peers and removes problematic peers from the pool.

Basic Usage

const { ChiaPeerPool, initTracing } = require('@dignetwork/chia-block-listener')

async function main() {
  // Initialize tracing
  initTracing()
  
  // Create a peer pool
  const pool = new ChiaPeerPool()
  
  // Listen for pool events
  pool.on('peerConnected', (event) => {
    console.log(`Peer connected to pool: ${event.peerId}`)
  })
  
  pool.on('peerDisconnected', (event) => {
    console.log(`Peer disconnected from pool: ${event.peerId}`)
  })
  
  pool.on('newPeakHeight', (event) => {
    console.log(`New blockchain peak detected!`)
    console.log(`  Previous: ${event.oldPeak || 'None'}`)
    console.log(`  New: ${event.newPeak}`)
    console.log(`  Discovered by: ${event.peerId}`)
  })
  
  // Add multiple peers
  await pool.addPeer('node1.chia.net', 8444, 'mainnet')
  await pool.addPeer('node2.chia.net', 8444, 'mainnet')
  await pool.addPeer('node3.chia.net', 8444, 'mainnet')
  
  // Fetch blocks with automatic load balancing
  const block1 = await pool.getBlockByHeight(5000000)
  const block2 = await pool.getBlockByHeight(5000001)
  const block3 = await pool.getBlockByHeight(5000002)
  
  console.log(`Block ${block1.height}: ${block1.coinSpends.length} spends`)
  console.log(`Block ${block2.height}: ${block2.coinSpends.length} spends`)
  console.log(`Block ${block3.height}: ${block3.coinSpends.length} spends`)
  
  // Shutdown the pool
  await pool.shutdown()
}

main().catch(console.error)

Advanced Pool Features

Rate Limiting

The pool automatically enforces a 500ms rate limit per peer for maximum performance while preventing node overload:

// Rapid requests are automatically queued and distributed
const promises = []
for (let i = 5000000; i < 5000100; i++) {
  promises.push(pool.getBlockByHeight(i))
}

// All requests will be processed efficiently across all peers
// with automatic load balancing and rate limiting
const blocks = await Promise.all(promises)
console.log(`Retrieved ${blocks.length} blocks`)

Automatic Failover and Error Handling

The pool provides robust error handling with automatic failover:

// The pool automatically handles various error scenarios:

// 1. Connection failures - automatically tries other peers
try {
  const block = await pool.getBlockByHeight(5000000)
  console.log(`Retrieved block ${block.height}`)
} catch (error) {
  // If all peers fail, you'll get an error after all retry attempts
  console.error('All peers failed:', error.message)
}

// 2. Protocol errors - peers that refuse blocks are automatically disconnected
pool.on('peerDisconnected', (event) => {
  console.log(`Peer ${event.peerId} disconnected: ${event.reason}`)
  // Reasons include: "Block request rejected", "Protocol error", "Connection timeout"
})

// 3. Automatic peer cleanup - problematic peers are removed from the pool
console.log('Active peers before:', await pool.getConnectedPeers())
await pool.getBlockByHeight(5000000) // May trigger peer removal
console.log('Active peers after:', await pool.getConnectedPeers())

// 4. Multiple retry attempts - tries up to 3 different peers per request
// This happens automatically and transparently
const block = await pool.getBlockByHeight(5000000) // Will try multiple peers if needed

Error Types Handled Automatically:

Connection Errors: Timeouts, network failures, WebSocket errors
Protocol Errors: Block rejections, parsing failures, handshake failures
Peer Misbehavior: Unexpected responses, invalid data formats

Dynamic Peer Management

// Monitor pool health
const peers = await pool.getConnectedPeers()
console.log(`Active peers in pool: ${peers.length}`)

// Remove underperforming peers
if (slowPeer) {
  await pool.removePeer(slowPeer)
  console.log('Removed slow peer from pool')
}

// Add new peers dynamically
if (peers.length < 3) {
  await pool.addPeer('backup-node.chia.net', 8444, 'mainnet')
}

Error Handling

try {
  const block = await pool.getBlockByHeight(5000000)
  console.log(`Retrieved block ${block.height}`)
} catch (error) {
  console.error('Failed to retrieve block:', error)
  
  // The pool will automatically try other peers
  // You can also add more peers if needed
  const peers = await pool.getConnectedPeers()
  if (peers.length === 0) {
    console.log('No peers available, adding new ones...')
    await pool.addPeer('node1.chia.net', 8444, 'mainnet')
  }
}

Peak Height Tracking

// Monitor blockchain sync progress
const pool = new ChiaPeerPool()

// Track peak changes
let currentPeak = null
pool.on('newPeakHeight', (event) => {
  currentPeak = event.newPeak
  const progress = event.oldPeak 
    ? `+${event.newPeak - event.oldPeak} blocks` 
    : 'Initial peak'
  console.log(`Peak update: ${event.newPeak} (${progress})`)
})

// Add peers
await pool.addPeer('node1.chia.net', 8444, 'mainnet')
await pool.addPeer('node2.chia.net', 8444, 'mainnet')

// Check current peak
const peak = await pool.getPeakHeight()
console.log(`Current highest peak: ${peak || 'None yet'}`)

// Fetch some blocks to trigger peak updates
await pool.getBlockByHeight(5000000)
await pool.getBlockByHeight(5100000)
await pool.getBlockByHeight(5200000)

// Monitor sync status
setInterval(async () => {
  const peak = await pool.getPeakHeight()
  if (peak) {
    const estimatedCurrent = 5200000 + Math.floor((Date.now() / 1000 - 1700000000) / 18.75)
    const syncPercentage = (peak / estimatedCurrent * 100).toFixed(2)
    console.log(`Sync status: ${syncPercentage}% (peak: ${peak})`)
  }
}, 60000) // Check every minute

When to Use ChiaPeerPool vs ChiaBlockListener

Use ChiaPeerPool when:
- You need to fetch historical blocks
- You want automatic load balancing across multiple peers
- You're making many block requests and need rate limiting
- You don't need real-time block notifications
Use ChiaBlockListener when:
- You need real-time notifications of new blocks
- You want to monitor the blockchain as it grows
- You need to track specific addresses or puzzle hashes in real-time
- You're building applications that react to blockchain events

Both classes can be used together in the same application for different purposes.

DNS Discovery Usage

The DnsDiscoveryClient enables automatic discovery of Chia network peers using DNS introducers, with full support for both IPv4 and IPv6 addresses.

Basic DNS Discovery

const { DnsDiscoveryClient, initTracing } = require('@dignetwork/chia-block-listener')

async function discoverPeers() {
  // Initialize tracing
  initTracing()
  
  // Create DNS discovery client
  const client = new DnsDiscoveryClient()
  
  // Discover mainnet peers
  const result = await client.discoverMainnetPeers()
  
  console.log(`Found ${result.totalCount} total peers:`)
  console.log(`  IPv4 peers: ${result.ipv4Peers.length}`)
  console.log(`  IPv6 peers: ${result.ipv6Peers.length}`)
  
  // Use with peer connections
  for (const peer of result.ipv4Peers.slice(0, 3)) {
    console.log(`IPv4 peer: ${peer.displayAddress}`)
    // peer.host and peer.port can be used with addPeer()
  }
  
  for (const peer of result.ipv6Peers.slice(0, 3)) {
    console.log(`IPv6 peer: ${peer.displayAddress}`) // [2001:db8::1]:8444
    // IPv6 addresses are properly formatted with brackets
  }
}

discoverPeers().catch(console.error)

Integration with Peer Pool

const { ChiaPeerPool, DnsDiscoveryClient } = require('@dignetwork/chia-block-listener')

async function setupPoolWithDnsDiscovery() {
  const pool = new ChiaPeerPool()
  const discovery = new DnsDiscoveryClient()
  
  // Discover peers automatically
  const peers = await discovery.discoverMainnetPeers()
  
  // Add discovered peers to pool (both IPv4 and IPv6)
  const allPeers = [...peers.ipv4Peers, ...peers.ipv6Peers]
  for (const peer of allPeers.slice(0, 5)) {
    await pool.addPeer(peer.host, peer.port, 'mainnet')
    console.log(`Added peer: ${peer.displayAddress}`)
  }
  
  // Now use the pool for block retrieval
  const block = await pool.getBlockByHeight(5000000)
  console.log(`Retrieved block ${block.height}`)
  
  await pool.shutdown()
}

setupPoolWithDnsDiscovery().catch(console.error)

Custom DNS Introducers

const client = new DnsDiscoveryClient()

// Use custom introducers
const customIntroducers = [
  'seeder.dexie.space',
  'chia.hoffmang.com'
]

const result = await client.discoverPeers(customIntroducers, 8444)
console.log(`Found ${result.totalCount} peers from custom introducers`)

Individual DNS Resolution

const client = new DnsDiscoveryClient()
const hostname = 'dns-introducer.chia.net'

// Resolve specific protocols
try {
  const ipv4 = await client.resolveIpv4(hostname)
  console.log(`IPv4 addresses: ${ipv4.addresses.join(', ')}`)
} catch (error) {
  console.log(`IPv4 resolution failed: ${error.message}`)
}

try {
  const ipv6 = await client.resolveIpv6(hostname)
  console.log(`IPv6 addresses: ${ipv6.addresses.join(', ')}`)
} catch (error) {
  console.log(`IPv6 resolution failed: ${error.message}`)
}

// Or resolve both at once
const both = await client.resolveBoth(hostname, 8444)
console.log(`Combined: ${both.totalCount} addresses`)

Error Handling

const client = new DnsDiscoveryClient()

try {
  const result = await client.discoverMainnetPeers()
  console.log(`Discovery successful: ${result.totalCount} peers`)
} catch (error) {
  console.error('Discovery failed:', error.message)
  
  // Handle different error types
  if (error.message.includes('NoPeersFound')) {
    console.log('No peers found from any introducer')
  } else if (error.message.includes('ResolutionFailed')) {
    console.log('DNS resolution failed')
  }
}

Key Features

Dual Stack Support: Separate IPv4 and IPv6 peer lists
Proper DNS Lookups: Uses A records for IPv4, AAAA records for IPv6
Built-in Networks: Ready configurations for mainnet and testnet11
Custom Introducers: Support for any DNS introducers
IPv6 URL Formatting: Automatic bracket formatting for IPv6 addresses
Type Safety: Full TypeScript support with detailed type definitions

ChiaBlockParser Usage

The ChiaBlockParser provides direct access to the Rust-based block parsing engine, enabling efficient parsing of Chia FullBlock data with complete control over the parsing process. This is ideal for applications that need to process block data from external sources or implement custom block analysis.

Basic Block Parsing

const { ChiaBlockParser, initTracing } = require('@dignetwork/chia-block-listener')

async function parseBlockData() {
  // Initialize tracing
  initTracing()
  
  // Create a block parser instance
  const parser = new ChiaBlockParser()
  
  // Parse a block from hex string
  const blockHex = "your_full_block_hex_data_here"
  const parsedBlock = parser.parseFullBlockFromHex(blockHex)
  
  console.log(`Parsed block ${parsedBlock.height}:`)
  console.log(`  Header hash: ${parsedBlock.headerHash}`)
  console.log(`  Weight: ${parsedBlock.weight}`)
  console.log(`  Timestamp: ${new Date(parsedBlock.timestamp * 1000)}`)
  console.log(`  Coin additions: ${parsedBlock.coinAdditions.length}`)
  console.log(`  Coin removals: ${parsedBlock.coinRemovals.length}`)
  console.log(`  Coin spends: ${parsedBlock.coinSpends.length}`)
  console.log(`  Has generator: ${parsedBlock.hasTransactionsGenerator}`)
  
  // Access detailed coin spend information
  parsedBlock.coinSpends.forEach((spend, index) => {
    console.log(`  Spend ${index + 1}:`)
    console.log(`    Coin: ${spend.coin.amount} mojos`)
    console.log(`    Puzzle hash: ${spend.coin.puzzleHash}`)
    console.log(`    Puzzle reveal: ${spend.puzzleReveal.substring(0, 100)}...`)
    console.log(`    Solution: ${spend.solution.substring(0, 100)}...`)
    console.log(`    Created coins: ${spend.createdCoins.length}`)
  })
}

parseBlockData().catch(console.error)

ChiaBlockParser Class

Constructor

const parser = new ChiaBlockParser()

Creates a new block parser instance with access to the full Rust parsing engine.

Methods

`parseFullBlockFromBytes(blockBytes): ParsedBlockJs`

Parses a FullBlock from raw bytes.

Parameters:

blockBytes (Buffer): The serialized FullBlock data

Returns: A ParsedBlockJs object containing all parsed block information

const fs = require('fs')
const blockData = fs.readFileSync('block.bin')
const parsedBlock = parser.parseFullBlockFromBytes(blockData)

`parseFullBlockFromHex(blockHex): ParsedBlockJs`

Parses a FullBlock from a hex-encoded string.

Parameters:

blockHex (string): The hex-encoded FullBlock data

Returns: A ParsedBlockJs object containing all parsed block information

const blockHex = "deadbeef..." // Your hex-encoded block data
const parsedBlock = parser.parseFullBlockFromHex(blockHex)

`extractGeneratorFromBlockBytes(blockBytes): string | null`

Extracts only the transactions generator from a block without full parsing.

Parameters:

blockBytes (Buffer): The serialized FullBlock data

Returns: Hex-encoded generator bytecode or null if no generator exists

const blockData = fs.readFileSync('block.bin')
const generator = parser.extractGeneratorFromBlockBytes(blockData)
if (generator) {
  console.log(`Generator size: ${generator.length / 2} bytes`)
}

`getHeightAndTxStatusFromBlockBytes(blockBytes): BlockHeightInfoJs`

Quickly extracts basic block information without full parsing.

Parameters:

blockBytes (Buffer): The serialized FullBlock data

Returns: A BlockHeightInfoJs object with height and transaction status

const blockData = fs.readFileSync('block.bin')
const info = parser.getHeightAndTxStatusFromBlockBytes(blockData)
console.log(`Block ${info.height}, has transactions: ${info.isTransactionBlock}`)

`parseBlockInfoFromBytes(blockBytes): GeneratorBlockInfoJs`

Extracts generator-related block metadata.

Parameters:

blockBytes (Buffer): The serialized FullBlock data

Returns: A GeneratorBlockInfoJs object with generator metadata

const blockData = fs.readFileSync('block.bin')
const blockInfo = parser.parseBlockInfoFromBytes(blockData)
console.log(`Previous hash: ${blockInfo.prevHeaderHash}`)
console.log(`Generator refs: ${blockInfo.transactionsGeneratorRefList.length}`)

Advanced Parsing Features

Batch Block Processing

const parser = new ChiaBlockParser()
const fs = require('fs')
const path = require('path')

// Process multiple block files
const blockFiles = fs.readdirSync('./blocks/').filter(f => f.endsWith('.bin'))

const stats = {
  totalBlocks: 0,
  totalSpends: 0,
  totalCoins: 0,
  generatorBlocks: 0
}

for (const filename of blockFiles) {
  const blockData = fs.readFileSync(path.join('./blocks/', filename))
  
  try {
    const parsed = parser.parseFullBlockFromBytes(blockData)
    
    stats.totalBlocks++
    stats.totalSpends += parsed.coinSpends.length
    stats.totalCoins += parsed.coinAdditions.length
    
    if (parsed.hasTransactionsGenerator) {
      stats.generatorBlocks++
    }
    
    console.log(`Processed block ${parsed.height} with ${parsed.coinSpends.length} spends`)
    
  } catch (error) {
    console.error(`Failed to parse ${filename}:`, error.message)
  }
}

console.log('\nBatch processing complete:')
console.log(`  Blocks processed: ${stats.totalBlocks}`)
console.log(`  Total spends: ${stats.totalSpends}`)
console.log(`  Total coins: ${stats.totalCoins}`)
console.log(`  Generator blocks: ${stats.generatorBlocks}`)

Generator Analysis

const parser = new ChiaBlockParser()

function analyzeBlockGenerator(blockHex) {
  // Parse the full block
  const parsed = parser.parseFullBlockFromHex(blockHex)
  
  if (!parsed.hasTransactionsGenerator) {
    console.log('Block has no generator')
    return
  }
  
  // Extract just the generator for analysis
  const blockBytes = Buffer.from(blockHex, 'hex')
  const generator = parser.extractGeneratorFromBlockBytes(blockBytes)
  
  console.log(`Generator Analysis for Block ${parsed.height}:`)
  console.log(`  Generator size: ${parsed.generatorSize} bytes`)
  console.log(`  Hex length: ${generator.length} characters`)
  console.log(`  Coin spends extracted: ${parsed.coinSpends.length}`)
  console.log(`  Coins created: ${parsed.coinCreations.length}`)
  
  // Analyze coin spends
  parsed.coinSpends.forEach((spend, i) => {
    console.log(`  Spend ${i + 1}:`)
    console.log(`    Amount: ${spend.coin.amount} mojos`)
    console.log(`    Puzzle size: ${spend.puzzleReveal.length / 2} bytes`)
    console.log(`    Solution size: ${spend.solution.length / 2} bytes`)
    console.log(`    Creates ${spend.createdCoins.length} new coins`)
  })
}

// Example usage
const blockHex = "your_generator_block_hex"
analyzeBlockGenerator(blockHex)

Integration with Other Components

const { ChiaBlockParser, ChiaPeerPool, DnsDiscoveryClient } = require('@dignetwork/chia-block-listener')

async function integratedBlockAnalysis() {
  // Set up components
  const parser = new ChiaBlockParser()
  const pool = new ChiaPeerPool()
  const discovery = new DnsDiscoveryClient()
  
  // Discover and connect to peers
  const peers = await discovery.discoverMainnetPeers()
  for (const peer of peers.ipv4Peers.slice(0, 3)) {
    await pool.addPeer(peer.host, peer.port, 'mainnet')
  }
  
  // Fetch blocks and parse with enhanced detail
  const heights = [5000000, 5000001, 5000002]
  
  for (const height of heights) {
    // Get block using peer pool
    const blockEvent = await pool.getBlockByHeight(height)
    
    // For more detailed analysis, you can also parse with ChiaBlockParser
    // if you have access to the raw block bytes
    console.log(`Block ${height}:`)
    console.log(`  From peer: ${blockEvent.peerId}`)
    console.log(`  Coin spends: ${blockEvent.coinSpends.length}`)
    console.log(`  Has generator: ${blockEvent.hasTransactionsGenerator}`)
    
    // Analyze puzzle patterns
    const puzzleHashes = new Set()
    blockEvent.coinSpends.forEach(spend => {
      puzzleHashes.add(spend.coin.puzzleHash)
    })
    console.log(`  Unique puzzle hashes: ${puzzleHashes.size}`)
  }
  
  await pool.shutdown()
}

integratedBlockAnalysis().catch(console.error)

Data Types

`ParsedBlockJs`

interface ParsedBlockJs {
  height: number                     // Block height
  weight: string                     // Block weight as string
  headerHash: string                 // Block header hash (hex)
  timestamp?: number                 // Block timestamp (Unix time)
  coinAdditions: CoinInfoJs[]        // New coins created
  coinRemovals: CoinInfoJs[]         // Coins spent
  coinSpends: CoinSpendInfoJs[]      // Detailed spend information
  coinCreations: CoinInfoJs[]        // Coins created by spends
  hasTransactionsGenerator: boolean  // Whether block has generator
  generatorSize?: number             // Generator size in bytes
}

`CoinInfoJs`

interface CoinInfoJs {
  parentCoinInfo: string  // Parent coin ID (hex)
  puzzleHash: string      // Puzzle hash (hex)
  amount: string          // Amount as string (to avoid JS precision issues)
}

`CoinSpendInfoJs`

interface CoinSpendInfoJs {
  coin: CoinInfoJs                // The coin being spent
  puzzleReveal: string            // CLVM puzzle bytecode (hex)
  solution: string                // CLVM solution bytecode (hex)
  realData: boolean               // Whether this is real transaction data
  parsingMethod: string           // Method used for parsing
  offset: number                  // Offset in generator bytecode
  createdCoins: CoinInfoJs[]      // Coins created by this spend
}

`GeneratorBlockInfoJs`

interface GeneratorBlockInfoJs {
  prevHeaderHash: string                    // Previous block hash (hex)
  transactionsGenerator?: string            // Generator bytecode (hex)
  transactionsGeneratorRefList: number[]    // Referenced block heights
}

`BlockHeightInfoJs`

interface BlockHeightInfoJs {
  height: number              // Block height
  isTransactionBlock: boolean // Whether block contains transactions
}

When to Use ChiaBlockParser

Use ChiaBlockParser when:
- You have raw block data from external sources
- You need detailed CLVM puzzle and solution analysis
- You're implementing custom block processing logic
- You need to extract generators for analysis
- You want fine-grained control over parsing
Use with ChiaPeerPool when:
- You need both block retrieval and detailed parsing
- You're analyzing historical blocks in detail
- You want to combine network access with parsing
Use with ChiaBlockListener when:
- You're processing real-time blocks with custom logic
- You need both live monitoring and detailed parsing

The ChiaBlockParser complements the other classes by providing the lowest-level access to the Chia block parsing engine, enabling sophisticated analysis and processing workflows.

TypeScript Usage

import { 
  ChiaBlockListener, 
  ChiaPeerPool,
  ChiaBlockParser,
  DnsDiscoveryClient,
  BlockReceivedEvent, 
  PeerConnectedEvent, 
  PeerDisconnectedEvent,
  NewPeakHeightEvent,
  DiscoveryResultJS,
  PeerAddressJS,
  AddressResult,
  CoinRecord,
  CoinSpend,
  ParsedBlockJs,
  CoinInfoJs,
  CoinSpendInfoJs,
  GeneratorBlockInfoJs,
  BlockHeightInfoJs,
  initTracing,
  getEventTypes
} from '@dignetwork/chia-block-listener'

// Initialize tracing for debugging
initTracing()

// Create listener with proper typing
const listener = new ChiaBlockListener()

// Type-safe event handlers
listener.on('blockReceived', (block: BlockReceivedEvent) => {
  console.log(`Block ${block.height} from peer ${block.peerId}`)
  
  // Process coin additions
  block.coinAdditions.forEach((coin: CoinRecord) => {
    console.log(`New coin: ${coin.amount} mojos`)
  })
  
  // Process coin spends
  block.coinSpends.forEach((spend: CoinSpend) => {
    console.log(`Spend: ${spend.coin.amount} mojos`)
    console.log(`Puzzle: ${spend.puzzleReveal}`)
    console.log(`Solution: ${spend.solution}`)
  })
})

listener.on('peerConnected', (peer: PeerConnectedEvent) => {
  console.log(`Connected: ${peer.peerId} at ${peer.host}:${peer.port}`)
})

listener.on('peerDisconnected', (peer: PeerDisconnectedEvent) => {
  console.log(`Disconnected: ${peer.peerId}`)
  if (peer.message) {
    console.log(`Reason: ${peer.message}`)
  }
})

// Connect to peers
const mainnetPeer = listener.addPeer('localhost', 8444, 'mainnet')
const testnetPeer = listener.addPeer('testnet-node.chia.net', 58444, 'testnet')

// Get historical blocks
async function getHistoricalBlocks() {
  try {
    const block = listener.getBlockByHeight(mainnetPeer, 1000000)
    console.log(`Block 1000000 hash: ${block.headerHash}`)
    
    const blocks = listener.getBlocksRange(mainnetPeer, 1000000, 1000010)
    console.log(`Retrieved ${blocks.length} blocks`)
  } catch (error) {
    console.error('Error getting blocks:', error)
  }
}

// Get event type constants
const eventTypes = getEventTypes()
console.log('Available events:', eventTypes)

// TypeScript support for ChiaPeerPool
const pool = new ChiaPeerPool()

// Type-safe event handling
pool.on('peerConnected', (event: PeerConnectedEvent) => {
  console.log(`Pool peer connected: ${event.peerId}`)
})

pool.on('newPeakHeight', (event: NewPeakHeightEvent) => {
  console.log(`New peak: ${event.oldPeak} → ${event.newPeak}`)
})

// Async/await with proper typing
async function fetchHistoricalData() {
  const block: BlockReceivedEvent = await pool.getBlockByHeight(5000000)
  const peers: string[] = await pool.getConnectedPeers()
  const peak: number | null = await pool.getPeakHeight()
  
  console.log(`Block ${block.height} has ${block.coinSpends.length} spends`)
  console.log(`Pool has ${peers.length} active peers`)
  console.log(`Current peak: ${peak || 'No peak yet'}`)
}

// TypeScript DNS Discovery
async function typedDnsDiscovery(): Promise<void> {
  const client = new DnsDiscoveryClient()
  
  // Type-safe discovery
  const result: DiscoveryResultJS = await client.discoverMainnetPeers()
  
  // Access with full type safety
  result.ipv4Peers.forEach((peer: PeerAddressJS) => {
    console.log(`IPv4: ${peer.host}:${peer.port} (${peer.displayAddress})`)
  })
  
  result.ipv6Peers.forEach((peer: PeerAddressJS) => {
    console.log(`IPv6: ${peer.displayAddress} (isIpv6: ${peer.isIpv6})`)
  })
  
  // Individual resolution with types
  const ipv4Result: AddressResult = await client.resolveIpv4('dns-introducer.chia.net')
  const ipv6Result: AddressResult = await client.resolveIpv6('dns-introducer.chia.net')
  
  console.log(`IPv4 count: ${ipv4Result.count}, IPv6 count: ${ipv6Result.count}`)
}

// TypeScript ChiaBlockParser
async function typedBlockParsing(): Promise<void> {
  const parser = new ChiaBlockParser()
  
  // Type-safe block parsing from hex
  const blockHex = "your_block_hex_data"
  const parsedBlock: ParsedBlockJs = parser.parseFullBlockFromHex(blockHex)
  
  console.log(`Parsed block ${parsedBlock.height}:`)
  console.log(`  Header hash: ${parsedBlock.headerHash}`)
  console.log(`  Weight: ${parsedBlock.weight}`)
  console.log(`  Coin additions: ${parsedBlock.coinAdditions.length}`)
  console.log(`  Coin spends: ${parsedBlock.coinSpends.length}`)
  console.log(`  Has generator: ${parsedBlock.hasTransactionsGenerator}`)
  
  // Type-safe access to coin spend details
  parsedBlock.coinSpends.forEach((spend: CoinSpendInfoJs) => {
    const coin: CoinInfoJs = spend.coin
    console.log(`Spend: ${coin.amount} mojos from ${coin.puzzleHash}`)
    console.log(`  Puzzle reveal size: ${spend.puzzleReveal.length / 2} bytes`)
    console.log(`  Solution size: ${spend.solution.length / 2} bytes`)
    console.log(`  Creates ${spend.createdCoins.length} new coins`)
    console.log(`  Real data: ${spend.realData}`)
    console.log(`  Parsing method: ${spend.parsingMethod}`)
  })
  
  // Type-safe generator extraction
  const blockBytes = Buffer.from(blockHex, 'hex')
  const generator: string | null = parser.extractGeneratorFromBlockBytes(blockBytes)
  if (generator) {
    console.log(`Generator found: ${generator.length / 2} bytes`)
  }
  
  // Type-safe height and tx status
  const heightInfo: BlockHeightInfoJs = parser.getHeightAndTxStatusFromBlockBytes(blockBytes)
  console.log(`Block ${heightInfo.height}, is transaction block: ${heightInfo.isTransactionBlock}`)
  
  // Type-safe block info extraction
  const blockInfo: GeneratorBlockInfoJs = parser.parseBlockInfoFromBytes(blockBytes)
  console.log(`Previous hash: ${blockInfo.prevHeaderHash}`)
  console.log(`Generator refs: ${blockInfo.transactionsGeneratorRefList.length}`)
  if (blockInfo.transactionsGenerator) {
    console.log(`Generator size: ${blockInfo.transactionsGenerator.length / 2} bytes`)
  }
}

Advanced Usage

Monitoring Specific Transactions

// Monitor all coin spends for a specific puzzle hash
listener.on('blockReceived', (block) => {
  const targetPuzzleHash = '0x1234...' // Your puzzle hash
  
  block.coinSpends.forEach((spend) => {
    if (spend.coin.puzzleHash === targetPuzzleHash) {
      console.log('Found spend for our puzzle!')
      console.log('Amount:', spend.coin.amount)
      console.log('Solution:', spend.solution)
    }
  })
})

Multiple Network Monitoring

// Monitor both mainnet and testnet
const mainnetPeer = listener.addPeer('localhost', 8444, 'mainnet')
const testnetPeer = listener.addPeer('localhost', 58444, 'testnet')

listener.on('blockReceived', (block) => {
  if (block.peerId === mainnetPeer) {
    console.log(`Mainnet block ${block.height}`)
  } else if (block.peerId === testnetPeer) {
    console.log(`Testnet block ${block.height}`)
  }
})

Connection Management

// Automatic reconnection
listener.on('peerDisconnected', (peer) => {
  console.log(`Lost connection to ${peer.peerId}, reconnecting...`)
  
  // Reconnect after 5 seconds
  setTimeout(() => {
    try {
      listener.addPeer(peer.host, peer.port, 'mainnet')
      console.log('Reconnected successfully')
    } catch (error) {
      console.error('Reconnection failed:', error)
    }
  }, 5000)
})

Utility Functions

`initTracing(): void`

Initializes the Rust tracing system for debugging purposes. Call this before creating any ChiaBlockListener instances if you want to see debug output.

`getEventTypes(): EventTypes`

Returns an object containing the event type constants:

const eventTypes = getEventTypes()
console.log(eventTypes)
// Output: { blockReceived: "blockReceived", peerConnected: "peerConnected", peerDisconnected: "peerDisconnected" }

Performance Tips

Use specific event handlers: Only listen for the events you need
Process blocks efficiently: Avoid heavy computation in event handlers
Manage connections: Don't create too many peer connections simultaneously
Handle errors gracefully: Always wrap peer operations in try-catch blocks

Development

Prerequisites

Rust (latest stable)
Node.js (20 or later)
npm

Setup

# Clone and install dependencies
git clone <repository-url>
cd chia-block-listener
npm install

# Build the native module
npm run build

# Run tests
npm test

Project Structure

chia-block-listener/
├── src/                     # Rust source code
│   ├── lib.rs              # Main NAPI bindings
│   ├── peer.rs             # Peer connection management
│   ├── protocol.rs         # Chia protocol implementation
│   ├── event_emitter.rs    # Event system
│   └── tls.rs              # TLS connection handling
├── crate/                  # Additional Rust crates
│   └── chia-generator-parser/ # CLVM parser
├── __test__/               # Test suite
├── npm/                    # Platform-specific binaries
├── .github/workflows/      # CI/CD pipeline
├── Cargo.toml              # Rust configuration
├── package.json            # Node.js configuration
└── index.d.ts              # TypeScript definitions

CI/CD & Publishing

This project uses GitHub Actions for:

Cross-platform builds (Windows, macOS, Linux)
Multiple architectures (x64, ARM64)
Automated testing on all platforms
npm publishing based on git tags

License

MIT

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes and add tests
Ensure all tests pass (npm test)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Support

For issues and questions:

GitHub Issues: Report bugs or request features
Documentation: Check the TypeScript definitions in index.d.ts
Examples: See the examples/ directory for more usage examples

Name		Name	Last commit message	Last commit date
Latest commit History 97 Commits
.github/workflows		.github/workflows
.knowledge		.knowledge
__test__		__test__
crate		crate
examples		examples
npm		npm
scripts		scripts
src		src
.gitignore		.gitignore
.yarnrc.yml		.yarnrc.yml
.yarnrc.yml.bak		.yarnrc.yml.bak
Cargo.toml		Cargo.toml
DNS_DISCOVERY_USAGE.md		DNS_DISCOVERY_USAGE.md
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs
dns-discovery.d.ts		dns-discovery.d.ts
index.d.ts		index.d.ts
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

License

DIG-Network/chia-block-listener

Folders and files

Latest commit

History

Repository files navigation

Chia Block Listener

Features

Installation

Quick Start

API Reference

ChiaBlockListener Class

Constructor

Methods

addPeer(host, port, networkId): string

disconnectPeer(peerId): boolean

disconnectAllPeers(): void

getConnectedPeers(): string[]

getBlockByHeight(peerId, height): BlockReceivedEvent

getBlocksRange(peerId, startHeight, endHeight): BlockReceivedEvent[]

ChiaPeerPool Class

Constructor

Methods

addPeer(host, port, networkId): Promise<string>

getBlockByHeight(height): Promise<BlockReceivedEvent>

removePeer(peerId): Promise<boolean>

shutdown(): Promise<void>

getConnectedPeers(): Promise<string[]>

getPeakHeight(): Promise<number | null>

on(event, callback): void

off(event, callback): void

Events

blockReceived

peerConnected

peerDisconnected

ChiaPeerPool Events

peerConnected

peerDisconnected

newPeakHeight

DnsDiscoveryClient Class

Constructor

Methods

discoverMainnetPeers(): Promise<DiscoveryResultJS>

discoverTestnet11Peers(): Promise<DiscoveryResultJS>

discoverPeers(introducers, port): Promise<DiscoveryResultJS>

resolveIpv4(hostname): Promise<AddressResult>

resolveIpv6(hostname): Promise<AddressResult>

resolveBoth(hostname, port): Promise<DiscoveryResultJS>

Event Data Types

BlockReceivedEvent

PeerConnectedEvent

PeerDisconnectedEvent

NewPeakHeightEvent

CoinRecord

CoinSpend

DiscoveryResultJS

PeerAddressJS

AddressResult

ChiaPeerPool Usage

Basic Usage

Advanced Pool Features

Rate Limiting

Automatic Failover and Error Handling

Dynamic Peer Management

Error Handling

Peak Height Tracking

When to Use ChiaPeerPool vs ChiaBlockListener

DNS Discovery Usage

Basic DNS Discovery

Integration with Peer Pool

Custom DNS Introducers

Individual DNS Resolution

Error Handling

Key Features

ChiaBlockParser Usage

Basic Block Parsing

ChiaBlockParser Class

Constructor

Methods

parseFullBlockFromBytes(blockBytes): ParsedBlockJs

`addPeer(host, port, networkId): string`

`disconnectPeer(peerId): boolean`

`disconnectAllPeers(): void`

`getConnectedPeers(): string[]`

`getBlockByHeight(peerId, height): BlockReceivedEvent`

`getBlocksRange(peerId, startHeight, endHeight): BlockReceivedEvent[]`

`addPeer(host, port, networkId): Promise<string>`

`getBlockByHeight(height): Promise<BlockReceivedEvent>`

`removePeer(peerId): Promise<boolean>`

`shutdown(): Promise<void>`

`getConnectedPeers(): Promise<string[]>`

`getPeakHeight(): Promise<number | null>`

`on(event, callback): void`

`off(event, callback): void`

`blockReceived`

`peerConnected`

`peerDisconnected`

`peerConnected`

`peerDisconnected`

`newPeakHeight`

`discoverMainnetPeers(): Promise<DiscoveryResultJS>`

`discoverTestnet11Peers(): Promise<DiscoveryResultJS>`

`discoverPeers(introducers, port): Promise<DiscoveryResultJS>`

`resolveIpv4(hostname): Promise<AddressResult>`

`resolveIpv6(hostname): Promise<AddressResult>`

`resolveBoth(hostname, port): Promise<DiscoveryResultJS>`

`BlockReceivedEvent`

`PeerConnectedEvent`

`PeerDisconnectedEvent`

`NewPeakHeightEvent`

`CoinRecord`

`CoinSpend`

`DiscoveryResultJS`

`PeerAddressJS`

`AddressResult`

`parseFullBlockFromBytes(blockBytes): ParsedBlockJs`

`parseFullBlockFromHex(blockHex): ParsedBlockJs`

`extractGeneratorFromBlockBytes(blockBytes): string | null`

`getHeightAndTxStatusFromBlockBytes(blockBytes): BlockHeightInfoJs`

`parseBlockInfoFromBytes(blockBytes): GeneratorBlockInfoJs`

`ParsedBlockJs`

`CoinInfoJs`

`CoinSpendInfoJs`

`GeneratorBlockInfoJs`

`BlockHeightInfoJs`

`initTracing(): void`

`getEventTypes(): EventTypes`

Packages