@stacks/node-publisher-client 0.2.0

package/README.md

@@ -0,0 +1,299 @@
+# @stacks/node-publisher-client
+
+A TypeScript client library for consuming Stacks blockchain events from the [Stacks Node Publisher](https://github.com/stx-labs/stacks-node-publisher) service.
+
+## Installation
+
+```bash
+npm install @stacks/node-publisher-client
+```
+
+## Quick Start
+
+```typescript
+import {
+  StacksMessageStream,
+  MessagePath,
+  StreamPosition,
+  Message,
+} from '@stacks/node-publisher-client';
+
+// Create the stream client
+const stream = new StacksMessageStream({
+  appName: 'my-app',
+  redisUrl: 'redis://localhost:6379',
+});
+
+// Connect to Redis
+await stream.connect({ waitForReady: true });
+
+// Define where to start streaming from
+const getStartPosition = async (): Promise<StreamPosition> => {
+  return null; // Start from the beginning
+};
+
+// Handle incoming messages
+const handleMessage = async (id: string, timestamp: string, message: Message) => {
+  console.log(`Received ${message.path} at ${timestamp}`);
+};
+
+// Start streaming
+stream.start(getStartPosition, handleMessage);
+```
+
+## API Reference
+
+### `StacksMessageStream`
+
+The main client class for connecting to and consuming events from a Stacks Node Publisher service.
+
+#### Constructor Options
+
+```typescript
+new StacksMessageStream({
+  appName: string;           // Required: Unique identifier for your application
+  redisUrl?: string;         // Redis connection URL (default: localhost)
+  redisStreamPrefix?: string; // Prefix for Redis stream keys
+  options?: {
+    selectedMessagePaths?: MessagePath[] | '*'; // Filter by message types (default: '*')
+    batchSize?: number;      // Messages per batch (default: 100)
+  };
+});
+```
+
+#### Methods
+
+##### `connect(options: { waitForReady: boolean }): Promise<void>`
+
+Connects to the Redis server.
+
+- `waitForReady: true` - Blocks until connected (recommended for startup)
+- `waitForReady: false` - Connects in the background
+
+```typescript
+await stream.connect({ waitForReady: true });
+```
+
+##### `start(positionCallback, messageCallback): void`
+
+Starts consuming the event stream.
+
+- `positionCallback: () => Promise<StreamPosition>` - Called to determine where to start/resume streaming
+- `messageCallback: (id, timestamp, message) => Promise<void>` - Called for each received message
+
+```typescript
+stream.start(
+  async () => ({ indexBlockHash: '0x...', blockHeight: 150000 }),
+  async (id, timestamp, message) => {
+    // Process message
+  }
+);
+```
+
+##### `stop(): Promise<void>`
+
+Gracefully stops the stream and closes the Redis connection.
+
+```typescript
+await stream.stop();
+```
+
+### `StreamPosition`
+
+Defines where to start or resume the event stream.
+
+```typescript
+type StreamPosition =
+  | { indexBlockHash: string; blockHeight: number } // Start from a specific block
+  | { messageId: string }                           // Start from a specific message ID
+  | null;                                           // Start from the beginning
+```
+
+## Message Types
+
+### `MessagePath`
+
+Enum of all available message paths:
+
+| Path | Description |
+|------|-------------|
+| `MessagePath.NewBlock` | New Stacks block with transactions and events |
+| `MessagePath.NewBurnBlock` | Bitcoin anchor block information |
+| `MessagePath.NewMempoolTx` | Transactions entering the mempool |
+| `MessagePath.DropMempoolTx` | Transactions removed from the mempool |
+| `MessagePath.StackerDbChunks` | Signer and StackerDB data chunks |
+| `MessagePath.NewMicroblocks` | Microblock data (legacy) |
+| `MessagePath.ProposalResponse` | Miner block proposal responses |
+| `MessagePath.AttachmentsNew` | Attachment data (legacy) |
+
+### `NewBlockMessage`
+
+Contains full block data including:
+
+- Block metadata (hash, height, timestamps)
+- All transactions with execution results
+- Events (STX transfers, contract events, NFT/FT operations)
+- Miner rewards
+- Signer information (epoch 3+)
+
+```typescript
+interface NewBlockMessage {
+  block_hash: string;
+  block_height: number;
+  index_block_hash: string;
+  burn_block_hash: string;
+  burn_block_height: number;
+  burn_block_time: number;
+  transactions: NewBlockTransaction[];
+  events: NewBlockEvent[];
+  matured_miner_rewards: MinerReward[];
+  // ... additional fields
+}
+```
+
+### `NewBurnBlockMessage`
+
+Bitcoin block anchoring information:
+
+```typescript
+interface NewBurnBlockMessage {
+  burn_block_hash: string;
+  burn_block_height: number;
+  burn_amount: number;           // BTC satoshis
+  reward_recipients: { recipient: string; amt: number }[];
+  reward_slot_holders: string[]; // Bitcoin addresses
+}
+```
+
+### `NewMempoolTxMessage`
+
+Array of raw hex-encoded transactions entering the mempool:
+
+```typescript
+type NewMempoolTxMessage = string[];
+```
+
+### `DropMempoolTxMessage`
+
+Transactions removed from the mempool:
+
+```typescript
+interface DropMempoolTxMessage {
+  dropped_txids: string[];
+  reason: 'ReplaceByFee' | 'ReplaceAcrossFork' | 'TooExpensive' | 'StaleGarbageCollect' | 'Problematic';
+  new_txid: string | null;
+}
+```
+
+### `StackerDbChunksMessage`
+
+Signer and StackerDB data chunks:
+
+```typescript
+interface StackerDbChunksMessage {
+  contract_id: { issuer: [number, number[]]; name: string };
+  modified_slots: {
+    slot_id: number;
+    slot_version: number;
+    data: string;    // hex string
+    sig: string;     // hex signature
+  }[];
+}
+```
+
+## Usage Examples
+
+### Filtering by Message Type
+
+```typescript
+const stream = new StacksMessageStream({
+  appName: 'block-indexer',
+  redisUrl: 'redis://localhost:6379',
+  options: {
+    selectedMessagePaths: [MessagePath.NewBlock, MessagePath.NewBurnBlock],
+  },
+});
+```
+
+### Resuming from Last Processed Block
+
+```typescript
+const getStartPosition = async (): Promise<StreamPosition> => {
+  const lastBlock = await db.getLastProcessedBlock();
+  if (lastBlock) {
+    return {
+      indexBlockHash: lastBlock.indexBlockHash,
+      blockHeight: lastBlock.height,
+    };
+  }
+  return null; // Start from beginning if no prior state
+};
+
+stream.start(getStartPosition, handleMessage);
+```
+
+### Processing Block Events
+
+```typescript
+import { MessagePath, NewBlockMessage, NewBlockEventType } from '@stacks/node-publisher-client';
+
+const handleMessage = async (id: string, timestamp: string, message: Message) => {
+  if (message.path !== MessagePath.NewBlock) return;
+
+  const block: NewBlockMessage = message.payload;
+
+  for (const event of block.events) {
+    switch (event.type) {
+      case NewBlockEventType.StxTransfer:
+        console.log(`STX Transfer: ${event.stx_transfer_event.amount} microSTX`);
+        console.log(`  From: ${event.stx_transfer_event.sender}`);
+        console.log(`  To: ${event.stx_transfer_event.recipient}`);
+        break;
+
+      case NewBlockEventType.Contract:
+        console.log(`Contract Event: ${event.contract_event.contract_identifier}`);
+        console.log(`  Topic: ${event.contract_event.topic}`);
+        break;
+
+      case NewBlockEventType.NftMint:
+        console.log(`NFT Minted: ${event.nft_mint_event.asset_identifier}`);
+        break;
+    }
+  }
+};
+```
+
+### Handling Reconnection
+
+The client automatically handles reconnection. You can listen for the `redisConsumerGroupDestroyed` event to perform additional cleanup:
+
+```typescript
+stream.events.on('redisConsumerGroupDestroyed', () => {
+  console.log('Consumer group was destroyed, will automatically reconnect');
+  // Optionally refresh your position callback state
+});
+```
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions. All message types are fully typed:
+
+```typescript
+import type {
+  Message,
+  MessagePath,
+  StreamPosition,
+  NewBlockMessage,
+  NewBlockEvent,
+  NewBlockTransaction,
+  NewBurnBlockMessage,
+  NewMempoolTxMessage,
+  DropMempoolTxMessage,
+  StackerDbChunksMessage,
+  ClarityAbi,
+} from '@stacks/node-publisher-client';
+```
+
+## License
+
+GPL-3.0-only

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { RedisClientType } from 'redis';
+import { EventEmitter } from 'node:events';
+import { Message, MessagePath } from './messages';
+/**
+ * The starting position for the message stream. Can be either an index block hash with block height
+ * or a message ID.
+ * - `indexBlockHash` + `blockHeight`: The index block hash and height of the Stacks block to start
+ *   from. The backend will resolve this to the corresponding message ID. If the block hash doesn't
+ *   exist but the height is higher than the highest available, it will start from the highest
+ *   available block.
+ * - `messageId`: The message ID to start from. The backend will validate this ID exists and is not
+ *   greater than the highest available ID.
+ *
+ * If neither is provided or validation fails, the stream will start from the beginning.
+ */
+export type StreamPosition = {
+    indexBlockHash: string;
+    blockHeight: number;
+} | {
+    messageId: string;
+} | null;
+/**
+ * The callback function for retrieving the starting position for the event stream. Should return
+ * either an index block hash with block height or a message ID. This callback is used to determine
+ * the starting message ID for the event stream and may be called periodically on reconnection.
+ */
+export type StreamPositionCallback = () => Promise<StreamPosition>;
+/**
+ * The callback function for event stream ingestion. Will be called for each message in the event
+ * stream. The callback should return a promise that resolves when the message has been processed.
+ */
+export type MessageCallback = (
+/** The message ID. */
+id: string, 
+/** The timestamp of the message. */
+timestamp: string, 
+/** The message */
+message: Message) => Promise<void>;
+/**
+ * Message paths to include in a message stream, where `*` means client wants to receive all
+ * messages.
+ */
+export type SelectedMessagePaths = MessagePath[] | '*';
+/**
+ * Stacks message stream options.
+ */
+export type StreamOptions = {
+    /**
+     * Message paths to include in a message stream, where `*` means client wants to receive all
+     * messages.
+     */
+    selectedMessagePaths?: SelectedMessagePaths;
+    /**
+     * The batch size for the message stream.
+     */
+    batchSize?: number;
+};
+/**
+ * A client for a Stacks core node message stream.
+ */
+export declare class StacksMessageStream {
+    static readonly GROUP_NAME = "primary_group";
+    static readonly CONSUMER_NAME = "primary_consumer";
+    readonly client: RedisClientType;
+    clientId: `${string}-${string}-${string}-${string}-${string}`;
+    private readonly selectedPaths;
+    private readonly redisStreamPrefix;
+    private readonly appName;
+    private readonly abort;
+    private readonly streamWaiter;
+    private readonly logger;
+    private readonly msgBatchSize;
+    /** For testing purposes only. The last message ID that was processed by this client. */
+    lastProcessedMessageId: string;
+    /** For testing purposes only. The connection status of the client. */
+    connectionStatus: 'not_started' | 'connected' | 'reconnecting' | 'ended';
+    readonly events: EventEmitter<{
+        redisConsumerGroupDestroyed: [];
+        msgReceived: [{
+            id: string;
+        }];
+    }>;
+    constructor(args: {
+        appName: string;
+        redisUrl?: string;
+        redisStreamPrefix?: string;
+        options?: StreamOptions;
+    });
+    sanitizeRedisClientName(name: string): string;
+    get redisClientName(): string;
+    connect({ waitForReady }: {
+        waitForReady: boolean;
+    }): Promise<void>;
+    start(positionCallback: StreamPositionCallback, messageCallback: MessageCallback): void;
+    private ingestEventStream;
+    stop(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StacksMessageStream = void 0;
+const redis_1 = require("redis");
+const api_toolkit_1 = require("@hirosystems/api-toolkit");
+const node_crypto_1 = require("node:crypto");
+const node_events_1 = require("node:events");
+/**
+ * A client for a Stacks core node message stream.
+ */
+class StacksMessageStream {
+    constructor(args) {
+        this.clientId = (0, node_crypto_1.randomUUID)();
+        this.logger = api_toolkit_1.logger.child({ module: 'StacksMessageStream' });
+        /** For testing purposes only. The last message ID that was processed by this client. */
+        this.lastProcessedMessageId = '0-0';
+        /** For testing purposes only. The connection status of the client. */
+        this.connectionStatus = 'not_started';
+        this.events = new node_events_1.EventEmitter();
+        this.selectedPaths = args.options?.selectedMessagePaths ?? '*';
+        this.abort = new AbortController();
+        this.streamWaiter = (0, api_toolkit_1.waiter)();
+        this.redisStreamPrefix = args.redisStreamPrefix ?? '';
+        if (this.redisStreamPrefix !== '' && !this.redisStreamPrefix.endsWith(':')) {
+            this.redisStreamPrefix += ':';
+        }
+        this.appName = this.sanitizeRedisClientName(args.appName);
+        this.msgBatchSize = args.options?.batchSize ?? 100;
+        this.client = (0, redis_1.createClient)({
+            url: args.redisUrl,
+            name: this.redisClientName,
+            disableOfflineQueue: true,
+        });
+        // Must have a listener for 'error' events to avoid unhandled exceptions
+        this.client.on('error', (err) => this.logger.error(err, `Redis error for client ${this.clientId}`));
+        this.client.on('reconnecting', () => {
+            this.connectionStatus = 'reconnecting';
+            this.logger.info(`Reconnecting to Redis for client ${this.clientId}`);
+        });
+        this.client.on('ready', () => {
+            this.connectionStatus = 'connected';
+            this.logger.info(`Redis connection ready for client ${this.clientId}`);
+        });
+        this.client.on('end', () => {
+            this.connectionStatus = 'ended';
+            this.logger.info(`Redis connection ended for client ${this.clientId}`);
+        });
+    }
+    // Sanitize the redis client name to only include valid characters (same approach used in the
+    // StackExchange.RedisClient https://github.com/StackExchange/StackExchange.Redis/pull/2654/files)
+    sanitizeRedisClientName(name) {
+        const nameSanitizer = /[^!-~]+/g;
+        return name.trim().replace(nameSanitizer, '-');
+    }
+    get redisClientName() {
+        return `${this.redisStreamPrefix}snp-consumer:${this.appName}:${this.clientId}`;
+    }
+    async connect({ waitForReady }) {
+        // Taken from `RedisBroker`.
+        if (waitForReady) {
+            while (true) {
+                try {
+                    await this.client.connect();
+                    this.logger.info(`Connected to Redis for client ${this.clientId}`);
+                    break;
+                }
+                catch (err) {
+                    this.logger.error(err, `Error connecting to Redis for client ${this.clientId}, retrying...`);
+                    await (0, api_toolkit_1.timeout)(500);
+                }
+            }
+        }
+        else {
+            void this.client.connect().catch((err) => {
+                this.logger.error(err, `Error connecting to Redis for client ${this.clientId}, retrying...`);
+                void (0, api_toolkit_1.timeout)(500).then(() => this.connect({ waitForReady }));
+            });
+        }
+    }
+    start(positionCallback, messageCallback) {
+        this.logger.info(`Starting stream ingestion for client ${this.clientId}`);
+        const runIngest = async () => {
+            while (!this.abort.signal.aborted) {
+                try {
+                    const startingPosition = await positionCallback();
+                    this.logger.info(`Starting position: ${JSON.stringify(startingPosition)}`);
+                    await this.ingestEventStream(startingPosition, messageCallback);
+                }
+                catch (error) {
+                    if (this.abort.signal.aborted) {
+                        this.logger.info('Stream ingestion aborted');
+                        break;
+                    }
+                    else if (error.message?.includes('NOGROUP')) {
+                        // The redis stream doesn't exist. This can happen if the redis server was restarted,
+                        // or if the client is idle/offline, or if the client is processing messages too slowly.
+                        // If this code path is reached, then we're obviously online so we just need to re-initialize
+                        // the connection.
+                        this.logger.error(error, `The Redis stream group for this client was destroyed by the server for client ${this.clientId}`);
+                        this.events.emit('redisConsumerGroupDestroyed');
+                        // re-announce connection, re-create group, etc
+                        continue;
+                    }
+                    else {
+                        // TODO: what are other expected errors and how should we handle them? For now we just retry
+                        // forever.
+                        this.logger.error(error, `Error reading or acknowledging from stream for client ${this.clientId}`);
+                        this.logger.info('Reconnecting to Redis stream in 1 second...');
+                        await (0, api_toolkit_1.timeout)(1000);
+                        continue;
+                    }
+                }
+            }
+        };
+        void runIngest()
+            .then(() => {
+            this.streamWaiter.finish();
+        })
+            .catch((err) => {
+            this.logger.error(err, 'Ingestion stream error');
+        });
+    }
+    async ingestEventStream(startingPosition, eventCallback) {
+        // Reset clientId for each new connection, this prevents race-conditions around cleanup
+        // for any previous connections.
+        this.clientId = (0, node_crypto_1.randomUUID)();
+        this.logger.info(`Connecting to Redis stream with clientId: ${this.clientId}`);
+        const streamKey = `${this.redisStreamPrefix}client:${this.clientId}`;
+        await this.client.clientSetName(this.redisClientName);
+        const handshakeMsg = {
+            client_id: this.clientId,
+            last_index_block_hash: startingPosition && 'indexBlockHash' in startingPosition
+                ? startingPosition.indexBlockHash
+                : '',
+            last_block_height: startingPosition && 'blockHeight' in startingPosition
+                ? startingPosition.blockHeight.toString()
+                : '',
+            last_message_id: startingPosition && 'messageId' in startingPosition ? startingPosition.messageId : '',
+            app_name: this.appName,
+            selected_paths: JSON.stringify(this.selectedPaths),
+        };
+        await this.client
+            .multi()
+            // Announce connection
+            .xAdd(this.redisStreamPrefix + 'connection_stream', '*', handshakeMsg)
+            // Create group for this stream
+            .xGroupCreate(streamKey, StacksMessageStream.GROUP_NAME, '$', {
+            MKSTREAM: true,
+        })
+            .exec();
+        // Start reading messages from the stream.
+        while (!this.abort.signal.aborted) {
+            // The backend creates the group with the correct starting position, so we use '>' here to
+            // get only messages after the last message ID.
+            const results = await this.client.xReadGroup(StacksMessageStream.GROUP_NAME, StacksMessageStream.CONSUMER_NAME, {
+                key: streamKey,
+                id: '>',
+            }, {
+                COUNT: this.msgBatchSize,
+                BLOCK: 1000, // Wait 1 second for new events.
+            });
+            if (!results) {
+                continue;
+            }
+            for (const stream of results) {
+                if (stream.messages.length > 0) {
+                    this.logger.debug(`Received messages ${stream.messages[0].id} - ${stream.messages[stream.messages.length - 1].id} with client ${this.clientId}`);
+                }
+                for (const item of stream.messages) {
+                    await eventCallback(item.id, item.message.timestamp, {
+                        path: item.message.path,
+                        payload: JSON.parse(item.message.body),
+                    });
+                    this.lastProcessedMessageId = item.id;
+                    this.events.emit('msgReceived', { id: item.id });
+                    await this.client
+                        .multi()
+                        // Acknowledge the message so that it is removed from the server's Pending Entries List (PEL)
+                        .xAck(streamKey, StacksMessageStream.GROUP_NAME, item.id)
+                        // Delete the message from the stream so that it doesn't get reprocessed
+                        .xDel(streamKey, item.id)
+                        .exec();
+                }
+            }
+        }
+    }
+    async stop() {
+        this.abort.abort();
+        await this.streamWaiter;
+        await this.client.close().catch((error) => {
+            if (error.message?.includes('client is closed')) {
+                // ignore
+            }
+            else {
+                throw error;
+            }
+        });
+    }
+}
+exports.StacksMessageStream = StacksMessageStream;
+StacksMessageStream.GROUP_NAME = 'primary_group';
+StacksMessageStream.CONSUMER_NAME = 'primary_consumer';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/messages/drop-mempool-tx.d.ts

@@ -0,0 +1,7 @@
+export type DropMempoolTxReasonType = 'ReplaceByFee' | 'ReplaceAcrossFork' | 'TooExpensive' | 'StaleGarbageCollect' | 'Problematic';
+/** Message sent when a transaction is dropped from the mempool. */
+export interface DropMempoolTxMessage {
+    dropped_txids: string[];
+    reason: DropMempoolTxReasonType;
+    new_txid: string | null;
+}

package/dist/messages/drop-mempool-tx.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=drop-mempool-tx.js.map

package/dist/messages/drop-mempool-tx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drop-mempool-tx.js","sourceRoot":"","sources":["../../src/messages/drop-mempool-tx.ts"],"names":[],"mappings":""}

package/dist/messages/index.d.ts

@@ -0,0 +1,48 @@
+import { DropMempoolTxMessage } from './drop-mempool-tx';
+import { NewBlockMessage } from './new-block';
+import { NewBurnBlockMessage } from './new-burn-block';
+import { NewMempoolTxMessage } from './new-mempool-tx';
+import { StackerDbChunksMessage } from './stackerdb-chunks';
+export * from './drop-mempool-tx';
+export * from './new-block';
+export * from './new-burn-block';
+export * from './new-mempool-tx';
+export * from './stackerdb-chunks';
+/**
+ * The path of the Stacks message as sent by the Stacks node.
+ */
+export declare enum MessagePath {
+    NewBlock = "/new_block",
+    NewBurnBlock = "/new_burn_block",
+    NewMempoolTx = "/new_mempool_tx",
+    DropMempoolTx = "/drop_mempool_tx",
+    NewMicroblocks = "/new_microblocks",
+    StackerDbChunks = "/stackerdb_chunks",
+    ProposalResponse = "/proposal_response",
+    AttachmentsNew = "/attachments/new"
+}
+export type Message = {
+    path: MessagePath.NewBlock;
+    payload: NewBlockMessage;
+} | {
+    path: MessagePath.NewBurnBlock;
+    payload: NewBurnBlockMessage;
+} | {
+    path: MessagePath.NewMempoolTx;
+    payload: NewMempoolTxMessage;
+} | {
+    path: MessagePath.DropMempoolTx;
+    payload: DropMempoolTxMessage;
+} | {
+    path: MessagePath.StackerDbChunks;
+    payload: StackerDbChunksMessage;
+} | {
+    path: MessagePath.NewMicroblocks;
+    payload: unknown;
+} | {
+    path: MessagePath.ProposalResponse;
+    payload: unknown;
+} | {
+    path: MessagePath.AttachmentsNew;
+    payload: unknown;
+};

package/dist/messages/index.js

@@ -0,0 +1,37 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessagePath = void 0;
+__exportStar(require("./drop-mempool-tx"), exports);
+__exportStar(require("./new-block"), exports);
+__exportStar(require("./new-burn-block"), exports);
+__exportStar(require("./new-mempool-tx"), exports);
+__exportStar(require("./stackerdb-chunks"), exports);
+/**
+ * The path of the Stacks message as sent by the Stacks node.
+ */
+var MessagePath;
+(function (MessagePath) {
+    MessagePath["NewBlock"] = "/new_block";
+    MessagePath["NewBurnBlock"] = "/new_burn_block";
+    MessagePath["NewMempoolTx"] = "/new_mempool_tx";
+    MessagePath["DropMempoolTx"] = "/drop_mempool_tx";
+    MessagePath["NewMicroblocks"] = "/new_microblocks";
+    MessagePath["StackerDbChunks"] = "/stackerdb_chunks";
+    MessagePath["ProposalResponse"] = "/proposal_response";
+    MessagePath["AttachmentsNew"] = "/attachments/new";
+})(MessagePath || (exports.MessagePath = MessagePath = {}));
+//# sourceMappingURL=index.js.map

package/dist/messages/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAMA,oDAAkC;AAClC,8CAA4B;AAC5B,mDAAiC;AACjC,mDAAiC;AACjC,qDAAmC;AAEnC;;GAEG;AACH,IAAY,WASX;AATD,WAAY,WAAW;IACrB,sCAAuB,CAAA;IACvB,+CAAgC,CAAA;IAChC,+CAAgC,CAAA;IAChC,iDAAkC,CAAA;IAClC,kDAAmC,CAAA;IACnC,oDAAqC,CAAA;IACrC,sDAAuC,CAAA;IACvC,kDAAmC,CAAA;AACrC,CAAC,EATW,WAAW,2BAAX,WAAW,QAStB"}

package/dist/messages/new-block.d.ts

@@ -0,0 +1,357 @@
+export declare enum NewBlockEventType {
+    Contract = "contract_event",
+    StxTransfer = "stx_transfer_event",
+    StxMint = "stx_mint_event",
+    StxBurn = "stx_burn_event",
+    StxLock = "stx_lock_event",
+    NftTransfer = "nft_transfer_event",
+    NftMint = "nft_mint_event",
+    NftBurn = "nft_burn_event",
+    FtTransfer = "ft_transfer_event",
+    FtMint = "ft_mint_event",
+    FtBurn = "ft_burn_event"
+}
+interface NewBlockEventBase {
+    /** 0x-prefix transaction hash. */
+    txid: string;
+    event_index: number;
+    committed: boolean;
+}
+export interface NewBlockContractEvent extends NewBlockEventBase {
+    type: NewBlockEventType.Contract;
+    contract_event: {
+        /** Fully qualified contract ID, e.g. "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH.kv-store" */
+        contract_identifier: string;
+        topic: string;
+        /** @deprecated Use `raw_value` instead. */
+        value: unknown;
+        /** Hex encoded Clarity value. */
+        raw_value: string;
+    };
+}
+export interface NewBlockStxTransferEvent extends NewBlockEventBase {
+    type: NewBlockEventType.StxTransfer;
+    stx_transfer_event: {
+        recipient: string;
+        sender: string;
+        amount: string;
+        /** Hex-encoded string. Only provided when a memo was specified in the Clarity `stx-transfer?` function (requires a Stacks 2.1 contract). */
+        memo?: string;
+    };
+}
+export interface NewBlockStxMintEvent extends NewBlockEventBase {
+    type: NewBlockEventType.StxMint;
+    stx_mint_event: {
+        recipient: string;
+        amount: string;
+    };
+}
+interface NewBlockStxBurnEvent extends NewBlockEventBase {
+    type: NewBlockEventType.StxBurn;
+    stx_burn_event: {
+        sender: string;
+        amount: string;
+    };
+}
+export interface NewBlockStxLockEvent extends NewBlockEventBase {
+    type: NewBlockEventType.StxLock;
+    committed: boolean;
+    stx_lock_event: {
+        /** String quoted base10 integer. */
+        locked_amount: string;
+        /** String quoted base10 integer. */
+        unlock_height: string;
+        /** STX principal associated with the locked tokens. */
+        locked_address: string;
+        /** Fully qualified contract ID, e.g. "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH.pox" or "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH.pox-2" */
+        contract_identifier?: string;
+    };
+}
+interface NewBlockNftTransferEvent extends NewBlockEventBase {
+    type: NewBlockEventType.NftTransfer;
+    nft_transfer_event: {
+        /** Fully qualified asset ID, e.g. "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH.contract-name.asset-name" */
+        asset_identifier: string;
+        recipient: string;
+        sender: string;
+        /** @deprecated Use `raw_value` instead. */
+        value: unknown;
+        /** Hex encoded Clarity value. */
+        raw_value: string;
+    };
+}
+export interface NewBlockNftMintEvent extends NewBlockEventBase {
+    type: NewBlockEventType.NftMint;
+    nft_mint_event: {
+        /** Fully qualified asset ID, e.g. "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH.contract-name.asset-name" */
+        asset_identifier: string;
+        recipient: string;
+        /** @deprecated Use `raw_value` instead. */
+        value: unknown;
+        /** Hex encoded Clarity value. */
+        raw_value: string;
+    };
+}
+interface NewBlockNftBurnEvent extends NewBlockEventBase {
+    type: NewBlockEventType.NftBurn;
+    nft_burn_event: {
+        /** Fully qualified asset ID, e.g. "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH.contract-name.asset-name" */
+        asset_identifier: string;
+        sender: string;
+        /** @deprecated Use `raw_value` instead. */
+        value: unknown;
+        /** Hex encoded Clarity value. */
+        raw_value: string;
+    };
+}
+interface NewBlockFtTransferEvent extends NewBlockEventBase {
+    type: NewBlockEventType.FtTransfer;
+    ft_transfer_event: {
+        /** Fully qualified asset ID, e.g. "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH.contract-name.asset-name" */
+        asset_identifier: string;
+        recipient: string;
+        sender: string;
+        amount: string;
+    };
+}
+export interface NewBlockFtMintEvent extends NewBlockEventBase {
+    type: NewBlockEventType.FtMint;
+    ft_mint_event: {
+        /** Fully qualified asset ID, e.g. "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH.contract-name.asset-name" */
+        asset_identifier: string;
+        recipient: string;
+        amount: string;
+    };
+}
+interface NewBlockFtBurnEvent extends NewBlockEventBase {
+    type: NewBlockEventType.FtBurn;
+    ft_burn_event: {
+        /** Fully qualified asset ID, e.g. "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH.contract-name.asset-name" */
+        asset_identifier: string;
+        sender: string;
+        amount: string;
+    };
+}
+export interface BurnchainOpRegisterAssetNft {
+    register_asset: {
+        asset_type: 'nft';
+        burn_header_hash: string;
+        l1_contract_id: string;
+        l2_contract_id: string;
+        txid: string;
+    };
+}
+export interface BurnchainOpRegisterAssetFt {
+    register_asset: {
+        asset_type: 'ft';
+        burn_header_hash: string;
+        l1_contract_id: string;
+        l2_contract_id: string;
+        txid: string;
+    };
+}
+export interface BurnchainOpStackStx {
+    stack_stx: {
+        auth_id: number;
+        burn_block_height: number;
+        burn_header_hash: string;
+        burn_txid: string;
+        max_amount: number;
+        num_cycles: number;
+        reward_addr: string;
+        sender: {
+            address: string;
+            address_hash_bytes: string;
+            address_version: number;
+        };
+        signer_key: string;
+        stacked_ustx: number;
+        vtxindex: number;
+    };
+}
+export interface BurnchainOpDelegateStx {
+    delegate_stx: {
+        burn_block_height: number;
+        burn_header_hash: string;
+        burn_txid: string;
+        delegate_to: {
+            address: string;
+            address_hash_bytes: string;
+            address_version: number;
+        };
+        delegated_ustx: number;
+        reward_addr: [
+            number,
+            string
+        ];
+        sender: {
+            address: string;
+            address_hash_bytes: string;
+            address_version: number;
+        };
+        until_burn_height: number;
+        vtxindex: number;
+    };
+}
+type BurnchainOp = BurnchainOpRegisterAssetNft | BurnchainOpRegisterAssetFt | BurnchainOpStackStx | BurnchainOpDelegateStx;
+export type NewBlockEvent = NewBlockContractEvent | NewBlockStxTransferEvent | NewBlockStxMintEvent | NewBlockStxBurnEvent | NewBlockStxLockEvent | NewBlockFtTransferEvent | NewBlockFtMintEvent | NewBlockFtBurnEvent | NewBlockNftTransferEvent | NewBlockNftMintEvent | NewBlockNftBurnEvent;
+export type NewBlockTransactionStatus = 'success' | 'abort_by_response' | 'abort_by_post_condition';
+type ClarityAbiTypeBuffer = {
+    buffer: {
+        length: number;
+    };
+};
+type ClarityAbiTypeResponse = {
+    response: {
+        ok: ClarityAbiType;
+        error: ClarityAbiType;
+    };
+};
+type ClarityAbiTypeOptional = {
+    optional: ClarityAbiType;
+};
+type ClarityAbiTypeTuple = {
+    tuple: {
+        name: string;
+        type: ClarityAbiType;
+    }[];
+};
+type ClarityAbiTypeList = {
+    list: {
+        type: ClarityAbiType;
+        length: number;
+    };
+};
+type ClarityAbiTypeUInt128 = 'uint128';
+type ClarityAbiTypeInt128 = 'int128';
+type ClarityAbiTypeBool = 'bool';
+type ClarityAbiTypePrincipal = 'principal';
+type ClarityAbiTypeNone = 'none';
+type ClarityAbiTypePrimitive = ClarityAbiTypeUInt128 | ClarityAbiTypeInt128 | ClarityAbiTypeBool | ClarityAbiTypePrincipal | ClarityAbiTypeNone;
+type ClarityAbiType = ClarityAbiTypePrimitive | ClarityAbiTypeBuffer | ClarityAbiTypeResponse | ClarityAbiTypeOptional | ClarityAbiTypeTuple | ClarityAbiTypeList;
+interface ClarityAbiFunction {
+    name: string;
+    access: 'private' | 'public' | 'read_only';
+    args: {
+        name: string;
+        type: ClarityAbiType;
+    }[];
+    outputs: {
+        type: ClarityAbiType;
+    };
+}
+interface ClarityAbiVariable {
+    name: string;
+    access: 'variable' | 'constant';
+    type: ClarityAbiType;
+}
+interface ClarityAbiMap {
+    name: string;
+    key: {
+        name: string;
+        type: ClarityAbiType;
+    }[];
+    value: {
+        name: string;
+        type: ClarityAbiType;
+    }[];
+}
+interface ClarityAbiTypeFungibleToken {
+    name: string;
+}
+interface ClarityAbiTypeNonFungibleToken {
+    name: string;
+    type: ClarityAbiType;
+}
+export interface ClarityAbi {
+    functions: ClarityAbiFunction[];
+    variables: ClarityAbiVariable[];
+    maps: ClarityAbiMap[];
+    fungible_tokens: ClarityAbiTypeFungibleToken[];
+    non_fungible_tokens: ClarityAbiTypeNonFungibleToken[];
+}
+interface NewBlockExecutionCost {
+    read_count: number;
+    read_length: number;
+    runtime: number;
+    write_count: number;
+    write_length: number;
+}
+export interface NewBlockTransaction {
+    raw_tx: string;
+    status: NewBlockTransactionStatus;
+    raw_result: string;
+    txid: string;
+    tx_index: number;
+    contract_interface: ClarityAbi | null;
+    /** @deprecated Use `contract_interface` instead. The node renamed `contract_abi` to `contract_interface`. */
+    contract_abi?: ClarityAbi | null;
+    execution_cost: NewBlockExecutionCost;
+    microblock_sequence: number | null;
+    microblock_hash: string | null;
+    microblock_parent_hash: string | null;
+    vm_error?: string | null;
+    burnchain_op?: BurnchainOp | null;
+}
+export interface NewBlockMessage {
+    block_hash: string;
+    block_height: number;
+    burn_block_time: number;
+    burn_block_hash: string;
+    burn_block_height: number;
+    miner_txid: string;
+    index_block_hash: string;
+    parent_index_block_hash: string;
+    parent_block_hash: string;
+    parent_microblock: string;
+    parent_microblock_sequence: number;
+    parent_burn_block_hash: string;
+    parent_burn_block_height: number;
+    parent_burn_block_timestamp: number;
+    events: NewBlockEvent[];
+    transactions: NewBlockTransaction[];
+    matured_miner_rewards: {
+        from_index_consensus_hash: string;
+        from_stacks_block_hash: string;
+        /** STX principal */
+        recipient: string;
+        /** STX principal (available starting in Stacks 2.1) */
+        miner_address: string | null;
+        /** String quoted micro-STX amount. */
+        coinbase_amount: string;
+        /** String quoted micro-STX amount. */
+        tx_fees_anchored: string;
+        /** String quoted micro-STX amount. */
+        tx_fees_streamed_confirmed: string;
+        /** String quoted micro-STX amount. */
+        tx_fees_streamed_produced: string;
+    }[];
+    anchored_cost?: NewBlockExecutionCost;
+    confirmed_microblocks_cost?: NewBlockExecutionCost;
+    pox_v1_unlock_height?: number;
+    pox_v2_unlock_height?: number;
+    pox_v3_unlock_height?: number;
+    /** Available starting in epoch3, only included in blocks where the pox cycle rewards are first calculated */
+    cycle_number?: number;
+    /** AKA `coinbase_height`. In epoch2.x this is the same as `block_height`. In epoch3 this is used to track tenure heights. Only available starting in stacks-core 3.0.0.0.0-rc6 */
+    tenure_height?: number | null;
+    /** Available starting in epoch3, only included in blocks where the pox cycle rewards are first calculated */
+    reward_set?: {
+        pox_ustx_threshold: string;
+        rewarded_addresses: string[];
+        signers?: {
+            signing_key: string;
+            weight: number;
+            stacked_amt: string;
+        }[];
+        start_cycle_state: {
+            missed_reward_slots: [];
+        };
+    };
+    block_time: number | null;
+    signer_bitvec?: string | null;
+    signer_signature?: string[];
+    signer_signature_hash: string;
+    miner_signature: string;
+}
+export {};

package/dist/messages/new-block.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NewBlockEventType = void 0;
+var NewBlockEventType;
+(function (NewBlockEventType) {
+    NewBlockEventType["Contract"] = "contract_event";
+    NewBlockEventType["StxTransfer"] = "stx_transfer_event";
+    NewBlockEventType["StxMint"] = "stx_mint_event";
+    NewBlockEventType["StxBurn"] = "stx_burn_event";
+    NewBlockEventType["StxLock"] = "stx_lock_event";
+    NewBlockEventType["NftTransfer"] = "nft_transfer_event";
+    NewBlockEventType["NftMint"] = "nft_mint_event";
+    NewBlockEventType["NftBurn"] = "nft_burn_event";
+    NewBlockEventType["FtTransfer"] = "ft_transfer_event";
+    NewBlockEventType["FtMint"] = "ft_mint_event";
+    NewBlockEventType["FtBurn"] = "ft_burn_event";
+})(NewBlockEventType || (exports.NewBlockEventType = NewBlockEventType = {}));
+//# sourceMappingURL=new-block.js.map

package/dist/messages/new-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-block.js","sourceRoot":"","sources":["../../src/messages/new-block.ts"],"names":[],"mappings":";;;AAAA,IAAY,iBAYX;AAZD,WAAY,iBAAiB;IAC3B,gDAA2B,CAAA;IAC3B,uDAAkC,CAAA;IAClC,+CAA0B,CAAA;IAC1B,+CAA0B,CAAA;IAC1B,+CAA0B,CAAA;IAC1B,uDAAkC,CAAA;IAClC,+CAA0B,CAAA;IAC1B,+CAA0B,CAAA;IAC1B,qDAAgC,CAAA;IAChC,6CAAwB,CAAA;IACxB,6CAAwB,CAAA;AAC1B,CAAC,EAZW,iBAAiB,iCAAjB,iBAAiB,QAY5B"}

package/dist/messages/new-burn-block.d.ts

@@ -0,0 +1,20 @@
+export interface NewBurnBlockMessage {
+    burn_block_hash: string;
+    burn_block_height: number;
+    /** Amount in BTC satoshis. */
+    burn_amount: number;
+    reward_recipients: [
+        {
+            /** Bitcoin address (b58 encoded). */
+            recipient: string;
+            /** Amount in BTC satoshis. */
+            amt: number;
+        }
+    ];
+    /**
+     * Array of the Bitcoin addresses that would validly receive PoX commitments during this block.
+     * These addresses may not actually receive rewards during this block if the block is faster
+     * than miners have an opportunity to commit.
+     */
+    reward_slot_holders: string[];
+}

package/dist/messages/new-burn-block.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=new-burn-block.js.map

package/dist/messages/new-burn-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-burn-block.js","sourceRoot":"","sources":["../../src/messages/new-burn-block.ts"],"names":[],"mappings":""}

package/dist/messages/new-mempool-tx.d.ts

@@ -0,0 +1,2 @@
+/** Array of raw hex encoded mempool transactions. */
+export type NewMempoolTxMessage = string[];

package/dist/messages/new-mempool-tx.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=new-mempool-tx.js.map

package/dist/messages/new-mempool-tx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"new-mempool-tx.js","sourceRoot":"","sources":["../../src/messages/new-mempool-tx.ts"],"names":[],"mappings":""}

package/dist/messages/stackerdb-chunks.d.ts

@@ -0,0 +1,17 @@
+export interface StackerDbChunksModifiedSlot {
+    /** Slot identifier (unique for each DB instance) */
+    slot_id: number;
+    /** Slot version (a lamport clock) */
+    slot_version: number;
+    /** Chunk data (use the sha512_256 hashed of this for generating a signature) */
+    data: string;
+    /** signature over the above */
+    sig: string;
+}
+export interface StackerDbChunksMessage {
+    contract_id: {
+        issuer: [number, number[]];
+        name: string;
+    };
+    modified_slots: StackerDbChunksModifiedSlot[];
+}

package/dist/messages/stackerdb-chunks.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=stackerdb-chunks.js.map

package/dist/messages/stackerdb-chunks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stackerdb-chunks.js","sourceRoot":"","sources":["../../src/messages/stackerdb-chunks.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@stacks/node-publisher-client",
+  "version": "0.2.0",
+  "description": "A client to consume Stacks events from the Stacks Node Publisher service",
+  "main": "./dist/index.js",
+  "typings": "./dist/index.d.ts",
+  "scripts": {
+    "build": "rimraf ./dist && tsc --project tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stx-labs/stacks-node-publisher.git",
+    "directory": "client"
+  },
+  "keywords": [
+    "stacks",
+    "node-publisher",
+    "client"
+  ],
+  "author": "Stacks Labs",
+  "license": "GPL-3.0-only",
+  "devDependencies": {
+    "rimraf": "^6.0.1",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "@hirosystems/api-toolkit": "^1.12.0",
+    "redis": "^5.10.0"
+  }
+}