# michaelhly/solana-py architecture

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

- Interactive diagram: https://gitdiagram.com/michaelhly/solana-py
- Repository: https://github.com/michaelhly/solana-py

## Overview

##### Project type and purpose
- This is a Python SDK (library) for interacting with the Solana blockchain via its JSON‑RPC and WebSocket APIs. It provides both synchronous and asynchronous clients, utility functions (e.g., cluster URL management, validation), and wrappers around Solana’s core programs (e.g., SPL Token, Memo, Vote).

##### File structure
- Top‑level config & tooling
- .github/, GitHub Actions workflows (CI, docs, release)
- mkdocs.yml + docs/ — static documentation site
- pyproject.toml, poetry.toml, Makefile — packaging, dependency, build/test scripts
- Source code (`src/solana` and `src/spl`):
- solana/rpc — API layers: `api.py`, `async_api.py`, `websocket_api.py`
- solana/rpc/providers — pluggable transport implementations (HTTP, AsyncHTTP, WebSocket, base classes)
- solana/utils — helpers (cluster selection, validation, security.txt)
- solana/_layouts & vote_program.py — transaction‑building helpers for on‑chain programs
- spl/token & spl/memo — high‑level clients and instruction builders for SPL programs
- Tests
- unit/ and integration/ — exercise client, provider, instruction‑builder functionality
- docker-compose.yml — spin up local validator for integration tests

##### README for additional insights
- Clarifies that the library wraps the Solana JSON RPC API and SPL Token program
- Emphasizes both sync and async clients, plus a WebSocket subscription client
- Points to external dependency: `solders` for low‑level type definitions

