Jetstream Protocol Reference

syntax = "proto3";

package jetstream.v2;

import "google/protobuf/timestamp.proto";

service JetstreamV2 {
  rpc SubscribeTransactions(stream SubscribeTransactionsRequest) returns (stream SubscribeTransactionsResponse) {}

  // Server-streaming slot lifecycle events.
  rpc SubscribeSlots(SubscribeSlotsRequest) returns (stream SlotEvent) {}

  // Unary health/version probes.
  rpc Ping(PingRequest) returns (PongResponse) {}
  rpc GetVersion(GetVersionRequest) returns (GetVersionResponse) {}
}

message SubscribeTransactionsRequest {
  oneof payload {
    Ping          ping           = 1;
    AddFilters    add_filters    = 2;
    RemoveFilters remove_filters = 3;
  }
}

message Ping {
  int32 ping_id = 1;
}

message AddFilters {
  repeated TxFilter filters = 1;
}

message TxFilter {
  string                             filter_id = 1;  // client-provided, max 127 chars
  SubscribeRequestFilterTransactions filter    = 2;
}

message SubscribeRequestFilterTransactions {
  repeated string account_include  = 1;
  repeated string account_exclude  = 2;
  repeated string account_required = 3;
  // account_required matches a tx that references AT LEAST ONE of these accounts
  // (any-of — identical to account_include). It is NOT the
  // "tx must contain ALL of these accounts" meaning.

  // Opt-in enrichment. Default false = lean response (core fields only). Set
  // true to also receive fee_payer / writable_accounts / program_ids /
  // compute_unit_price / compute_limit / tx_size. Applies to the whole
  // subscription: if any of your active filters sets this true, every
  // transaction you receive is enriched.
  bool include_enrichment = 4;
}

message RemoveFilters {
  repeated string filter_ids = 1;
}

message SubscribeTransactionsResponse {
  google.protobuf.Timestamp created_at = 1;

  oneof payload {
    FilteredTransaction transaction       = 2;
    Pong                pong              = 3;
    FilterResult        filter_validation = 5;
    Heartbeat           heartbeat         = 6;
  }

  uint64 sequence = 4;
}

message Pong {
  int32 ping_id = 1;
}

message FilterResult {
  string filter_id        = 1;
  bool   accepted         = 2;
  string rejection_reason = 3;  // empty string when accepted=true (proto3 default elision)
}

message Heartbeat {
  // Server wall-clock at emit time, milliseconds since Unix epoch. Lets
  // clients measure one-way skew / network delay and age out stale
  // connections.
  uint64 server_ts_ms = 1;
}

message FilteredTransaction {
  repeated string    filter_ids  = 1;
  TransactionMessage transaction = 2;
}

