Protosol

Protocol buffer + flatbuffer definitions for the Solana Virtual Machine (SVM) testing harness in Agave. This crate provides Rust bindings for protobuf schemas used in fuzzing and testing the Solana blockchain's execution environment.

Overview

Protosol defines the data structures used to capture, serialize, and replay Solana blockchain execution contexts for testing and fuzzing purposes. These protocol buffers represent the complete state and execution flow of Solana transactions, blocks, and virtual machine operations.

What These Protocol Buffers Represent

Core Components

• Transaction Processing: Complete transaction lifecycle from input to execution effects
• Block Execution: Block-level context including transactions, account states, and consensus data
• Virtual Machine State: SVM execution context, compute budgets, and program execution
• Account Management: Account states, ownership, and data storage
• Consensus Context: Slot information, epoch data, and leader schedules

Key Message Types

Transaction Layer (txn.proto)

• SanitizedTransaction: Complete transaction with message and signatures
• TransactionMessage: Transaction payload with accounts and instructions
• CompiledInstruction: Individual program instructions with account references
• MessageHeader: Transaction metadata (signatures, read-only accounts)

Block Layer (block.proto)

• BlockContext: Input state for block execution (transactions, accounts, block hash queue)
• BlockEffects: Output state after block execution (bank hash, costs, leader schedule)
• BlockFixture: Complete test fixture combining input context and expected effects

Execution Context (context.proto)

• AcctState: Complete account state (address, lamports, data, owner)
• FeatureSet: Enabled Solana features for execution

Usage

As a Dependency

Add to your Cargo.toml:

[dependencies]
protosol = "X.Y.Z"

Basic Usage

use protosol::protos;

// Create a transaction fixture
let txn = protos::SanitizedTransaction {
    message: Some(protos::TransactionMessage {
        header: Some(protos::MessageHeader {
            num_required_signatures: 1,
            num_readonly_signed_accounts: 0,
            num_readonly_unsigned_accounts: 0,
        }),
        account_keys: vec![/* account keys */],
        recent_blockhash: vec![/* blockhash */],
        instructions: vec![/* instructions */],
        address_table_lookups: vec![],
    }),
    signatures: vec![vec![/* signature bytes */]],
};

// Create account state
let account = protos::AcctState {
    address: vec![/* 32-byte address */],
    lamports: 1000000,
    data: vec![/* account data */],
    executable: false,
    owner: vec![/* 32-byte owner */],
};

// Create block context for testing
let block_ctx = protos::BlockContext {
    txns: vec![txn],
    acct_states: vec![account],
    blockhash_queue: vec![/* recent blockhashes */],
    slot_ctx: Some(protos::SlotContext {
        slot: 12345,
        poh: vec![/* POH hash */],
        parent_bank_hash: vec![/* parent hash */],
        parent_lthash: vec![/* parent LT hash */],
    }),
    features: Some(protos::FeatureSet {
        features: vec![/* feature flags */],
    }),
    bank: None,

Testing and Fuzzing

These protocol buffers are designed for:

1. Test Fixture Generation: Create reproducible test cases with complete blockchain state
2. Fuzzing: Generate random but valid blockchain execution contexts
3. State Capture: Record actual blockchain execution for later replay
4. Regression Testing: Compare execution results across different SVM implementations

Integration with Agave

This crate is specifically designed for use with the anza-xyz/agave repository's testing infrastructure:

• SVM Fuzzing: Generate test cases for the Solana Virtual Machine
• Execution Testing: Validate transaction and block execution across different implementations
• Performance Testing: Measure execution costs and resource usage
• Compatibility Testing: Ensure different SVM implementations produce identical results

Usage

Add to your Cargo.toml:

[dependencies]
protosol = "5.2.0"

No system dependencies needed — pre-generated Rust code is included.

Development

Setup

git clone --recurse-submodules https://github.com/firedancer-io/protosol.git
cd protosol
cargo build                # Uses pre-generated code, no tools needed

Pre-commit hooks

git config core.hooksPath .githooks

Modifying proto/flatbuffers schemas

If you change files in proto/ or flatbuffers/, you must regenerate src/generated/:

./deps.sh    # Builds protoc + flatc from vendored submodules into opt/bin/
cargo build --features regenerate --locked

The exact pinned compiler revisions come from the submodule commits recorded in this repository (.gitmodules records their URL and branch hint). The deps.sh script builds from these vendored submodules. Prerequisites for deps.sh: CMake, Make, C++ compiler.

CI

CI runs on every push and pull request:

• cargo fmt --check
• cargo build --release --locked (default and solana-types features)
• cargo clippy --all-features --locked -- -D warnings
• Regenerates from source and verifies src/generated/ is up to date

File Structure

src/generated/           # Pre-generated Rust code (checked in, no tools needed to build)

proto/
├── block.proto          # Block execution context and effects
├── context.proto        # Account states and execution context
├── gossip.proto         # Gossip protocol structures
├── invoke.proto         # Program invocation context
├── metadata.proto       # Test fixture metadata
├── pack.proto           # Compute budget testing
├── serialize.proto      # Serialization structures
├── shred.proto          # Shred structures
├── txn.proto            # Transaction structures
├── vm.proto             # Virtual machine state
└── *.options            # Nanopb configuration files

flatbuffers/
├── context.fbs          # Account and execution context definitions
├── elf.fbs              # ELF VM program and state structures
└── metadata.fbs         # Test fixture metadata

shlr/
├── flatbuffers/         # Vendored flatbuffers compiler (submodule, pinned in .gitmodules)
└── protobuf/            # Vendored protobuf compiler (submodule, pinned in .gitmodules)

License

Apache-2.0

Repository

https://github.com/firedancer-io/protosol