TypeScript gRPC 客户端（Yellowstone）

安装

npm install @orbitflare/sdk @grpc/grpc-js yaml

@grpc/grpc-js 与 yaml 为可选对等依赖。仅在使用 gRPC 客户端（或 YAML 配置）时才需要安装。

构建客户端

以下示例启用全部选项：

import { GeyserClientBuilder } from '@orbitflare/sdk/grpc';
import type { RetryPolicy } from '@orbitflare/sdk';

const client = new GeyserClientBuilder()
  .url('http://ny.rpc.orbitflare.com:10000')
  .fallbackUrl('http://fra.rpc.orbitflare.com:10000')
  .retry({
    initialDelayMs: 100,
    maxDelayMs: 30_000,
    multiplier: 2.0,
    maxAttempts: 0,
  })
  .timeoutSecs(30)
  .keepaliveSecs(60)
  .pingIntervalSecs(10)
  .maxMissedPongs(3)
  .channelCapacity(4096)
  .build();

最简配置：

const client = new GeyserClientBuilder()
  .url('http://ny.rpc.orbitflare.com:10000')
  .build();

构建器方法

.url(url) - 主 gRPC 端点。回退读取环境变量 ORBITFLARE_GRPC_URL。

.url('http://ny.rpc.orbitflare.com:10000')

.urls([...]) - 一次设置主端点与备用端点。第一个元素为主端点。

.urls(['http://ny.rpc.orbitflare.com:10000', 'http://fra.rpc.orbitflare.com:10000'])

.fallbackUrl(url) / .fallbackUrls([...]) - 添加备用端点。连接失败时 SDK 会轮换尝试。

.fallbackUrl('http://fra.rpc.orbitflare.com:10000')

.retry(policy) - 控制重连退避。连接断开时，SDK 先等待 initialDelayMs，随后每次尝试加倍（上限 maxDelayMs）。将 maxAttempts 设为 0 表示无限重试。默认：初始 100ms、最大 30s、2 倍乘数、无限次。

.retry({
  initialDelayMs: 200,
  maxDelayMs: 15_000,
  multiplier: 2.0,
  maxAttempts: 0,
})

.timeoutSecs(n) - 单次 gRPC 请求超时。默认：30。

.timeoutSecs(15)

.keepaliveSecs(n) - TCP keepalive 间隔。操作系统按此间隔发送探测以在 TCP 层检测死亡连接。默认：60。

.keepaliveSecs(30)

.pingIntervalSecs(n) - SDK 发送协议层 Ping 的频率。服务端应以 Pong 回应。默认：10。

.pingIntervalSecs(15)

.maxMissedPongs(n) - 连续多少次 Ping 无应答后，SDK 认为连接已死并重连。默认：3。在默认参数下，约 30 秒内可检测到死亡连接。

.maxMissedPongs(5)

.channelCapacity(n) - 后台任务与你的代码之间的有界通道容量。若消费事件较慢，后台任务在填满时会暂停，而非无限占用内存。默认：4096。

.channelCapacity(8192)

编写 YAML 配置

创建包含所需过滤器的 YAML 文件：

# grpc.yml
transactions:
  pumpfun:
    vote: false
    failed: false
    account_include:
      - "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"
  jupiter:
    vote: false
    failed: false
    account_include:
      - "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"

accounts:
  usdc_mint:
    account:
      - "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
  token_program:
    owner:
      - "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"

slots:
  all:
    filter_by_commitment: true

commitment: confirmed

YAML 过滤器参考

transactions - 每个条目是一个命名过滤器。若交易涉及任一 account_include 地址则匹配。account_exclude 排除匹配。account_required 表示所列地址必须全部出现。vote 与 failed 按交易类型过滤。 accounts - 按地址监视特定账户，或通过 owner 监视某程序拥有的全部账户。 slots - 订阅槽位更新。filter_by_commitment 仅在你设定的承诺级别发送更新。 commitment - 'processed'、'confirmed' 或 'finalized'。默认为 'confirmed'。 YAML 支持 ${ENV_VAR} 展开：

transactions:
  target:
    account_include:
      - "${TARGET_PROGRAM}"

订阅与读取事件

自 YAML

const stream = client.subscribeYaml('grpc.yml');

