> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jetstream 协议参考

> OrbitFlare Jetstream 的 Protocol Buffer 规范

## 可用端点

Jetstream 在所有 OrbitFlare 地区均可使用。连接到距您基础设施最近的地区以获得最低延迟。

<Tabs>
  <Tab title="美国">
    | 城市  | 地区标识  | 端点                                    |
    | --- | ----- | ------------------------------------- |
    | 纽约  | `ny`  | `http://ny.jetstream.orbitflare.com`  |
    | 盐湖城 | `slc` | `http://slc.jetstream.orbitflare.com` |
  </Tab>

  <Tab title="欧洲">
    | 城市       | 地区标识   | 端点                                     |
    | -------- | ------ | -------------------------------------- |
    | 法兰克福     | `fra`  | `http://fra.jetstream.orbitflare.com`  |
    | 阿姆斯特丹    | `ams`  | `http://ams.jetstream.orbitflare.com`  |
    | 伦敦       | `lon`  | `http://lon.jetstream.orbitflare.com`  |
    | 都柏林      | `dub`  | `http://dub.jetstream.orbitflare.com`  |
    | 希奥利艾，立陶宛 | `siau` | `http://siau.jetstream.orbitflare.com` |
  </Tab>

  <Tab title="亚太">
    | 城市  | 地区标识  | 端点                                    |
    | --- | ----- | ------------------------------------- |
    | 东京  | `jp`  | `http://jp.jetstream.orbitflare.com`  |
    | 新加坡 | `sgp` | `http://sgp.jetstream.orbitflare.com` |
  </Tab>
</Tabs>

<Note>
  Jetstream 使用普通 `http://`（而非 `https://`）进行 gRPC 连接。gRPC 通过 HTTP/2 使用自己的传输安全协商。仅当您的专用节点明确要求时才使用 `https://`。
</Note>

## Protocol Buffer 规范

