Imported from ValidatorsDAO/slv (oss-skills/slv-rpc/SKILL.md). Install upstream with npx skills add ValidatorsDAO/slv --skill slv-rpc. Copyright stays with the author.

SLV RPC Skill

Ansible playbooks and Jinja2 templates for deploying and managing Solana RPC nodes (mainnet, testnet, devnet).

Supported RPC Types

Directory Structure

ansible/
  mainnet-rpc/   — Mainnet RPC playbooks
  testnet-rpc/   — Testnet RPC playbooks
  devnet-rpc/    — Devnet RPC playbooks
  cmn/           — Shared common playbooks
jinja/
  mainnet-rpc/   — Mainnet Jinja2 templates
  testnet-rpc/   — Testnet Jinja2 templates
  devnet-rpc/    — Devnet Jinja2 templates
  cmn/           — Shared templates

Benchmarking Notes

Planned CLI shape

A natural future command shape is:

slv check geyserbench <options>

This would mirror the existing slv check grpc / slv check shreds style by passing arguments through to the installed benchmark binary.

geyserbench config generation

For shredstream and grpc benchmark flows, the agent should be able to generate config.toml from:

• benchmark type
• two endpoint URLs
• ERPC API key from ~/.slv/api.yml

If ~/.slv/api.yml does not contain the required ERPC API key, instruct the user to get a free key and configure it first.

Example config:

[config]
region = "frankfurt"
erpc_url = "https://edge.erpc.global"
erpc_api_key = "api-key"
transactions = 10000
account = "pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA"
commitment = "processed"

[[endpoint]]
name = "http://shreds-fra6-1.erpc.global"
url = "http://shreds-fra6-1.erpc.global"
kind = "shredstream"

[[endpoint]]
name = "http://shreds-turbo-fra-1.erpc.global"
url = "http://shreds-turbo-fra-1.erpc.global"
kind = "shredstream"

For gRPC benchmarks, use the same structure but set the endpoint kind to the appropriate gRPC-compatible type.

CLI Command ↔ Playbook Mapping

The slv r CLI commands map directly to these playbooks. {net} = mainnet-rpc, testnet-rpc, or devnet-rpc.

All Playbooks

Mainnet RPC (mainnet-rpc/)

Testnet RPC (testnet-rpc/)

Devnet RPC (devnet-rpc/)

Shared Common (cmn/)

Key Variables (extra_vars)

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

ansible-playbook -i inventory mainnet-rpc/init.yml \
  -e '{"rpc_type":"Index RPC","solana_version":"3.1.8","snapshot_url":"https://..."}'

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

Conditionally Required Variables

Optional Variables

Optional: Reference RPC

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-rpc/ansible/
ansible-playbook -i inventory.yml {network}-rpc/init.yml \
  -e '{"rpc_type":"<type>","solana_version":"<version>"}'

Performance Tuning

slv r init automatically applies node-level performance tuning after the SSH connection check and before slv r deploy. The orchestrator playbook cmn/optimize_node.yml chains three sub-skills and reboots the node once when GRUB / kernel changes require it.

Idempotency markers: /var/lib/slv/.smt_disabled, .irq_tuned, .boost_applied. The orchestrator reboots once if any sub-skill requested it and waits for the host to come back.

SHA256 patch (RPC only)

After slv r deploy completes successfully, the optimized SHA256 binary is automatically built and deployed by calling runSha256Patch with the Solana version pulled from ~/.slv/versions.yml. This replaces the agave-validator binary with one that uses solana-sha256-hasher-optimized in PoH hashing. Restart the RPC manually when ready (the patch step does not restart on its own).

Standalone Usage

# Run full optimization stack
ansible-playbook -i inventory.yml cmn/optimize_node.yml --limit <host>

# Run a single sub-skill
ansible-playbook -i inventory.yml cmn/smt_disable.yml --limit <host>
ansible-playbook -i inventory.yml cmn/irq_tune.yml --limit <host>
ansible-playbook -i inventory.yml cmn/boost_performance.yml --limit <host>

# Apply SHA256 patch manually
slv r patch:sha256 -n <network> -p <pubkey>

CLI Command Mapping

Index RPC: Rolling Index Cache

Index RPC and Index RPC + gRPC deploys add a rolling cache of yellowstone-faithful indexes for the most recent N epochs (default 30) so historical RPC queries answer locally instead of round-tripping to files.old-faithful.net on every lookup.

How it works

The index files (cid-to-offset, slot-to-cid, sig-to-cid, sig-exists, slot-to-blocktime) are kept on local disk; CAR files stay remote and are fetched via HTTP Range requests as needed. A daily systemd timer (of1-index-sync.timer) calls /usr/local/bin/of1-index-sync.sh, which:

1. Discovers the latest available epoch on Old Faithful.
2. Downloads any missing indexes for the last index_rpc_window_epochs epochs (parallel aria2c).
3. Regenerates per-epoch config YAMLs in /home/solv/configs/ with file:// URIs for indexes + https:// URI for CAR.
4. Evicts caches older than the window.
5. Restarts faithful.service only if anything changed.

faithful.service runs through /usr/local/bin/start-faithful.sh, which globs config-epoch*.yaml so the timer can add or remove epochs without editing the systemd unit.

Disk budget

A recent epoch is ~30 GB of indexes (CAR is excluded — it would be 500-800 GB per epoch). 30 epochs ≈ ~1 TB on local disk and covers ~63 days of mainnet history.

Measured impact (representative production RPC node)

getTransaction is the win because it traverses three indexes; with all of them remote each query becomes an HTTP-Range chain. Localizing collapses that to a single CAR roundtrip.

Standalone control

sudo systemctl start of1-index-sync.service        # ad-hoc sync
WINDOW=10 sudo /usr/local/bin/of1-index-sync.sh    # smaller window
DRY_RUN=1 sudo /usr/local/bin/of1-index-sync.sh    # show plan without DL