# availproject/avail architecture

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

- Interactive diagram: https://gitdiagram.com/availproject/avail
- Repository: https://github.com/availproject/avail

## Overview

##### Project type and purpose
- This is a Substrate‑based blockchain node implementation (“Avail Node”).
- Purpose: run a full node for the Avail blockchain, exposing JSON‑RPC, consensus (BABE/GRANDPA), runtime rules (pallets), and state storage.

##### File structure
- Top‑level crates:
- node/ : the binary entrypoint (CLI, service, RPC, network, consensus).
- runtime/ : the WebAssembly runtime logic (pallet wiring, weights, transaction filter).
- pallets/ : on‑chain modules (system, vector, dactr, mandate, mocked_runtime).
- client/ : library crates for subsystem utilities (e.g., basic‑authorship).
- base/ : common utilities (metrics, temporary storage, header extension).
- rpc/ : custom RPC extensions (kate‑rpc, testing‑rpc).
- patricia-merkle-trie/ : standalone trie library for proofs.
- e2e/ : end‑to‑end test harness.
- dockerfiles/, scripts/, misc/genesis/ : deployment, CI, dev‑chain assets.
- Config and automation: Cargo.toml, Dockerfile, GitHub workflows under .github/workflows.

##### README for additional insights
- Confirms this is an “official client” for Avail blockchain.
- Describes network roles (authority vs. full), JSON‑RPC server, Prometheus metrics.
- Outlines custom flags (kate‑RPC), supported chains, and Docker usage.
- Mentions benchmarks and external SDKs (avail‑js, avail‑rust, avail‑go).

##### Main components
a. Node Binary (node/):
– CLI interface (node/src/cli.rs)
– Service orchestrator (networking, consensus, RPC registration)
– Consensus workers (BABE authoring, GRANDPA finality)
b. Runtime Engine (runtime/):
– Wasm executor loading compiled runtime
– Runtime APIs (header extension, custom RPC hooks)
– Pallet dispatch (system, balances, vector, dactr, mandate, etc.)
c. On‑chain Modules (pallets/):
– Transaction validation, state transitions, storage schema
d. Storage Layer:
– ParityDB (persistent key‑value store)
– Patricia Merkle Trie (proof generation)
– Temporary in‑memory caches (base/src/mem_tmp_storage.rs)
e. Networking Layer:
– libp2p or Substrate network subsystem (block propagation, gossip)
– RPC server (node/src/rpc.rs) exposing JSON‑RPC on port 9944
– Metrics exporter (Prometheus endpoint on 9615)
f. Clients & Tests:
– e2e harness (e2e/src/) invoking RPCs, block submission
g. Build and Deployment:
– Docker images (dockerfiles/avail-node.Dockerfile)
– CI/CD (GitHub Actions workflows)
– Scripts for chainspec and devnet management

##### Relationships and interactions
- CLI → Node Service
- Node Service ↔ Network subsystem (peer discovery, block/extrinsic gossip)
- Node Service → Consensus workers → Runtime Engine
- Runtime Engine → Pallets → Storage Layer
- Node Service ←→ RPC Layer → External Clients / SDKs / e2e tests
- Node Service → Metrics exporter → Prometheus
- Build/CI pipelines → Docker image → Node container

