# iotaledger/gas-station architecture

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

- Interactive diagram: https://gitdiagram.com/iotaledger/gas-station
- Repository: https://github.com/iotaledger/gas-station

## Overview

##### Project type and purpose
- This is a Rust-based backend microservice (“IOTA Gas Station”) for sponsoring IOTA transactions at scale.
- It exposes an RPC/HTTP API to reserve and consume “gas coins,” manages a coin pool in Redis, enforces access policies, tracks usage, integrates with an IOTA full node, and supports pluggable key management (local or KMS sidecar).

##### File structure
- Top-level:
- docker/ & docker-compose.yml – Dockerized deployment of Gas Station and Redis
- src/
– main.rs / lib.rs – service entrypoint and public API
– rpc/ – server & client RPC layer (HTTP API on port 9527)
– access_controller/ – policy engine (allow/deny/disable modes)
– gas_station/ – core logic (initializer, usage cap, pool management)
– storage/redis/ – Redis client + Lua scripts for atomic coin ops
– tracker/ – metrics & stats tracking (also backed by Redis)
– config.rs, logging.rs, metrics.rs – configuration, logging, Prometheus metrics
– iota_client.rs – integration with IOTA full node
– tx_signer.rs – key signing (local or via sidecar)
- sample_kms_sidecar/ – TypeScript example of external key manager sidecar
- examples/ – Rust & TypeScript client usage samples
- utils/ – shell helpers for config generation

##### README for additional insights
- Describes Docker setup, API port (9527), metrics port (9184), configuration schema (Redis URL, full-node URL, signer config).
- Points to docs on access-controller policies and KMS integration.
- Emphasizes high-throughput via Redis + Lua, pluggable keys, and Prometheus metrics.

a. Main components
- Gas Station Service (Rust binary)
– RPC/API Layer
– Access Controller
– Gas Station Core (initializer + pool management + usage cap)
– Storage Layer (Redis + Lua scripts)
– Stats Tracker (metrics)
– Signer (local module or external KMS sidecar)
– IOTA Full Node Client
- Redis Server (atomic data store)
- External IOTA Full Node (HTTP API)
- KMS Sidecar (optional HTTP key-signing service)
- Clients (Rust/TS examples)
- Docker Compose (orchestration)
- Prometheus (scrapes metrics port)

b. Relationships & data flow
1. Client → RPC/API Layer (HTTP JSON or gRPC)
2. RPC → Access Controller → Gas Station Core
3. Core → Redis (reserve, split, expire, aggregate via Lua scripts)
4. Core → IOTA Full Node (fetch UTXOs, submit transactions)
5. Core → Signer (local code path or HTTP calls to KMS sidecar)
6. Core/Tracker → Metrics → Prometheus
7. Docker Compose wires Gas Station, Redis, (optional) sidecar

c. Architectural patterns & principles
- Layered modularity: separation of API, policy, core logic, storage, and tracking.
- High‐throughput data store: Redis + Lua for atomic, low-latency operations.
- Pluggable components: key management (local vs. external), access policies.
- Observability: structured logging, Prometheus metrics.
- Containerized deployment with Docker Compose.

d. Key technologies & libraries
- Rust ecosystem: Tokio (async), Warp or tonic for RPC, redis-rs
- Lua scripts for atomic storage operations
- Docker / Docker Compose
- Prometheus exporter (metrics-port 9184)
- IOTA client crate for full node interaction

## Diagram (Mermaid)

```mermaid
flowchart TD
    direction TB

    Clients["Clients (Rust/TS)"]:::client

    subgraph "IOTA Gas Station Service" 
        direction TB
        Entrypoint["Entrypoint\n(src/main.rs)"]:::service
        RPC["RPC/API Layer\n(port 9527)"]:::service
        AC["Access Controller"]:::service
        Core["Gas Station Core"]:::service
        StorageModule["Storage Module\n(Redis + Lua scripts)"]:::service
        TrackerModule["Stats Tracker"]:::service
        SignerModule["Transaction Signer"]:::service
        IotaModule["IOTA Full Node Client"]:::service
        ConfigModule["Config/Logging/Metrics"]:::service

        Entrypoint --> RPC
        Entrypoint --> ConfigModule
        RPC --> AC
        AC --> Core
        Core --> StorageModule
        Core --> IotaModule
        Core --> SignerModule
        Core --> TrackerModule
        TrackerModule --> ConfigModule
    end

    Redis["Redis Database"]:::datastore
    IotaNode["External IOTA Full Node"]:::external
    KMS["KMS Sidecar"]:::sidecar
    Prometheus["Prometheus\n(port 9184)"]:::external
    DockerCompose["Docker Compose"]:::infra
    CLITool["CLI Tool"]:::client

    Clients --> RPC
    CLI["CLI Tool"]:::client
    CLITool --> CLITool

    StorageModule --> Redis
    IotaModule --> IotaNode
    SignerModule --> KMS
    ConfigModule --> Prometheus
    DockerCompose -->|"orchestrates"| Entrypoint
    DockerCompose --> Redis
    DockerCompose --> KMS

    click RPC "https://github.com/iotaledger/gas-station/tree/dev/src/rpc/"
    click AC "https://github.com/iotaledger/gas-station/tree/dev/src/access_controller/"
    click Core "https://github.com/iotaledger/gas-station/tree/dev/src/gas_station/"
    click StorageModule "https://github.com/iotaledger/gas-station/tree/dev/src/storage/redis/"
    click TrackerModule "https://github.com/iotaledger/gas-station/tree/dev/src/tracker/"
    click IotaModule "https://github.com/iotaledger/gas-station/blob/dev/src/iota_client.rs"
    click SignerModule "https://github.com/iotaledger/gas-station/blob/dev/src/tx_signer.rs"
    click Entrypoint "https://github.com/iotaledger/gas-station/blob/dev/src/main.rs"
    click CLITool "https://github.com/iotaledger/gas-station/blob/dev/src/bin/tool.rs"
    click DockerCompose "https://github.com/iotaledger/gas-station/blob/dev/docker/docker-compose.yml"

    classDef service fill:#D6EAF8,stroke:#1F618D
    classDef datastore fill:#FDEBD0,stroke:#D35400
    classDef external fill:#D5F5E3,stroke:#27AE60
    classDef sidecar fill:#ECECEC,stroke:#A6ACAF
    classDef client fill:#F5EEF8,stroke:#8E44AD
    classDef infra fill:#F0F3F4,stroke:#566573
```
