Overview
The Yellowstone gRPC Geyser plugin is configured using a JSON configuration file. This file defines gRPC server settings, filter limits, logging, and performance tuning options.Configuration File Structure
The configuration file has the following top-level sections:libpath: Path to the plugin shared librarylog: Logging configurationtokio: Async runtime settingsgrpc: gRPC server and filter configurationprometheus: Metrics endpoint configuration
Complete Example
Here’s a complete configuration example from the source repository:Configuration Fields
Library Path
- libpath (string): Path to the compiled plugin shared library. Can be relative or absolute.
Logging
- level (string): Log level for the plugin. Options:
error,warn,info,debug,trace
Tokio Runtime
- worker_threads (number): Number of worker threads for the async runtime. Tune based on your CPU cores.
- affinity (string): CPU affinity for worker threads. Format:
"core1-core2,core3-core4". Helps with performance isolation.
gRPC Server
Basic Settings
- address (string): Bind address and port for the gRPC server
TLS Configuration
- cert_path (string): Path to TLS certificate file. Leave empty to disable TLS.
- key_path (string): Path to TLS private key file. Leave empty to disable TLS.
When both
cert_path and key_path are empty strings, the gRPC server runs without TLS encryption.Compression
- accept (array): Compression algorithms accepted from clients. Options:
gzip,zstd - send (array): Compression algorithms used for server responses. Options:
gzip,zstd
HTTP/2 Settings
- server_http2_adaptive_window (number|null): Enable adaptive flow control window
- server_http2_keepalive_interval (string|null): Interval for HTTP/2 keepalive pings (e.g.,
"30s") - server_http2_keepalive_timeout (string|null): Timeout for keepalive pings (e.g.,
"10s") - server_initial_connection_window_size (number|null): Initial HTTP/2 connection window size in bytes
- server_initial_stream_window_size (number|null): Initial HTTP/2 stream window size in bytes
Set these to
null to use default values. Adjust only if you experience connection issues.Channel Settings
- max_decoding_message_size (string): Maximum message size for decoding (in bytes). Uses underscore notation for readability.
- snapshot_plugin_channel_capacity (string|null): Channel capacity for snapshot plugin messages
- snapshot_client_channel_capacity (string): Channel capacity for snapshot client messages
- channel_capacity (string): General channel capacity for message passing
Unary Methods
- unary_concurrency_limit (number): Maximum concurrent unary RPC calls
- unary_disabled (boolean): Disable unary methods (Ping, GetLatestBlockhash, GetBlockHeight, GetSlot, IsBlockhashValid, GetVersion)
Authentication
- x_token (string|null): Authentication token for client requests. Set to
nullto disable authentication.
Replay Settings
- replay_stored_slots (number): Number of stored slots to replay on client connection. Set to
0to disable replay.
Filter Name Limits
- filter_name_size_limit (number): Maximum size for a single filter name in bytes
- filter_names_size_limit (number): Maximum total size for all filter names in bytes
- filter_names_cleanup_interval (string): Interval for cleaning up expired filter names (e.g.,
"1s","5s")
Filter Limits
Filter limits control how clients can subscribe to data streams. These limits prevent abuse and ensure fair resource usage.Account Filters
- max (number): Maximum number of account filters per subscription
- any (boolean): Allow clients to subscribe to all accounts
- account_max (number): Maximum number of specific accounts per filter
- account_reject (array): List of account pubkeys that cannot be filtered
- owner_max (number): Maximum number of owner pubkeys per filter
- owner_reject (array): List of owner pubkeys that cannot be filtered
- data_slice_max (number): Maximum number of data slices per filter
Slot Filters
- max (number): Maximum number of slot filters per subscription
Transaction Filters
- max (number): Maximum number of transaction filters per subscription
- any (boolean): Allow clients to subscribe to all transactions
- account_include_max (number): Maximum accounts in the include list
- account_include_reject (array): Accounts that cannot be in the include list
- account_exclude_max (number): Maximum accounts in the exclude list
- account_required_max (number): Maximum accounts in the required list
Transaction Status Filters
Block Filters
- max (number): Maximum number of block filters per subscription
- account_include_max (number): Maximum accounts in the include list
- account_include_any (boolean): Allow subscribing to blocks with any account
- account_include_reject (array): Accounts that cannot be in the include list
- include_transactions (boolean): Whether to include transactions in blocks
- include_accounts (boolean): Whether to include account updates in blocks
- include_entries (boolean): Whether to include entries in blocks
Block Meta Filters
- max (number): Maximum number of block metadata filters per subscription
Entry Filters
- max (number): Maximum number of entry filters per subscription
Prometheus Metrics
- address (string): Bind address and port for the Prometheus metrics endpoint
The plugin exposes various metrics including
invalid_full_blocks_total for monitoring block reconstruction failures.Validation
Before deploying your configuration, validate it using the config-check tool:Common Configurations
Development Setup
Production Setup with TLS
High-Performance Setup
Next Steps
After configuring the plugin:- Deploy to validator - Integrate with your Solana validator
- Review the Filters documentation - Learn about data filtering options