four-flap-meme-sdk 1.5.55 → 1.5.56

package/dist/sol/dex/blockrazor/geyser.d.ts

@@ -0,0 +1,128 @@
+/**
+ * BlockRazor Geyser Stream 服务
+ * @module sol/dex/blockrazor/geyser
+ *
+ * Geyser Stream 是基于 Yellowstone gRPC 的高性能 Solana 数据流服务。
+ *
+ * @see https://blockrazor.gitbook.io/blockrazor/solana/geyser-stream
+ */
+import type { GeyserRegion, GeyserSubscribeConfig, GeyserClientConfig, GeyserEventHandlers, GeyserStreamControl } from './types.js';
+/**
+ * Geyser Proto 定义（内联）
+ *
+ * 用于动态加载 gRPC 服务
+ */
+export declare const GEYSER_PROTO_DEFINITION = "\nsyntax = \"proto3\";\n\npackage geyser;\n\nservice Geyser {\n  rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeUpdate);\n}\n\nmessage SubscribeRequest {\n  map<string, SubscribeRequestFilterAccounts> accounts = 1;\n  map<string, SubscribeRequestFilterSlots> slots = 2;\n  map<string, SubscribeRequestFilterTransactions> transactions = 3;\n  map<string, SubscribeRequestFilterBlocks> blocks = 4;\n  map<string, SubscribeRequestFilterBlocksMeta> blocks_meta = 5;\n  map<string, SubscribeRequestFilterEntry> entry = 6;\n  optional CommitmentLevel commitment = 7;\n  repeated SubscribeRequestAccountsDataSlice accounts_data_slice = 8;\n  optional SubscribeRequestPing ping = 9;\n}\n\nenum CommitmentLevel {\n  PROCESSED = 0;\n  CONFIRMED = 1;\n  FINALIZED = 2;\n}\n\nmessage SubscribeRequestFilterAccounts {\n  repeated string account = 1;\n  repeated string owner = 2;\n  repeated SubscribeRequestFilterAccountsFilter filters = 3;\n  optional bool nonempty_txn_signature = 4;\n}\n\nmessage SubscribeRequestFilterAccountsFilter {\n  oneof filter {\n    SubscribeRequestFilterAccountsFilterMemcmp memcmp = 1;\n    uint64 datasize = 2;\n    bool token_account_state = 3;\n    SubscribeRequestFilterAccountsFilterLamports lamports = 4;\n  }\n}\n\nmessage SubscribeRequestFilterAccountsFilterMemcmp {\n  uint64 offset = 1;\n  oneof data {\n    bytes bytes = 2;\n    string base58 = 3;\n    string base64 = 4;\n  }\n}\n\nmessage SubscribeRequestFilterAccountsFilterLamports {\n  oneof cmp {\n    uint64 eq = 1;\n    uint64 ne = 2;\n    uint64 lt = 3;\n    uint64 gt = 4;\n  }\n}\n\nmessage SubscribeRequestFilterSlots {\n  optional bool filter_by_commitment = 1;\n  optional bool interleave_global_updates = 2;\n}\n\nmessage SubscribeRequestFilterTransactions {\n  optional bool vote = 1;\n  optional bool failed = 2;\n  optional string signature = 3;\n  repeated string account_include = 4;\n  repeated string account_exclude = 5;\n  repeated string account_required = 6;\n}\n\nmessage SubscribeRequestFilterBlocks {\n  repeated string account_include = 1;\n  optional bool include_transactions = 2;\n  optional bool include_accounts = 3;\n  optional bool include_entries = 4;\n}\n\nmessage SubscribeRequestFilterBlocksMeta {}\n\nmessage SubscribeRequestFilterEntry {}\n\nmessage SubscribeRequestAccountsDataSlice {\n  uint64 offset = 1;\n  uint64 length = 2;\n}\n\nmessage SubscribeRequestPing {\n  int32 id = 1;\n}\n\nmessage SubscribeUpdate {\n  repeated string filters = 1;\n  oneof update_oneof {\n    SubscribeUpdateAccount account = 2;\n    SubscribeUpdateSlot slot = 3;\n    SubscribeUpdateTransaction transaction = 4;\n    SubscribeUpdateTransactionInfo transaction_info = 10;\n    SubscribeUpdateBlock block = 5;\n    SubscribeUpdatePing ping = 6;\n    SubscribeUpdatePong pong = 7;\n    SubscribeUpdateBlockMeta block_meta = 8;\n    SubscribeUpdateEntry entry = 9;\n  }\n  uint64 created_at = 11;\n}\n\nmessage SubscribeUpdateAccount {\n  SubscribeUpdateAccountInfo account = 1;\n  uint64 slot = 2;\n  optional bool is_startup = 3;\n}\n\nmessage SubscribeUpdateAccountInfo {\n  bytes pubkey = 1;\n  uint64 lamports = 2;\n  bytes owner = 3;\n  bool executable = 4;\n  uint64 rent_epoch = 5;\n  bytes data = 6;\n  uint64 write_version = 7;\n  optional bytes txn_signature = 8;\n}\n\nmessage SubscribeUpdateSlot {\n  uint64 slot = 1;\n  optional uint64 parent = 2;\n  CommitmentLevel status = 3;\n  optional int64 dead_error = 4;\n}\n\nmessage SubscribeUpdateTransaction {\n  SubscribeUpdateTransactionInfo transaction = 1;\n  uint64 slot = 2;\n}\n\nmessage SubscribeUpdateTransactionInfo {\n  bytes signature = 1;\n  bool is_vote = 2;\n  bytes transaction = 3;\n  bytes meta = 4;\n  optional uint64 index = 5;\n}\n\nmessage SubscribeUpdateBlock {\n  uint64 slot = 1;\n  string blockhash = 2;\n  SubscribeUpdateBlockRewards rewards = 3;\n  UnixTimestamp block_time = 4;\n  BlockHeight block_height = 5;\n  uint64 parent_slot = 6;\n  string parent_blockhash = 7;\n  uint64 executed_transaction_count = 8;\n  uint64 entries_count = 9;\n  repeated SubscribeUpdateTransactionInfo transactions = 10;\n  repeated SubscribeUpdateAccountInfo updated_account_count = 11;\n  repeated SubscribeUpdateEntry entries = 12;\n}\n\nmessage SubscribeUpdateBlockRewards {\n  bytes rewards = 1;\n}\n\nmessage UnixTimestamp {\n  int64 timestamp = 1;\n}\n\nmessage BlockHeight {\n  uint64 block_height = 1;\n}\n\nmessage SubscribeUpdatePing {}\n\nmessage SubscribeUpdatePong {\n  int32 id = 1;\n}\n\nmessage SubscribeUpdateBlockMeta {\n  uint64 slot = 1;\n  string blockhash = 2;\n  SubscribeUpdateBlockRewards rewards = 3;\n  UnixTimestamp block_time = 4;\n  BlockHeight block_height = 5;\n  uint64 parent_slot = 6;\n  string parent_blockhash = 7;\n  uint64 executed_transaction_count = 8;\n  uint64 entries_count = 9;\n}\n\nmessage SubscribeUpdateEntry {\n  uint64 slot = 1;\n  uint64 index = 2;\n  uint64 num_hashes = 3;\n  bytes hash = 4;\n  uint64 executed_transaction_count = 5;\n  optional uint64 starting_transaction_index = 6;\n}\n";
+/**
+ * 获取 Geyser Stream 端点
+ *
+ * @param region 区域
+ * @returns gRPC 端点地址
+ */
+export declare function getGeyserEndpoint(region?: GeyserRegion): string;
+/**
+ * 构建 Geyser 订阅请求
+ *
+ * @param config 订阅配置
+ * @returns gRPC 请求对象
+ */
+export declare function buildGeyserSubscribeRequest(config: GeyserSubscribeConfig): Record<string, unknown>;
+/**
+ * 创建默认账户订阅配置
+ *
+ * @param owners 拥有者地址列表
+ * @param accounts 特定账户地址列表
+ * @returns 订阅配置
+ */
+export declare function createAccountSubscribeConfig(owners?: string[], accounts?: string[]): GeyserSubscribeConfig;
+/**
+ * 创建默认交易订阅配置
+ *
+ * @param accountInclude 包含涉及这些账户的交易
+ * @param accountRequired 交易必须涉及这些账户
+ * @returns 订阅配置
+ */
+export declare function createTransactionSubscribeConfig(accountInclude?: string[], accountRequired?: string[]): GeyserSubscribeConfig;
+/**
+ * 创建默认区块订阅配置
+ *
+ * @param accountInclude 包含涉及这些账户的区块
+ * @param includeTransactions 是否包含交易
+ * @returns 订阅配置
+ */
+export declare function createBlockSubscribeConfig(accountInclude?: string[], includeTransactions?: boolean): GeyserSubscribeConfig;
+/**
+ * 创建 Geyser 订阅（需要 @grpc/grpc-js 和 @grpc/proto-loader）
+ *
+ * 注意：此函数需要安装 gRPC 依赖：
+ * ```bash
+ * npm install @grpc/grpc-js @grpc/proto-loader
+ * ```
+ *
+ * @param clientConfig 客户端配置
+ * @param subscribeConfig 订阅配置
+ * @param handlers 事件处理器
+ * @returns 流控制对象
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ * import bs58 from 'bs58'
+ *
+ * const stream = await Sol.createGeyserSubscription(
+ *   {
+ *     host: Sol.getGeyserEndpoint('tokyo'),
+ *     token: 'your-auth-token',
+ *   },
+ *   Sol.createTransactionSubscribeConfig(
+ *     ['your-account-address'], // 监听涉及此账户的交易
+ *   ),
+ *   {
+ *     onTransaction: (update, raw) => {
+ *       console.log(`交易: ${bs58.encode(update.transaction.signature)}`)
+ *     },
+ *     onError: (err) => console.error('错误:', err),
+ *     onEnd: () => console.log('流结束'),
+ *   },
+ * )
+ *
+ * // 关闭流
+ * stream.close()
+ * ```
+ */
+export declare function createGeyserSubscription(clientConfig: GeyserClientConfig, subscribeConfig: GeyserSubscribeConfig, handlers: GeyserEventHandlers): Promise<GeyserStreamControl>;
+/**
+ * 简化版：订阅账户更新
+ *
+ * @param token 认证 Token
+ * @param accounts 账户地址列表
+ * @param onUpdate 更新回调
+ * @param region 区域（默认 tokyo）
+ * @returns 流控制对象
+ */
+export declare function subscribeGeyserAccounts(token: string, accounts: string[], onUpdate: (pubkey: string, lamports: string, slot: string) => void, region?: GeyserRegion): Promise<{
+    close: () => void;
+}>;
+/**
+ * 简化版：订阅交易更新
+ *
+ * @param token 认证 Token
+ * @param accountInclude 包含涉及这些账户的交易
+ * @param onUpdate 更新回调
+ * @param region 区域（默认 tokyo）
+ * @returns 流控制对象
+ */
+export declare function subscribeGeyserTransactions(token: string, accountInclude: string[], onUpdate: (signature: string, isVote: boolean, slot: string) => void, region?: GeyserRegion): Promise<{
+    close: () => void;
+}>;
+/**
+ * 简化版：订阅区块更新
+ *
+ * @param token 认证 Token
+ * @param onUpdate 更新回调
+ * @param region 区域（默认 tokyo）
+ * @returns 流控制对象
+ */
+export declare function subscribeGeyserBlocks(token: string, onUpdate: (slot: string, blockhash: string, txCount: number) => void, region?: GeyserRegion): Promise<{
+    close: () => void;
+}>;

