How iotaledger/gas-station works
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