Madara Documentation

Madara is a high-performance Starknet sequencer designed to enable the creation of customized, high-throughput App Chains (L3s). By building an App Chain instead of deploying directly to Starknet (L2), developers can achieve:

• Increased Throughput & Lower Costs: Dedicated resources prevent competition with other applications, potentially reducing costs by up to a million times from L1 to L3.
• Customization: Developers can fine-tune infrastructure, such as choosing specific hash functions, consensus algorithms, or even excluding certain Cairo VM features.
• Innovation: Enables experimental features like on-chain KYC without compromising privacy or using risky functions on a general-purpose chain.

Madara leverages the Substrate framework to provide this modularity while integrating the Cairo VM to ensure all executions are provable and secure, inheriting the security of the underlying Starknet L2.

The genesis of a Madara chain is defined in a JSON file. This file specifies the initial state of the chain, including deployed code, contract instances, and initial storage values. The JSON structure consists of three primary components:

1. contract_classes: A list of tuples containing the class hash and the class definition. The class can be provided in two ways:
   • Path Reference: An object with a path (relative to the repository root) and a version (0 or 1) indicating the Cairo version. Example: { "path": "cairo-contracts/NoValidateAccount.json", "version": 0 }.
   • Serialized Class: The complete serialized class data.
2. contracts: A list of tuples mapping a contract address to its associated class hash.
3. storage: A list of tuples mapping a storage key to a storage value. The storage key is a tuple containing the target contract address and the Starknet storage key.

{
  "contract_classes": [
    ["class_hash", { "path": "cairo-contracts/NoValidateAccount.json", "version": 0 }]
  ],
  "contracts": [
    ["contract_address", "class_hash"]
  ],
  "storage": [
    [["contract_address", "starknet_storage_key"], "storage_value"]
  ]
}

A module, class, or function should have one, and only one, reason to change. If a component handles both data management and data presentation/output, it violates SRP.

Refactoring Pattern: Separate the data structure (responsible for state and formatting) from the printer/output logic (responsible for rendering to the user).

pub struct Report {
    title: String,
    data: Vec<String>,
}

impl Report {
    pub fn new(title: String, data: Vec<String>) -> Report {
        Report { title, data }
    }

    pub fn format(&mut self) {
        self.data = self.data.iter().map(|line| format!("{}\n", line)).collect();
    }
}

pub struct ReportPrinter {
    report: Report,
}

impl ReportPrinter {
    pub fn new(report: Report) -> ReportPrinter {
        ReportPrinter { report }
    }

    pub fn print(&self) {
        println!("Title: {}", self.report.title);
        for line in &self.report.data {
            println!("{}", line);
        }
    }
}

The mc-starknet-block-import crate provides a specialized Starknet handler for the block import pipeline. It acts as a wrapper that executes at the beginning of the import queue to perform security checks on declare transactions.

Purpose

It mitigates a Denial of Service (DoS) attack vector where a malicious user submits a Cairo contract that cannot be proven. Without this handler, a node might accept a transaction without verifying the corresponding Sierra classes, leading to a failure in the sequencer's ability to prove execution or charge for work.

How it works

1. Detection: Upon receiving a new block, the handler scans for declare transactions.
2. Verification: For each declare transaction, it searches for the corresponding Sierra classes in the local database.
3. Validation: It attempts to compile the found classes to ensure they match the contract class provided in the transaction.
4. Enforcement: If any transaction contains mismatching class hashes, the block import process fails immediately.

When using the Starknet block import handler, be aware of the following operational constraints:

Multi-node Setup

Currently, the Sierra classes database is populated via RPC requests. This means the verification mechanism is optimized for single-node setups. In a multi-node environment, nodes cannot automatically find missing Sierra classes from peers. To support multi-node settings, you must implement a mechanism to query missing Sierra classes via P2P (referencing the Starknet P2P specs).

Compiler Versioning

Because the handler relies on compiling Sierra classes to verify hashes, the Cairo compiler version used by Madara is critical:

• Lagging Versions: If Madara's compiler is significantly older than the one used to generate recent Sierra classes, compilation may fail.
• Backward Compatibility: Old Sierra classes may fail to compile if backward compatibility is broken in newer compiler versions.

Madara provides a modular stack for building App Chains, allowing developers to customize different layers of the blockchain architecture:

1. Execution Layer: Defines block execution and state diff generation. Madara allows switching between execution toolkits: StarkWare's blockifier or LambdaClass's starknet_in_rust. Both use the Cairo VM to generate validity proofs.
2. Settlement Layer: As a Validity Rollup, the App Chain state is reconstructed via the settlement layer. Frequent settlement on Starknet L2 provides faster hard finality, while a decentralized sequencer provides strong soft finality.
3. Ordering Layer: Responsible for transaction sequencing. Supports various schemes ranging from simple First-Come-First-Served (FCFS) or Priority Gas Auctions (PGA) to complex consensus like Narwhall and Bullshark. Supports encrypted mempools to mitigate MEV.
4. Data Availability (DA): Ensures the full state tree is accessible so users can prove ownership even if Madara fails. Madara supports multiple DA solutions.
5. Governance Layer: Supports various models, including on-chain governance via Snapshot X (relying on storage proofs) or native Substrate governance pallets.