Skip to content

Latest commit

 

History

History
328 lines (242 loc) · 11.7 KB

README.md

File metadata and controls

328 lines (242 loc) · 11.7 KB
Raw

🥷 Madara: Starknet client

Madara is a powerfull Starknet hybrid client written in Rust.

Table of Contents

⬇️ Installation

Run from Source

  1. Install dependencies

    Ensure you have the necessary dependencies:

    sudo apt-get update && sudo apt-get install -y \
  clang \
  protobuf-compiler \
  build-essential

    Install Rust:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s

    Clone the Madara repository:

    cd <your-destination-path>
git clone https://github.com/madara-alliance/madara .

  2. Run Madara

    Start the Madara client with synchronization to Starknet mainnet:

    cargo run --release -- \
  --name madara \
  --base-path ../madara-db \
  --network main \
  --l1-endpoint ${ETHEREUM_API_URL} \

Run with Docker

1 Run docker image

To run Madara with Docker, use the following command:

docker run -d                          \
    --name madara                      \
    -p 9944:9944                       \
    -v /var/lib/madara:/var/lib/madara \
    madara:latest                      \
    --base-path ./madara-db            \
    --network main                     \
    --rpc-external                     \
    --rpc-cors all                     \
    --preset mainnet                   \
    --l1-endpoint <rpc key>

Check the logs of the running Madara service:

docker logs -f madara

Run with Docker Compose

  1. Ensure environment variable

    Set the necessary environment variable:

    export L1_ENDPOINT="your-ethereum-api-url"

    Or create a .env file in the same directory as your docker-compose.yml file:

    L1_ENDPOINT=your-ethereum-api-url

  2. Build and Run the Container

    Navigate to the directory with your docker-compose.yml file and run one of the following commands:

    • Mainnet:

      docker-compose --profile mainnet up -d

    • Testnet:

      docker-compose --profile testnet up -d

    Check the logs of the running Madara service:

    docker-compose logs -f madara

⚙️ Configuration

Configuring your Madara node properly ensures it meets your specific needs

Basic Command-Line Options

Here are the recommended options for a quick and simple configuration of your Madara full node:

  • --name <NAME>: The human-readable name for this node. It's used as the network node name.
  • --base-path <PATH>: Set the directory for Starknet data (default is /tmp/madara).
  • --network <NETWORK>: The network type to connect to (main, test, or integration).
  • --l1-endpoint <URL>: Specify the Layer 1 endpoint the node will verify its state from.
  • --rpc-port <PORT>: Specify the JSON-RPC server TCP port.
  • --rpc-cors <ORIGINS>: Specify browser origins allowed to access the HTTP & WS RPC servers.
  • --rpc-external: Listen to all RPC interfaces. Default is local.
  • --snap <BLOCK_NUMBER>: Start syncing from the closest snapshot available for the desired block (default is highest).

Advanced Command-Line Options

Here are more advanced command-line options, organized by namespace, for running and development purposes:

Network
  • -n, --network <NETWORK>: The network type to connect to (default: integration).
  • --port <PORT>: Set the network listening port.
  • --l1-endpoint <URL>: Specify the Layer 1 endpoint the node will verify its state from.
  • --gateway-key <GATEWAY_KEY>: Gateway API key to avoid rate limiting (optional).
  • --sync-polling-interval <SECONDS>: Polling interval in seconds (default: 2).
  • --no-sync-polling: Stop sync polling.
  • --n-blocks-to-sync <NUMBER>: Number of blocks to sync.
  • --starting-block <BLOCK>: The block to start syncing from (make sure to set --disable-root).
RPC
  • --rpc-external: Listen to all RPC interfaces. Note: not all RPC methods are safe to be exposed publicly. Use an RPC proxy server to filter out dangerous methods.
  • --rpc-methods <METHOD_SET>: RPC methods to expose (auto, safe, unsafe).
  • --rpc-max-request-size <SIZE>: Set the maximum RPC request payload size in megabytes (default: 15).
  • --rpc-max-response-size <SIZE>: Set the maximum RPC response payload size in megabytes (default: 15).
  • --rpc-max-subscriptions-per-connection <NUMBER>: Set the maximum concurrent subscriptions per connection (default: 1024).
  • --rpc-port <PORT>: Specify JSON-RPC server TCP port.
  • --rpc-max-connections <NUMBER>: Maximum number of RPC server connections (default: 100).
  • --rpc-cors <ORIGINS>: Specify browser origins allowed to access the HTTP & WS RPC servers.
Database
  • --base-path <PATH>: Specify custom base path (default: /tmp/madara).
  • --snap <BLOCK_NUMBER>: Start syncing from the closest snapshot available for the desired block.
  • --tmp: Run a temporary node. A temporary directory will be created and deleted at the end of the process.
  • --cache: Enable caching of blocks and transactions to improve response times.
  • --db-cache <MiB>: Limit the memory the database cache can use.
  • --trie-cache-size <Bytes>: Specify the state cache size (default: 67108864).
  • --backup-every-n-blocks <NUMBER>: Specify the number of blocks after which a backup should be created.
  • --backup-dir <DIR>: Specify the directory where backups should be stored.
  • --restore-from-latest-backup: Restore the database from the latest backup available.

ℹ️ Info: Note that not all parameters may be referenced here. Please refer to the cargo run -- --help command for the full list of parameters.

📸 Snapshots

Snapshots are under developpement and will be available through the --snap <block_number> parameter.

🌐 Interactions

Madara fully supports all the JSON-RPC methods as specified in 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.

Supported JSON-RPC Methods

Here is a list of all the supported methods with their current status:

Read Methods
Status Method
✅ starknet_specVersion
✅ starknet_getBlockWithTxHashes
✅ starknet_getBlockWithReceipts
✅ starknet_getBlockWithTxs
✅ 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
Trace Methods
Status Method
✅ starknet_traceTransaction
✅ starknet_simulateTransactions
✅ starknet_traceBlockTransactions
Write Methods
Status Method
✅ starknet_addInvokeTransaction
✅ starknet_addDeclareTransaction
✅ starknet_addDeployAccountTransaction

ℹ️ Info: Madara currently supports latest JSON-RPC specs specs up to version v0.7.1

Example of Calling a JSON-RPC Method

Here is an example of how to call a JSON-RPC method using Madara:

{
  "jsonrpc": "2.0",
  "method": "starknet_getBlockWithTxHashes",
  "params": {
    "block_id": "latest"
  },
  "id": 1
}

You can use any JSON-RPC client to interact with the Madara node, such as curl, httpie, or a custom client in your preferred programming language. For more detailed information and examples on each method, please refer to the Starknet JSON-RPC specs.

⚠️ Warning: Write methods are forwarded to the Sequencer for execution. Ensure you handle errors appropriately as per the JSON-RPC schema.

✔ Supported Features

Madara offers numerous features and is constantly improving to stay at the cutting edge of Starknet technology.

  • Starknet Version: v0.13.2
  • JSON-RPC Version: v0.7.1
  • Feeder-Gateway State Synchronization
  • State Commitment Computation
  • L1 State Verification
  • Handling L1 and L2 Reorgs

Each feature is designed to ensure optimal performance and seamless integration with the Starknet ecosystem.

👍 Contribute

🤝 Partnerships

To establish a partnership with the Kasar team, or if you have any suggestion or special request, feel free to reach us on telegram.

⚠️ License

Copyright (c) 2022-present, with the following contributors.

Madara is open-source software licensed under the Apache-2.0 License.