Levandor

yellowstone-grpc 12.x/13.x — Proto Module Layout & Version Gotchas

2 min read

Three gotchas hit wiring a yellowstone-grpc (Geyser) transactions subscription in Rust, found building the solv1-rig Yellowstone adapter: where the confirmed-block proto types actually live, a new struct field that breaks exhaustive literals, and the fact that client and proto crates are no longer lockstep-versioned.

For Agents

Wiring yellowstone-grpc-client + yellowstone-grpc-proto? (1) Message / Transaction / TransactionStatusMeta live under solana::storage::confirmed_block (use the crate prelude). (2) Always build SubscribeRequestFilterTransactions with ..Default::default() — it gained a token_accounts field. (3) Pin the client and proto crate versions independently; matching majors are not guaranteed.

1. Confirmed-block types live in solana::storage::confirmed_block

The decoded transaction types you need on the receive side — Message, Transaction, TransactionStatusMeta (and the surrounding confirmed-block messages) — are generated under:

yellowstone_grpc_proto::solana::storage::confirmed_block::{Message, Transaction, TransactionStatusMeta}

The crate prelude re-exports them, so the ergonomic import is:

use yellowstone_grpc_proto::prelude::*;

Reaching for them under a top-level module (or copying import paths from older examples / geyser plugin docs) sends you looking in the wrong place. When in doubt, import from the prelude.

2. SubscribeRequestFilterTransactions gained token_accounts (tag 30)

The transactions filter struct picked up a new field:

pub token_accounts: Option<i32>,   // protobuf tag 30

Any exhaustive struct literal (listing every field: account_include, account_exclude, account_required, vote, failed, signature, …) fails to compile against a proto version that added token_accounts. Always construct it with a spread so future field additions don’t break the build:

SubscribeRequestFilterTransactions {
    account_include: venues.include_list(),
    vote: Some(false),
    failed: None,          // include failed txs — shreds can't exclude them
    ..Default::default()
}

Note the field is singular

The venue filter field is account_include (singular _include), and failed: None deliberately includes failed transactions — the shred side can’t drop them, so excluding on the Yellowstone side would poison the cross-feed match population.

3. Client 13.x and proto 12.x are no longer lockstep-versioned

Older yellowstone-grpc releases moved the client and proto crates together; they no longer do. The rig pins them independently:

yellowstone-grpc-client = "13.2"
yellowstone-grpc-proto  = "12.5"

Do not assume the client and proto crates share a major version — pin each to what actually resolves and compiles together. Separately, client/proto ↔ server compatibility with a given vendor’s Yellowstone deployment (e.g. RPC Fast) is prudent-but-undocumented: verify against their server version during shakeout, not by assuming version parity.

Graph View

Backlinks