​
Protocol Buffer Specification

This document outlines the Protocol Buffer (protobuf) specification used by OrbitFlare Jetstream. The complete specification can be found in our GitHub repository.

​
Service Definition

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) {}
  // Basic ping/pong for connection testing
  rpc Ping(PingRequest) returns (PongResponse) {}
  // Get information about current state
  rpc GetVersion(GetVersionRequest) returns (GetVersionResponse) {}
}

​
Request Messages

​
SubscribeRequest

The main request message for subscribing to data updates:

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

​
Transaction Filtering

message SubscribeRequestFilterTransactions {
  repeated string account_include = 1;
  repeated string account_exclude = 2;
  repeated string account_required = 3;
}

​
Account Filtering

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 Request

message SubscribeRequestPing {
  int32 id = 1;
}

​
Response Messages

​
SubscribeUpdate

The main response message containing updates:

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

​
Transaction Update

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

​
Account Update

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 Updates

message SubscribeUpdatePing {}

message SubscribeUpdatePong {
  int32 id = 1;
}

​
Shared Types

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

​
Non-streaming Methods

message PingRequest {
  int32 count = 1;
}

message PongResponse {
  int32 count = 1;
}

message GetVersionRequest {}

message GetVersionResponse {
  string version = 1;
}

message GetSlotResponse {
  uint64 slot = 1;
}

​
Using the Protocol

When implementing a client for Jetstream, you’ll need to:

  1. Generate client code from the protobuf definition
  2. Implement the Subscribe RPC method for data streaming
  3. Use Ping/Pong for connection health checks
  4. Use GetVersion to check server compatibility
  5. Handle different types of updates (transactions, accounts, pongs)

​
Code Generation

For TypeScript/JavaScript:

protoc --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto \
  --ts_proto_out=. \
  --ts_proto_opt=esModuleInterop=true \
  jetstream.proto

For Rust:

protoc --rust_out=. jetstream.proto

​
Best Practices

  1. Version Compatibility

    • Use GetVersion to check for protocol compatibility
    • Monitor for breaking changes in beta releases
    • Test thoroughly when upgrading

  2. Error Handling

    • Implement proper error handling for all message types
    • Handle connection failures gracefully
    • Validate message fields before processing

  3. Connection Management

    • Use Ping/Pong for connection health checks
    • Implement automatic reconnection logic
    • Set appropriate timeouts

  4. Performance

    • Use appropriate filters to minimize unnecessary data
    • Consider using account filtering for large datasets
    • Monitor resource usage, especially with account subscriptions

​
Support

For technical questions about the protocol specification or implementation details, please visit our GitHub repository or join our Discord community.