Madara: a modular Starknet app chain stack on Substrate

What Madara is and where it sits

Madara is the modular stack to build chains using Cairo and the Starknet technology, and the readme frames the ambition directly.

Apps like dYdX V3, Immutable and Sorare have been using StarkEx for scaling for a while, and now with Madara it's open source for everyone to use. The project description calls it a modular stack to build Starknet based scaling engines written in Rust.

So the lineage is clear. StarkEx is the closed-source system those applications used, and Madara is an open implementation of the same idea, built on the open substrate framework instead of a proprietary one.

The choice of Substrate is the load-bearing decision. Madara is built on the Substrate framework which not only makes it modular but also gives it access to years of dev tooling, libraries and a strong developer community. And the readme is explicit about who this is for: it is specifically helpful if you want to own more of the stack and get more control over your chain.

That last sentence is the honest framing. A general purpose Starknet node already exists and is easier to run. Madara is for the case where the chain's own parameters, its data availability, its block production or its runtime logic need to be under your own control, and where operating a fork is acceptable.

The project is Rust and MIT licensed, with the last push on 2026-10-18 and the recent releases being weekly builds, weekly-2026-10-18, weekly-2026-10-11 and weekly-2026-10-04. The cadence tells you something useful about how the project is run: automated weekly snapshots rather than hand-cut version releases.

It is worth noting the repository topics, which include archived, deprecated and obsolete alongside the technical ones such as cairo, ethereum, starknet, starknet-appchain, starknet-stack and substrate. The weekly build tags continue to land despite those labels, so the topic list and the release history disagree, and anyone evaluating the project would be better served by checking the current state of the repository than by either signal alone.

The four things Madara provides

The readme lists what the stack gives you by default, and the four items are the components a Starknet chain actually needs.

pallet_starknet adds the CairoVM to Substrate, which allows you to deploy and execute Cairo contracts. This is the core of it. Rather than writing a Cairo interpreter and integrating it with a consensus engine, the stack packages it as a Substrate pallet, which means it inherits the runtime model, the benchmarking machinery and the ecosystem around it.

Starknet RPC adds all the Starknet RPC calls to your chain so that it's compatible with all RPC tools like starknet-js, wallets, etc. This is the piece that decides whether existing tooling works against your chain. If the RPC surface matches, wallets and block explorers and indexers work without modification, and if it does not, every one of those has to be adapted.

DA Interface is a general interface which allows you to use any DA layer like Avail, Celestia, Ethereum etc. That is what makes the stack modular in the data availability dimension rather than only in the runtime one. Your chain posts its data somewhere, and the interface abstracts where.

Proving runs the Starknet OS, which is the runtime logic in Cairo so that it can be proven on the L1. This is the step that ties the chain back to Ethereum, because the validity of the state transition is checked there.

Put together, those four cover execution, interoperability, data availability and settlement. That is the complete set of concerns for a rollup-style chain, and the modularity is in each one being replaceable.

The documentation set maps onto that structure, with a Getting Started Guide, an Architecture Overview, a Chain Genesis Information document, a Project Structure document and a benchmarking README for running the benchmark yourself.

Fork or import, and how the decision is framed

The readme is unusually direct about the choice between forking and composing, and that guidance is the most useful operational content in the document.

For many use cases you do not need to fork this repo to build your app chain. By adding changes using forking, you will have to periodically rebase and solve conflicts to remain updated with the latest version of Madara. Madara by default provides the four components described above.

The readme then separates the changes into two lists, and the distinction is a sensible engineering rule rather than a rule of thumb.

For many use cases where you want to change common things like configuration parameters for example block time and maximum steps, the DA layer, genesis state, new off chain workers, and new pallets, you don't need to fork the Madara repo. Instead, you can import the relevant code as crates/pallets. The readme points at an app-chain-template repository which imports Madara as a library to show an example and says it would recommend you start from there.

For more detailed use cases like adding a new syscall to the Cairo VM, or changing the runtime logic to deviate from Starknet's logic, you should consider forking parts of Madara.

So the dividing line is between configuration and semantics. If you are changing what the chain does, parameters, where the data goes, what is in genesis, what workers exist, which pallets exist, you compose. If you are changing what the chain can do at the machine level, a new Cairo syscall or different runtime semantics, you fork.

That distinction has a direct operational consequence. Composed chains pull the upstream code as a library dependency and take updates when they choose to, with the usual recompilation work. Forked chains have to rebase periodically and resolve conflicts by hand, which is the recurring cost the readme is warning about, and it is the reason the project publishes an app-chain-template as the recommended starting point.

The peripheral repositories section completes the picture, with a docs site repository, an open source block explorer for Starknet based chains from the LambdaClass team, and a Madara Infra repository collecting scripts and tools to deploy and manage Madara across different environments such as AWS, Docker and Ansible.

The Rust workspace and the container image

