Build upon Madara

Uchiwa Madara
In this section, we will guide you through the building process so you can start hacking on the Madara stack. We will go from running your chain locally to changing the consensus algorithm and interacting with smart contracts on your own chain!

Let's start

Install dependencies

We first need to make sure you have everything needed to complete this tutorial.

Dependency	Version	Installation
Rust	rustc 1.69.0-nightly	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` `rustup toolchain install nightly`
nvm	latest	`curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh \| bash`
Cairo	1.0	`curl -L https://github.com/franalgaba/cairo-installer/raw/main/bin/cairo-installer \| bash`

Build the chain

We will spin up a CairoVM Rollup from the Madara Stack source code. You could use docker images, but this way we keep the option to modify component behavior if you need to do so. The Madara stack source code is a monorepo which can be found here (opens in a new tab)

cd ~
git clone git@github.com:keep-starknet-strange/madara.git

Then let's build the chain in release mode

cd madara
cargo build --release

Single-Node Development Chain

This command will start the single-node development chain with non-persistent state:

./target/release/madara --dev

Purge the development chain's state:

./target/release/madara purge-chain --dev

Start the development chain with detailed logging:

RUST_BACKTRACE=1 ./target/release/madara -ldebug --dev

If everything works correctly, we can go to the next step and create our own genesis state!

Create your chain specification

First, run this command to create a plain chain spec

./target/release/madara build-spec > ./infra/chain-sepcs/chain-spec-plain.json

By default, the chain will run with the following config :

GRANDPA & AURA (opens in a new tab)
An admin account contract at address 0x0000000000000000000000000000000000000000000000000000000000000001
A test contract at address 0x0000000000000000000000000000000000000000000000000000000000001111
A fee token (ETH) at address 0x040e59c2c182a58fb0a74349bfa4769cbbcba32547591dd3fb1def8623997d00
The admin account address has a MAX balance of fee token
An ERC20 contract at address 0x040e59c2c182a58fb0a74349bfa4769cbbcba32547591dd3fb1def8623997d00

This chain specification can be thought of as the main source of information that will be used when connecting to the chain.

(Not available yet) Deploy your settlement smart contracts

Start your chain

Now that we are all setup, we can finally run the chain! 🥷

There are a lot of ways you can run the chain depending on which role you want to take :

Full node
Synchronizes with the chain to store the most recent block state and block headers for older blocks.
Archive node
Maintains all blocks starting from the genesis block with complete state available for every block.
RPC node
Exposes an RPC interface over HTTP or WebSocket ports for the chain so that users can read the blockchain state and submit transactions. There are often multiple RPC nodes behind a load balancer.
Validator node
Secures the chain by staking some chosen asset and votes on consensus along with other validators.

When developing your chain, you can simply run it in developer mode :

./target/release/madara --dev --execution=native

If you only care about exposing the RPC you can run the following :

./target/release/madara --unsafe-ws-external --rpc-methods Safe --rpc-cors ‘*’ --ws-max-connections 5000

If you want to keep the whole state of the chain in a `/tmp/ folder :

./target/release/madara --base-path /tmp/

In this case, note that you can purge the chain's state whenever you like by running :

./target/release/madara purge-chain --base-path /tmp