doc: improve docs (#1269)

Author: apoorvsadana

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Next release
 
+- chore: update README.md and getting-started.md
 - chore: remove crates that have been copy-pasted from plkdtSDK
 - feat(rpc): return deployed contract address and actual fee in transaction
   receipt

README.md

@@ -35,61 +35,86 @@
 </a>
 </div>
 
-# ⚡ Madara: Starknet Sequencer 👉👈
+# ⚡ Madara App Chain Stack
 
-Welcome to **Madara**, a blazing fast ⚡ [Starknet](https://www.starknet.io/)
-sequencer designed to make your projects soar!
+Welcome to **Madara**, the modular stack to build chains using
+[Cairo](https://book.cairo-lang.org/title-page.html) and the
+[Starknet](https://www.starknet.io/) technology. Apps like dYdX V3, Immutable
+and Sorare have been using StarkEx for scaling for a while and now with Madara,
+it's open source for everyone to use.
 
-Built on the robust Substrate framework and fast, thanks to Rust 🦀, Madara
-delivers unmatched performance and scalability to power your Starknet-based
-Validity Rollup chain.
+Madara is built on the [Substrate](https://substrate.io/) framework which not
+only makes it modular but also gives it access to years of dev tooling,
+libraries and a strong developer community. It is specifically helpful if you
+want to own more of the stack and get more control over your chain.
 
-Dive into the world of Madara and join our passionate community of contributors!
-Together, we're pushing the boundaries of what's possible within the Starknet
-ecosystem.
+## 📚 Documentation
 
-🚀 Discover the unparalleled flexibility and might of Madara, your gateway to
-launching your very own Starknet appchain or L3. Harness the prowess of Cairo,
-while maintaining complete control over your custom appchain, tailored to your
-specific requirements. Madara is designed to empower a multitude of projects,
-fueling growth within the Starknet ecosystem.
+Get started with our comprehensive documentation, which covers everything from
+project structure and architecture to benchmarking and running Madara:
+
+- [Getting Started Guide](./docs/getting-started.md)
+- [Architecture Overview](./docs/architecture.md)
+- [Chain Genesis Information](./docs/genesis.md)
+- [Project Structure](./docs/project-structure.md)
+- [Run benchmark yourself](./benchmarking/README.md)
+
+## 📣 Building App Chains
+
+For many use cases, you do not need to fork this repo to build your app chain.
+By adding changes using forking, you will have to periodically rebase (and solve
+conflicts) to remain updated with the latest version of Madara. Madara by
+default provides
+
+- `pallet_starknet`: Adds the CairoVM to Substrate which allows you to deploy
+  and execute Cairo contracts.
+- `Starknet RPC`: Adds all the Starknet RPC calls to your chain so that it's
+  compatible with all RPC tools like starknet-js, wallets, etc.
+- `DA Interface`: A general interface which allows you to use any DA layer like
+  `Avail`, `Celestia`, `Ethereum` etc.
+- `Proving`: Running the Starknet OS which is the runtime logic in Cairo so that
+  it can be proven on the L1.
+
+So for many use cases where you want to change common things like
+
+- Configuration
+  [parameters](https://github.com/keep-starknet-strange/madara/blob/d90cb1a3ce5389f5f530ee5eaf3c3d4c96561b12/crates/runtime/src/pallets.rs#L33)
+  for example block time, maximum steps etc.
+- DA layer
+- Genesis state
+- Add new off chain workers
+- Add new pallets
+
+you don't need to fork the Madara repo. Instead, you can import the relevant
+code as crates/pallets. We have created an
+[app-chain-template](https://github.com/keep-starknet-strange/madara-app-chain-template)
+which imports Madara as a library to show an example and would recommend you
+start from here. For other more detailed use cases like
+
+- Adding a new syscall to the cairo VM
+- Changing the runtime logic to deviate from Starknet's logic
+
+You should consider forking parts of Madara.
 
 ## 📣 Peripheral repositories
 
-- [Madara Explorer](https://github.com/lambdaclass/madara_explorer) by the great
-  [LambdaClass](https://lambdaclass.com/) team 🫶: A block explorer for Madara.
+- [Madara Docsite](https://github.com/keep-starknet-strange/madara-docs): The
+  source code of the Madara documentation website. Deployed on
+  `https://docs.madara.zone`.
+- [Stark Compass Explorer](https://github.com/lambdaclass/madara_explorer) by
+  the [LambdaClass](https://lambdaclass.com/) team : An open source block
+  explorer for Starknet based chains.
 - [Madara Infra](https://github.com/keep-starknet-strange/madara-infra): A
   collection of scripts and tools to deploy and manage Madara on different
   environments (e.g. AWS, docker, ansible, etc.). It also contains the
   [Starknet Stack](https://github.com/keep-starknet-strange/madara-infra/blob/main/starknet-stack/docker-compose.yml)
   demo `docker-compose` file.
-- [Madara Kit Application](https://github.com/keep-starknet-strange/madara-app):
-  A simple application that demonstrates how to use Madara. Deployed on
-  `https://app.madara.zone`.
-- [Madara Docsite](https://github.com/keep-starknet-strange/madara-docs): The
-  source code of the Madara documentation website. Deployed on
-  `https://docs.madara.zone`.
 - [Madara Tsukuyomi](https://github.com/keep-starknet-strange/madara-tsukuyomi):
   The source code of the Madara Desktop App. A friendly GUI to start a Madara
   node and interact with it.
 - [App Chain Template](<(https://github.com/keep-starknet-strange/madara-app-chain-template)>):
   A ready to use template that allows you to easily start an app chain.
 
-## 📣 Building App Chains
-
-> Do NOT fork this repo and build your app chain on top unless completely
-> necessary. By adding changes using forking, you will have to periodically
-> rebase (and solve conflicts) to remain updated with the latest version of
-> Madara.
-
-One of the main features of Madara is to allow users to start their app chains
-that support Cairo contracts and Starknet like blocks. Hence, to make it easy
-for users to build a custom app chain, we have created an
-[app-chain-template](https://github.com/keep-starknet-strange/madara-app-chain-template)
-which imports Madara as a pallet. This removes all the boilerplate code and
-allows you to focus on code only relevant to your app chain. Moreover, updating
-Madara is as simple as updating the pallet version.
-
 ## 🌟 Features
 
 - Starknet sequencer 🐺
@@ -99,17 +124,6 @@ Madara is as simple as updating the pallet version.
 - Comprehensive documentation 📚
 - Active development and community support 🤝
 
-## 📚 Documentation
-
-Get started with our comprehensive documentation, which covers everything from
-project structure and architecture to benchmarking and running Madara:
-
-- [Architecture Overview](./docs/architecture.md)
-- [Chain Genesis Information](./docs/genesis.md)
-- [Project Structure](./docs/project-structure.md)
-- [Getting Started Guide](./docs/getting-started.md)
-- [Run benchmark yourself](./benchmarking/README.md)
-
 ## 🏗️ Build & Run
 
 Want to dive straight in? Check out our

docs/getting-started.md

@@ -11,45 +11,64 @@ then run:
 rustup show
 ```
 
-### Cargo Run
+### Single-Node Development Chain
 
 Use Rust's native `cargo` command to build and launch the template node:
 
+You first need to setup up the node, which means you need to load the genesis
+state into your file system.
+
 ```sh
 cargo run --release -- setup --chain=dev --from-remote
-cargo run --release -- --dev
 ```
 
-The node also supports to use manual seal (to produce block manually through
-RPC). This is also used by the typescript tests:
+Now, you can start the node in development mode
 
 ```sh
-$ cargo run --release -- --dev --sealing=manual
-# Or
-$ cargo run --release -- --dev --sealing=instant
+cargo run --release -- --dev
 ```
 
-Log level can be specified with `-l` flag. For example, `-ldebug` will show
-debug logs. It can also be specified via the `RUST_LOG` environment variable.
-For example:
+### Interacting with the node
 
-```sh
-RUSTLOG=runtime=info cargo run --release -- --dev
-```
+Madara is compatible with the Starknet
+[spec](https://github.com/starkware-libs/starknet-specs) which means all tooling
+around Starknet (starknet-js, starknet-rs, wallets, etc.) can be used out of the
+box by just changing the RPC url to point to your node. By default, this would
+be `http://localhost:9944`.
+
+### Common chain flags
+
+You can check all the available using the `--help` flag. Some common points to
+know about have been mentioned below.
+
+Madara overrides the default `dev` flag in substrate to meet its requirements.
+The following flags are automatically enabled with the `--dev` argument:
+
+`--chain=dev`, `--force-authoring`, `--alice`, `--tmp`, `--rpc-external`,
+`--rpc-methods=unsafe`
 
-### Cargo Build
+The `--tmp` flag stores the chain database in a temporary folder. You can
+specify a custom folder to store the chain state by using the `--base-path`
+flag. You cannot combine the `base-path` command with `--dev` as `--dev`
+enforces `--tmp` which will store the db at a temporary folder. You can,
+however, manually specify all flags that the dev flag adds automatically. Keep
+in mind, the path must be the same as the one you used in the setup command.
 
-The `cargo run` command will perform an initial build. Use the following command
-to build the node without launching it:
+The node also supports to use manual seal (to produce block manually through
+RPC).
 
 ```sh
-cargo build --release
+cargo run --release -- --dev --sealing=manual
+# Or
+cargo run --release -- --dev --sealing=instant
 ```
 
-You can optionally specify the compiler version for the build:
+Log level can be specified with `-l` flag. For example, `-ldebug` will show
+debug logs. It can also be specified via the `RUST_LOG` environment variable.
+For example:
 
 ```sh
-COMPILER_VERSION=0.12.0 cargo build --release
+RUSTLOG=runtime=info cargo run --release -- --dev
 ```
 
 ### Using Nix (optional, only for degens)
@@ -69,67 +88,6 @@ all parameters and subcommands:
 ./target/release/madara -h
 ```
 
-## Run
-
-The provided `cargo run` command will launch a temporary node and its state will
-be discarded after you terminate the process. After the project has been built,
-there are other ways to launch the node.
-
-### Single-Node Development Chain
-
-This command will start the single-node development chain with non-persistent
-state:
-
-```bash
-./target/release/madara setup --chain=dev --from-remote
-./target/release/madara --dev
-```
-
-Purge the development chain's state:
-
-```bash
-./target/release/madara purge-chain --dev
-```
-
-Start the development chain with detailed logging:
-
-```bash
-RUST_BACKTRACE=1 ./target/release/madara -ldebug --dev
-```
-
-> Development chain means that the state of our chain will be in a tmp folder
-> while the nodes are running. Also, **alice** account will be authority and
-> sudo account as declared in the
-> [genesis state](https://github.com/substrate-developer-hub/substrate-madara/blob/main/node/src/chain_spec.rs#L49).
-> At the same time the following accounts will be pre-funded:
->
-> - Alice
-> - Bob
-> - Alice//stash
-> - Bob//stash
-
-In case of being interested in maintaining the chain' state between runs a base
-path must be added so the db can be stored in the provided folder instead of a
-temporal one. We could use this folder to store different chain databases, as a
-different folder will be created per different chain that is ran. The following
-commands shows how to use a newly created folder as our db base path.
-
-```bash
-// Create a folder to use as the db base path
-$ mkdir my-chain-state
-
-// Use of that folder to store the chain state
-$ ./target/release/madara --dev --base-path ./my-chain-state/
-
-// Check the folder structure created inside the base path after running the chain
-$ ls ./my-chain-state
-chains
-$ ls ./my-chain-state/chains/
-dev
-$ ls ./my-chain-state/chains/dev
-db keystore network
-```
-
 ### Connect with Polkadot-JS Apps Front-end
 
 Once the node template is running locally, you can connect it with **Polkadot-JS