diff --git a/pages/_meta.en.json b/pages/_meta.en.json index 9249d94..20e7cb2 100644 --- a/pages/_meta.en.json +++ b/pages/_meta.en.json @@ -9,9 +9,6 @@ "pagination": false } }, - "Installation": { - "title": "Installation" - }, "quickstart": { "title": "Quickstart" }, @@ -29,9 +26,6 @@ "chain-configuration": { "title": "Configuration" }, - "chain-management": { - "title": "Management" - }, "--- NODE OPERATORS": { "title": "NODE OPERATORS", @@ -40,6 +34,9 @@ "introduction": { "title": "Overview" }, + "installation": { + "title": "Installation" + }, "fundamentals": { "title": "Fundamentals" }, @@ -52,14 +49,6 @@ "display": "hidden" }, - "--- DEVNET": { - "title": "DEVNET", - "type": "separator" - }, - "chain-devnet": { - "title": "Devnet" - }, - "--- Tutorials": { "title": "TUTORIALS", "type": "separator" diff --git a/pages/chain-devnet/_meta.en.json b/pages/chain-devnet/_meta.en.json deleted file mode 100644 index abe6840..0000000 --- a/pages/chain-devnet/_meta.en.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "configuration": "Configuration" -} diff --git a/pages/chain-management/_meta.en.json b/pages/chain-management/_meta.en.json deleted file mode 100644 index abe6840..0000000 --- a/pages/chain-management/_meta.en.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "configuration": "Configuration" -} diff --git a/pages/index.en.mdx b/pages/index.en.mdx index 766967e..bdc9572 100644 --- a/pages/index.en.mdx +++ b/pages/index.en.mdx @@ -17,6 +17,8 @@ import { PanelsTopLeft, Package, Rocket, + Wrench, + BrainCircuit } from "lucide-react"; # Welcome to the Madara Documentation @@ -29,7 +31,7 @@ Madara is an open-source framework that makes it simple for you to deploy your o ## Madara Supports the Following Use Cases -- **Appchain Stack:** Allows to easily deploy your own Starknet instance to host you application +- **App Chain Stack:** Allows to easily deploy your own Starknet instance to host you application - **Full Node:** Enables to interact with different Starknet networks - **Devnet:** Simulates a Starknet network to test out you Cairo smart contracts @@ -68,12 +70,17 @@ Take a look at these essential tools to get started with Madara and Cairo. } + icon={} /> } + icon={} + /> + } /> {/* diff --git a/pages/quickstart/_meta.en.json b/pages/quickstart/_meta.en.json index 5cc8992..26c3d19 100644 --- a/pages/quickstart/_meta.en.json +++ b/pages/quickstart/_meta.en.json @@ -1,5 +1,5 @@ { - "quickstart_1": { - "href": "/quickstart/quickstart_1" + "launch": { + "title": "Launch your App Chain!" } } diff --git a/pages/quickstart/quickstart_1.en.mdx b/pages/quickstart/launch.en.mdx similarity index 99% rename from pages/quickstart/quickstart_1.en.mdx rename to pages/quickstart/launch.en.mdx index 9af840e..de332b8 100644 --- a/pages/quickstart/quickstart_1.en.mdx +++ b/pages/quickstart/launch.en.mdx @@ -15,7 +15,7 @@ import { } from "@fortawesome/free-brands-svg-icons"; import { Tabs, Tab } from "nextra/components"; -# How to Start a Self-Hosted Chain with Madara +# How to launch your first App-Chain with Madara This guide will walk you through the process of building, configuring, testing, and launching your own self-hosted chain using Madara. Unlike the [Node operators](/introduction) section, which focuses on understanding how Madara works as a client, here we explain in a more application-oriented way how to run and customize your own chain. diff --git a/pages/tutorials-full-node/_meta.en.json b/pages/tutorials-full-node/_meta.en.json index 8a31d03..391d0cf 100644 --- a/pages/tutorials-full-node/_meta.en.json +++ b/pages/tutorials-full-node/_meta.en.json @@ -1,4 +1,5 @@ { - "launch": "How to launch a Madara full node?", + "launch": "How to launch a Madara Full Node?", + "customize": "How to customize a Madara Full Node?", "query": "How to query Madara RPC endpoint?" } diff --git a/pages/tutorials-full-node/customize.en.mdx b/pages/tutorials-full-node/customize.en.mdx new file mode 100644 index 0000000..c111668 --- /dev/null +++ b/pages/tutorials-full-node/customize.en.mdx @@ -0,0 +1,165 @@ +--- +title: Customize a Madara Full Node +lang: en-US +description: Learn how to customize a Madara Full Node +--- + +import { Steps } from "nextra-theme-docs"; +import { Callout } from "nextra-theme-docs"; +import { Cards, Card } from "nextra/components"; +import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"; +import { + faLinux, + faApple, + faWindows, +} from "@fortawesome/free-brands-svg-icons"; +import { Tabs, Tab } from "nextra/components"; + +# How to customize a Madara Full Node + +This guide will walk you through the process of customizing a Madara Full Node. + +## Quick start tutorial + +As an introduction to the following section, we created a video tutorial to give you more context on how to customize your Madara Full Node. + +-- Video goes here -- + + + We recommend continuing with the [Next Section](#step-by-step-tutorial), which will help you better understand the different components of Madara customization. + + +## Step by step tutorial + + + This tutorial assumes that you already know how to launch a Madara Full Node. For more information about how to launch a Madara Full Node, please head up to [this tutorial](/tutorials-full-node/launch). + + +### Configure your Full Node + +Now that you have your node installed and running smoothly, you may want to configure it further to match your desired configuration or network. There are two types of configuration for your node: + +- **Node Configuration**: the configuration of your node itself as an engine. +- **Chain Configuration**: the configuration of the chain you are currently running your node on. + +In this tutorial, we'll focus on a simple configuration of both so you can understand them better. + + + + ### Node Configuration + + We have over a hundred configuration options available for your Full Node client. You can find all the configuration parameters in the [Configuration](/fundamentals/configuration) chapter of the Node Operators section. For a comprehensive list of command-line options, you can also run: + + ```bash + cargo run -- --help + ``` + + Here, we will simply add the necessary parameters so that you can query your RPC endpoint from anywhere. To do this, we will use 3 additional parameters: + + - **`--rpc-port `**: Specify 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. + + This will give us the following command: + + ```bash + cargo run --release -- \ + --name Madara \ + --full + --base-path /var/lib/madara \ + --network mainnet \ + --l1-endpoint ${ETHEREUM_API_URL} \ + --rpc-port 9945 \ + --rpc-cors '*' \ + --rpc-external + ``` + + If you run this command, you can now query your Madara Full Node on the RPC endpoint 9945. + + + For more information on how to query your Full Node client, we recommend following the tutorial [How to query a Madara RPC endpoint](/tutorials-full-node/query). + + + ### Chain Configuration + + Your Madara Full Node is a configurable client that can connect and synchronize with any network respecting the Starknet specs. These networks may have specific configurations, so it's preferable to adapt your Full Node to this configuration to ensure compatibility. + + Here, we will simply imagine that our node wants to connect to a Starknet clone App Chain with the following configuration: + + ```yml + chain_name: "Starklone" + chain_id: "SN_KLONE" + native_fee_token_address: "0x012345a0fc34fa1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" + parent_fee_token_address: "0x012346570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7" + latest_protocol_version: "0.13.2" + block_time: "30s" + pending_block_update_time: "2s" + execution_batch_size: 16 + bouncer_config: + block_max_capacity: + builtin_count: + add_mod: 18446744073709551615 + bitwise: 18446744073709551615 + ecdsa: 18446744073709551615 + ec_op: 18446744073709551615 + keccak: 18446744073709551615 + mul_mod: 18446744073709551615 + pedersen: 18446744073709551615 + poseidon: 18446744073709551615 + range_check: 18446744073709551615 + range_check96: 18446744073709551615 + gas: 5000000 + n_steps: 40000000 + message_segment_length: 18446744073709551615 + n_events: 18446744073709551615 + state_diff_size: 131072 + sequencer_address: "0x01234a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8" + eth_core_contract_address: "0xc662c410C0ECf747543f5bA90660f6ABeBD9C8c4" + eth_gps_statement_verifier: "0x47312450B3Ac8b5b8e247a6bB6d523e7605bDb60" + ``` + + You simply need to take this configuration and save it as a `.yml` file somewhere on your machine, then call it via: + + - **`--chain-config-path `**: Specifies the chain configuration file path. + + Which in our case would give the following command: + + ```bash + cargo run --release -- \ + --name Madara \ + --full + --base-path /var/lib/madara \ + --l1-endpoint ${ETHEREUM_API_URL} \ + --rpc-port 9945 \ + --rpc-cors '*' \ + --rpc-external \ + --chain-config-path "/path/to/your/config.yml" + ``` + + + Please note that the `--network mainnet` parameter, which overwrites any chain config with the mainnet configuration preset, has been removed here to allow the custom chain config via `--chain-config-path`. + + + Another way to run this configuration would have been, for example, to override the elements that differ here with the original Starknet mainnet configuration using: + + - **`--chain-config-override `**: Overrides specific chain configuration parameters. + +This would give the following command: + + ```bash + cargo run --release -- \ + --name Madara \ + --full \ + --network mainnet \ + --base-path /var/lib/madara \ + --l1-endpoint ${ETHEREUM_API_URL} \ + --rpc-port 9945 \ + --rpc-cors '*' \ + --rpc-external \ + --chain-config-override chain_name="Starklone" chain_id="SN_KLONE" native_fee_token_address="0x012345a0fc34fa1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" parent_fee_token_address="0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7" sequencer_address="0x01234a1bd84444c89232ec27754698e5d2e7e1a7f1539f12027f28b23ec9f3d8" + ``` + + + You now know how to configure both your Full Node client and the chain it connects to! To learn more, visit the sections [Node Configuration](/fundamentals/configuration) and [Chain Configuration](/chain-configuration/parameters). diff --git a/pages/tutorials-full-node/launch.en.mdx b/pages/tutorials-full-node/launch.en.mdx new file mode 100644 index 0000000..f129f80 --- /dev/null +++ b/pages/tutorials-full-node/launch.en.mdx @@ -0,0 +1,95 @@ +--- +title: Launch a Madara Full Node +lang: en-US +description: Learn how to launch a Madara Full Node +--- + +import { Steps } from "nextra-theme-docs"; +import { Callout } from "nextra-theme-docs"; +import { Cards, Card } from "nextra/components"; +import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"; +import { + faLinux, + faApple, + faWindows, +} from "@fortawesome/free-brands-svg-icons"; +import { Tabs, Tab } from "nextra/components"; + +# How to launch a Madara Full Node + +This guide will walk you through the process of installing and launching a Madara Full Node. + +## Quick start tutorial + +As an introduction to the following section, we created a video tutorial to give you more context how to launch your Madara Full Node. + +/video goes here/ + + + We recommend continuing with the [Next Section](#Step-by-step-tutorial), which will help you better understand the different components of Madara by building from source. + + +## Step by step tutorial + +### Install your Full Node + + + ### Install dependencies + + We first need to make sure you have everything needed to complete this tutorial. + + | 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 ` | + + ### Get code + + Fetch the code from the Official [Madara](https://github.com/madara-alliance/madara) repository in the folder of your choice. + + ```bash + cd + git clone https://github.com/madara-alliance/madara . + ``` + + ### Build program + + Then let's build the dependencies. You can choose between 3 different build modes: + + - **Debug** (fastest build mode, but lower performances, for testing purpose only) + + ```bash + cargo build + ``` + + - **Release** (the recommend build mode) + + ```bash + cargo build --release + ``` + + - **Production** (the recommend build mode for production performances) + + ```bash + cargo build --profile=production + ``` + + ### Run Madara + + This command will start the Madara client with a basic set arguments syncronizing directly with Starknet mainnet. For further configuration we recomand you to head up to the [Configure Your Node](#configure-your-node) section down below. + + ```bash + cargo run --release -- \ + --name Madara \ + --full + --base-path /var/lib/madara \ + --network mainnet \ + --l1-endpoint ${ETHEREUM_API_URL} + ``` + + + If you don't have an L1 endpoint url we recommend you to head up to the + [Verification](/) section to get one + + \ No newline at end of file diff --git a/pages/tutorials-full-node/query.en.mdx b/pages/tutorials-full-node/query.en.mdx new file mode 100644 index 0000000..97d3148 --- /dev/null +++ b/pages/tutorials-full-node/query.en.mdx @@ -0,0 +1,239 @@ +--- +title: How to Query a Madara RPC Endpoint +lang: en-US +description: Learn how to query a Madara RPC endpoint +--- + +import { Steps } from "nextra-theme-docs"; +import { Callout } from "nextra-theme-docs"; +import { Cards, Card } from "nextra/components"; +import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"; +import { + faLinux, + faApple, + faWindows, +} from "@fortawesome/free-brands-svg-icons"; +import { Tabs, Tab } from "nextra/components"; + +# How to Query a Madara RPC Endpoint + +This guide will walk you through the process of querying a Madara RPC endpoint to interact with your Madara Full Node and the Starknet network. + +## Quick Start Tutorial + +As an introduction to the following section, we have created a video tutorial to give you more context on how to query your Madara RPC endpoint. + +-- Insert video here -- + + + We recommend continuing with the [Step-by-Step Tutorial](#step-by-step-tutorial), which will help you better understand how to interact with Madara RPC endpoints. + + +## Step-by-Step Tutorial + +### Interact with the Madara RPC Endpoint + + + +### Prerequisites + +Before you begin, ensure that: + +1. **You have a Madara client running**: If you haven't set up a node yet, you can refer to the [Launch a Madara Full Node](/tutorials-full-node/launch) tutorial. +2. **This client have an RPC Endpoint accessible**: You can expose the RPC endpoint of your Madara client by using the following parameters: + + - **`--rpc-port `**: Specify 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. + +3. **You have an HTTP Client Tool**: Have a tool to make HTTP POST requests, such as [curl](https://curl.se/docs/manpage.html), [Postman](https://www.postman.com/), or any programming language with HTTP capabilities. + +### Understanding the JSON-RPC Interface + +Now that you have everything set up, let's try to understand the interface Madara exposes. +A Madara client exposes a JSON-RPC interface that adheres to the latest [Starknet JSON-RPC specifications](https://github.com/starkware-libs/starknet-specs/releases). This interface allows you to interact with the node by sending JSON-RPC requests and receiving responses. + +Cette interface JSON-RPC a plusieurs catégorie de methodes: + +- **Read methods**: des methodes de lecture seule, celles ci vont juste demander a votre client des donnees statique stockee par celui ci tel que par exemple les transactions du block 100000. +- **Historical methods**: Celle-ci sont des methodes de lecture particulieres. Toutes les methodes finissant par "at" tel que `starknet_getStorageAt` vous permettent de recuperer une valeur a un momment donnee de sa vie. L'address de stockage 0x5 d'un contract peut avoir eu la valeur "0x123" au block 50000 et "0x321" au block 100000. +- **Trace methods**: ces methodes permettent de generer la trace d'une execution et necessitent generalement une re-execution de celle ci via Blockifier +- **Write methods**: ces methodes vont directement modifier l'état de la chaine en question. Si celle-ci sont run depuis un Full Node alors celui-ci les forward au sequencer, seul responsavle des modification d'etat + +### Testing the Connection + +To verify that your client is accessible, let's send a simple request to get the chain id: + + + **Note**: Pour des raisons de simplicité ici nous allons utiliser l'endpoint par defaut: http://localhost:9944, il se peut que le votre soit different, pour savoir quel est votre endpoint RPC veuillez examiner les logs au lancement de votre client. + + +```bash +curl --location 'http://localhost:9944' \ +--header 'Content-Type: application/json' \ +--data '{ + "jsonrpc": "2.0", + "method": "starknet_chainId", + "params": [], + "id": 1 +}' +``` + +**Expected Response:** + +```json +{ + "jsonrpc": "2.0", + "result": "0x534e5f4d41494e", // Example chain ID in hexadecimal + "id": 1 +} +``` + +If you receive a response similar to the above, your node is accessible and ready to accept JSON-RPC requests. + +### Perform a Read call + +No let's go further and try to retrieve the most recent block and its transactions: + +```bash +curl --location 'http://localhost:9944' \ +--header 'Content-Type: application/json' \ +--data '{ + "jsonrpc": "2.0", + "method": "starknet_blockNumber", + "params": [], + "id": 1 +}' +``` + +**Response:** + +```json +{ + "jsonrpc": "2.0", + "result": 12345, // Example block number + "id": 1 +} +``` + +### Perform an historical call + +To get detailed information about a specific storage value at a specific moment you can run the `starknet_getStorageAt` historical call. + +**Example Request:** + +```bash +curl --location 'http://localhost:9944' \ +--header 'Content-Type: application/json' \ +--data '{ + "jsonrpc": "2.0", + "method": "starknet_getStorageAt", + "params": { + "contract_address": "0x124aeb495b947201f5fac96fd1138e326ad86195b98df6dec9009158a533b49", + "key": "0x1001e85047571380eed1d7e1cc5a9af6a707b3d65789bb1702c7d680e5e87e", + "block_id": "latest" + }, + "id": 1 +}' +``` + +### Perform an trace call + +To get detailed information about a specific storage value at a specific moment you can run the `starknet_getStorageAt` historical call. + +**Example Request:** + +```bash +curl --location 'https://free-rpc.nethermind.io/mainnet-juno/' \ +--header 'Content-Type: application/json' \ +--data '{ + "jsonrpc": "2.0", + "method": "starknet_traceTransaction", + "params": { + "transaction_hash": "0x7641514f46a77013e80215cdce2e55d5aca49c13428b885c7ecb9d3ddb4ab11" + }, + "id": 1 +}' +``` + +### Using JSON-RPC Clients and Libraries + +While `curl` is useful for quick tests, you can use programming languages and libraries to interact with the RPC endpoint more efficiently. + +#### Using JavaScript and Axios + +**JavaScript Example:** + +```javascript +const axios = require('axios'); + +const rpcEndpoint = 'http://localhost:9944/'; + +const getBlockNumber = async () => { + try { + const response = await axios.post(rpcEndpoint, { + jsonrpc: '2.0', + method: 'starknet_blockNumber', + params: [], + id: 1 + }); + console.log('Current block number:', response.data.result); + } catch (error) { + console.error('Error:', error.response.data.error); + } +}; + +getBlockNumber(); +``` + +### Exploring Available Methods + +You can find the list of available methods in the [Starknet JSON-RPC methods documentation](https://github.com/starkware-libs/starknet-specs). + +**Commonly Used Methods:** + +- `starknet_getTransactionByHash` +- `starknet_getTransactionReceipt` +- `starknet_getClass` +- `starknet_getNonce` +- `starknet_getEvents` + +### Using RPC Playgrounds + +To experiment with JSON-RPC methods interactively, you can use online tools: + +- **Voyager Playground**: [rpc-request-builder.voyager.online](https://rpc-request-builder.voyager.online/) +- **OpenRPC Playground**: [playground.open-rpc.org](https://playground.open-rpc.org/?uiSchema%5BappBar%5D%5Bui:splitView%5D=false&schemaUrl=https://raw.githubusercontent.com/starkware-libs/starknet-specs/master/api/starknet_api_openrpc.json&uiSchema%5BappBar%5D%5Bui:input%5D=false&uiSchema%5BappBar%5D%5Bui:darkMode%5D=true&uiSchema%5BappBar%5D%5Bui:examplesDropdown%5D=false) + + + **Note**: Adjust the endpoint URL in these tools to point to your Madara node. + + +### Next Steps + +Now that you're familiar with querying the Madara RPC endpoint, you can: + +- **Build Applications**: Create applications that interact with the Starknet network. +- **Monitor Blockchain Data**: Track events, transactions, and state changes. +- **Integrate Tools**: Use wallets and other tools that leverage the JSON-RPC API. + + + + + For more advanced interactions, consider using Starknet SDKs or client libraries that provide higher-level abstractions over the JSON-RPC API. + + +## Summary + +In this tutorial, you've learned how to: + +- **Access the Madara RPC Endpoint**: Connect to your node's RPC interface. +- **Send JSON-RPC Requests**: Query blockchain data and interact with smart contracts. +- **Handle Responses and Errors**: Interpret successful responses and manage errors. +- **Use Tools and Libraries**: Leverage programming languages and online tools for efficient interaction. + +By leveraging the JSON-RPC interface, you can fully interact with the Starknet network through your Madara Full Node. + +--- \ No newline at end of file