@ohmpathorn/block-node-client 0.1.0

package/README.md

@@ -0,0 +1,322 @@
+# @ohmpathorn/block-node-client
+
+[![npm version](https://img.shields.io/npm/v/@ohmpathorn/block-node-client)](https://www.npmjs.com/package/@ohmpathorn/block-node-client)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen)](https://nodejs.org)
+
+JavaScript/TypeScript SDK for the [Hedera Block Node](https://github.com/hiero-ledger/hiero-block-node) gRPC API.
+
+Wraps all four Block Node RPCs with a clean async/callback interface, full TypeScript types, and built-in protobuf decoding — so you never have to touch raw bytes.
+
+---
+
+## Install
+
+```bash
+npm install @ohmpathorn/block-node-client
+```
+
+## Quick start
+
+```ts
+import { BlockNodeClient } from "@ohmpathorn/block-node-client";
+
+const client = new BlockNodeClient({
+  endpoint: "s01.test.blk.ams.lat.ope.eng.hashgraph.io:40840",
+});
+
+// Check node health
+const status = await client.serverStatus();
+console.log("Latest block:", status.lastAvailableBlock);
+
+// Subscribe to live blocks
+const handle = client.subscribeBlockStream(
+  { startBlockNumber: status.lastAvailableBlock - 10n },
+  {
+    onStatus: (code, name) => console.log("Stream:", name),
+    onBlock:  (num, items) => console.log(`Block ${num} — ${items.length} items`),
+    onError:  (err)        => console.error(err.message),
+    onEnd:    ()           => client.close(),
+  },
+);
+
+// Cancel after 60 seconds
+setTimeout(() => handle.cancel(), 60_000);
+```
+
+---
+
+## Testnet endpoints
+
+All endpoints use port **40840**.
+
+| Region | Endpoint |
+|--------|----------|
+| Amsterdam | `s01.test.blk.ams.lat.ope.eng.hashgraph.io:40840` |
+| Singapore | `s01.test.blk.sgp.lat.ope.eng.hashgraph.io:40840` |
+| Chicago | `s01.test.blk.chi.lat.ope.eng.hashgraph.io:40840` |
+| Tier 2 | `lfh01.testnet.blocknode.hashgraph-devops.com:40840` |
+
+---
+
+## API reference
+
+### `new BlockNodeClient(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `endpoint` | `string` | required | `host:port` of the block node |
+| `tls` | `"tls" \| "insecure"` | `"tls"` | TLS or plaintext |
+| `timeout` | `number` | `10000` | Unary call timeout in ms |
+
+---
+
+### `client.serverStatus()` → `Promise<ServerStatusResponse>`
+
+Lightweight health check. Returns the available block range and node state. Always call this first to validate the range before subscribing.
+
+```ts
+const status = await client.serverStatus();
+console.log(status.firstAvailableBlock); // bigint
+console.log(status.lastAvailableBlock);  // bigint
+console.log(status.onlyLatestState);     // boolean
+```
+
+---
+
+### `client.serverStatusDetail()` → `Promise<ServerStatusDetailResponse>`
+
+Full capability report: software versions, all available block ranges, and the network address book.
+
+```ts
+const detail = await client.serverStatusDetail();
+
+const v = detail.versionInformation?.blockNodeVersion;
+console.log(`Block node: ${v?.major}.${v?.minor}.${v?.patch}`);
+
+detail.availableRanges.forEach(r =>
+  console.log(`${r.rangeStart} → ${r.rangeEnd}`)
+);
+```
+
+---
+
+### `client.getBlock(request)` → `Promise<GetBlockResponse>`
+
+Fetch a single block by number or the latest block.
+
+```ts
+// By number
+const result = await client.getBlock({ blockNumber: 38764703n });
+
+// Latest
+const latest = await client.getBlock({ retrieveLatest: true });
+
+console.log(result.statusName);    // "SUCCESS"
+console.log(result.block?.length); // number of BlockItems
+```
+
+---
+
+### `client.subscribeBlockStream(options, callbacks)` → `StreamHandle`
+
+Server-streaming RPC. Buffers `BlockItemSet` messages and fires `onBlock` once per complete block (after `end_of_block` is received).
+
+```ts
+const handle = client.subscribeBlockStream(
+  {
+    startBlockNumber: 38764000n,
+    endBlockNumber: 0n,   // 0 = live open-ended stream
+  },
+  {
+    onStatus: (code, name) => console.log("Stream status:", name),
+    onBlock:  (blockNumber, items) => {
+      items.filter(i => i.kind === "event_transaction").forEach(item => {
+        console.log(item.payload.type);                     // "CRYPTO_TRANSFER"
+        console.log(item.payload.transactionId?.toString()); // "0.0.3569@..."
+      });
+    },
+    onError: (err) => console.error(err.message),
+    onEnd:   ()    => console.log("Stream ended"),
+  },
+);
+
+handle.cancel(); // stop at any time
+```
+
+> **Note:** `endBlockNumber: 0` is automatically converted to `uint64_max` for a live stream. Pass an explicit number for a bounded historical range.
+
+---
+
+### `client.close()`
+
+Releases gRPC connections and cleans up temp files. Always call when done.
+
+---
+
+## Block items
+
+Each block is an ordered list of `BlockItem` objects. Every item has:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `kind` | `BlockItemKind` | Which oneof field is set |
+| `payload` | typed per `kind` | Decoded message |
+| `raw` | `Buffer` | Original bytes |
+
+### Item kinds
+
+| Kind | Description | Payload type |
+|------|-------------|--------------|
+| `block_header` | Block number, hash algorithm, SW versions | `BlockHeader` |
+| `event_header` | Gossip event metadata | `EventHeader` |
+| `round_header` | Consensus round number | `RoundHeader` |
+| `event_transaction` | Transaction type, ID, memo, raw bytes | `EventTransaction` |
+| `transaction_result` | Status, fee, payer, transfers, tx hash | `TransactionResult` |
+| `state_changes` | Which state tables changed | `StateChanges` |
+| `filtered_item_hash` | Hash placeholder for filtered items | `FilteredItemHash` |
+| `block_proof` | TSS block signature + Merkle proof | `BlockProof` |
+| `record_file` | Historical block (pre-HIP-1056) with embedded transactions | `RecordFile` |
+| `address_book_proof` | Network address book hashes for record-file blocks | `AddressBookProof` |
+
+### Example: switch on kind
+
+```ts
+items.forEach(item => {
+  switch (item.kind) {
+    case "block_header":
+      console.log("Block #", item.payload.number);
+      break;
+
+    case "event_transaction":
+      console.log(item.payload.type);                      // "CRYPTO_TRANSFER"
+      console.log(item.payload.transactionId?.toString()); // "0.0.3@1753912345.000000001"
+      console.log(item.payload.memo);
+      break;
+
+    case "transaction_result":
+      console.log(item.payload.statusName);      // "SUCCESS"
+      console.log(item.payload.transactionFee);  // bigint tinybars
+      item.payload.transfers.forEach(t =>
+        console.log(`  ${t.accountId?.accountNum}: ${t.amount}`)
+      );
+      break;
+
+    case "record_file":
+      // Historical block format — transactions are nested inside
+      item.payload.transactions.forEach(tx =>
+        console.log(tx.type, tx.transactionId?.toString())
+      );
+      break;
+  }
+});
+```
+
+---
+
+## Transaction IDs
+
+Hedera transaction IDs follow the format `shard.realm.account@seconds.nanos`:
+
+```ts
+const txId = item.payload.transactionId;
+console.log(txId.toString());
+// "0.0.3569@1753912345.123456789"
+
+console.log(txId.accountId);
+// { shardNum: 0n, realmNum: 0n, accountNum: 3569n }
+
+console.log(txId.transactionValidStart.toDate());
+// JavaScript Date
+```
+
+---
+
+## Transaction types
+
+All 55 Hedera transaction types are decoded automatically. You can also import the lookup table directly:
+
+```ts
+import { TX_TYPES } from "@ohmpathorn/block-node-client";
+
+TX_TYPES[14]  // "CRYPTO_TRANSFER"
+TX_TYPES[27]  // "CONSENSUS_SUBMIT_MESSAGE"
+TX_TYPES[50]  // "ETHEREUM_TRANSACTION"
+```
+
+---
+
+## Status codes
+
+```ts
+import { SubscribeStreamCode, BlockResponseCode } from "@ohmpathorn/block-node-client";
+
+// Stream subscription status (first message)
+SubscribeStreamCode.SUCCESS                   // 1
+SubscribeStreamCode.INVALID_START_BLOCK_NUMBER // 4
+SubscribeStreamCode.INVALID_END_BLOCK_NUMBER  // 5 — caused by sending end_block = 0
+SubscribeStreamCode.NOT_AVAILABLE             // 6 — block not on this node
+
+// getBlock response status
+BlockResponseCode.SUCCESS       // 1
+BlockResponseCode.NOT_FOUND     // 4
+BlockResponseCode.NOT_AVAILABLE // 5
+```
+
+---
+
+## TypeScript
+
+Full types ship with the package. Import what you need:
+
+```ts
+import {
+  BlockNodeClient,
+  BlockNodeClientOptions,
+  ServerStatusResponse,
+  ServerStatusDetailResponse,
+  BlockItem,
+  BlockItemKind,
+  BlockHeader,
+  EventTransaction,
+  TransactionResult,
+  RecordFile,
+  AddressBookProof,
+  StreamHandle,
+  SubscribeStreamCode,
+  BlockResponseCode,
+} from "@ohmpathorn/block-node-client";
+```
+
+---
+
+## Examples
+
+```bash
+# Basic usage — all four APIs
+node examples/basic.js
+
+# Live transaction monitor
+node examples/transaction-monitor.js
+
+# Multi-endpoint failover
+node examples/multi-endpoint.js
+
+# Plaintext instead of TLS
+USE_INSECURE=1 node examples/basic.js
+
+# Different endpoint
+ENDPOINT=s01.test.blk.sgp.lat.ope.eng.hashgraph.io:40840 node examples/basic.js
+```
+
+---
+
+## How it works
+
+The SDK writes the necessary protobuf definitions to a temp directory at startup and loads them via `@grpc/proto-loader`. Inner `BlockItem` payloads are decoded manually using a hand-rolled `ProtoReader` rather than generated stubs — this makes the SDK resilient to schema evolution and unknown fields.
+
+---
+
+## License
+
+[Apache 2.0](LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,81 @@
+import { BlockNodeClientOptions, ServerStatusResponse, ServerStatusDetailResponse, BlockRequestSpecifier, GetBlockResponse, BlockStreamOptions, BlockStreamCallbacks, StreamHandle } from "./types";
+/**
+ * BlockNodeClient — the main entry point for the Hedera Block Node SDK.
+ *
+ * @example
+ * ```ts
+ * import { BlockNodeClient } from "@ohmpathorn/block-node-client";
+ *
+ * const client = new BlockNodeClient({
+ *   endpoint: "s01.test.blk.ams.lat.ope.eng.hashgraph.io:40840",
+ * });
+ *
+ * const status = await client.serverStatus();
+ * console.log(status.lastAvailableBlock);
+ *
+ * client.close();
+ * ```
+ */
+export declare class BlockNodeClient {
+    private readonly options;
+    private proto;
+    private timeout;
+    constructor(options: BlockNodeClientOptions);
+    /**
+     * Lightweight health check.
+     * Returns the first/last available block and whether the node is running.
+     * Always call this before subscribing to validate the block range.
+     */
+    serverStatus(): Promise<ServerStatusResponse>;
+    /**
+     * Full capability report: versions, available block ranges, TSS data,
+     * and the current network address book.
+     */
+    serverStatusDetail(): Promise<ServerStatusDetailResponse>;
+    /**
+     * Fetch a single block by number or retrieve the latest block.
+     *
+     * @example
+     * ```ts
+     * const result = await client.getBlock({ blockNumber: 38764703n });
+     * const latest = await client.getBlock({ retrieveLatest: true });
+     * ```
+     */
+    getBlock(request: BlockRequestSpecifier): Promise<GetBlockResponse>;
+    /**
+     * Subscribe to a live or historical block stream.
+     *
+     * The server sends `block_items` batches followed by `end_of_block` for each
+     * block. This method accumulates items per block and calls `onBlock` once the
+     * block is complete.
+     *
+     * Passing `endBlockNumber: 0` (or omitting it) subscribes to a live stream.
+     *
+     * @returns A `StreamHandle` with a `cancel()` method.
+     *
+     * @example
+     * ```ts
+     * const status = await client.serverStatus();
+     *
+     * const handle = client.subscribeBlockStream(
+     *   { startBlockNumber: status.lastAvailableBlock - 10n },
+     *   {
+     *     onStatus: (code, name) => console.log("Stream status:", name),
+     *     onBlock:  (num, items) => console.log(`Block ${num}: ${items.length} items`),
+     *     onError:  (err)        => console.error("Stream error:", err.message),
+     *     onEnd:    ()           => console.log("Stream ended"),
+     *   },
+     * );
+     *
+     * // Cancel after 30 seconds
+     * setTimeout(() => handle.cancel(), 30_000);
+     * ```
+     */
+    subscribeBlockStream(options: BlockStreamOptions, callbacks: BlockStreamCallbacks): StreamHandle;
+    /**
+     * Release gRPC resources and clean up temp proto files.
+     * Call when you're done with the client.
+     */
+    close(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACrB,gBAAgB,EAEhB,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EAMb,MAAM,SAAS,CAAC;AAcjB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAS;gBAEK,OAAO,EAAE,sBAAsB;IAU5D;;;;OAIG;IACH,YAAY,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAqB7C;;;OAGG;IACH,kBAAkB,IAAI,OAAO,CAAC,0BAA0B,CAAC;IA2CzD;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,oBAAoB,CAClB,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,oBAAoB,GAC9B,YAAY;IA0Df;;;OAGG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/client.js

@@ -0,0 +1,251 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BlockNodeClient = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const proto_manager_1 = require("./proto-manager");
+const decoder_1 = require("./decoder");
+const types_1 = require("./types");
+const UINT64_MAX = "18446744073709551615";
+const SUBSCRIBE_CODE_NAMES = {
+    0: "UNKNOWN", 1: "SUCCESS", 2: "INVALID_REQUEST", 3: "ERROR",
+    4: "INVALID_START_BLOCK_NUMBER", 5: "INVALID_END_BLOCK_NUMBER", 6: "NOT_AVAILABLE",
+};
+const BLOCK_CODE_NAMES = {
+    "0": "UNKNOWN", "1": "SUCCESS", "2": "INVALID_REQUEST",
+    "3": "ERROR", "4": "NOT_FOUND", "5": "NOT_AVAILABLE",
+};
+/**
+ * BlockNodeClient — the main entry point for the Hedera Block Node SDK.
+ *
+ * @example
+ * ```ts
+ * import { BlockNodeClient } from "@ohmpathorn/block-node-client";
+ *
+ * const client = new BlockNodeClient({
+ *   endpoint: "s01.test.blk.ams.lat.ope.eng.hashgraph.io:40840",
+ * });
+ *
+ * const status = await client.serverStatus();
+ * console.log(status.lastAvailableBlock);
+ *
+ * client.close();
+ * ```
+ */
+class BlockNodeClient {
+    constructor(options) {
+        this.options = options;
+        this.proto = new proto_manager_1.ProtoManager(options.endpoint, options.tls ?? "tls");
+        this.timeout = options.timeout ?? 10000;
+    }
+    // ── 1. serverStatus ──────────────────────────────────────────────────────────
+    /**
+     * Lightweight health check.
+     * Returns the first/last available block and whether the node is running.
+     * Always call this before subscribing to validate the block range.
+     */
+    serverStatus() {
+        return new Promise((resolve, reject) => {
+            const deadline = new Date(Date.now() + this.timeout);
+            this.proto.nodeClient.serverStatus({}, { deadline }, (err, res) => {
+                if (err)
+                    return reject(err);
+                resolve({
+                    firstAvailableBlock: BigInt(res.first_available_block ?? "0"),
+                    lastAvailableBlock: BigInt(res.last_available_block ?? "0"),
+                    nextExpectedBlock: BigInt(res.next_expected_block ?? "0"),
+                    onlyLatestState: Boolean(res.only_latest_state),
+                });
+            });
+        });
+    }
+    // ── 2. serverStatusDetail ────────────────────────────────────────────────────
+    /**
+     * Full capability report: versions, available block ranges, TSS data,
+     * and the current network address book.
+     */
+    serverStatusDetail() {
+        return new Promise((resolve, reject) => {
+            const deadline = new Date(Date.now() + this.timeout);
+            this.proto.nodeClient.serverStatusDetail({}, { deadline }, (err, res) => {
+                if (err)
+                    return reject(err);
+                const mapRange = (r) => ({
+                    rangeStart: BigInt(r.range_start ?? "0"),
+                    rangeEnd: BigInt(r.range_end ?? "0"),
+                });
+                const mapSemver = (v) => v ? { major: Number(v.major), minor: Number(v.minor), patch: Number(v.patch) } : undefined;
+                let versionInformation;
+                if (res.version_information) {
+                    const vi = res.version_information;
+                    versionInformation = {
+                        streamProtoVersion: mapSemver(vi.stream_proto_version),
+                        blockNodeVersion: mapSemver(vi.block_node_version),
+                        installedPluginVersions: (vi.installed_plugin_versions ?? []).map((p) => ({
+                            pluginId: p.plugin_id ?? "",
+                            pluginSoftwareVersion: mapSemver(p.plugin_software_version),
+                            pluginFeatureNames: p.plugin_feature_names ?? [],
+                        })),
+                    };
+                }
+                resolve({
+                    versionInformation,
+                    availableRanges: (res.available_ranges ?? []).map(mapRange),
+                    storedRanges: (res.stored_ranges ?? []).map(mapRange),
+                });
+            });
+        });
+    }
+    // ── 3. getBlock ──────────────────────────────────────────────────────────────
+    /**
+     * Fetch a single block by number or retrieve the latest block.
+     *
+     * @example
+     * ```ts
+     * const result = await client.getBlock({ blockNumber: 38764703n });
+     * const latest = await client.getBlock({ retrieveLatest: true });
+     * ```
+     */
+    getBlock(request) {
+        return new Promise((resolve, reject) => {
+            const deadline = new Date(Date.now() + this.timeout);
+            const grpcRequest = "blockNumber" in request
+                ? { block_number: request.blockNumber.toString() }
+                : { retrieve_latest: true };
+            this.proto.blockClient.getBlock(grpcRequest, { deadline }, (err, res) => {
+                if (err)
+                    return reject(err);
+                // Status may come back as enum string or number
+                const statusRaw = res.status ?? "0";
+                const statusNum = typeof statusRaw === "string" && isNaN(Number(statusRaw))
+                    ? Object.values(types_1.BlockResponseCode).indexOf(statusRaw)
+                    : Number(statusRaw);
+                const statusName = BLOCK_CODE_NAMES[String(statusNum)] ?? `CODE_${statusNum}`;
+                let block;
+                if (res.block && res.block.items) {
+                    block = res.block.items.map(raw => (0, decoder_1.decodeBlockItem)(Buffer.from(raw)));
+                }
+                resolve({ status: statusNum, statusName, block });
+            });
+        });
+    }
+    // ── 4. subscribeBlockStream ──────────────────────────────────────────────────
+    /**
+     * Subscribe to a live or historical block stream.
+     *
+     * The server sends `block_items` batches followed by `end_of_block` for each
+     * block. This method accumulates items per block and calls `onBlock` once the
+     * block is complete.
+     *
+     * Passing `endBlockNumber: 0` (or omitting it) subscribes to a live stream.
+     *
+     * @returns A `StreamHandle` with a `cancel()` method.
+     *
+     * @example
+     * ```ts
+     * const status = await client.serverStatus();
+     *
+     * const handle = client.subscribeBlockStream(
+     *   { startBlockNumber: status.lastAvailableBlock - 10n },
+     *   {
+     *     onStatus: (code, name) => console.log("Stream status:", name),
+     *     onBlock:  (num, items) => console.log(`Block ${num}: ${items.length} items`),
+     *     onError:  (err)        => console.error("Stream error:", err.message),
+     *     onEnd:    ()           => console.log("Stream ended"),
+     *   },
+     * );
+     *
+     * // Cancel after 30 seconds
+     * setTimeout(() => handle.cancel(), 30_000);
+     * ```
+     */
+    subscribeBlockStream(options, callbacks) {
+        const start = BigInt(options.startBlockNumber);
+        const endRaw = options.endBlockNumber ?? 0;
+        // Sending 0 causes INVALID_END_BLOCK_NUMBER — convert to uint64_max for live streams
+        const end = BigInt(endRaw) === 0n ? UINT64_MAX : BigInt(endRaw).toString();
+        const stream = this.proto.streamClient.subscribeBlockStream({
+            start_block_number: start.toString(),
+            end_block_number: end,
+        });
+        let pending = [];
+        stream.on("data", (response) => {
+            // ── Status (first message) ─────────────────────────────────────────────
+            if (response.response === "status") {
+                const code = parseInt(response.status, 10);
+                const name = SUBSCRIBE_CODE_NAMES[code] ?? `CODE_${code}`;
+                callbacks.onStatus?.(code, name);
+                return;
+            }
+            // ── BlockItemSet (one or more items per message) ───────────────────────
+            if (response.response === "block_items") {
+                const rawItems = response.block_items?.block_items ?? [];
+                rawItems.forEach(raw => pending.push(Buffer.from(raw)));
+                return;
+            }
+            // ── end_of_block (block complete) ──────────────────────────────────────
+            if (response.response === "end_of_block") {
+                const blockNumber = BigInt(response.end_of_block?.block_number ?? "0");
+                const items = pending.map(raw => (0, decoder_1.decodeBlockItem)(raw));
+                pending = [];
+                callbacks.onBlock?.(blockNumber, items);
+                return;
+            }
+        });
+        stream.on("error", (err) => {
+            if (err.code === grpc.status.CANCELLED) {
+                callbacks.onEnd?.();
+                return;
+            }
+            callbacks.onError?.(err);
+        });
+        stream.on("end", () => {
+            callbacks.onEnd?.();
+        });
+        return {
+            cancel: () => stream.cancel(),
+        };
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────────
+    /**
+     * Release gRPC resources and clean up temp proto files.
+     * Call when you're done with the client.
+     */
+    close() {
+        this.proto.cleanup();
+    }
+}
+exports.BlockNodeClient = BlockNodeClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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