Madara is a powerful Starknet client written in Rust.
- β¬οΈ Installation
- βοΈ Configuration
- π Database Migration
- β Supported Features
- π¬ Get in touch
Ensure you have all the necessary dependencies available on your host system.
Dependency | Version | Installation |
---|---|---|
Rust | rustc 1.81 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh |
Clang | Latest | sudo apt-get install clang |
Openssl | 0.10 | sudo apt install openssl |
Once all dependencies are satisfied, you can clone the Madara repository:
cd <your-destination-path>
git clone https://github.com/madara-alliance/madara .
You can choose between different build modes:
-
Debug (low performance, fastest builds, for testing purposes only):
cargo build
-
Release (fast performance, slower build times):
cargo build --release
-
Production (fastest performance, very slow build times):
cargo build --profile=production
Start the Madara client with a basic set of arguments depending on your chosen mode:
Synchronizes the state of the chain from genesis.
cargo run --release -- \
--name Madara \
--full \
--base-path /var/lib/madara \
--network mainnet \
--l1-endpoint ${ETHEREUM_API_URL}
Produces new blocks for other nodes to synchronize.
cargo run --release -- \
--name Madara \
--sequencer \
--base-path /var/lib/madara \
--preset sepolia \
--l1-endpoint ${ETHEREUM_API_URL}
A node in a private local network.
cargo run --release -- \
--name Madara \
--devnet \
--base-path /var/lib/madara \
--preset sepolia
Note
Head to the Configuration section to learn more about customizing your node.
You can use cli presets for certain common node configurations, for example enabling rpc endpoints:
cargo run --release -- \
--name Madara \
--full \
--preset mainnet \
--rpc
...or the madara feeder gateway:
cargo run --release -- \
--name Madara \
--full \
--preset mainnet \
--fgw
Dependency | Version | Installation |
---|---|---|
Docker | Latest | Official instructions |
Once you have Docker installed, you will need to pull the madara image from the github container registry (ghr):
docker pull ghcr.io/madara-alliance/madara:latest
docker tag ghcr.io/madara-alliance/madara:latest madara:latest
docker rmi ghcr.io/madara-alliance/madara:latest
You can then launch madara as follows:
docker run -d \
-p 9944:9944 \
-v /var/lib/madara:/tmp/madara \
--name Madara \
madara:latest \
--name Madara \
--full \
--network mainnet \
--l1-endpoint ${ETHEREUM_API_URL}
To display the node's logs, you can use:
docker logs -f -n 100 Madara
Warning
Make sure to change the volume -v
of your container if ever you update
--base-path
.
Alternatively, you can use the provided Makefile and compose.yaml
to
simplify this process.
Dependency | Version | Installation |
---|---|---|
Docker Compose | Latest | Official instructions |
Gnu Make | Latest | sudo apt install make |
Once you have all the dependencies installed, start by saving your rpc key
to a .secrets
forlder:
mkdir .secrets
echo *** .secrets/rpc_api.secret
Then, run madara with the following commands:
make start # This will automatically pull the madara image if not available
make logs # Displays the last 100 lines of logs
make stop # Stop the madara node
make clean-db # Removes the madara db, including files on the host
make restart # Restarts the madara node
Important
By default, make start
will try and restart Madara indefinitely if it is
found to be unhealthy using docker autoheal.
This is done by checking the availability of http://localhost:9944/health
,
which means your container will be marked as unhealthy
and restart if you
have disabled the RPC service! You can run watch docker ps
to monitor the
health of your containers.
To change runtime arguments, you can update the script in madara-runner.sh
:
#!/bin/sh
export RPC_API_KEY=$(cat $RPC_API_KEY_FILE)
./madara \
--name madara \
--network mainnet \
--rpc-external \
--rpc-cors all \
--full \
--l1-endpoint $RPC_API_KEY
For more information, run:
make help
Tip
When running Madara from a docker container, make sure to set options such
as --rpc-external
, --gateway-external
and --rpc-admin-external
so as
to be able to access these services from outside the container.
For a comprehensive list of all command-line options, check out:
cargo run -- --help
Or if you are using docker, simply:
docker run madara:latest --help
Here are some recommended options to get up and started with your Madara client:
Option | About |
---|---|
--name <NAME> |
The human-readable name for this node. It's used as the network node name. |
--base-path <PATH> |
Sets the database location for Madara (default is/tmp/madara ) |
--full |
The mode of your Madara client (either --sequencer , --full , or --devnet ) |
--l1-endpoint <URL> |
The Layer 1 endpoint the node will verify its state from |
--rpc-port <PORT> |
The JSON-RPC server TCP port, used to receive requests |
--rpc-cors <ORIGINS> |
Browser origins allowed to make calls to the RPC servers |
--rpc-external |
Exposes the rpc service on 0.0.0.0 |
Each cli argument has its own corresponding environment variable you can set to change its value. For example:
MADARA_BASE_PATH=/path/to/db
MADARA_RPC_PORT=1111
These variables allow you to adjust the node's configuration without using command-line arguments, which can be useful in CI pipelines or with docker.
Note
If the command-line argument is specified then it takes precedent over the environment variable.
Madara fully supports all the JSON-RPC methods as of the latest version of the
Starknet mainnet official JSON-RPC specs.
These methods can be categorized into three main types: Read-Only Access Methods,
Trace Generation Methods, and Write Methods. They are accessible through port
9944 unless specified otherwise with --rpc-port
.
Tip
You can use the special rpc_methods
call to view a list of all the methods
which are available on an endpoint.
Here is a list of all the supported methods with their current status:
Read Methods
Status | Method |
---|---|
β | starknet_specVersion |
β | starknet_getBlockWithTxHashes |
β | starknet_getBlockWithTxs |
β | starknet_getBlockWithReceipts |
β | starknet_getStateUpdate |
β | starknet_getStorageAt |
β | starknet_getTransactionStatus |
β | starknet_getTransactionByHash |
β | starknet_getTransactionByBlockIdAndIndex |
β | starknet_getTransactionReceipt |
β | starknet_getClass |
β | starknet_getClassHashAt |
β | starknet_getClassAt |
β | starknet_getBlockTransactionCount |
β | starknet_call |
β | starknet_estimateFee |
β | starknet_estimateMessageFee |
β | starknet_blockNumber |
β | starknet_blockHashAndNumber |
β | starknet_chainId |
β | starknet_syncing |
β | starknet_getEvents |
β | starknet_getNonce |
β | starknet_getCompiledCasm (v0.8.0) |
π§ | starknet_getMessageStatus (v0.8.0) |
π§ | starknet_getStorageProof (v0.8.0) |
Trace Methods
Status | Method |
---|---|
β | starknet_traceTransaction |
β | starknet_simulateTransactions |
β | starknet_traceBlockTransactions |
Write Methods
Status | Method |
---|---|
β | starknet_addInvokeTransaction |
β | starknet_addDeclareTransaction |
β | starknet_addDeployAccountTransaction |
Websocket Methods
Status | Method |
---|---|
β | starknet_unsubscribe (v0.8.0) |
β | starknet_subscribeNewHeads (v0.8.0) |
β | starknet_subscribeEvents (v0.8.0) |
β | starknet_subscribeTransactionStatus (v0.8.0) |
β | starknet_subscribePendingTransactions (v0.8.0) |
β | starknet_subscriptionReorg (v0.8.0) |
Important
Write methods are forwarded to the Sequencer and are not executed by Madara. These might fail if you provide the wrong arguments or in case of a conflicting state. Make sure to refer to the Starknet JSON-RPC specs for a list of potential errors.
As well as the official RPC methods, Madara also supports its own set of custom
extensions to the starknet specs. These are referred to as admin
methods and
are exposed on a separate port 9943 unless specified otherwise with
--rpc-admin-port
.
Write Methods
Method | About |
---|---|
madara_addDeclareV0Transaction |
Adds a legacy Declare V0 Transaction to the state |
Status Methods
Method | About |
---|---|
madara_ping |
Return the unix time at which this method was called |
madara_shutdown |
Gracefully stops the running node |
madara_service |
Sets the status of one or more services |
Websocket Methods
Method | About |
---|---|
madara_pulse |
Periodically sends a signal that the node is alive |
Caution
These methods are exposed on locahost
by default for obvious security
reasons. You can always exposes them externally using --rpc-admin-external
,
but be very careful when doing so as you might be compromising your node!
Madara does not do any authorization checks on the caller of these
methods and instead leaves it up to the user to set up their own proxy to
handle these situations.
You can use any JSON-RPC client to interact with Madara, such as curl
,
httpie
, websocat
or any client sdk in your preferred programming language.
For more detailed information on how to call each method, please refer to the
Starknet JSON-RPC specs.
Dependency | Version | Installation |
---|---|---|
Curl | Latest | sudo apt install curl |
Here is an example of how to call a JSON-RPC method using Madara. Before running the bellow code, make sure you have a node running with rpc enabled on port 9944 (this is the default configuration).
Important
Madara currently defaults to v0.7.1
for its rpc calls. To access methods
in other or more recent versions, add rpc/v*_*_*/
to your rpc url. This
Also works for websocket methods.
curl --location 'localhost:9944'/v0_7_1/ \
--header 'Content-Type: application/json' \
--data '{
"jsonrpc": "2.0",
"method": "rpc_methods",
"params": [],
"id": 1
}' | jq --sort-keys
You should receive something like the following:
{
"id": 1,
"jsonrpc": "2.0",
"result": {
"methods": [
"rpc/V0_7_1/starknet_addDeclareTransaction",
"rpc/V0_7_1/starknet_addDeployAccountTransaction",
"rpc/V0_7_1/starknet_addInvokeTransaction",
...
"rpc/V0_8_0/starknet_traceBlockTransactions",
"rpc/V0_8_0/starknet_traceTransaction",
"rpc/V0_8_0/starknet_unsubscribe",
"rpc/rpc_methods"
]
}
}
Dependency | Version | Installation |
---|---|---|
Websocat | Latest | Official instructions |
Websockets methods are enabled by default and are accessible through the same
port as http RPC methods. Here is an example of how to call a JSON-RPC method
using websocat
.
(echo '{"jsonrpc":"2.0","method":"starknet_subscribeNewHeads","params":{"block_id":"latest"},"id":1}'; cat -) | \
websocat -v ws://localhost:9944/rpc/v0_8_0
Tip
This command and the strange use of echo
in combination with cat
is just a
way to start a websocket stream with websocat
while staying in interactive
mode, meaning you can still enter other websocket requests.
This will display header information on each new block synchronized. Use
Ctrl-C
to stop the subscription. Alternatively, you can achieve the same
result more gracefully by calling starknet_unsubscribe
. Paste the following
into the subscription stream:
{ "jsonrpc": "2.0", "method": "starknet_unsubscribe", "params": ["your-subscription-id"], "id": 1 }
Where you-subscription-id
corresponds to the value of the subscription
field
which is returned with each websocket response.
When migration to a newer version of Madara you might need to update your database. Instead of re-synchronizing the entirety of your chain's state from genesis, you can use Madara's warp update feature. This is essentially a form of trusted sync with better performances as it is run from a local source.
Warp update requires a working database source for the migration. If you do not already have one, you can use the following command to generate a sample database:
cargo run --release -- \
--name madara \
--network mainnet \
--full \
--l1-sync-disabled `# We disable sync, for testing purposes` \
--n-blocks-to-sync 1000 `# Only synchronize the first 1000 blocks` \
--stop-on-sync `# ...and shutdown the node once this is done`
To begin the database migration, you will need to start your node with
admin methods and
feeder gateway enabled. This will be
the source of the migration. You can do this with the --warp-update-sender
preset:
cargo run --release -- \
--name Sender \
--full `# This also works with other types of nodes` \
--network mainnet \
--warp-update-sender \
--l1-sync-disabled `# We disable sync, for testing purposes` \
--l2-sync-disabled
Tip
Here, we have disabled sync for testing purposes, so the migration only
synchronizes the blocks that were already present in the source node's
database. In a production usecase, you most likely want the source node to
keep synchronizing with an --l1-endpoint
, that way when the migration is
complete the receiver is fully up-to-date with any state that might have been
produced by the chain during the migration.
You will then need to start a second node to synchronize the state of your database:
cargo run --release -- \
--name Receiver \
--base-path /tmp/madara_new `# Where you want the new database to be stored` \
--full \
--network mainnet \
--l1-sync-disabled `# We disable sync, for testing purposes` \
--warp-update-receiver \
--warp-update-shutdown-receiver `# Shuts down the receiver once the migration has completed`
This will start generating a new up-to-date database under /tmp/madara_new
.
Once this process is over, the receiver node will automatically shutdown.
Tip
There also exists a --warp-update--shutdown-sender
option which allows the
receiver to take the place of the sender in certain limited circumstances.
Up until now we have had to start a node with --warp-update-sender
to begin
a migration, but this is only a preset. In a production
environment, you can start your node with the following arguments and achieve
the same results:
cargo run --release -- \
--name Sender \
--full `# This also works with other types of nodes` \
--network mainnet \
--feeder-gateway-enable `# The source of the migration` \
--gateway-port 8080 `# Default port, change as required` \
--rpc-admin `# Used to shutdown the sender after the migration` \
--rpc-admin-port 9943 `# Default port, change as required` \
--l1-sync-disabled `# We disable sync, for testing purposes` \
--l2-sync-disabled
--warp-update-receiver
doesn't override any cli arguments but is still needed
on the receiver end to start the migration. Here is an example of using it with
custom ports:
Important
If you have already run a node with --warp-update-receiver
following the
examples above, remember to delete its database with rm -rf /tmp/madara_new
.
cargo run --release -- \
--name Receiver \
--base-path /tmp/madara_new `# Where you want the new database to be stored` \
--full \
--network mainnet \
--l1-sync-disabled `# We disable sync, for testing purposes` \
--warp-update-port-rpc 9943 `# Same as set with --rpc-admin-port on the sender` \
--warp-update-port-fgw 8080 `# Same as set with --gateway-port on the sender` \
--feeder-gateway-enable \
--warp-update-receiver \
--warp-update-shutdown-receiver `# Shuts down the receiver once the migration has completed`
Madara is compliant with the latest v0.13.2
version of Starknet and v0.7.1
JSON-RPC specs. You can find out more about this in the interactions
section or at the official Starknet JSON-RPC specs.
Madara supports its own implementation of the Starknet feeder gateway, which allows nodes to synchronize state from each other at much faster speeds than a regular sync.
Note
Starknet does not currently have a specification for its feeder-gateway protocol, so despite our best efforts at output parity, you might still notice some discrepancies between official feeder gateway endpoints and our own implementation. Please let us know about if you encounter this by raising an issue
Madara supports merkelized state commitments through its own implementation of Besu Bonsai Merkle Tries. See the bonsai lib. You can read more about Starknet Block structure and how it affects state commitment here.
For guidelines on how to contribute to Madara, please see the Contribution Guidelines.
To establish a partnership with the Madara team, or if you have any suggestions or special requests, feel free to reach us on Telegram.
Madara is open-source software licensed under the Apache-2.0 License.