# rpcpool/yellowstone-grpc architecture

> Architecture diagram of the GitHub repository rpcpool/yellowstone-grpc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rpcpool/yellowstone-grpc
- Repository: https://github.com/rpcpool/yellowstone-grpc

## Overview

##### Main Components
- gRPC Plugin (yellowstone-grpc-geyser): This is the core component that integrates with a Solana validator via the Geyser interface. It receives blockchain updates and (optionally) performs block reconstruction (noting its configurable error-handling behavior).
- Proto Definitions (yellowstone-grpc-proto): Contains all the gRPC message definitions and service contracts, including filters and unary methods (e.g., Ping, GetLatestBlockhash).
- Client Libraries and Implementations:
– yellowstone-grpc-client (Rust-based)
– yellowstone-grpc-client-nodejs (Node.js-based, with its own embedded WASM component for Solana encoding)
– Multiple examples for Go, Python, Rust, and TypeScript in the examples/ directory.

##### Relationships and Interactions
- Solana Validator (external component): Although not part of the repo, its interaction is critical—it pushes Geyser updates to the plugin.
- The Plugin (yellowstone-grpc-geyser):
– Receives raw Solana data streams from the validator.
– Processes and reconstructs the block data (with configurable error actions, as per block reconstruction details in the README).
– Applies filtering rules (accounts, transactions, slots, etc.) defined in its configuration.
– Emits processed messages over a gRPC endpoint.
- gRPC Server Interface:
– Acts as the exposed API that multiple client applications (from different language implementations) connect to.
– Uses the proto definitions to ensure a standardized communication protocol.
- gRPC Clients:
– The client libraries (Rust, Node.js, etc.) and sample clients illustrate different approaches to connecting to the gRPC server.
– They respond to server-sent ping messages to keep connections alive and can send subscriptions (with various filtering options).

##### Architectural Patterns & Design Principles
- Modularity: The project divides the system cleanly into components (plugin, shared proto, and multiple client libraries).
- Separation of Concerns: The plugin handles data ingestion and processing; proto definitions provide a single source of truth for communication contracts; and client examples demonstrate usage separately.
- Extensibility: With multiple language examples and a standardized gRPC interface, the system is designed to be integrated into various environments.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Component
    S["Solana Validator"]:::external

    %% Core Services
    subgraph "Core Services"
        GP["gRPC Plugin (yellowstone-grpc-geyser)"]:::server
        PD["Proto Definitions (yellowstone-grpc-proto)"]:::server
    end

    %% Client Interfaces
    subgraph "Client Interfaces"
        CR["gRPC Client (Rust)"]:::client
        CN["gRPC Client (Node.js)"]:::client
        ExGo["Client Example: Go"]:::client
        ExPy["Client Example: Python"]:::client
        ExRust["Client Example: Rust"]:::client
        ExTS["Client Example: TS/Node.js"]:::client
    end

    %% CI & Build Infrastructure Cluster
    subgraph "CI & Build Infrastructure"
        CI1["GitHub Workflows"]:::ci
        CI2["CI Scripts"]:::ci
        MF["Makefile"]:::ci
        CIC["CI Central"]:::ci
    end

    %% Data Flow Arrows
    S -->|"push_updates"| GP
    GP -->|"uses_proto"| PD
    GP -->|"gRPC_calls"| CR
    GP -->|"gRPC_calls"| CN
    GP -->|"gRPC_calls"| ExGo
    GP -->|"gRPC_calls"| ExPy
    GP -->|"gRPC_calls"| ExRust
    GP -->|"gRPC_calls"| ExTS

    %% CI Build & Test Dotted Arrows
    CIC -.->|"build&test"| GP
    CIC -.->|"build&test"| PD
    CIC -.->|"build&test"| CR
    CIC -.->|"build&test"| CN
    CIC -.->|"build&test"| ExGo
    CIC -.->|"build&test"| ExPy
    CIC -.->|"build&test"| ExRust
    CIC -.->|"build&test"| ExTS

    %% Styles
    classDef external fill:#f96,stroke:#333,stroke-width:2px;
    classDef server fill:#bbf,stroke:#333,stroke-width:2px;
    classDef client fill:#cfc,stroke:#333,stroke-width:2px;
    classDef ci fill:#ddd,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;

    %% Click Events
    click GP "https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-geyser/"
    click PD "https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-proto/"
    click CR "https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-client/"
    click CN "https://github.com/rpcpool/yellowstone-grpc/tree/master/yellowstone-grpc-client-nodejs/"
    click ExGo "https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/golang/"
    click ExPy "https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/python/"
    click ExRust "https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/rust/"
    click ExTS "https://github.com/rpcpool/yellowstone-grpc/tree/master/examples/typescript/"
    click CI1 "https://github.com/rpcpool/yellowstone-grpc/tree/master/.github/"
    click CI2 "https://github.com/rpcpool/yellowstone-grpc/tree/master/ci/"
    click MF "https://github.com/rpcpool/yellowstone-grpc/tree/master/Makefile"
```
