syntax = "proto3";

package geyser;

service Geyser {
  // Subscribe to blockchain updates (bidirectional streaming)
  rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeUpdate);

  // Ping for health check
  rpc Ping(PingRequest) returns (PongResponse);

  // Get latest blockhash
  rpc GetLatestBlockhash(GetLatestBlockhashRequest)
      returns (GetLatestBlockhashResponse);

  // Get block height
  rpc GetBlockHeight(GetBlockHeightRequest)
      returns (GetBlockHeightResponse);

  // Get version information
  rpc GetVersion(GetVersionRequest) returns (GetVersionResponse);
}

message SubscribeRequest {
  // Map of subscription name to transaction filters
  map<string, SubscribeRequestFilterTransactions> transactions = 1;

  // Map of subscription name to account filters
  map<string, SubscribeRequestFilterAccounts> accounts = 2;

  // Map of subscription name to slot filters
  map<string, SubscribeRequestFilterSlots> slots = 3;

  // Map of subscription name to block filters
  map<string, SubscribeRequestFilterBlocks> blocks = 4;

  // Map of subscription name to block meta filters
  map<string, SubscribeRequestFilterBlocksMeta> blocks_meta = 5;

  // Map of subscription name to entry filters
  map<string, SubscribeRequestFilterEntry> entry = 6;

  // Commitment level (optional, default: PROCESSED)
  optional CommitmentLevel commitment = 7;

  // Accounts data slice (optional)
  repeated SubscribeRequestAccountsDataSlice accounts_data_slice = 8;

  // Ping interval (optional)
  optional int32 ping = 9;
}

message SubscribeRequestFilterTransactions {
  // Include vote transactions (default: true)
  optional bool vote = 1;

  // Include failed transactions (default: true)
  optional bool failed = 2;

  // Include transaction signatures (default: false)
  optional bool signature = 3;

  // Include full transaction data (default: true)
  optional bool transaction = 4;

  // Include account keys (default: true)
  optional bool account_keys = 5;

  // List of accounts to include
  repeated string account_include = 6;

  // List of accounts to exclude
  repeated string account_exclude = 7;

  // Account required (all must be present)
  repeated string account_required = 8;
}

message SubscribeRequestFilterAccounts {
  // List of specific account addresses
  repeated string account = 1;

  // List of owner program addresses
  repeated string owner = 2;

  // Include filters (all must match)
  repeated SubscribeRequestAccountsFilter filters = 3;
}

message SubscribeRequestFilterSlots {
  // Filter by commitment level
  optional bool filter_by_commitment = 1;
}

message SubscribeRequestFilterBlocks {
  // Include transaction details
  optional bool include_transactions = 1;

  // Include account keys
  optional bool include_accounts = 2;

  // Include entries
  optional bool include_entries = 3;
}

message SubscribeUpdate {
  // Update timestamp
  google.protobuf.Timestamp timestamp = 1;

  // One of the following update types
  oneof update_oneof {
    SubscribeUpdateAccount account = 2;
    SubscribeUpdateSlot slot = 3;
    SubscribeUpdateTransaction transaction = 4;
    SubscribeUpdateBlock block = 5;
    SubscribeUpdatePing ping = 6;
    SubscribeUpdatePong pong = 7;
    SubscribeUpdateBlockMeta block_meta = 8;
    SubscribeUpdateEntry entry = 9;
  }
}

message SubscribeUpdateTransaction {
  // Transaction data
  Transaction transaction = 1;

  // Slot number
  uint64 slot = 2;

  // Subscription name (matches request)
  string subscription = 3;
}

message Transaction {
  // Transaction signature
  bytes signature = 1;

  // Is vote transaction
  bool is_vote = 2;

  // Transaction message
  Message message = 3;

  // Transaction metadata
  TransactionMeta meta = 4;
}

message Message {
  // Message header
  MessageHeader header = 1;

  // Account keys
  repeated bytes account_keys = 2;

  // Recent blockhash
  bytes recent_blockhash = 3;

  // Instructions
  repeated CompiledInstruction instructions = 4;

  // Versioned message (if applicable)
  bool versioned = 5;

  // Address table lookups
  repeated MessageAddressTableLookup address_table_lookups = 6;
}

message TransactionMeta {
  // Transaction error
  TransactionError error = 1;

  // Fee
  uint64 fee = 2;

  // Pre balances
  repeated uint64 pre_balances = 3;

  // Post balances
  repeated uint64 post_balances = 4;

  // Inner instructions
  repeated InnerInstructions inner_instructions = 5;

  // Log messages
  repeated string log_messages = 6;

  // Pre token balances
  repeated TokenBalance pre_token_balances = 7;

  // Post token balances
  repeated TokenBalance post_token_balances = 8;

  // Rewards
  repeated Reward rewards = 9;

  // Loaded addresses
  LoadedAddresses loaded_addresses = 10;

  // Return data
  optional ReturnData return_data = 11;

  // Compute units consumed
  optional uint64 compute_units_consumed = 12;
}

