Saturn Mempool and Fee Rate Oracle SDK

A TypeScript SDK for connecting to the Saturn Mempool and Fee Rate Oracle service, allowing real-time access to Bitcoin mempool data through a TCP connection.

Overview

This SDK provides a simple interface for subscribing to real-time Bitcoin mempool events, including transaction additions, updates, and deletions. By using this SDK, applications can make informed decisions based on current mempool state and dynamics.

Installation

npm install saturn-mempool-oracle-sdk
# or
yarn add saturn-mempool-oracle-sdk

Basic Usage

import {
  SaturnOracleTcpClient,
  MempoolOpType,
} from 'saturn-mempool-oracle-sdk';

// Create a client with auto-reconnect enabled
const client = new SaturnOracleTcpClient('localhost', 4000, {
  autoReconnect: true,
  reconnectDelayMs: 5000,
});

// Listen for mempool events
client.on('event', (event) => {
  console.log('Received mempool event:', event);

  // Handle different event types
  switch (event.operation) {
    case MempoolOpType.AddEntry:
      console.log(`New transaction ${event.data.txid} added to mempool`);
      console.log(
        `Fee: ${event.data.entry.totalFee}, Size: ${event.data.entry.totalVsize}`,
      );
      break;
    case MempoolOpType.UpdateEntry:
      console.log(`Transaction ${event.data.txid} updated in mempool`);
      break;
    case MempoolOpType.DeleteEntry:
      console.log(`Transaction ${event.data.txid} removed from mempool`);
      break;
  }
});

// Handle connection errors
client.on('error', (err) => {
  console.error('Connection error:', err);
});

// Subscribe to all mempool operations
client.subscribe({
  subscribe: [
    MempoolOpType.AddEntry,
    MempoolOpType.DeleteEntry,
    MempoolOpType.UpdateEntry,
  ],
});

// Later, to close the connection:
// client.shutdown();

API Reference

SaturnOracleTcpClient

The main client class for connecting to the Saturn Oracle service.

Constructor

constructor(addr: string, port: number, options?: TcpClientOptions)

• addr: The hostname or IP address of the Oracle server
• port: The port number of the Oracle server
• options: Optional configuration:
  • autoReconnect: Boolean indicating whether to automatically reconnect (default: false)
  • reconnectDelayMs: Delay in milliseconds before attempting to reconnect (default: 5000)

Methods

• subscribe(request: MempoolSubscriptionRequest): Initiates the subscription process
• shutdown(): Closes the connection and stops any reconnection attempts

Events

• 'event': Emitted when a new mempool event is received
• 'error': Emitted when an error occurs
• 'close': Emitted when the connection is closed
• 'reconnect': Emitted when a reconnection attempt is made

Types

MempoolOpType

Enum for the types of mempool operations:

• AddEntry: When a transaction is added to the mempool
• DeleteEntry: When a transaction is removed from the mempool
• UpdateEntry: When a transaction's state in the mempool is updated
• All: Subscribe to all operation types

MempoolEntry

Information about a transaction in the mempool:

• totalFee: The total fee in satoshis
• totalVsize: The virtual size of the transaction
• descendants: Number of descendant transactions
• ancestors: Number of ancestor transactions

MempoolEvent

Represents an event from the mempool, with operation type and relevant data.

Best Practices

1. Always implement error handling for robust applications
2. Consider enabling autoReconnect for persistent connections
3. Process events asynchronously to avoid blocking the event loop
4. When shutting down your application, call client.shutdown() to properly clean up resources