本文档概述了 OrbitFlare Jetstream 使用的 Protocol Buffer (protobuf) 规范。完整规范可在我们的 [GitHub 仓库](https://github.com/orbitflare/jetstream-client-example/blob/main/jetstream_protos/protos/jetstream.proto) 中找到。

### 服务定义

```protobuf theme={null}
syntax = "proto3";

import "google/protobuf/timestamp.proto";
package jetstream;

// ============= Service Definition =============
service Jetstream {
  // Subscribe to data streams with filtering support
  rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeUpdate) {}
  // Subscribe to data streams with filtering support and parsed instructions
  rpc SubscribeParsed(stream SubscribeParsedRequest) returns (stream SubscribeUpdateParsedTransaction) {}
  // Basic ping/pong for connection testing
  rpc Ping(PingRequest) returns (PongResponse) {}
  // Get information about current state
  rpc GetVersion(GetVersionRequest) returns (GetVersionResponse) {}
}
```

### 请求消息

#### SubscribeRequest

用于订阅数据更新的主要请求消息：

```protobuf theme={null}
message SubscribeRequest {
  map<string, SubscribeRequestFilterTransactions> transactions = 1;
  map<string, SubscribeRequestFilterAccounts> accounts = 2;
  optional SubscribeRequestPing ping = 4;
}
```

#### 交易过滤

```protobuf theme={null}
message SubscribeRequestFilterTransactions {
  repeated string account_include = 1;
  repeated string account_exclude = 2;
  repeated string account_required = 3;
}
```

#### 账户过滤

```protobuf theme={null}
message SubscribeRequestFilterAccounts {
  repeated string account = 1;
  repeated string owner = 2;
  repeated SubscribeRequestFilterAccountsFilter filters = 3;
}

message SubscribeRequestFilterAccountsFilter {
  oneof filter {
    SubscribeRequestFilterAccountsFilterMemcmp memcmp = 1;
    uint64 datasize = 2;
    SubscribeRequestFilterAccountsFilterLamports lamports = 3;
  }
}

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;
  }
}
```

#### Ping 请求

```protobuf theme={null}
message SubscribeRequestPing {
  int32 id = 1;
}
```

### 响应消息

#### SubscribeUpdate

包含更新的主要响应消息：

```protobuf theme={null}
message SubscribeUpdate {
  repeated string filters = 1;
  google.protobuf.Timestamp created_at = 2;
  oneof update_oneof {
    SubscribeUpdateTransaction transaction = 3;
    SubscribeUpdateAccount account = 4;
    SubscribeUpdatePing ping = 5;
    SubscribeUpdatePong pong = 6;
  }
}
```

#### 交易更新

```protobuf theme={null}
message SubscribeUpdateTransaction {
  SubscribeUpdateTransactionInfo transaction = 1;
  uint64 slot = 2;
}

message SubscribeUpdateTransactionInfo {
  bytes signature = 1;
  uint64 slot = 2;
  uint32 num_required_signatures = 3;
  uint32 num_readonly_signed_accounts = 4;
  uint32 num_readonly_unsigned_accounts = 5;
  bytes recent_blockhash = 6;
  repeated bytes signatures = 7;
  repeated bytes account_keys = 8;
  repeated CompiledInstruction instructions = 9;
  repeated MessageAddressTableLookup address_table_lookups = 10;
}
```

#### 账户更新

```protobuf theme={null}
message SubscribeUpdateAccount {
  SubscribeUpdateAccountInfo account = 1;
  uint64 slot = 2;
  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;
}
```

#### Ping/Pong 更新

```protobuf theme={null}
message SubscribeUpdatePing {}

message SubscribeUpdatePong {
  int32 id = 1;
}
```

#### 共享类型

```protobuf theme={null}
message MessageAddressTableLookup {
  bytes account_key = 1;
  bytes writable_indexes = 2;
  bytes readonly_indexes = 3;
}

message CompiledInstruction {
  uint32 program_id_index = 1;
  bytes accounts = 2;
  bytes data = 3;
}
```

### 解析指令支持

#### 解析请求

```protobuf theme={null}
message SubscribeParsedRequest {
  optional SubscribeRequestPing ping = 1;
}
```

#### 解析交易更新

```protobuf theme={null}
message SubscribeUpdateParsedTransaction {
  bytes signature = 1;
  uint64 slot = 2;
  SubscribeUpdateAccount account = 3;
  bytes recent_blockhash = 4;
  repeated bytes signatures = 5;
  repeated Instruction instructions = 6;
}
```

#### 指令类型

```protobuf theme={null}
message Instruction {
  oneof instruction_oneof {
    Initialize initialize = 1;
    SetParams set_params = 2;
    Create create = 3;
    Buy buy = 4;
    Sell sell = 5;
    Withdraw withdraw = 6;
  }
}

message Initialize {}

message SetParams {
  bytes fee_recipient = 1;
  uint64 initial_virtual_token_reserves = 2;
  uint64 initial_virtual_sol_reserves = 3;
  uint64 initial_real_token_reserves = 4;
  uint64 token_total_supply = 5;
  uint64 fee_basis_points = 6;
}

message Create {
  string name = 1;
  string symbol = 2;
  string uri = 3;
}

message Buy {
  uint64 amount = 1;
  uint64 max_sol_cost = 2;
}

message Sell {
  uint64 amount = 1;
  uint64 min_sol_output = 2;
}

message Withdraw {}
```

### 非流式方法

```protobuf theme={null}
message PingRequest {
  int32 count = 1;
}

message PongResponse {
  int32 count = 1;
}

message GetVersionRequest {}

message GetVersionResponse {
  string version = 1;
}

message GetSlotResponse {
  uint64 slot = 1;
}
```

## 使用协议

实现 Jetstream 客户端时，您需要：

1. 从 protobuf 定义生成客户端代码
2. 实现 Subscribe RPC 方法用于数据流
3. 使用 SubscribeParsed 获取解析指令支持
4. 使用 Ping/Pong 进行连接健康检查
5. 使用 GetVersion 检查服务器兼容性
6. 处理不同类型的更新（交易、账户、pong）

### 代码生成

TypeScript/JavaScript：

```bash theme={null}
protoc --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto \
  --ts_proto_out=. \
  --ts_proto_opt=esModuleInterop=true \
  jetstream.proto
```

Rust：

```bash theme={null}
protoc --rust_out=. jetstream.proto
```

## 最佳实践

1. **版本兼容性**
   * 使用 GetVersion 检查协议兼容性
   * 监控 beta 版本中的破坏性变更
   * 升级时进行充分测试

2. **错误处理**
   * 为所有消息类型实现适当的错误处理
   * 优雅地处理连接失败
   * 在处理之前验证消息字段

3. **连接管理**
   * 使用 Ping/Pong 进行连接健康检查
   * 实现自动重连逻辑
   * 设置适当的超时时间

4. **性能**
   * 使用适当的过滤器最小化不必要的数据
   * 考虑对大型数据集使用账户过滤
   * 监控资源使用情况，特别是账户订阅
   * 需要时使用 SubscribeParsed 获取解析指令支持

## 另请参阅

<CardGroup cols={2}>
  <Card title="Jetstream 概览" icon="bolt" href="/cn/data-streaming/jetstream">
    入门指南、示例和过滤文档。
  </Card>

  <Card title="更新日志" icon="clock-rotate-left" href="/cn/data-streaming/jetstream-changelog">
    版本历史和协议更新。
  </Card>
</CardGroup>

## 支持

如有关于协议规范或实现细节的技术问题，请访问我们的 [GitHub 仓库](https://github.com/orbitflare/jetstream-client-example) 或加入我们的 [Discord 社区](https://discord.gg/orbitflare)。