message SubscribeUpdateAccount {
  // Account data
  Account account = 1;

  // Slot number
  uint64 slot = 2;

  // Subscription name
  string subscription = 3;

  // Is startup update
  bool is_startup = 4;
}

message Account {
  // Account pubkey
  bytes pubkey = 1;

  // Lamports balance
  uint64 lamports = 2;

  // Owner program
  bytes owner = 3;

  // Is executable
  bool executable = 4;

  // Rent epoch
  uint64 rent_epoch = 5;

  // Account data
  bytes data = 6;

  // Write version
  uint64 write_version = 7;

  // Transaction signature that updated account
  optional bytes txn_signature = 8;
}

message SubscribeUpdateSlot {
  // Slot number
  uint64 slot = 1;

  // Parent slot
  uint64 parent = 2;

  // Slot status
  CommitmentLevel status = 3;

  // Subscription name
  string subscription = 4;
}

message SubscribeUpdateBlock {
  // Slot number
  uint64 slot = 1;

  // Blockhash
  bytes blockhash = 2;

  // Rewards
  repeated Reward rewards = 3;

  // Block time
  optional google.protobuf.Timestamp block_time = 4;

  // Block height
  optional uint64 block_height = 5;

  // Parent slot
  uint64 parent_slot = 6;

  // Parent blockhash
  bytes parent_blockhash = 7;

  // Executed transaction count
  uint64 executed_transaction_count = 8;

  // Transactions
  repeated Transaction transactions = 9;

  // Updated accounts count
  uint64 updated_account_count = 10;

  // Entries
  repeated Entry entries = 11;

  // Subscription name
  string subscription = 12;
}

enum CommitmentLevel {
  PROCESSED = 0;
  CONFIRMED = 1;
  FINALIZED = 2;
}

message TransactionError {
  oneof error {
    InstructionError instruction_error = 1;
    DuplicateInstruction duplicate_instruction = 2;
    InsufficientFundsForRent insufficient_funds_for_rent = 3;
    // ... other error types
  }
}

message TokenBalance {
  // Account index
  uint32 account_index = 1;

  // Token mint
  string mint = 2;

  // UI amount
  optional UiTokenAmount ui_token_amount = 3;

  // Owner
  string owner = 4;

  // Program ID
  string program_id = 5;
}

message UiTokenAmount {
  // UI amount as string
  string ui_amount = 1;

  // Decimals
  uint32 decimals = 2;

  // Raw amount as string
  string amount = 3;

  // UI amount as float
  optional double ui_amount_float = 4;
}

message Reward {
  // Account pubkey
  string pubkey = 1;

  // Lamports
  int64 lamports = 2;

  // Post balance
  uint64 post_balance = 3;

  // Reward type
  RewardType reward_type = 4;

  // Commission (for voting rewards)
  optional uint32 commission = 5;
}

enum RewardType {
  UNSPECIFIED = 0;
  FEE = 1;
  RENT = 2;
  STAKING = 3;
  VOTING = 4;
}

message PingRequest {
  // Number of pings
  int32 count = 1;
}

message PongResponse {
  // Pong count
  int32 count = 1;
}

message GetLatestBlockhashRequest {
  // Commitment level
  optional CommitmentLevel commitment = 1;
}

message GetLatestBlockhashResponse {
  // Slot number
  uint64 slot = 1;

  // Blockhash
  string blockhash = 2;

  // Last valid block height
  uint64 last_valid_block_height = 3;
}

message GetBlockHeightRequest {
  // Commitment level
  optional CommitmentLevel commitment = 1;
}

message GetBlockHeightResponse {
  // Block height
  uint64 block_height = 1;
}

message GetVersionRequest {}

message GetVersionResponse {
  // Server version
  string version = 1;
}

const request = {
  transactions: {
    'my_subscription': {
      vote: false,
      failed: false,
      accountInclude: ['JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4']
    }
  },
  commitment: 'CONFIRMED'
};

stream.write(request);

const request = {
  transactions: {
    'txs': { vote: false }
  },
  slots: {
    'slots': { filterByCommitment: true }
  },
  blocks: {
    'blocks': { includeTransactions: false }
  },
  commitment: 'CONFIRMED'
};

stream.write(request);

const request = {
  accounts: {
    'token_accounts': {
      owner: ['TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA']
    }
  }
};

stream.write(request);

curl -O https://raw.githubusercontent.com/rpcpool/yellowstone-grpc/master/yellowstone-grpc-proto/proto/geyser.proto

npm install @grpc/proto-loader @grpc/grpc-js

# Use dynamic loading (no generation needed)

pip install grpcio-tools

python -m grpc_tools.protoc \
  -I. \
  --python_out=. \
  --grpc_python_out=. \
  geyser.proto

[build-dependencies]
tonic-build = "0.11"

// build.rs
fn main() {
    tonic_build::compile_protos("proto/geyser.proto")
        .expect("Failed to compile protos");
}

protoc --go_out=. --go-grpc_out=. geyser.proto