How madara-alliance/madara works
Based on our analysis of the file tree and README, this project appears to be a large, multi-component blockchain/node system (named “Madara”) that includes several lower-level libraries and clients (written in Rust and Cairo) along with an orchestrator component. In addition, there is a very modularized CI/CD system implemented through GitHub Actions workflows that enables builds, testing, linting, deployments, and integration verifications using custom actions (like load-env and rust-setup).
Main Components
• CI/CD & Workflow Engine: Represent the entire “.github” folder as the CI/CD engine. Break it into:
– Trigger Workflows (e.g. pull-request-main-ci.yml, push workflows)
– Task Workflows (files prefixed with “task-…” that encapsulate specific build or test steps)
– Scheduled Workflows (files prefixed with “schedule-…”)
– Custom Actions (e.g. load-env and rust-setup that set environment variables and configure the Rust toolchain)
• Node and Client Libraries (“madara” directory):
– Core Node: This is the runtime part (located in madara/crates/node) that includes command-line interfaces, block production, and service modules.
• Core Cryptography & Primitives: Display the “primitives” directory, which is further divided (block, class, chain_config, rpc, transactions, oracle, etc.). This layer encapsulates fundamental data formats, hash and crypto utilities, and conversion tools for both Starknet and Ethereum integrations.
• Orchestrator: Show a separate component drawn from the “orchestrator” directory. Outline submodules such as:
– CLI and configuration management that deal with alerts, da-clients (Ethereum and others), databases, queues (SQS, AWS), and proofs.
– Worker processes that handle data submission, proof registration, and state updates.
• Cairo Codebase: Represent the “cairo” directory with its source files, tests, and artifacts. This is likely responsible for on-chain contracts and related tooling in the Starknet ecosystem.
• Infrastructure & Deployment: Include deployment and containerization components:
– Dockerfiles (everywhere from the root Dockerfile to production-specific Dockerfiles in docker/ and infra/)
– Devcontainer configurations and compose files (e.g. compose.yaml) which hint at local development and testing provisions.
– Monitoring dashboards and configuration (Grafana, Prometheus, telegraf, etc. under infra/ and dashboards).
Relationships and Interactions
– The CI/CD engine (GitHub Actions workflows) triggers builds for the madara node, orchestrator, and helper libraries.
– Custom actions and scripts (load-env, rust-setup) provide an interface between configuration (env.yml) and build artifacts.
– The orchestrator communicates with core node libraries via API endpoints (covered by the RPC modules) and may use the clients (DA, Ethereum, etc.) to aggregate data.
– The primitives provide essential functions that are consumed by various client modules.
– External tools (like Docker, Act for local testing, and external Ethereum/Starknet RPC endpoints) integrate into several components.
Architectural Patterns and Technologies
• Separation of Concerns: Clearly label components (for instance, separating out primitives from the network clients and node core) to show clean architectural boundaries.
• GitHub Actions Patterns: Indicate how trigger workflows invoke reusable task workflows, and how environment settings from config files pass into the build and test pipelines.
• Technology Stacks: Label primary languages and frameworks – Rust for most back-end components, Cairo for contract-related code, and JavaScript/TypeScript for testing and some orchestration scripts.