How astraly-labs/pragma-common works
Project type and purpose
• This is a Rust “common” library crate (“Pragma Common”) that provides shared data types, helpers, and service-level abstractions for other Pragma Rust libraries. It is not a standalone service or executable but a collection of modules for on-chain data handling (Ethereum, Starknet), telemetry, and Protobuf-based definitions.
File structure
Top-level items:
• Cargo.toml / build.rs – defines crate metadata, dependencies, and invokes Protobuf code-gen
• schema/entries.proto – Protobuf definitions for various “entry” types
• src/
– aggregation.rs – aggregation utilities
– entries/… – entry types: price, volume, orderbook, open_interest, funding_rate
– pair/… – trading pair helpers
– instrument_type.rs, interval.rs – enums for instruments & time intervals
– services.rs – core service abstractions (e.g., fetching, processing entries)
– web3/… – Ethereum client wrappers
– starknet/… – Starknet client wrappers, typed data, network errors
– telemetry/… – metrics & tracing instrumentation
– task_group.rs – task orchestration helpers
• tests/ – unit tests for Protobuf and service modules
• .github/, Makefile, taplo/ – CI, build scripts, formatting
Key insights from README
• “Common utilities and types used in Pragma rust libraries” – confirms that this crate is a shared module set. No runtime “system” of its own; its value lies in the modules it exposes and how they interconnect.
a. Main components to show
• Protobuf Schema & Code Generator (build.rs)
• Core Domain Types (entries, pair, instrument_type, interval)
• Service Layer (services.rs, aggregation.rs)
• Blockchain Clients:
– Ethereum/Web3 module
– Starknet module
• Telemetry Module
• Task Orchestrator (task_group)
• Consumers (downstream Pragma applications or other crates)
b. Relationships & interactions
– Protobuf schema → build.rs → generated entry types → core domain types
– Service Layer invokes blockchain clients (web3, starknet) to fetch on-chain data
– Service Layer emits metrics/traces via Telemetry Module
– Task Orchestrator coordinates asynchronous calls through the Service Layer
– Downstream crates import public APIs from this library
c. Architectural patterns & design principles
– Modular separation: domain types vs. service logic vs. infra clients vs. telemetry
– Dependency inversion: service layer depends on abstract traits of web3/starknet clients
– Code-gen boundary: Protobuf definitions isolated from hand-written code
– Single Responsibility: each module has a clear focus
d. Key technologies and libraries
– Rust (Cargo, build.rs)
– Protocol Buffers (schema/entries.proto)
– Async HTTP/JSON-RPC (web3 module)
– Starknet Typed Data & network errors
– OpenTelemetry or metrics crates (telemetry module)