# helium/helium-program-library architecture

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

- Interactive diagram: https://gitdiagram.com/helium/helium-program-library
- Repository: https://github.com/helium/helium-program-library

## Overview

This project is a comprehensive suite of Solana programs and related services that integrate with Helium’s ecosystem. It spans on‐chain programs (written in Rust and managed via Anchor), off‐chain services (written in TypeScript/JavaScript, using Yarn workspaces and Node-based tooling), as well as CI/CD and deployment configurations. In short, it is a full-stack blockchain integration system that manages proprietary Helium assets such as hotspots, data credits, reward distribution, and on-chain governance, all integrated with Solana.

##### Main Components
- On‐chain Programs: The “programs” directory contains many Rust/Anchor programs such as:
– Helium Sub Daos (reward and governance management)
– Data Credits (burn mechanism and oracle reading)
– Helium Entity Manager (hotspot and entity issuance)
– Lazy Distributor (oracle-powered token distribution)
– Other specialized programs (circuit-breaker, fanout, lazy-distributor, price oracle, rewards oracle, treasury management, voter-stake registry, etc.)
- Utility & CLI Tools: The “utils” folder holds scripts and tools for tasks such as migrations, signature validations (e.g. ecc-sig-verifier), and bulk operations.
- CI/CD and Deployment Pipelines: The “.github” directory includes GitHub Actions and workflows which are essential for building, testing, deployment, and releases.

##### Relationships & Interactions
- On-Chain Interactions:
– Many programs interact directly via instructions. For example, the Helium Entity Manager calls into Helium Sub Daos when issuing hotspots, while the Data Credits program interacts with the Helium Sub Daos to burn credits.
– The Lazy Distributor receives oracle inputs (via GET/POST flows) and then drives token distribution transactions on Solana.
– Interactions between programs (e.g., between treasury management, voter-stake registry, and lazy distributor) are crucial.
- Off-Chain to On-Chain:
– Services (like distributor-oracle and monitor-service) and web applications (like the wallet app, admin CLI, and docsite) integrate with the on-chain programs.
– The client-side components (for example, Helium React Hooks SDK) abstract access to these on-chain instructions.
- External Services & Infrastructure:
– There is integration with external systems like S3, Oracle RDS, and possibly other external data sources.
– The CI/CD pipelines also interact with Docker, localnet setups, and deployment scripts.

##### Architectural Patterns
- Modular/Microservice Architecture: Each program and package represents an independent module or microservice with its own responsibility.
- Client-Server and SDK Layers: The off-chain packages are designed to serve as client libraries and servers that coordinate with the on-chain programs.
- Event-Driven and Decoupled Services: Oracle designs, asynchronous job queues (e.g., in the “crons” package), and utility scripts show design principles for eventual consistency and decoupled deployment.
- CI/CD Automation: Extensive GitHub workflows and deployment scripts show an automated build, test, and deploy cycle.

##### Relevant Technologies & Frameworks
- Solana and Anchor for smart contract development.
- Rust for on-chain program implementations.
- TypeScript/JavaScript for off-chain services and front-end components.
- Docker and Docker Compose (see “migration-docker”, “monitor-service/docker-compose”) for containerized deployments.
- Yarn Workspaces for package management.
- GitHub Actions for CI/CD workflows.

## Diagram (Mermaid)