package/dist/sol/dex/blockrazor/geyser.js

@@ -0,0 +1,530 @@
+/**
+ * BlockRazor Geyser Stream 服务
+ * @module sol/dex/blockrazor/geyser
+ *
+ * Geyser Stream 是基于 Yellowstone gRPC 的高性能 Solana 数据流服务。
+ *
+ * @see https://blockrazor.gitbook.io/blockrazor/solana/geyser-stream
+ */
+import { GEYSER_STREAM_ENDPOINTS } from './constants.js';
+// ============================================================================
+// Geyser Proto 定义
+// ============================================================================
+/**
+ * Geyser Proto 定义（内联）
+ *
+ * 用于动态加载 gRPC 服务
+ */
+export const GEYSER_PROTO_DEFINITION = `
+syntax = "proto3";
+
+package geyser;
+
+service Geyser {
+  rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeUpdate);
+}
+
+message SubscribeRequest {
+  map<string, SubscribeRequestFilterAccounts> accounts = 1;
+  map<string, SubscribeRequestFilterSlots> slots = 2;
+  map<string, SubscribeRequestFilterTransactions> transactions = 3;
+  map<string, SubscribeRequestFilterBlocks> blocks = 4;
+  map<string, SubscribeRequestFilterBlocksMeta> blocks_meta = 5;
+  map<string, SubscribeRequestFilterEntry> entry = 6;
+  optional CommitmentLevel commitment = 7;
+  repeated SubscribeRequestAccountsDataSlice accounts_data_slice = 8;
+  optional SubscribeRequestPing ping = 9;
+}
+
+enum CommitmentLevel {
+  PROCESSED = 0;
+  CONFIRMED = 1;
+  FINALIZED = 2;
+}
+
+message SubscribeRequestFilterAccounts {
+  repeated string account = 1;
+  repeated string owner = 2;
+  repeated SubscribeRequestFilterAccountsFilter filters = 3;
+  optional bool nonempty_txn_signature = 4;
+}
+
+message SubscribeRequestFilterAccountsFilter {
+  oneof filter {
+    SubscribeRequestFilterAccountsFilterMemcmp memcmp = 1;
+    uint64 datasize = 2;
+    bool token_account_state = 3;
+    SubscribeRequestFilterAccountsFilterLamports lamports = 4;
+  }
+}
+
+message SubscribeRequestFilterAccountsFilterMemcmp {
+  uint64 offset = 1;
+  oneof data {
+    bytes bytes = 2;
+    string base58 = 3;
+    string base64 = 4;
+  }
+}
+
+message SubscribeRequestFilterAccountsFilterLamports {
+  oneof cmp {
+    uint64 eq = 1;
+    uint64 ne = 2;
+    uint64 lt = 3;
+    uint64 gt = 4;
+  }
+}
+
+message SubscribeRequestFilterSlots {
+  optional bool filter_by_commitment = 1;
+  optional bool interleave_global_updates = 2;
+}
+
+message SubscribeRequestFilterTransactions {
+  optional bool vote = 1;
+  optional bool failed = 2;
+  optional string signature = 3;
+  repeated string account_include = 4;
+  repeated string account_exclude = 5;
+  repeated string account_required = 6;
+}
+
+message SubscribeRequestFilterBlocks {
+  repeated string account_include = 1;
+  optional bool include_transactions = 2;
+  optional bool include_accounts = 3;
+  optional bool include_entries = 4;
+}
+
+message SubscribeRequestFilterBlocksMeta {}
+
+message SubscribeRequestFilterEntry {}
+
+message SubscribeRequestAccountsDataSlice {
+  uint64 offset = 1;
+  uint64 length = 2;
+}
+
+message SubscribeRequestPing {
+  int32 id = 1;
+}
+
+message SubscribeUpdate {
+  repeated string filters = 1;
+  oneof update_oneof {
+    SubscribeUpdateAccount account = 2;
+    SubscribeUpdateSlot slot = 3;
+    SubscribeUpdateTransaction transaction = 4;
+    SubscribeUpdateTransactionInfo transaction_info = 10;
+    SubscribeUpdateBlock block = 5;
+    SubscribeUpdatePing ping = 6;
+    SubscribeUpdatePong pong = 7;
+    SubscribeUpdateBlockMeta block_meta = 8;
+    SubscribeUpdateEntry entry = 9;
+  }
+  uint64 created_at = 11;
+}
+
+message SubscribeUpdateAccount {
+  SubscribeUpdateAccountInfo account = 1;
+  uint64 slot = 2;
+  optional bool is_startup = 3;
+}
+
+message SubscribeUpdateAccountInfo {
+  bytes pubkey = 1;
+  uint64 lamports = 2;
+  bytes owner = 3;
+  bool executable = 4;
+  uint64 rent_epoch = 5;
+  bytes data = 6;
+  uint64 write_version = 7;
+  optional bytes txn_signature = 8;
+}
+
+message SubscribeUpdateSlot {
+  uint64 slot = 1;
+  optional uint64 parent = 2;
+  CommitmentLevel status = 3;
+  optional int64 dead_error = 4;
+}
+
+message SubscribeUpdateTransaction {
+  SubscribeUpdateTransactionInfo transaction = 1;
+  uint64 slot = 2;
+}
+
+message SubscribeUpdateTransactionInfo {
+  bytes signature = 1;
+  bool is_vote = 2;
+  bytes transaction = 3;
+  bytes meta = 4;
+  optional uint64 index = 5;
+}
+
+message SubscribeUpdateBlock {
+  uint64 slot = 1;
+  string blockhash = 2;
+  SubscribeUpdateBlockRewards rewards = 3;
+  UnixTimestamp block_time = 4;
+  BlockHeight block_height = 5;
+  uint64 parent_slot = 6;
+  string parent_blockhash = 7;
+  uint64 executed_transaction_count = 8;
+  uint64 entries_count = 9;
+  repeated SubscribeUpdateTransactionInfo transactions = 10;
+  repeated SubscribeUpdateAccountInfo updated_account_count = 11;
+  repeated SubscribeUpdateEntry entries = 12;
+}
+
+message SubscribeUpdateBlockRewards {
+  bytes rewards = 1;
+}
+
+message UnixTimestamp {
+  int64 timestamp = 1;
+}
+
+message BlockHeight {
+  uint64 block_height = 1;
+}
+
+message SubscribeUpdatePing {}
+
+message SubscribeUpdatePong {
+  int32 id = 1;
+}
+
+message SubscribeUpdateBlockMeta {
+  uint64 slot = 1;
+  string blockhash = 2;
+  SubscribeUpdateBlockRewards rewards = 3;
+  UnixTimestamp block_time = 4;
+  BlockHeight block_height = 5;
+  uint64 parent_slot = 6;
+  string parent_blockhash = 7;
+  uint64 executed_transaction_count = 8;
+  uint64 entries_count = 9;
+}
+
+message SubscribeUpdateEntry {
+  uint64 slot = 1;
+  uint64 index = 2;
+  uint64 num_hashes = 3;
+  bytes hash = 4;
+  uint64 executed_transaction_count = 5;
+  optional uint64 starting_transaction_index = 6;
+}
+`;
+// ============================================================================
+// 辅助函数
+// ============================================================================
+/**
+ * 获取 Geyser Stream 端点
+ *
+ * @param region 区域
+ * @returns gRPC 端点地址
+ */
+export function getGeyserEndpoint(region = 'tokyo') {
+    switch (region) {
+        case 'tokyo':
+            return GEYSER_STREAM_ENDPOINTS.TOKYO;
+        case 'frankfurt':
+            return GEYSER_STREAM_ENDPOINTS.FRANKFURT;
+        case 'newyork':
+            return GEYSER_STREAM_ENDPOINTS.NEW_YORK;
+        case 'amsterdam':
+            return GEYSER_STREAM_ENDPOINTS.AMSTERDAM;
+        default:
+            return GEYSER_STREAM_ENDPOINTS.TOKYO;
+    }
+}
+/**
+ * 构建 Geyser 订阅请求
+ *
+ * @param config 订阅配置
+ * @returns gRPC 请求对象
+ */
+export function buildGeyserSubscribeRequest(config) {
+    const request = {};
+    // 账户订阅
+    if (config.subscribeAccounts && config.accountParams) {
+        const { filterKey, owners, accounts, filters, nonemptyTxnSignature } = config.accountParams;
+        request.accounts = {
+            [filterKey]: {
+                owner: owners || [],
+                account: accounts || [],
+                filters: filters || [],
+                nonempty_txn_signature: nonemptyTxnSignature || false,
+            },
+        };
+    }
+    // 区块订阅
+    if (config.subscribeBlocks && config.blockParams) {
+        const { filterKey, accountInclude, includeTransactions, includeAccounts, includeEntries } = config.blockParams;
+        request.blocks = {
+            [filterKey]: {
+                account_include: accountInclude || [],
+                include_transactions: includeTransactions ?? true,
+                include_accounts: includeAccounts ?? false,
+                include_entries: includeEntries ?? false,
+            },
+        };
+    }
+    // 交易订阅
+    if (config.subscribeTransactions && config.transactionParams) {
+        const { filterKey, vote, failed, accountInclude, accountExclude, accountRequired, signature } = config.transactionParams;
+        request.transactions = {
+            [filterKey]: {
+                vote: vote ?? false,
+                failed: failed ?? false,
+                account_include: accountInclude || [],
+                account_exclude: accountExclude || [],
+                account_required: accountRequired || [],
+                signature: signature || null,
+            },
+        };
+    }
+    // Commitment
+    request.commitment = config.commitment || 'CONFIRMED';
+    return request;
+}
+// ============================================================================
+// 配置工厂函数
+// ============================================================================
+/**
+ * 创建默认账户订阅配置
+ *
+ * @param owners 拥有者地址列表
+ * @param accounts 特定账户地址列表
+ * @returns 订阅配置
+ */
+export function createAccountSubscribeConfig(owners, accounts) {
+    return {
+        commitment: 'CONFIRMED',
+        subscribeAccounts: true,
+        accountParams: {
+            filterKey: 'account-filter',
+            owners: owners || [],
+            accounts: accounts || [],
+            filters: [],
+            nonemptyTxnSignature: false,
+        },
+    };
+}
+/**
+ * 创建默认交易订阅配置
+ *
+ * @param accountInclude 包含涉及这些账户的交易
+ * @param accountRequired 交易必须涉及这些账户
+ * @returns 订阅配置
+ */
+export function createTransactionSubscribeConfig(accountInclude, accountRequired) {
+    return {
+        commitment: 'CONFIRMED',
+        subscribeTransactions: true,
+        transactionParams: {
+            filterKey: 'tx-filter',
+            vote: false,
+            failed: false,
+            accountInclude: accountInclude || [],
+            accountExclude: [],
+            accountRequired: accountRequired || [],
+            signature: null,
+        },
+    };
+}
+/**
+ * 创建默认区块订阅配置
+ *
+ * @param accountInclude 包含涉及这些账户的区块
+ * @param includeTransactions 是否包含交易
+ * @returns 订阅配置
+ */
+export function createBlockSubscribeConfig(accountInclude, includeTransactions = true) {
+    return {
+        commitment: 'CONFIRMED',
+        subscribeBlocks: true,
+        blockParams: {
+            filterKey: 'block-filter',
+            accountInclude: accountInclude || [],
+            includeTransactions,
+            includeAccounts: false,
+            includeEntries: false,
+        },
+    };
+}
+// ============================================================================
+// Geyser 订阅
+// ============================================================================
+/**
+ * 创建 Geyser 订阅（需要 @grpc/grpc-js 和 @grpc/proto-loader）
+ *
+ * 注意：此函数需要安装 gRPC 依赖：
+ * ```bash
+ * npm install @grpc/grpc-js @grpc/proto-loader
+ * ```
+ *
+ * @param clientConfig 客户端配置
+ * @param subscribeConfig 订阅配置
+ * @param handlers 事件处理器
+ * @returns 流控制对象
+ *
+ * @example
+ * ```typescript
+ * import { Sol } from 'four-flap-meme-sdk'
+ * import bs58 from 'bs58'
+ *
+ * const stream = await Sol.createGeyserSubscription(
+ *   {
+ *     host: Sol.getGeyserEndpoint('tokyo'),
+ *     token: 'your-auth-token',
+ *   },
+ *   Sol.createTransactionSubscribeConfig(
+ *     ['your-account-address'], // 监听涉及此账户的交易
+ *   ),
+ *   {
+ *     onTransaction: (update, raw) => {
+ *       console.log(`交易: ${bs58.encode(update.transaction.signature)}`)
+ *     },
+ *     onError: (err) => console.error('错误:', err),
+ *     onEnd: () => console.log('流结束'),
+ *   },
+ * )
+ *
+ * // 关闭流
+ * stream.close()
+ * ```
+ */
+export async function createGeyserSubscription(clientConfig, subscribeConfig, handlers) {
+    // 动态导入 gRPC 依赖（可选依赖）
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let grpc;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let protoLoader;
+    try {
+        // 使用动态 require 避免类型检查问题
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        grpc = require('@grpc/grpc-js');
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        protoLoader = require('@grpc/proto-loader');
+    }
+    catch {
+        throw new Error('Geyser Stream requires @grpc/grpc-js and @grpc/proto-loader. ' +
+            'Install them with: npm install @grpc/grpc-js @grpc/proto-loader');
+    }
+    // 使用内联 proto 定义
+    const packageDefinition = protoLoader.loadSync(GEYSER_PROTO_DEFINITION, {
+        keepCase: true,
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const geyserProto = grpc.loadPackageDefinition(packageDefinition).geyser;
+    // 创建 SSL 凭证
+    const sslCreds = grpc.credentials.createSsl();
+    // 创建 metadata
+    const metadata = new grpc.Metadata();
+    metadata.add('x-token', clientConfig.token);
+    // 创建客户端
+    const client = new geyserProto.Geyser(clientConfig.host, sslCreds);
+    // 建立流
+    const stream = client.Subscribe(metadata);
+    // 处理更新
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    stream.on('data', (update) => {
+        const geyserUpdate = update;
+        switch (geyserUpdate.update_oneof) {
+            case 'account':
+                if (geyserUpdate.account && handlers.onAccount) {
+                    handlers.onAccount(geyserUpdate.account, geyserUpdate.account.account.pubkey);
+                }
+                break;
+            case 'block':
+                if (geyserUpdate.block && handlers.onBlock) {
+                    handlers.onBlock(geyserUpdate.block);
+                }
+                break;
+            case 'transaction':
+                if (geyserUpdate.transaction && handlers.onTransaction) {
+                    handlers.onTransaction(geyserUpdate.transaction, geyserUpdate.transaction.transaction.signature);
+                }
+                break;
+        }
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    stream.on('error', (err) => {
+        if (handlers.onError) {
+            handlers.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+    stream.on('end', () => {
+        if (handlers.onEnd) {
+            handlers.onEnd();
+        }
+    });
+    // 发送订阅请求
+    const request = buildGeyserSubscribeRequest(subscribeConfig);
+    stream.write(request);
+    return {
+        close: () => stream.end(),
+        write: (data) => stream.write(data),
+    };
+}
+// ============================================================================
+// 简化版订阅方法
+// ============================================================================
+/**
+ * 简化版：订阅账户更新
+ *
+ * @param token 认证 Token
+ * @param accounts 账户地址列表
+ * @param onUpdate 更新回调
+ * @param region 区域（默认 tokyo）
+ * @returns 流控制对象
+ */
+export async function subscribeGeyserAccounts(token, accounts, onUpdate, region = 'tokyo') {
+    const bs58 = await import('bs58');
+    return createGeyserSubscription({ host: getGeyserEndpoint(region), token }, createAccountSubscribeConfig(undefined, accounts), {
+        onAccount: (update) => {
+            const pubkey = bs58.default.encode(update.account.pubkey);
+            onUpdate(pubkey, update.account.lamports, update.slot);
+        },
+    });
+}
+/**
+ * 简化版：订阅交易更新
+ *
+ * @param token 认证 Token
+ * @param accountInclude 包含涉及这些账户的交易
+ * @param onUpdate 更新回调
+ * @param region 区域（默认 tokyo）
+ * @returns 流控制对象
+ */
+export async function subscribeGeyserTransactions(token, accountInclude, onUpdate, region = 'tokyo') {
+    const bs58 = await import('bs58');
+    return createGeyserSubscription({ host: getGeyserEndpoint(region), token }, createTransactionSubscribeConfig(accountInclude), {
+        onTransaction: (update) => {
+            const signature = bs58.default.encode(update.transaction.signature);
+            onUpdate(signature, update.transaction.isVote, update.slot);
+        },
+    });
+}
+/**
+ * 简化版：订阅区块更新
+ *
+ * @param token 认证 Token
+ * @param onUpdate 更新回调
+ * @param region 区域（默认 tokyo）
+ * @returns 流控制对象
+ */
+export async function subscribeGeyserBlocks(token, onUpdate, region = 'tokyo') {
+    return createGeyserSubscription({ host: getGeyserEndpoint(region), token }, createBlockSubscribeConfig(), {
+        onBlock: (update) => {
+            onUpdate(update.slot, update.blockhash, update.transactions.length);
+        },
+    });
+}

package/dist/sol/dex/blockrazor/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * BlockRazor Solana Service
+ * @module sol/dex/blockrazor
+ *
+ * BlockRazor 提供 Solana 服务：
+ * - 高性能交易落地 (Transaction Landing)
+ * - 三明治攻击缓解模式 (Sandwich Mitigation)
+ * - Revert 保护
+ * - Geyser Stream (gRPC 实时数据流)
+ *
+ * @see https://blockrazor.gitbook.io/blockrazor/solana/send-transaction
+ * @see https://blockrazor.gitbook.io/blockrazor/solana/geyser-stream
+ */
+export * from './types.js';
+export * from './constants.js';
+export { setBlockRazorConfig, getBlockRazorConfig, getBlockRazorEndpoint, getRandomBlockRazorTipAccount, validateSendParams, } from './client.js';
+export { blockRazorSendTransaction, blockRazorSendTransactionV2, blockRazorHealth, blockRazorHealthV2, blockRazorFastSend, blockRazorSafeSend, blockRazorSendWithRevertProtection, startBlockRazorKeepAlive, } from './send.js';
+export { GEYSER_PROTO_DEFINITION, getGeyserEndpoint, buildGeyserSubscribeRequest, createAccountSubscribeConfig, createTransactionSubscribeConfig, createBlockSubscribeConfig, createGeyserSubscription, subscribeGeyserAccounts, subscribeGeyserTransactions, subscribeGeyserBlocks, } from './geyser.js';