编程方式

运行时动态构建过滤器：

import { proto } from '@orbitflare/sdk/proto';

const request: proto.geyser.SubscribeRequest = {
  transactions: {
    target: {
      vote: false,
      failed: false,
      signature: undefined,
      accountInclude: [someAddress],
      accountExclude: [],
      accountRequired: [],
    },
  },
  accounts: {},
  slots: {},
  transactionsStatus: {},
  blocks: {},
  blocksMeta: {},
  entry: {},
  accountsDataSlice: [],
  commitment: 1,
  ping: { id: 1 },
};

const stream = client.subscribe(request);

读取流

subscribeYaml 与 subscribe 均返回 GeyserStream。它是异步可迭代对象 - 使用 for await：

for await (const update of stream) {
  if (update.transaction) {
    // update.transaction.slot - the slot this transaction was in
    // update.transaction.transaction - the transaction info (signature, accounts, instructions, meta)
  } else if (update.account) {
    // update.account.slot - the slot
    // update.account.account - account info (pubkey, lamports, owner, data)
    // update.account.isStartup - true during initial account snapshot
  } else if (update.slot) {
    // update.slot.slot - the slot number
    // update.slot.status - processed, confirmed, finalized, etc.
  } else if (update.blockMeta) {
    // update.blockMeta.slot, update.blockMeta.blockhash, update.blockMeta.parentSlot
    // update.blockMeta.executedTransactionCount
  }
}

或直接调用 await stream.next() 逐个拉取事件。流关闭时返回 undefined。若已用尽全部重试，下一次迭代会抛出错误。 Pong 消息在内部消费，不会出现在你的流中。

关闭

stream.close();

立即停止后台任务。

多路流

一个客户端可同时运行多条流。每条流使用独立的后台连接：

const pumpfun = client.subscribeYaml('config/pumpfun.yml');
const raydium = client.subscribeYaml('config/raydium.yml');
const slots = client.subscribeYaml('config/slots.yml');

它们共享端点健康状态 - 若某条流将失败端点隔离，其他流在下次重连时会跳过该端点。但各流的连接与生命周期完全独立。可随时新建流，包括根据已有流的数据动态创建。

完整示例

监听 pump.fun 交易、解码签名并打印每条摘要的流：

import bs58 from 'bs58';
import { GeyserClientBuilder } from '@orbitflare/sdk/grpc';

async function main() {
  const client = new GeyserClientBuilder()
    .url('http://ny.rpc.orbitflare.com:10000')
    .fallbackUrl('http://fra.rpc.orbitflare.com:10000')
    .build();

  const stream = client.subscribeYaml('grpc.yml');
  let txCount = 0;

  console.log('streaming...');

  for await (const update of stream) {
    if (update.transaction) {
      txCount += 1;
      const info = update.transaction.transaction;
      if (info?.signature) {
        const sig = bs58.encode(info.signature);
        const fee = info.meta?.fee ?? 0n;
        const ixCount = info.transaction?.message?.instructions.length ?? 0;
        console.log(
          `#${txCount} slot=${update.transaction.slot} sig=${sig.slice(0, 16)}... fee=${fee} instructions=${ixCount}`,
        );
      }
    } else if (update.slot) {
      console.log(`slot ${update.slot.slot} (${update.slot.status})`);
    }
  }
}

void main();

配合以下 grpc.yml：

transactions:
  pumpfun:
    vote: false
    failed: false
    account_include:
      - "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"

slots:
  all:
    filter_by_commitment: true

commitment: confirmed

开始使用

产品

解决方案

数据获取

RPC

数据流

交易 API

TypeScript gRPC 客户端（Yellowstone）

安装

构建客户端

构建器方法

编写 YAML 配置

YAML 过滤器参考

订阅与读取事件

自 YAML

编程方式

读取流

关闭

多路流

完整示例

​安装

​构建客户端

​构建器方法

​编写 YAML 配置

​YAML 过滤器参考

​订阅与读取事件

​自 YAML

​编程方式

​读取流

​关闭

​多路流

​完整示例

安装

构建客户端

构建器方法

编写 YAML 配置

YAML 过滤器参考

订阅与读取事件

自 YAML

编程方式

读取流

关闭

多路流

完整示例