# paritytech/subxt architecture

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

- Interactive diagram: https://gitdiagram.com/paritytech/subxt
- Repository: https://github.com/paritytech/subxt

## Overview

Based on our review, this repository is the Subxt project—a multi-crate Rust workspace whose purpose is to provide a robust library (and accompanying tools) for interfacing with Substrate-based blockchain nodes. Its components include both static and dynamic interfaces, a CLI tool for metadata retrieval and extrinsic submission, internal libraries for code generation and runtime API handling, as well as dedicated modules for signing, interacting with RPCs, and even a built‐in light client.

##### Main Components
- Subxt Library Core: This works as the primary interface for external users. It provides safe APIs for submitting extrinsics, reading storage and events, and interacting with runtime APIs.
- CLI Tool (cli): A command-line front end that lets users download metadata, run commands, and interact with nodes.
- Code Generation (codegen): Generates API code based on the runtime metadata so that users can interact with blockchain elements in a statically typed way.
- Core Module (core): Contains central abstractions for extrinsics, blocks, runtime API calls, storage interactions, configuration, and more.
- RPC and Networking Layers (rpcs): Implements low-level JSON-RPC clients (including reconnecting and light client implementations) for communicating with Substrate nodes.
- Signer Module (signer): Handles cryptographic functions, signing payloads, and ensuring protocol-accurate message formation.
- Metadata Handlers (metadata): Deals with decoding, validating, and mapping runtime metadata to the internal types.
- Light Client (lightclient): Provides a WASM-based client able to interact with the chain in low-resource or browser environments.
- Supporting Utilities and Macros (macro, utils, etc.): Contains helper functions, macros for common tasks, error handling, testing infrastructures, and custom value management.
- Testing and Examples: The repository includes extensive integration, UI, and no-std tests along with example applications (like parachain and WASM examples) to showcase usage.

##### Relationships and Interactions
- The CLI tool (cli) integrates with the core library to allow operations such as metadata fetching and extrinsic submission.
- The core library relies on codegen and metadata modules to provide strongly typed (and optionally dynamic) interfaces to the blockchain’s runtime.
- The RPC modules (rpcs) provide the communication layer between the client (either through the CLI or library interfaces) and the actual Substrate node.
- The signer module works in tandem with the core when signing transactions or payloads before submission.
- The lightclient can be called upon for environments or testing scenarios where a full node isn’t available.
- Testing directories are external to these components but interact with almost every module to verify ABI compatibility and runtime behavior.
- The tooling for building, publishing, and continuous integration (e.g., GitHub workflows and scripts) supports the overall lifecycle of the project.

##### Architectural Patterns and Design Principles
- Modularity: The project is split into multiple Rust crates, each responsible for a distinct domain (CLI, core functionality, metadata management, signing, etc.).
- Separation of Concerns: The clear boundaries between codegen, core, networking, and signing indicate an architecture that isolates functionality for clarity, testing, and reuse.
- Abstraction Layers: There is a well-defined boundary between low-level RPC communication and higher-level business logic.
- Flexibility & Extensibility: Offering both static and dynamic API interfaces shows attention to varying user needs, from safety via Rust’s type system to flexibility when required.
- Testing & Validation: The comprehensive integration and UI tests emphasize design correctness and backward compatibility.

##### Technologies and Libraries
- Main Language: Rust, utilizing Cargo for dependency and workspace management.
- Blockchain Connectivity: Adapters and low-level JSON-RPC (possibly using libraries like jsonrpsee).
- WebAssembly: For browser-based clients, as seen in the WASM examples and lightclient implementations.
- Cryptography: For signing (ECDSA, sr25519, etc.) in the signer module.
- CI/CD Pipelines: GitHub workflows for building, nightly tests, artifact updates, and dependabot validation.

- Use a layered approach: show a “User Layer” (CLI/Examples), an “Application Core” layer (subxt, core, codegen, metadata, signer), and an “Infrastructure” layer (RPC, lightclient, external blockchain node).
- That design patterns (such as separation of concerns and modularity) are clearly annotated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        CLI["CLI Tool"]:::user
        Examples["Examples"]:::user
        Tests["Tests"]:::user
    end

    %% Application Core Layer
    subgraph "Application Core"
        Subxt["Subxt Library Core"]:::core
        Core["Core Module"]:::core
        Codegen["Code Generation"]:::core
        Metadata["Metadata Handlers"]:::core
        Signer["Signer Module"]:::core
        Macros["Macros"]:::core
        Utilities["Utilities"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        RPC["RPC and Networking Layers"]:::infra
        LightClient["Light Client"]:::infra
        Substrate["Substrate Node"]:::external
    end

    %% Connections from User Layer to Application Core
    CLI -->|"invokes"| Subxt
    Examples -->|"tests"| Subxt
    Tests -->|"verifies"| Subxt

    %% Connections within Application Core
    Subxt -->|"uses"| Core
    Subxt -->|"depends_on"| Macros
    Subxt -->|"depends_on"| Utilities
    Core -->|"integrates"| Codegen
    Core -->|"integrates"| Metadata
    Core -->|"utilizes"| Signer
    Core -->|"routes_to"| RPC

    %% Connections from Application Core to Infrastructure
    Subxt -->|"optionally_uses"| LightClient
    RPC -->|"communicates_with"| Substrate

    %% Click events
    click Subxt "https://github.com/paritytech/subxt/blob/master/subxt/src/lib.rs"
    click CLI "https://github.com/paritytech/subxt/blob/master/cli/src/main.rs"
    click Codegen "https://github.com/paritytech/subxt/blob/master/codegen/src/lib.rs"
    click Core "https://github.com/paritytech/subxt/blob/master/core/src/lib.rs"
    click RPC "https://github.com/paritytech/subxt/blob/master/rpcs/src/lib.rs"
    click Signer "https://github.com/paritytech/subxt/blob/master/signer/src/lib.rs"
    click Metadata "https://github.com/paritytech/subxt/blob/master/metadata/src/lib.rs"
    click LightClient "https://github.com/paritytech/subxt/blob/master/lightclient/src/lib.rs"
    click Macros "https://github.com/paritytech/subxt/blob/master/macro/src/lib.rs"
    click Utilities "https://github.com/paritytech/subxt/blob/master/utils/fetch-metadata/src/lib.rs"
    click Examples "https://github.com/paritytech/subxt/blob/master/examples/README.md"
    click Tests "https://github.com/paritytech/subxt/tree/master/testing/integration-tests/"

    %% Styles
    classDef user fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef core fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef infra fill:#ffdab9,stroke:#333,stroke-width:2px;
    classDef external fill:#e6e6e6,stroke:#333,stroke-width:2px;
```