// TransactionMessage — a flat transaction representation (all fields inline).
// Fields 1-13 are the core transaction and are always present (the default
// "lean" output). Fields 14-22 and 24 are optional enrichment, emitted only
// when the session opts in via SubscribeRequestFilterTransactions.include_enrichment.
// Field 23 (config) is intrinsic transaction data — always sent for a V1
// transaction, never enrichment-gated. Fields 23-24 are additive (SIMD-0385).
message TransactionMessage {
  // Identity / placement
  uint64 slot      = 1;
  bytes  signature = 2;  // primary signature (signatures[0])
  uint32 tx_index  = 3;  // position of this tx within its entry

  // Full signature set (repeated bytes)
  repeated bytes signatures = 4;

  // Always false: vote transactions are filtered out and never delivered.
  bool is_vote = 5;

  // Message header
  uint32 num_required_signatures        = 6;
  uint32 num_readonly_signed_accounts   = 7;
  uint32 num_readonly_unsigned_accounts = 8;

  // Recent blockhash
  bytes recent_blockhash = 9;

  // Versioned-transaction flag.
  bool versioned = 10;

  // Core body contents
  repeated bytes                     account_keys          = 11;
  repeated CompiledInstruction       instructions          = 12;
  repeated MessageAddressTableLookup address_table_lookups = 13;

  // Enrichment — emitted only when the session opts in via
  // SubscribeRequestFilterTransactions.include_enrichment.
  bytes          fee_payer         = 14;
  repeated bytes writable_accounts = 15;
  repeated bytes program_ids       = 16;
  // Compute-unit price (micro-lamports per CU) from SetComputeUnitPrice; 0 if unset.
  // The per-CU price, NOT the total priority fee — total priority fee in lamports
  // ~= compute_unit_price * compute_limit / 1_000_000.
  uint64         compute_unit_price = 17;
  // Explicit SetComputeUnitLimit only; 0 if the tx sets none (no implicit
  // 200k-CU-per-instruction default is applied).
  uint32         compute_limit     = 18;
  uint32         tx_size           = 19;

  // Resolved addresses from a versioned tx's address_table_lookups. Emitted
  // only when enrichment is opted in (same gate as fields 14-19). Empty for a
  // legacy (non-versioned) tx; when a lookup can't be fully resolved,
  // alt_resolution_incomplete (field 22) is set and any addresses that did
  // resolve are still included.
  repeated bytes loaded_writable_addresses = 20;
  repeated bytes loaded_readonly_addresses = 21;

  // Set true when one or more of this transaction's address_table_lookups could
  // NOT be fully resolved, so the loaded_writable_addresses /
  // loaded_readonly_addresses above are INCOMPLETE. When true, resolve the tx's
  // accounts yourself from address_table_lookups (fetch the tables via
  // RPC). Default false = fully resolved. Emitted only under
  // enrichment (same gate as fields 14-21).
  bool alt_resolution_incomplete = 22;

  // ---- SIMD-0385 Transaction V1 ----

  // Transaction config carried in the message body by V1 transactions.
  // PRESENT ONLY FOR V1 (absent for legacy and V0) — its presence is how you
  // identify a V1 transaction. Always sent (NOT enrichment-gated).
  //   version | versioned (10) | config (23)
  //   legacy  | false          | absent
  //   v0      | true           | absent
  //   v1      | true           | PRESENT
  optional TransactionConfig config = 23;

  // Priority fee in TOTAL LAMPORTS, populated for ALL versions so they can be
  // ranked against one another. Use this — not compute_unit_price (17) — to
  // sort by fee: field 17 is absent for every V1 transaction. For v1 this is
  // config.priority_fee; for legacy/v0 it is derived from the ComputeBudget
  // instructions. Emitted only under enrichment.
  optional uint64 priority_fee_lamports = 24;
}

// Transaction-level configuration carried by V1 messages (SIMD-0385). Replaces
// the ComputeBudget instructions used by legacy/V0. Explicit presence: an
// absent field means the sender requested nothing, which is NOT the same as 0.
message TransactionConfig {
  optional uint64 priority_fee                     = 1;  // TOTAL lamports, not per-CU. Absent = 0.
  optional uint32 compute_unit_limit              = 2;  // Absent = 0 requested.
  optional uint32 loaded_accounts_data_size_limit = 3;  // Bytes. Absent = 0 (legacy/V0 default is 64 MiB).
  optional uint32 heap_size                        = 4;  // Bytes, multiple of 1024 in [32768, 262144]. Absent = 32 KiB default.
}

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

message MessageAddressTableLookup {
  bytes account_key      = 1;
  bytes writable_indexes = 2;
  bytes readonly_indexes = 3;
}

// SubscribeSlots takes no request parameters.
message SubscribeSlotsRequest {
}

enum SlotStatus {
  SLOT_STATUS_UNSPECIFIED = 0;
  SLOT_STATUS_ALIVE       = 1;  // first shred of this slot received
  SLOT_STATUS_COMPLETE    = 2;  // last shred of this slot received
  SLOT_STATUS_DEAD        = 3;  // slot skipped, or superseded by later slots without completing
}

message SlotEvent {
  uint64     slot           = 1;
  SlotStatus status         = 2;
  // 32-byte pubkey. Empty bytes (proto3 default) means the current leader is
  // unavailable.
  bytes      current_leader = 3;
  // Parent slot, from the first shred received for this slot. 0 means
  // "unknown parent" (e.g. a DEAD event for a slot that was never observed).
  uint64     parent_slot    = 4;
  uint64     sequence       = 5;  // monotonic per-stream
}

message PingRequest {
  int32 count = 1;
}

message PongResponse {
  int32 count = 1;
}

message GetVersionRequest {}

message GetVersionResponse {
  string version = 1;
}

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

protoc --rust_out=. jetstream_v2.proto