```mermaid
graph TD
    %% On-chain Programs
    subgraph "On-chain Programs"
        HSD("Helium Sub Daos"):::onchain
        DC("Data Credits"):::onchain
        HEM("Helium Entity Manager"):::onchain
        LD("Lazy Distributor"):::onchain
        CB("Circuit Breaker"):::onchain
        FO("Fanout"):::onchain
        PO("Price Oracle"):::onchain
        RO("Rewards Oracle"):::onchain
        TM("Treasury Management"):::onchain
        VSR("Voter Stake Registry"):::onchain
    end

    %% Off-chain Services & Packages
    subgraph "Off-chain Services & Packages"
        FS("Faucet Service"):::offchain
        MS("Monitor Service"):::offchain
        DO("Distributor Oracle"):::offchain

        DCS("Data Credits SDK"):::offchain
        HEMSdk("Helium Entity Manager SDK"):::offchain
        HRH("Helium React Hooks"):::offchain
        HSDsdk("Helium Sub Daos SDK"):::offchain
        LDD("Lazy Distributor SDK"):::offchain
        LTD("Lazy Transactions SDK"):::offchain
        POS("Price Oracle SDK"):::offchain
        ROSdk("Rewards Oracle SDK"):::offchain
        TMSdk("Treasury Management SDK"):::offchain
        VRSdk("Voter Stake Registry SDK"):::offchain
        SU("SPL Utils"):::offchain
        HBS("Hexboosting SDK"):::offchain
        CBSdk("Circuit Breaker SDK"):::offchain
    end

    %% Utility & CLI Tools
    subgraph "Utility & CLI Tools"
        HAC("Helium Admin CLI"):::utility
        UT("Utils"):::utility
    end

    %% CI/CD & Deployment Pipelines
    subgraph "CI/CD & Deployment"
        GHA("GitHub Actions"):::cicd
        GHW("GitHub Workflows"):::cicd
        MD("Migration Docker"):::cicd
    end

    %% Documentation
    subgraph "Documentation"
        DIAG("Diagrams"):::doc
        RMD("README.md"):::doc
    end

    %% External / Blockchain Layer
    subgraph "External / Blockchain"
        SA("Solana Blockchain"):::external
        EXTS("External Services"):::external
    end

    %% On-chain interactions
    HEM -->|"calls"| HSD
    DC -->|"burnsCredits"| HSD
    DO -->|"oracleInput"| LD
    LDD -->|"triggers"| LD
    LTD -->|"initiatesTx"| LD
    CBSdk -->|"interfaces"| CB

    %% SDKs interacting with corresponding on-chain programs
    DCS -->|"queries"| DC
    HEMSdk -->|"manages"| HEM
    HSDsdk -->|"controls"| HSD
    POS -->|"queries"| PO
    ROSdk -->|"queries"| RO
    TMSdk -->|"manages"| TM
    VRSdk -->|"interacts"| VSR

    %% Off-chain Service interactions
    FS -->|"funds"| HEM
    MS -->|"monitors"| HEM

    %% External integrations and blockchain execution
    HRH -->|"accesses"| SA
    SA -->|"executes"| HEM
    SA -->|"executes"| DC
    SA -->|"executes"| HSD
    SA -->|"executes"| LD
    SA -->|"executes"| CB
    SA -->|"executes"| FO
    SA -->|"executes"| PO
    SA -->|"executes"| RO
    SA -->|"executes"| TM
    SA -->|"executes"| VSR
    EXTS -->|"feedsData"| HSD
    EXTS -->|"feedsData"| DC
    EXTS -->|"feedsData"| TM

    %% CI/CD interactions
    GHA -->|"automates"| HEM
    GHA -->|"builds"| DC
    GHA -->|"tests"| LD
    GHW -->|"deploys"| HSD
    MD -->|"deploys"| HEM

    %% Utility & CLI Tools interactions
    HAC -->|"administers"| UT
    HAC -->|"controls"| HEM
    HAC -->|"interfaces"| HSD

    %% Class definitions for colouring
    classDef onchain fill:#FAD7A0,stroke:#333,stroke-width:2px;
    classDef offchain fill:#CFF0FF,stroke:#333,stroke-width:2px;
    classDef utility fill:#FFDAB9,stroke:#333,stroke-width:2px;
    classDef cicd fill:#D5F5E3,stroke:#333,stroke-width:2px;
    classDef doc fill:#E8DAEF,stroke:#333,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#333,stroke-width:2px;

    %% Click Events for On-chain Programs
    click HSD "https://github.com/helium/helium-program-library/tree/master/programs/helium-sub-daos"
    click DC "https://github.com/helium/helium-program-library/tree/master/programs/data-credits"
    click HEM "https://github.com/helium/helium-program-library/tree/master/programs/helium-entity-manager"
    click LD "https://github.com/helium/helium-program-library/tree/master/programs/lazy-distributor"
    click CB "https://github.com/helium/helium-program-library/tree/master/programs/circuit-breaker"
    click FO "https://github.com/helium/helium-program-library/tree/master/programs/fanout"
    click PO "https://github.com/helium/helium-program-library/tree/master/programs/price-oracle"
    click RO "https://github.com/helium/helium-program-library/tree/master/programs/rewards-oracle"
    click TM "https://github.com/helium/helium-program-library/tree/master/programs/treasury-management"
    click VSR "https://github.com/helium/helium-program-library/tree/master/programs/voter-stake-registry"

    %% Click Events for Off-chain Services & Packages
    click FS "https://github.com/helium/helium-program-library/tree/master/packages/faucet-service"
    click MS "https://github.com/helium/helium-program-library/tree/master/packages/monitor-service"
    click DO "https://github.com/helium/helium-program-library/tree/master/packages/distributor-oracle"
    click DCS "https://github.com/helium/helium-program-library/tree/master/packages/data-credits-sdk"
    click HEMSdk "https://github.com/helium/helium-program-library/tree/master/packages/helium-entity-manager-sdk"
    click HRH "https://github.com/helium/helium-program-library/tree/master/packages/helium-react-hooks"
    click HSDsdk "https://github.com/helium/helium-program-library/tree/master/packages/helium-sub-daos-sdk"
    click LDD "https://github.com/helium/helium-program-library/tree/master/packages/lazy-distributor-sdk"
    click LTD "https://github.com/helium/helium-program-library/tree/master/packages/lazy-transactions-sdk"
    click POS "https://github.com/helium/helium-program-library/tree/master/packages/price-oracle-sdk"
    click ROSdk "https://github.com/helium/helium-program-library/tree/master/packages/rewards-oracle-sdk"
    click TMSdk "https://github.com/helium/helium-program-library/tree/master/packages/treasury-management-sdk"
    click VRSdk "https://github.com/helium/helium-program-library/tree/master/packages/voter-stake-registry-sdk"
    click SU "https://github.com/helium/helium-program-library/tree/master/packages/spl-utils"
    click HBS "https://github.com/helium/helium-program-library/tree/master/packages/hexboosting-sdk"
    click CBSdk "https://github.com/helium/helium-program-library/tree/master/packages/circuit-breaker-sdk"

    %% Click Events for Utility & CLI Tools
    click HAC "https://github.com/helium/helium-program-library/tree/master/packages/helium-admin-cli"
    click UT "https://github.com/helium/helium-program-library/tree/master/utils/"

    %% Click Events for CI/CD & Deployment Pipelines
    click GHA "https://github.com/helium/helium-program-library/tree/master/.github/actions"
    click GHW "https://github.com/helium/helium-program-library/tree/master/.github/workflows"
    click MD "https://github.com/helium/helium-program-library/tree/master/migration-docker"

    %% Click Events for Documentation
    click DIAG "https://github.com/helium/helium-program-library/tree/master/diagrams"
    click RMD "https://github.com/helium/helium-program-library/blob/master/README.md"
```
