From 6e6986804ba61b027c1f71988ac3fdd47e07399e Mon Sep 17 00:00:00 2001 From: antiyro <74653697+antiyro@users.noreply.github.com> Date: Wed, 2 Oct 2024 14:33:50 +0100 Subject: [PATCH] fix(docs): updated readme and fixed launcher (#298) Co-authored-by: Apoorv Sadana <95699312+apoorvsadana@users.noreply.github.com> --- .github/workflows/docker-build.yml | 7 - CHANGELOG.md | 1 + Dockerfile | 58 ++--- README.md | 389 ++++++++++++++++++++--------- scripts/launcher | 15 +- 5 files changed, 307 insertions(+), 163 deletions(-) diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml index 9cc8da280..199a37765 100644 --- a/.github/workflows/docker-build.yml +++ b/.github/workflows/docker-build.yml @@ -12,12 +12,6 @@ jobs: - name: Checkout repository uses: actions/checkout@v3 - - name: Set up QEMU - uses: docker/setup-qemu-action@v2 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v2 - - name: Log in to GitHub Container Registry uses: docker/login-action@v2 with: @@ -31,7 +25,6 @@ jobs: context: . file: ./Dockerfile push: true - platforms: linux/amd64,linux/arm64 tags: | ghcr.io/${{ github.repository_owner }}/madara:latest ghcr.io/${{ github.repository_owner }}/madara:${{ github.event.release.tag_name }} diff --git a/CHANGELOG.md b/CHANGELOG.md index fe7c03e67..54bb151bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Next release +- fix(docs): updated readme and fixed launcher - fix(ci): added gateway key to fix rate limit on tests - feat(cli): launcher script and release workflows - fix: cleaned cli settings for sequencer, devnet and full diff --git a/Dockerfile b/Dockerfile index d75185f7f..79ddb9ebf 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,60 +1,48 @@ # Stage 1: Build the application FROM rust:1.78 AS builder - # Install build dependencies -RUN apt-get -y update && \ +RUN apt-get -y update && \ apt-get install -y clang && \ - apt-get autoremove -y; \ - apt-get clean; \ + apt-get autoremove -y; \ + apt-get clean; \ rm -rf /var/lib/apt/lists/* - # Set the working directory WORKDIR /usr/src/madara/ - -# Copy the source code +# Copy the source code into the container COPY Cargo.toml Cargo.lock ./ COPY crates crates COPY cairo cairo COPY cairo_0 cairo_0 -# Installing Scarb -# Dynamically detect the architecture -ARG SCARB_VERSION="v2.8.2" -ARG SCARB_REPO="https://github.com/software-mansion/scarb/releases/download" -RUN ARCH=$(uname -m); \ - if [ "$ARCH" = "x86_64" ]; then \ - PLATFORM="x86_64-unknown-linux-gnu"; \ - elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then \ - PLATFORM="aarch64-unknown-linux-gnu"; \ - else \ - echo "Unsupported architecture: $ARCH"; exit 1; \ - fi && \ - curl -fLS -o /usr/src/scarb.tar.gz \ - $SCARB_REPO/$SCARB_VERSION/scarb-$SCARB_VERSION-$PLATFORM.tar.gz && \ - tar -xz -C /usr/local --strip-components=1 -f /usr/src/scarb.tar.gz + +# Installing scarb, new since devnet integration +ENV SCARB_VERSION="v2.8.2" +ENV SHELL="/bin/bash" +RUN curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | sh -s -- ${SCARB_VERSION} +ENV PATH="/root/.local/bin:${PATH}" +RUN scarb --version + +# Install runtime dependencies +RUN apt-get -y update && \ + apt-get install -y openssl ca-certificates busybox && \ + apt-get autoremove -y; \ + apt-get clean; \ + rm -rf /var/lib/apt/lists/* # Build the application in release mode RUN cargo build --release - # Stage 2: Create the final runtime image -FROM debian:bookworm-slim - +FROM debian:bookworm # Install runtime dependencies -RUN apt-get -y update && \ - apt-get install -y openssl ca-certificates && \ - apt-get autoremove -y; \ - apt-get clean; \ +RUN apt-get -y update && \ + apt-get install -y openssl ca-certificates &&\ + apt-get autoremove -y; \ + apt-get clean; \ rm -rf /var/lib/apt/lists/* - # Set the working directory WORKDIR /usr/local/bin - # Copy the compiled binary from the builder stage COPY --from=builder /usr/src/madara/target/release/madara . -# Chain presets to be mounted at startup -VOLUME crates/primitives/chain_config/presets -VOLUME crates/primitives/chain_config/resources - # Set the entrypoint ENTRYPOINT ["./madara"] diff --git a/README.md b/README.md index cbbbbde65..22ee5208d 100644 --- a/README.md +++ b/README.md @@ -17,20 +17,18 @@ -# 🥷 Madara: Starknet client +# 🥷 Madara: Starknet Client -Madara is a powerfull Starknet hybrid client written in Rust. +Madara is a powerful Starknet client written in Rust. ## Table of Contents - ⬇️ Installation - [Run from Source](#run-from-source) - [Run with Docker](#run-with-docker) - - [Run with Docker Compose](#run-with-docker-compose) - ⚙️ Configuration - [Basic Command-Line Options](#basic-command-line-options) - [Advanced Command-Line Options](#advanced-command-line-options) -- 📸 Snapshots - 🌐 Interactions - [Supported JSON-RPC Methods](#supported-json-rpc-methods) - [Example of Calling a JSON-RPC Method](#example-of-calling-a-json-rpc-method) @@ -45,173 +43,337 @@ Madara is a powerfull Starknet hybrid client written in Rust. Ensure you have the necessary dependencies: - ```sh - sudo apt-get update && sudo apt-get install -y \ - clang \ - protobuf-compiler \ - build-essential - ``` - - Install Rust: - - ```sh - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s - ``` + | Dependency | Version | Installation | + | ---------- | ---------- | --------------------------------------------------------------------------------- | --- | + | Rust | rustc 1.78 | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` | + | Clang | Latest | `sudo apt-get install clang` | + | Scarb | v2.8.2 | `curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | sh` | Clone the Madara repository: - ```sh + ```bash cd git clone https://github.com/madara-alliance/madara . ``` -2. **Run Madara** +2. **Build Program** - Start the Madara client with synchronization to Starknet mainnet: + Choose between different build modes: - ```sh - cargo run --release -- \ - --name madara \ - --base-path ../madara-db \ - --network main \ - --l1-endpoint ${ETHEREUM_API_URL} \ - ``` + - **Debug** (fastest build mode, but lower performance, for testing purposes only): -### Run with Docker + ```bash + cargo build + ``` -1 **Run docker image** - -To run Madara with Docker, use the following command: - -```sh -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 -``` + - **Release** (recommended build mode): -Check the logs of the running Madara service: + ```bash + cargo build --release + ``` -```sh -docker logs -f madara -``` + - **Production** (recommended for production performance): -### Run with Docker Compose + ```bash + cargo build --profile=production + ``` -1. **Ensure environment variable** +3. **Run Madara** - Set the necessary environment variable: + Start the Madara client with a basic set of arguments depending on your chosen mode: - ```sh - export L1_ENDPOINT="your-ethereum-api-url" + **Full Node** + + ```bash + cargo run --release -- \ + --name Madara \ + --full \ + --base-path /var/lib/madara \ + --network mainnet \ + --l1-endpoint ${ETHEREUM_API_URL} ``` - Or create a `.env` file in the same directory as your `docker-compose.yml` file: + **Sequencer** - ```sh - L1_ENDPOINT=your-ethereum-api-url + ```bash + cargo run --release -- \ + --name Madara \ + --sequencer \ + --base-path /var/lib/madara \ + --preset test \ + --l1-endpoint ${ETHEREUM_API_URL} ``` -2. **Build and Run the Container** + **Devnet** - Navigate to the directory with your `docker-compose.yml` file and run one of the following commands: + ```bash + cargo run --release -- \ + --name Madara \ + --devnet \ + --base-path /var/lib/madara \ + --preset test + ``` - - Mainnet: + > ℹ️ **Info:** We recommend you to head to the [Configuration](https://docs.madara.build/fundamentals/configuration) + > section to customize your node parameters. + > ℹ️ **Info:** If you don't have an L1 endpoint URL, we recommend you refer to the relevant + > section to obtain one. - ```sh - docker-compose --profile mainnet up -d - ``` +### Run with Docker - - Testnet: +1. **Install Docker** - ```sh - docker-compose --profile testnet up -d - ``` + Ensure you have Docker installed on your machine. Once you have Docker installed, you can run Madara using the available Docker images. + + ```bash + docker run -d \ + --name Madara \ + --full + -p 9944:9944 \ + -v /var/lib/madara:/var/lib/madara \ + madara:latest \ + --base-path /var/lib/madara \ + --network mainnet \ + --l1-endpoint ${ETHEREUM_API_URL} + ``` - Check the logs of the running Madara service: + > ℹ️ **Info:** This is a default configuration for a Full Node on Starknet mainnet. + > For more information on possible configurations, please visit the + > [Configuration](https://docs.madara.build/fundamentals/configuration) section. + > ⚠️ **Warning:** Make sure to change the volume `-v` of your container if you change the `--base-path`. + > ℹ️ **Info:** If you don't have an L1 endpoint URL, we recommend you refer to the relevant section to obtain one. - ```sh - docker-compose logs -f madara +2. **Check Logs** + + ```bash + docker logs -f Madara ``` + > ℹ️ **Info:** Now you can head to the [Metrics](https://docs.madara.build/monitoring/grafana) + > section to deploy a Grafana and Prometheus dashboard. + ## ⚙️ Configuration -Configuring your Madara node properly ensures it meets your specific needs +### Command-Line Options -### Basic Command-Line Options +For a comprehensive list of command-line options: + +```bash +cargo run -- --help +``` -Here are the recommended options for a quick and simple configuration of your Madara full node: +Below are some essential command-line options and a categorized list of advanced configurations: + +#### Basic Command-Line Options + +Here are the recommended options for a quick and simple configuration of your Madara client: - **`--name `**: The human-readable name for this node. It's used as the network node name. + - **`--base-path `**: Set the directory for Starknet data (default is `/tmp/madara`). -- **`--network `**: The network type to connect to (`main`, `test`, or `integration`). + +- **`--full`**: The mode of your Madara client (either `--sequencer`, `--full`, or `devnet`). + - **`--l1-endpoint `**: Specify the Layer 1 endpoint the node will verify its state from. + - **`--rpc-port `**: Specify the JSON-RPC server TCP port. + - **`--rpc-cors `**: Specify browser origins allowed to access the HTTP & WS RPC servers. + - **`--rpc-external`**: Listen to all RPC interfaces. Default is local. -- **`--snap `**: Start syncing from the closest snapshot available for the desired block (default is highest). + +> ℹ️ **Info:** For more information regarding synchronization configuration, please refer to the +> [Configuration](https://docs.madara.build/fundamentals/configuration) section. ### Advanced Command-Line Options -Here are more advanced command-line options, organized by namespace, for running and development purposes: +Toggle details for each namespace to view additional settings:
-Network +Network -- **`-n, --network `**: The network type to connect to (default: `integration`). -- **`--port `**: Set the network listening port. -- **`--l1-endpoint `**: Specify the Layer 1 endpoint the node will verify its state from. -- **`--gateway-key `**: Gateway API key to avoid rate limiting (optional). -- **`--sync-polling-interval `**: Polling interval in seconds (default: 2). -- **`--no-sync-polling`**: Stop sync polling. -- **`--n-blocks-to-sync `**: Number of blocks to sync. -- **`--starting-block `**: The block to start syncing from (make sure to set `--disable-root`). +- **`-n, --network `**: The network type to connect to. + + - [default: mainnet] + + Possible values: + + - `mainnet`: The main network (mainnet). Alias: main + - `testnet`: The test network (testnet). Alias: sepolia + - `integration`: The integration network + - `devnet`: A devnet for local testing + +- **`--l1-endpoint `**: Specify the Layer 1 RPC endpoint for state verification. + +- **`--gateway-key `**: Gateway API key to avoid rate limiting (optional). + +- **`--sync-polling-interval `**: Polling interval in seconds. + + - [default: 4] + +- **`--pending-block-poll-interval `**: Pending block polling interval in seconds. + + - [default: 2] + +- **`--no-sync-polling`**: Disable sync polling. + +- **`--n-blocks-to-sync `**: Number of blocks to sync, useful for benchmarking. + +- **`--unsafe-starting-block `**: Start syncing from a specific block. May cause database inconsistency. + +- **`--sync-disabled`**: Disable the sync service. + +- **`--sync-l1-disabled`**: Disable L1 sync service. + +- **`--gas-price-sync-disabled`**: Disable the gas price sync service. + +- **`--gas-price-poll-ms `**: Interval in milliseconds for the gas price sync service to fetch the gas price. + - [default: 10000]
-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 `**: RPC methods to expose (`auto`, `safe`, `unsafe`). -- **`--rpc-max-request-size `**: Set the maximum RPC request payload size in megabytes (default: 15). -- **`--rpc-max-response-size `**: Set the maximum RPC response payload size in megabytes (default: 15). -- **`--rpc-max-subscriptions-per-connection `**: Set the maximum concurrent subscriptions per connection (default: 1024). -- **`--rpc-port `**: Specify JSON-RPC server TCP port. -- **`--rpc-max-connections `**: Maximum number of RPC server connections (default: 100). -- **`--rpc-cors `**: Specify browser origins allowed to access the HTTP & WS RPC servers. +RPC + +- **`--rpc-disabled`**: Disable the RPC server. + +- **`--rpc-external`**: Listen to all network interfaces. + +- **`--rpc-methods `**: RPC methods to expose. + + - [default: auto] + + Possible values: + + - `auto`: Expose all methods if RPC is on localhost, otherwise serve only safe methods. + - `safe`: Allow only a safe subset of RPC methods. + - `unsafe`: Expose all RPC methods (even potentially unsafe ones). + +- **`--rpc-rate-limit `**: RPC rate limiting per connection. + +- **`--rpc-rate-limit-whitelisted-ips `**: Disable RPC rate limiting for specific IP addresses or ranges. + +- **`--rpc-rate-limit-trust-proxy-headers`**: Trust proxy headers for disabling rate limiting in reverse proxy setups. + +- **`--rpc-max-request-size `**: Maximum RPC request payload size for both HTTP and WebSockets. + + - [default: 15] + +- **`--rpc-max-response-size `**: Maximum RPC response payload size for both HTTP and WebSockets. + + - [default: 15] + +- **`--rpc-max-subscriptions-per-connection `**: Maximum concurrent subscriptions per connection. + + - [default: 1024] + +- **`--rpc-port `**: The RPC port to listen on. + + - [default: 9944] + +- **`--rpc-max-connections `**: Maximum number of RPC server connections at a given time. + + - [default: 100] + +- **`--rpc-disable-batch-requests`**: Disable RPC batch requests. + +- **`--rpc-max-batch-request-len `**: Limit the max length for an RPC batch request. + +- **`--rpc-cors `**: Specify browser origins allowed to access the HTTP & WebSocket RPC servers. + +- **`--rpc-message-buffer-capacity-per-connection `**: Maximum number of messages in memory per connection. + - [default: 64] + +
+ +
+Database + +- **`--base-path `**: The path where Madara will store the database. + + - [default: /tmp/madara] + +- **`--backup-dir `**: Directory for backups. + +- **`--backup-every-n-blocks `**: Periodically create a backup. + +- **`--restore-from-latest-backup`**: Restore the database from the latest backup version. + +
+ +
+Block Production + +- **`--block-production-disabled`**: Disable the block production service. + +- **`--devnet`**: Launch in block production mode, with devnet contracts. + +- **`--devnet-contracts `**: Create this number of contracts in the genesis block for the devnet configuration. + + - [default: 10] + +- **`--override-devnet-chain-id`**: Launch a devnet with a production chain ID. + +- **`--authority`**: Enable authority mode; the node will run as a sequencer and try to produce its own blocks.
-Database - -- **`--base-path `**: Specify custom base path (default: `/tmp/madara`). -- **`--snap `**: 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 `**: Limit the memory the database cache can use. -- **`--trie-cache-size `**: Specify the state cache size (default: 67108864). -- **`--backup-every-n-blocks `**: Specify the number of blocks after which a backup should be created. -- **`--backup-dir `**: Specify the directory where backups should be stored. -- **`--restore-from-latest-backup`**: Restore the database from the latest backup available. +Metrics + +- **`--telemetry-disabled`**: Disable connection to the Madara telemetry server. + +- **`--telemetry-url `**: The URL of the telemetry server with verbosity level. + + - [default: "wss://starknodes.com/submit 0"] + +- **`--prometheus-port `**: The port used by the Prometheus RPC service. + + - [default: 9615] + +- **`--prometheus-external`**: Listen on all network interfaces for Prometheus. + +- **`--prometheus-disabled`**: Disable the Prometheus service.
> ℹ️ **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 +### Environment Variables -Snapshots are under developpement and will be available through the `--snap ` parameter. +Set up your node's environment variables using the `STARKNET_` prefix. For example: + +- `STARKNET_BASE_PATH=/path/to/data` +- `STARKNET_LOG=info` + +These variables allow you to adjust the node's configuration without using command-line arguments. + +### Configuration File + +You can use a JSON, TOML, or YAML file to structure your configuration settings. +Specify your configuration file on startup with the `-c` option. Here's a basic example in JSON format: + +```json +{ + "name": "Deoxys", + "base_path": "../deoxys-db", + "network": "mainnet", + "l1_endpoint": "l1_key_url", + "rpc_port": 9944, + "rpc_cors": "*", + "rpc_external": true, + "prometheus_external": true +} +``` + +> 💡 **Tip:** Review settings carefully for optimal performance and refer to Starknet's +> official documentation for detailed configuration guidelines. + +Always test your configuration in a non-production environment before rolling it out to a live node to prevent downtime +and other potential issues. + +> ℹ️ **Info:** For a custom chain configuration, you can refer to the configuration section of chain operator deployments. ## 🌐 Interactions @@ -275,7 +437,7 @@ Here is a list of all the supported methods with their current status: -> ℹ️ **Info:** Madara currently supports latest [JSON-RPC specs](https://github.com/starkware-libs/starknet-specs) specs up to version v0.7.1 +> ℹ️ **Info:** Madara currently supports the latest [JSON-RPC specs](https://github.com/starkware-libs/starknet-specs) up to version v0.7.1. ### Example of Calling a JSON-RPC Method @@ -314,15 +476,14 @@ Each feature is designed to ensure optimal performance and seamless integration ## 👍 Contribute +For guidelines on how to contribute to Madara, please see the [Contribution Guidelines](https://github.com/madara-alliance/madara/blob/main/CONTRIBUTING.md). + ## 🤝 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](https://t.me/madara-alliance). +To establish a partnership with the Madara team, or if you have any suggestions or +special requests, feel free to reach us on [Telegram](https://t.me/madara-alliance). ## ⚠️ License -Copyright (c) 2022-present, with the following -[contributors](https://github.com/madara-alliance/madara/graphs/contributors). - Madara is open-source software licensed under the [Apache-2.0 License](https://github.com/madara-alliance/madara/blob/main/LICENSE). diff --git a/scripts/launcher b/scripts/launcher index a2cc388a1..b64b933a1 100755 --- a/scripts/launcher +++ b/scripts/launcher @@ -47,6 +47,7 @@ RED=$(tput setaf 1) CYAN=$(tput setaf 6) NC=$(tput sgr0) # No Color BOLD=$(tput bold) +ITALIC=$(tput sitm) UNDERLINE=$(tput smul) BLINK=$(tput blink) @@ -289,9 +290,9 @@ fi # Choose the mode echo -e "\n🕹️ ${YELLOW}${BOLD}On which mode would you like to run Madara? (Enter a number)${NC}\n" -echo "${YELLOW}1. Full Node${NC}" -echo "${YELLOW}2. Sequencer${NC}" -echo "${YELLOW}3. Devnet${NC}" +echo "${YELLOW}1. Full Node ${ITALIC}(Syncronize state from a specific Network)${NC}" +echo "${YELLOW}2. Sequencer ${ITALIC}(Produce state for a specific Network)${NC}" +echo "${YELLOW}3. Devnet ${ITALIC}(Launch a test network with pre-funded accounts) ${NC}" while true; do read -p "> " MODE_CHOICE case $MODE_CHOICE in @@ -324,7 +325,7 @@ tput ed echo -e "\n${GREEN}Your node has been correctly named: ${BOLD}${NODE_NAME}${NC}${GREEN}.${NC}" # Ask for the database path -echo -e "\n💾 ${YELLOW}${BOLD}Where would you like to store your database? (default: /tmp/madara)${NC}" +echo -e "\n💾 ${YELLOW}${BOLD}Where would you like to store your database?${NC}${YELLOW} (it will be located inside your docker container) (default: /tmp/madara)${NC}" read -p "> " BASE_PATH BASE_PATH=${BASE_PATH:-/tmp/madara} @@ -387,7 +388,7 @@ modify_chain_config() { # Check if the user wants to skip modifications if [[ -z "$MODIFY_NUMBERS" ]]; then - echo -e "${GREEN}No parameters selected for modification. Proceeding with the original configuration.${NC}" + echo -e "${GREEN}No parameters selected for modification. Proceeding with the original configuration.${NC}" else selected_indices=($MODIFY_NUMBERS) @@ -482,8 +483,8 @@ else echo -e "\n🌐 ${YELLOW}${BOLD}Please choose a Network or provide a custom Chain config path: (Enter a number)${NC}\n" echo "${YELLOW}1. Starknet Mainnet${NC}" echo "${YELLOW}2. Starknet Testnet${NC}" - echo "${YELLOW}3. Test${NC}" - echo "${YELLOW}4. Custom Chain config${NC}" + echo "${YELLOW}3. Test Network${NC}" + echo "${YELLOW}4. Custom Network${NC}" while true; do read -p "> " NETWORK_CHOICE case $NETWORK_CHOICE in