SLV gRPC Geyser Skill
Ansible playbooks and Jinja2 templates for deploying and managing Solana gRPC Geyser streaming nodes.
Supported Configurations
| Config | Description |
|---|
| Yellowstone gRPC | Standard Geyser gRPC plugin (Triton/rpcpool) |
| Richat gRPC | Richat Geyser plugin (lamports-dev) |
Directory Structure
ansible/
mainnet-rpc/ — Playbooks (gRPC Geyser uses mainnet-rpc playbooks)
cmn/ — Shared common playbooks
jinja/
mainnet-rpc/ — Jinja2 templates
cmn/ — Shared templates
CLI Command ↔ Playbook Mapping
gRPC Geyser nodes are managed via slv r (RPC) commands with rpc_type set to Geyser gRPC or Index RPC + gRPC.
| CLI Command | Playbook | Description |
|---|
slv r deploy | mainnet-rpc/init.yml | Full gRPC Geyser node initialization |
slv r start | mainnet-rpc/start_node.yml | Start node |
slv r stop | mainnet-rpc/stop_node.yml | Stop node |
slv r restart | mainnet-rpc/restart_node.yml | Restart node |
slv r build:solana | mainnet-rpc/install_solana.yml | Build Solana from source |
slv r update:geyser | mainnet-rpc/update_geyser.yml | Update Geyser plugin |
slv r update:script | mainnet-rpc/update_startup_config.yml | Update start-validator.sh |
slv r setup:firedancer | mainnet-rpc/setup_firedancer.yml | Setup Firedancer |
Key Playbooks
| Playbook | Description |
|---|
init.yml | Full gRPC Geyser node initialization |
init_richat_geyser.yml | Richat Geyser initialization |
geyser_build.yml | Build Yellowstone gRPC from GitHub source |
geyser_richat_build.yml | Build Richat plugin from GitHub source |
install_richat.yml | Install Richat plugin |
update_geyser.yml | Update Geyser plugin |
restart_node.yml | Restart node |
start_node.yml / stop_node.yml | Start/stop node |
update_startup_config.yml | Update start-validator.sh from template |
setup_firedancer.yml | Setup Firedancer |
run_snapshot_finder.yml | Find and download best snapshot |
run_restarter.yml | Run restarter script |
Geyser Build Details
Yellowstone gRPC (geyser_build.yml)
- Clones from https://github.com/rpcpool/yellowstone-grpc
- Builds with
cargo build --release - Produces
libyellowstone_grpc_geyser.so - Config template:
jinja/mainnet-rpc/geyser.json.j2
Richat (geyser_richat_build.yml)
- Clones from https://github.com/lamports-dev/richat
- Builds with
cargo build --release - Produces
librichat_plugin_agave.so - Config template:
jinja/mainnet-rpc/geyser-richat.json.j2 - Service template:
jinja/mainnet-rpc/richat.service.j2 - Settings template:
jinja/mainnet-rpc/richat-setting.yml.j2
Key Variables (extra_vars)
| Variable | Description | Default |
|---|
rpc_type | Must be Geyser gRPC or Index RPC + gRPC | — |
validator_type | Client type (agave, jito, firedancer-agave, etc.) | — |
solana_version | Solana/Agave version | — |
yellowstone_grpc_version | Yellowstone gRPC version tag | — |
richat_version | Richat plugin version (e.g. richat-v8.1.0) | — |
snapshot_url | Snapshot download URL | — |
port_grpc | gRPC listen port | 10000 |
limit_ledger_size | Ledger size limit | 100000000 |
Jinja Templates
| Template | Description |
|---|
start-validator.sh.j2 | Main start script (branches by rpc_type) |
start-mainnet-rpc-grpc.sh.j2 | gRPC-specific start script |
geyser.json.j2 | Yellowstone gRPC config |
geyser-richat.json.j2 | Richat gRPC config |
richat-setting.yml.j2 | Richat settings |
richat.service.j2 | Richat systemd service |
firedancer-config.toml.j2 | Firedancer config |
firedancer.service.j2 | Firedancer systemd service |
solv.service.j2 | Solv systemd service |
generate_configs.sh.j2 | Config generation script |
Geyser Plugin Sources
Both plugins are built from source (no binary downloads):
- Yellowstone gRPC: https://github.com/rpcpool/yellowstone-grpc
- Richat: https://github.com/lamports-dev/richat
Usage
# Deploy a new gRPC Geyser node
ansible-playbook -i inventory mainnet-rpc/init.yml \
-e '{"rpc_type":"Geyser gRPC","solana_version":"3.1.8","yellowstone_grpc_version":"v6.0.0","snapshot_url":"https://..."}'
# Build/update Richat plugin
ansible-playbook -i inventory mainnet-rpc/geyser_richat_build.yml \
-e '{"richat_version":"richat-v8.1.0"}'
No versions.yml required — all variables can be passed via extra_vars.
Interactive Deployment Flow
See AGENT.md for the full step-by-step flow and examples/inventory.yml for output format.
Required Variables
| Variable | Prompt | Validation |
|---|
server_ip | "Target server IP?" | Valid IPv4 |
region | "Server region?" | String |
rpc_type | "Geyser gRPC or Index RPC + gRPC?" | Geyser gRPC, Index RPC + gRPC |
validator_type | "Underlying client?" | agave, jito, jito-bam, firedancer-agave |
solana_version | "Solana version? (default: 3.1.8)" | Semver |
identity_account | "Node identity pubkey?" | Base58 pubkey |
snapshot_url | "Snapshot URL? (auto for ERPC)" | URL (cannot be empty for init) |
Plugin Selection (choose ONE)
| Plugin | Version Variable | Source | Output |
|---|
| Yellowstone gRPC | yellowstone_grpc_version | github.com/rpcpool/yellowstone-grpc | libyellowstone_grpc_geyser.so |
| Richat | richat_version | github.com/lamports-dev/richat | librichat_plugin_agave.so |
Both are built from source (no pre-built binaries). Build time: ~15-30 min. Only collect the version variable for the selected plugin.
Conditionally Required Variables
| Variable | When Required |
|---|
jito_version | jito/jito-bam types |
firedancer_version | firedancer types |
shred_receiver_address | jito/jito-bam (auto by region) |
block_engine_url | jito/jito-bam (auto by region) |
Optional Variables
| Variable | Default | When Required |
|---|
ssh_user | solv | Always |
port_grpc | 10000 | Always |
port_rpc | 8899 (ERPC: 7211) | Always |
limit_ledger_size | 100000000 | Always |
dynamic_port_range | 8000-8025 | Always |
allowed_ssh_ips | — | Strongly recommended (UFW) |
allowed_ips | — | Optional (UFW) |
Optional: Reference RPC
| Variable | Description | Default |
|---|
reference_rpc_url | Reference RPC endpoint for slot sync comparison (e.g., ERPC) | — |
ERPC API keys are free at https://erpc.global — enables full slot sync monitoring during deployment and updates.
Pre-flight: Fresh Server Setup
ansible-playbook -i inventory.yml cmn/add_solv.yml \
-e '{"ansible_user":"ubuntu"}' --become
Deployment Command
All paths relative to skill's ansible/ directory:
cd /path/to/slv-grpc-geyser/ansible/
ansible-playbook -i inventory.yml mainnet-rpc/init.yml \
-e '{"rpc_type":"Geyser gRPC","solana_version":"<version>","richat_version":"<version>"}'