##### Architectural patterns and design principles
- Modular Runtime: pallets plugged into a Wasm runtime.
- Service‑oriented: clear separation of concerns (network, consensus, RPC, state).
- Pluggable RPC: kate‑RPC and testing RPC layered on top of core JSON‑RPC.
- Layered storage: in‑memory buffers, ParityDB, Merkle proofs.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client & Tests
    subgraph "Client & Tests"
        SDKJS(("avail-js")):::external
        SDKGO(("avail-go")):::external
        E2EMain["E2E Runner"]:::external
    end

    %% Node Binary layer
    subgraph "Node Binary (node/)"
        CLI["CLI Interface"]:::backend
        Service["Node Service"]:::backend
        Network["Network Subsystem"]:::network
        Consensus["Consensus Workers"]:::backend
        RPCServer["RPC Server (9944/TCP)"]:::network
        Metrics["Metrics Exporter (9615)"]:::network
    end

    %% Runtime Engine layer
    subgraph "Runtime Engine (runtime/)"
        Wasm["Wasm Executor"]:::runtime
        RuntimeLib["Runtime Definition"]:::runtime
        APIs["Runtime APIs"]:::runtime
        TxFilter["Transaction Filter"]:::runtime
        KateMod["Kate Commitments"]:::runtime
    end

    %% Pallets layer
    subgraph "On-chain Modules (pallets/)"
        SysPal["System Pallet"]:::pallet
        VecPal["Vector Pallet"]:::pallet
        DactrPal["DACTR Pallet"]:::pallet
        MandPal["Mandate Pallet"]:::pallet
        MockPal["Mocked Runtime Pallet"]:::pallet
    end

    %% Storage layer
    subgraph "Storage Layer"
        InMem["In-Memory Temp Storage"]:::storage
        Parity["ParityDB"]:::storage
        Merkle["Merkle Trie"]:::storage
    end

    %% RPC Extensions
    subgraph "RPC Extensions (rpc/)"
        KateRPC["Kate-RPC"]:::network
        TestRPC["Testing-RPC"]:::network
    end

    %% Build & Deployment
    subgraph "Build & Deployment"
        Docker["Docker Image"]:::ci
        CI["GitHub Workflows"]:::ci
        Chainspec["Chainspec Scripts"]:::ci
        Genesis["Genesis Assets"]:::ci
    end

    %% Interactions
    CLI -->|invokes| Service
    Service -->|manages| Network
    Service -->|spawns| Consensus
    Service -->|registers| RPCServer
    Service -->|exports| Metrics
    Service -->|executes| Wasm
    Consensus -->|uses| Wasm
    Wasm -->|loads| RuntimeLib
    RuntimeLib -->|calls| APIs
    RuntimeLib -->|applies| TxFilter
    RuntimeLib -->|includes| KateMod
    Wasm -->|dispatches| SysPal
    Wasm -->|dispatches| VecPal
    Wasm -->|dispatches| DactrPal
    Wasm -->|dispatches| MandPal
    Wasm -->|dispatches| MockPal
    SysPal -->|reads/writes| InMem
    VecPal -->|reads/writes| Parity
    DactrPal -->|reads/writes| Parity
    MandPal -->|reads/writes| Parity
    MockPal -->|reads/writes| Parity
    Parity -->|proofs| Merkle
    RPCServer -->|extends| KateRPC
    RPCServer -->|extends| TestRPC
    RPCServer -->|services| Service
    SDKJS -->|calls| RPCServer
    SDKGO -->|calls| RPCServer
    E2EMain -->|tests via RPC| RPCServer
    CI -->|builds| Docker
    CI -->|runs| Chainspec
    CI -->|deploys| Genesis
    Docker -->|runs container| Service

    %% Click Events
    click CLI "https://github.com/availproject/avail/blob/main/node/src/cli.rs"
    click Service "https://github.com/availproject/avail/blob/main/node/src/service.rs"
    click RPCServer "https://github.com/availproject/avail/blob/main/node/src/rpc.rs"
    click RuntimeLib "https://github.com/availproject/avail/blob/main/runtime/src/lib.rs"
    click APIs "https://github.com/availproject/avail/blob/main/runtime/src/apis.rs"
    click TxFilter "https://github.com/availproject/avail/blob/main/runtime/src/transaction_filter.rs"
    click KateMod "https://github.com/availproject/avail/tree/main/runtime/src/kate/"
    click SysPal "https://github.com/availproject/avail/blob/main/pallets/system/src/lib.rs"
    click VecPal "https://github.com/availproject/avail/blob/main/pallets/vector/src/lib.rs"
    click DactrPal "https://github.com/availproject/avail/blob/main/pallets/dactr/src/lib.rs"
    click MandPal "https://github.com/availproject/avail/blob/main/pallets/mandate/src/lib.rs"
    click MockPal "https://github.com/availproject/avail/blob/main/pallets/mocked_runtime/src/lib.rs"
    click InMem "https://github.com/availproject/avail/blob/main/base/src/mem_tmp_storage.rs"
    click Parity "https://github.com/availproject/avail/blob/main/patricia-merkle-trie/src/lib.rs"
    click Merkle "https://github.com/availproject/avail/blob/main/base/src/header_extension/mod.rs"
    click KateRPC "https://github.com/availproject/avail/blob/main/rpc/kate-rpc/src/lib.rs"
    click TestRPC "https://github.com/availproject/avail/blob/main/rpc/testing-rpc/src/lib.rs"
    click Docker "https://github.com/availproject/avail/blob/main/dockerfiles/avail-node.Dockerfile"
    click CI "https://github.com/availproject/avail/tree/main/.github/workflows/"
    click Chainspec "https://github.com/availproject/avail/tree/main/scripts/chainspec/"
    click Genesis "https://github.com/availproject/avail/tree/main/misc/genesis/"

    %% Styles
    classDef backend fill:#f9f,stroke:#333,stroke-width:1px
    classDef runtime fill:#bbf,stroke:#333,stroke-width:1px
    classDef pallet fill:#bfb,stroke:#333,stroke-width:1px
    classDef storage fill:#ffb,stroke:#333,stroke-width:1px
    classDef network fill:#fbf,stroke:#333,stroke-width:1px
    classDef external fill:#ffc,stroke:#333,stroke-width:1px
    classDef ci fill:#cdf,stroke:#333,stroke-width:1px
```