The repository is a Cargo workspace and the shape of the crate list is the clearest description of the architecture available.

There is crates/node and crates/runtime, then crates/pallets/starknet and crates/pallets/starknet/runtime_api, which is the pallet and its runtime API surface. Then a primitives directory broken into small focused crates: genesis-config, digest-log, snos-output, transactions, felt, hashers, block, starknet-inherent, storage, chain-id, messages and program-hash. That granularity is what lets a chain import only the pieces it needs.

The client directory is similarly split, with crates for genesis-data-provider, db, rpc-core, rpc, mapping-sync, storage, commitment-state-diff, eth-client and starknet-block-import. The separation of rpc-core from rpc, and the presence of a separate eth-client crate, are the two that tell you something. rpc-core being separate means the RPC types can be consumed without pulling in the server, and an eth-client in a Starknet stack is the component that talks to L1.

There are also workspace members for the test infrastructure, starknet-rpc-test, madara-test-runner and starknet-test-utils, and the Cargo.toml carries a comment explaining why they are handled the way they are: all previous except for starknet-rpc-test, and we don't want cargo test to trigger its tests. So default-members excludes the RPC test crate, because that test needs a running node and would otherwise break a plain cargo test run.

The Dockerfile is a two-stage build. The builder is rust:slim-buster and it installs the toolchain a Substrate node needs, including libssl-dev, clang, g++, llvm, protobuf-compiler, libprotobuf-dev, pkg-config, libz-dev, zstd, git and build-essential. The protobuf packages are there because Substrate's networking and state code uses protobuf for the wire format.

The final image is debian:buster-slim with the release binary copied in, curl and ca-certificates installed, and a healthcheck that runs every ten seconds against the JSON-RPC port, posting a starknet_chainId request:

EXPOSE 9944 9615 30333
ENTRYPOINT ["/madara-bin"]

The exposed ports are labelled in the Dockerfile: 9944 is the JSON-RPC server, 9615 is the Prometheus exporter and 30333 is for P2P communication. The healthcheck using the chain id call rather than a simple TCP check is a sensible choice, since it confirms the node is actually answering RPC rather than merely listening.

The build is cargo build --release, and there is a rust-toolchain.toml pinning the compiler, plus a rustfmt.toml, a flake.nix and a Dockerfile, so the toolchain is pinned in several ways depending on how you build.

The tooling around the stack

The repository layout shows a project that has put real effort into the things around the sequencer itself, and for a chain platform that support tooling is often the difference between a framework and a codebase.

The top level contains a mix of build, test and documentation infrastructure. There is a Cargo.lock and a Cargo.toml for the workspace, a rust-toolchain.toml pinning the compiler and a rustfmt.toml for formatting, a package.json with prettier as its only dev dependency and a .prettierrc.json, and a .markdownlint.json for the documentation. The presence of both a Rust and a JavaScript formatting setup is a small signal that the repository spans documentation written in more than one place.

Then there is the Cairo side. The cairo-contracts/ directory holds the contracts, and the scripts/ directory holds the build helpers, with a taplo/ directory for TOML formatting and an autodoc.config.json for the API documentation generation that the Rust doc badge points at. There is a docs/ directory with the documentation the readme links, and a docs/images/logo/PNGs directory for the assets the readme uses.

The test infrastructure is worth calling out because it is the part that determines whether the stack is usable. There is a madara-test-runner/ directory, a starknet-rpc-test/ directory and a starknet-test-utils/ directory, and the examples/ directory holds a messaging example and an rpc example. The Cargo.toml comment about default-members excluding starknet-rpc-test, with the reason that we don't want cargo test to trigger its tests, tells you the RPC tests need something running, and that the workspace is arranged so a plain cargo test still works.

There is also a .devcontainer/ directory and a .envrc, so a contributor can get a working environment without assembling one, and a Dockerfile for the container image. A flake.nix and flake.lock sit alongside, which is the fourth build path in the repository, alongside Cargo, Docker and the devcontainer.

The readme badges point at most of this. There is a badge for the contributor starter pack, a documentation website badge for docs.madara.zone, a Rust doc badge, a benchmark performance badge pointing at the benchmark results site, and badges for the community calls on YouTube and the Exploration Team. The benchmark badge in particular is the one to watch, because for a sequencer the numbers are the argument, and a project that publishes them automatically has a mechanism to notice a regression.

Editorial conclusion

Adopt Madara if you want to run a Starknet app chain and would rather compose the chain than fork a sequencer, since the pallet and RPC layers are importable as crates. Do not adopt it if you need to change CairoVM syscalls or deviate from Starknet's runtime logic, because those cases require forking parts of the stack. Before you commit, note that the repository's own topics still carry archived and deprecated labels while weekly builds continue to land, so check the project state rather than assuming either way.

Frequently asked questions

Official sources

1. AbdelStark/madara on GitHub
2. Issues
3. License: MIT
4. README
5. Releases