##### Capturing essential elements in detail
- Major sub‑packages: `rpc`, `rpc/providers`, `rpc/websocket_api`, `utils`, `vote_program`, `spl/token`, `spl/memo`
- Interaction with external dependencies: `solders`, remote endpoints
- Where tests plug in (integration tests use docker‑compose local validator)
- Call out CI/CD and docs pipeline if relevant for a holistic view

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "API Layer"
        SC["SyncClient\n(solana.rpc.api.Client)"]:::sync
        AC["AsyncClient\n(solana.rpc.async_api.AsyncClient)"]:::async
        WC["WebSocketClient\n(solana.rpc.websocket_api)"]:::ws
    end

    subgraph "Core Layer"
        RC["RPC Core\n(core.py)"]:::core
        RT["RPC Types\n(types.py)"]:::core
        CM["Commitment Levels\n(commitment.py)"]:::core
    end

    subgraph "Providers"
        subgraph "Base Providers"
            BP["BaseProvider"]:::provider
            ABP["AsyncBaseProvider"]:::provider
            CP["CoreProvider"]:::provider
        end
        subgraph "HTTP Providers"
            HP["HTTPProvider"]:::provider
            AHP["AsyncHTTPProvider"]:::provider
        end
        WP["WebSocketProvider"]:::provider
    end

    subgraph "Utils"
        CU["Cluster URL Utility\n(cluster.py)"]:::utils
        VH["Validation Helpers\n(validate.py)"]:::utils
        SM["Security Metadata\n(security_txt.py)"]:::utils
    end

    subgraph "Instruction Builders & Layouts"
        VI["Vote Layouts\n(vote_instructions.py)"]:::builder
        VP["Vote Program\n(vote_program.py)"]:::builder
    end

    subgraph "SPL Modules"
        subgraph "Token"
            STC["Token Sync Client\n(client.py)"]:::spl
            ATC["Token Async Client\n(async_client.py)"]:::spl
            SIB["Token Instructions\n(instructions.py)"]:::spl
            SCR["Token Core\n(core.py)"]:::spl
            SCT["Token Constants\n(constants.py)"]:::spl
            SL["Token Layouts\n(_layouts.py)"]:::spl
        end
        subgraph "Memo"
            MC["Memo Constants\n(constants.py)"]:::spl
            MI["Memo Instructions\n(instructions.py)"]:::spl
        end
    end

    subgraph "External Dependencies"
        SO["Solders"]:::external
        RPC["Solana JSON RPC Endpoint"]:::external
        WS["Solana WebSocket Endpoint"]:::external
    end

    subgraph "CI/CD & Docs"
        GH["GitHub Actions"]:::ci
        MK["MkDocs Site"]:::ci
        PY["PyPI Release"]:::ci
    end

    SC -->|"calls"| RC
    AC -->|"calls"| RC
    WC -->|"calls"| RC

    RC -->|"uses types"| RT
    RC -->|"uses commitment"| CM

    SC -->|"uses provider"| HP
    SC -->|"uses provider"| BP
    AC -->|"uses provider"| AHP
    AC -->|"uses provider"| ABP
    WC -->|"uses provider"| WP

    HP -->|"connects to"| RPC
    AHP -->|"connects to"| RPC
    WP -->|"connects to"| WS

    CU -->|"provides config to"| SC
    CU -->|"provides config to"| AC
    CU -->|"provides config to"| WC
    VH -->|"provides validation to"| SC
    SM -->|"provides metadata to"| SC

    VI -->|"builds instructions for"| SC
    VP -->|"builds transactions for"| SC

    STC -->|"calls"| RC
    ATC -->|"calls"| RC
    SIB -->|"builds instructions for"| STC
    SIB -->|"builds instructions for"| ATC
    SCR -->|"used by"| STC
    SCT -->|"constants for"| STC
    SL -->|"layouts for"| STC

    MC -->|"constants for"| SC
    MI -->|"instruction builders for"| SC

    SC -->|"depends on"| SO
    AC -->|"depends on"| SO
    WC -->|"depends on"| SO

    GH -->|"runs CI/CD"| SC
    GH -->|"deploys docs"| MK
    GH -->|"publishes package"| PY

    classDef sync fill:#cce5ff,stroke:#4da3ff,color:#004085
    classDef async fill:#d4edda,stroke:#28a745,color:#155724
    classDef ws fill:#fff3cd,stroke:#ffcd39,color:#856404
    classDef core fill:#e2e3e5,stroke:#bfbfbf,color:#383d41
    classDef provider fill:#f8d7da,stroke:#f5c6cb,color:#721c24
    classDef utils fill:#fff5e6,stroke:#ffe4b3,color:#8a6d3b
    classDef builder fill:#e6e6fa,stroke:#d1c4e9,color:#4b0082
    classDef spl fill:#e0f7fa,stroke:#b2ebf2,color:#006064
    classDef external fill:#f1f8e9,stroke:#dcedc8,color:#33691e,stroke-dasharray: 5
    classDef ci fill:#f0f0f0,stroke:#d0d0d0,color:#505050

    click SC "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/api.py"
    click AC "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/async_api.py"
    click WC "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/websocket_api.py"
    click RC "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/core.py"
    click RT "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/types.py"
    click CM "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/commitment.py"
    click BP "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/providers/base.py"
    click ABP "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/providers/async_base.py"
    click CP "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/providers/core.py"
    click HP "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/providers/http.py"
    click AHP "https://github.com/michaelhly/solana-py/blob/master/src/solana/rpc/providers/async_http.py"
    click CU "https://github.com/michaelhly/solana-py/blob/master/src/solana/utils/cluster.py"
    click VH "https://github.com/michaelhly/solana-py/blob/master/src/solana/utils/validate.py"
    click SM "https://github.com/michaelhly/solana-py/blob/master/src/solana/utils/security_txt.py"
    click VI "https://github.com/michaelhly/solana-py/blob/master/src/solana/_layouts/vote_instructions.py"
    click VP "https://github.com/michaelhly/solana-py/blob/master/src/solana/vote_program.py"
    click STC "https://github.com/michaelhly/solana-py/blob/master/src/spl/token/client.py"
    click ATC "https://github.com/michaelhly/solana-py/blob/master/src/spl/token/async_client.py"
    click SIB "https://github.com/michaelhly/solana-py/blob/master/src/spl/token/instructions.py"
    click SCR "https://github.com/michaelhly/solana-py/blob/master/src/spl/token/core.py"
    click SCT "https://github.com/michaelhly/solana-py/blob/master/src/spl/token/constants.py"
    click SL "https://github.com/michaelhly/solana-py/blob/master/src/spl/token/_layouts.py"
    click MC "https://github.com/michaelhly/solana-py/blob/master/src/spl/memo/constants.py"
    click MI "https://github.com/michaelhly/solana-py/blob/master/src/spl/memo/instructions.py"
```
