Agave Documentation

The agave-watchtower program monitors cluster health by periodically polling an RPC API. It performs several sanity checks to ensure the cluster is functioning correctly:

• Transaction Advancement: Confirms the transaction count is increasing.
• Blockhash Availability: Ensures new blockhashes are being produced.
• Validator Delinquency: Checks that no validators are in a delinquent state.
• Vote Account Balance: Alerts when a monitored validator's vote account balance falls below the bank-side VAT balance threshold (computed from RPC-visible state).

Note: The vote account balance check only verifies the balance via public RPC and does not verify full VAT eligibility (e.g., BLS pubkey presence, stake, or top validator set inclusion).

The Solana Virtual Machine (SVM) can be used as a standalone library outside of the standard Solana Validator. This allows developers to build applications such as:

• SVM Rollups: Execute blocks with reduced hardware requirements.
• SVM Fraud Proofs: Generate succinct proofs of invalid state transitions.
• Validator Sidecars: Implement JSON-RPC services that require transaction replaying and account data access (e.g., simulateTransaction).
• Custom Subnets: Run SVM within alternative consensus frameworks like Avalanche.
• Modified SVM (SVM+): Extend the current functionality with custom instructions.

The Geyser Plugin Interface allows developers to extend the Solana Validator runtime by implementing a plugin that reacts to real-time validator events. Plugins can take actions during account updates, block processing, or transaction processing. A common use case is streaming account state to an external database for indexing or monitoring.

To create a plugin, you must:

1. Implement the GeyserPlugin trait defined in geyser_plugin_interface.rs.
2. Compile the plugin as a cdylib dynamic library.
3. Expose a C function named _create_plugin() that returns an instance of your GeyserPlugin implementation.

The SVM's control flow manages the lifecycle of transaction execution through a series of high-level steps: loading program accounts, verifying them, creating an invocation context, and invoking the Runtime BPF (RBPF) on programs.

Key components include:

• Account Database: Provides access to account data.
• Sysvar Cache: Accessed via traits for system variables.
• MessageProcessor: Contained in the solana-program-runtime crate, responsible for the actual execution of the transaction message.
• LogCollector: Defined in solana-program-runtime, used to capture execution logs.

In a validator context, the primary entry point is load_and_execute_sanitized_transactions, which is called by simulate_transaction (for single transactions) or load_execute_and_commit_transactions (for batches).

In production, the project expects a BigTable instance named solana-ledger that has been previously initialized using the ./init-bigtable.sh script.

To connect, you must provide service account credentials via the GOOGLE_APPLICATION_CREDENTIALS environment variable. The application will request either https://www.googleapis.com/auth/bigtable.data or https://www.googleapis.com/auth/bigtable.data.readonly OAuth scopes depending on the required operation mode.

To build a plugin for the Solana Validator, follow these requirements:

1. Implement the Trait

Your plugin must implement the GeyserPlugin trait. This trait defines the hooks for interacting with the validator's lifecycle (e.g., account updates, block processing).

2. Export the Entry Point

The validator expects a dynamic library (cdylib) with a specific C-compatible entry point. You must export a function named _create_plugin to allow the validator to instantiate your plugin.

3. Example Implementation

For a reference implementation that saves account data to a PostgreSQL database, see the solana-accountsdb-plugin-postgres repository.

On Linux, XDP (eXpress Data Path) transmit is enabled by default but requires specific kernel capabilities. You must grant these to the validator binary after building.

Standard XDP

For standard XDP transmit:

$ sudo setcap 'cap_net_admin,cap_net_raw+eip' <path-to-agave-validator-binary>

XDP Zero-Copy

If you are using the --xdp-zero-copy flag, you must grant additional capabilities:

$ sudo setcap 'cap_net_admin,cap_net_raw,cap_bpf,cap_perfmon+eip' <path-to-agave-validator-binary>

Before building Agave, you must install the Rust toolchain and necessary system dependencies. The project uses a rust-toolchain.toml file to pin a specific version, which cargo will automatically install if missing.

1. Install Rust

Install rustc, cargo, and rustfmt using rustup:

$ curl https://sh.rustup.rs -sSf | sh
$ source $HOME/.cargo/env
$ rustup component add rustfmt

2. Install System Dependencies

Depending on your Linux distribution, install the required development libraries:

Ubuntu:

$ sudo apt-get update
$ sudo apt-get install libssl-dev libudev-dev pkg-config zlib1g-dev llvm clang cmake make libprotobuf-dev protobuf-compiler libclang-dev

Fedora:

$ sudo dnf install openssl-devel systemd-devel pkg-config zlib-devel llvm clang cmake make protobuf-devel protobuf-compiler perl-core libclang-dev

This command distributes tokens by splitting existing stake accounts. New stake accounts are created, inheriting any lockup or custodian settings from the original account.

Behavior: The tool subtracts 1 SOL from each allocation and stores it in the recipient address (to cover future staking operation fees like delegation). The remainder of the allocation is placed into a new stake account.

Command:

solana-tokens distribute-stake --stake-account-address <ACCOUNT_ADDRESS> \
    --input-csv <ALLOCATIONS_CSV> \
    --stake-authority <KEYPAIR> --withdraw-authority <KEYPAIR> --fee-payer <KEYPAIR>