Merge branch 'main' into joroshiba/gh-pages-configure

docs/dev-cluster/1-overview.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+---
+
+# Dev-Cluster Overview
+
+Astria's Shared Sequencer Network allows multiple rollups to share a single decentralized network of sequencers that’s permissionless to join. This shared sequencer network provides out-of-the-box censorship resistance, fast block confirmations, and atomic cross-rollup inclusion guarantees.
+
+The Astria [dev-cluster](https://github.com/astriaorg/dev-cluster) is the
+collective stack of all of Astria's components packaged together using
+Kubernetes. While we generally refer to Astria as the network of shared
+sequencers, we provide several other components to make it simpler to integrate
+with the shared sequencer network. The dev-cluster is provided to make
+developing and testing the Astria network, as well as integrations with Astria,
+as simple as possible.
+
+:::tip
+The primary use of the dev-cluster is running the full stack completely locally.
+There are elements of it that are used for running a local rollup that connects
+to the remote dev-net, but those will be [discussed in another
+section](/docs/running-a-rollup-on-astria-dusknet/local-rollup-deployment/).
+:::
+
+See the [dev-cluster repo here.](https://github.com/astriaorg/dev-cluster)

docs/dev-cluster/2-run-dev-cluster-locally.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 2
+---
+
+# Running the Dev Cluster Locally
+
+### Installation
+You will need to pull both the [dev-cluster](https://github.com/astriaorg/dev-cluster) and [astria-web3](https://github.com/astriaorg/astria-web3) repos from our github.
+
+Install the necessary dependencies and tools listed for each repo:
+
+* docker - https://docs.docker.com/get-docker/
+* kubectl - https://kubernetes.io/docs/tasks/tools/
+* helm - https://helm.sh/docs/intro/install/
+* kind - https://kind.sigs.k8s.io/docs/user/quick-start/#installation
+* just - https://just.systems/man/en/chapter_4.html
+
+For contract deployment:
+
+* Forge (part of Foundry) - https://book.getfoundry.sh/getting-started/installation
+
+### Deployment
+
+:::tip
+Make sure that Docker is running before deploying with `just`.
+:::
+
+To deploy the Astria Sequencer and a local DA, open a terminal in the dev-cluster directory and run the commands: 
+```bash
+# create control plane cluster
+just create-cluster
+# ingress controller
+just deploy-ingress-controller
+# wait for ingress.
+just wait-for-ingress-controller
+# Deploys Sequencer + local DA
+just deploy-astria-local
+```
+
+This may take a minute or two if this the first time you are deploying as quite
+a few containers need to be downloaded. Once the command completes, all elements
+of the dev-cluster will be up and running. This does not run a rollup, block
+explorer, or faucet. 
+
+Now that the sequencer and DA are running, the next step is to deploy a rollup.

docs/dev-cluster/3-deploy-a-local-rollup.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 3
+---
+
+# Running a Local Rollup
+
+### Faucet, Block Explorer, and Test Data
+With the dev-cluster running, you can then deploy a rollup, block explorer, and
+faucet by running the following command in the terminal withing the dev-cluster:
+
+```sh
+just deploy-rollup
+```
+
+This `just` command launches a local rollup, block explorer, and faucet using
+the default in
+[helm/rollup/values.yaml](https://github.com/astriaorg/dev-cluster/blob/main/helm/rollup/values.yaml)
+in the `config.rollup` definition.
+
+For reference, these are:
+- Rollup name: `astria`
+- Network Id: `912559`
+
+This will also take a moment as the rollup node, block explorer, and faucet spin
+up. You can check the progress of the deployment with the following command:
+
+```bash
+kubectl get deployments --all-namespaces
+```
+
+Or you can run:
+```bash
+just wait-for-rollup
+```
+
+Once deployed, you can view the block explorer and faucet by opening a couple new windows in your browser and going to to the
+following urls.
+For the block explorer:
+```
+http://blockscout.astria.localdev.me/
+```
+For the faucet:
+```
+http://faucet.astria.localdev.me/
+```
+
+You can copy and paste a wallet address on the faucet page and give yourself 1 RIA. 
+
+To test out the block explorer, open a terminal in the [astria-web3 repo](https://github.com/astriaorg/astria-web3/tree/main) you downloaded earlier and navigate to the `packages/evm-test-data/` and run the following command:
+```sh
+just generate-transactions
+```
+This command uses the default rollup name and network id (see above), and will
+submit commands to the newly deployed default rollup.
+
+You can now go back to your browser and pull up the block explorer and you will now see blocks with transactions getting created in real time.

docs/dev-cluster/4-run-multiple-rollups-locally.md

@@ -0,0 +1,96 @@
+---
+sidebar_position: 4
+---
+
+# Run Multiple Rollups Locally
+
+At Astria we believe strongly that deploying a rollup should be as easy as deploying a smart contract. The dev-cluster shows this is indeed possible.
+
+Navigate back to the [dev-cluster](https://github.com/astriaorg/dev-cluster)
+repo in your terminal and run the following command with your own rollup name
+and network id:
+
+:::warning
+
+**NOTE:** The default rollup name and network id are `astria` and `912559`. When
+deploying your second rollup you ___must___ use a different name and number.
+
+:::
+
+```sh
+just deploy-rollup <rollup_name> <network_id>
+```
+
+As before, it will take a moment for everything to spin up, but in the meantime keep the the rollup name and network id handy and navigate back to your browser and open a new window with the following url, replacing `rollup_name` with the name you just used to deploy your new rollup:
+
+```
+http://blockscout.<rollup_name>.localdev.me/
+```
+
+Once everything has spin up you will see a new block explorer for your new rollup.
+
+You can now deploy transaction to that rollup independently.
+In the `astria-web3/packages/evm-test-data` directory open a new terminal and run the following:
+
+```sh
+just generate-transactions <rollup_name> <network_id>
+```
+
+As before, this command will deploy test transaction data to your new rollup.
+You can also go back to your original terminal window for the test data deployment on the default rollup and rerun the `just generate-transactions` command. If you switch back and forth between the default block explorer window and your new rollup window, you will see transactions showing up on each rollup independently!
+
+To navigate to the new Block Explorer and Faucet from the additional rollup,
+take the rollup name that you used and replace `<rollup_name>` in the urls
+below:
+
+```
+http://blockscout.<rollup_name>.localdev.me/
+http://faucet.<rollup_name>.localdev.me/
+```
+
+The only limitations to running numerous rollups are the following:
+ - Can your hardware handle it
+ - There are no rollup name and network id clashes
+
+### What's Going on Under the Hood?
+
+One last thing to mention is what is actually happening when you deploy a new rollup in the dev-cluster. When you you deploy a new rollup the only new containers that are getting spun up in the cluster are a new rollup node, a conductor, block explorer, and faucet. Only one instance of the shared sequencer and the DA layer remain running and the transactions from all the rollups are collectively getting run though those networks.
+
+![Multiple Rollups](assests/multiple-rollups.png)
+
+You can also use `kubectl` to see that this is the case.
+
+When running only the default rollup:
+
+```bash
+dev-cluster % kubectl get deployments --all-namespaces
+NAMESPACE            NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
+astria-dev-cluster   astria-blockscout          1/1     1            1           37s
+astria-dev-cluster   astria-faucet              1/1     1            1           37s
+astria-dev-cluster   astria-geth                1/1     1            1           37s
+astria-dev-cluster   celestia-local             1/1     1            1           94m
+astria-dev-cluster   sequencer                  1/1     1            1           94m
+ingress-nginx        ingress-nginx-controller   1/1     1            1           94m
+kube-system          calico-kube-controllers    1/1     1            1           95m
+kube-system          coredns                    2/2     2            2           95m
+local-path-storage   local-path-provisioner     1/1     1            1           95m
+```
+
+After deploying the second rollup:
+
+```bash
+dev-cluster % kubectl get deployments --all-namespaces
+NAMESPACE            NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
+astria-dev-cluster   anotherrollup-blockscout   1/1     1            1           114s
+astria-dev-cluster   anotherrollup-faucet       1/1     1            1           114s
+astria-dev-cluster   anotherrollup-geth         1/1     1            1           114s
+astria-dev-cluster   astria-blockscout          1/1     1            1           2m13s
+astria-dev-cluster   astria-faucet              1/1     1            1           2m13s
+astria-dev-cluster   astria-geth                1/1     1            1           2m13s
+astria-dev-cluster   celestia-local             1/1     1            1           95m
+astria-dev-cluster   sequencer                  1/1     1            1           95m
+ingress-nginx        ingress-nginx-controller   1/1     1            1           96m
+kube-system          calico-kube-controllers    1/1     1            1           97m
+kube-system          coredns                    2/2     2            2           97m
+local-path-storage   local-path-provisioner     1/1     1            1           97m
+```

docs/dev-cluster/5-shutdown.md

@@ -0,0 +1,31 @@
+---
+sidebar_position: 5
+---
+
+# Shutting Down the Cluster
+
+## Deleting Specific Rollups
+
+To delete a specific rollup deployment, you can use the following command:
+```bash
+just delete-rollup <ROLLUP_NAME>
+```
+
+This will remove the rollup, its block explorer, and faucet, but keep the rest
+of the cluster running.
+
+## Shutting Down the Whole Cluster
+
+If you just want to shut everything down, you can run:
+```bash
+just clean
+```
+
+To delete all the data that may have also been created during your testing, you
+can then run:
+
+```bash
+just clean-persisted-data
+```
+
+Which will delete all the local data created.

docs/dev-cluster/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Local Dev Cluster",
+  "position": 2,
+  "link": {
+    "type": "doc",
+    "id": "dev-cluster/overview"
+  }
+}

docs/overview-of-astria/1-introduction.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 1
+---
+
+# Introduction
+
+Astria is a shared sequencing network that allows many rollups to share a single
+decentralized network of sequencers. These sequencers are simple and
+permissionless to join, completely replacing centralized sequencers.
+
+This shared sequencer network provides out-of-the-box censorship resistance,
+fast block confirmations, and atomic cross-rollup composability – all while
+retaining each rollup’s sovereignty.
+Astria envisions a future where thousands of decentralized rollups
+flourish, each one tailored to meet the unique requirements of different
+industries, applications, and use cases. 
+
+To achieve this vision, we believe that
+deploying an economically secure, decentralized, and censorship-resistant rollup
+should be as easy as deploying a smart contract. 
+
+See the [Astria repo here.](https://github.com/astriaorg/astria)

docs/overview-of-astria/2-why-decentralized-sequencers.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 2
+---
+
+# Why Decentralized Sequencers?
+
+Centralization is antithetical to crypto. And yet, today’s rollups almost universally depend on a single sequencer. Centralized sequencers provide fast transaction confirmations and reduce costs by batching and compressing transactions. However, these benefits come at the cost of relying on a single trusted actor for liveness and censorship resistance.
+
+**Sacrificing decentralization for an improved user experience is an unacceptable Faustian bargain.**
+
+Astria tackles centralization head-on, providing rollups with a decentralized sequencer and even better UX. Astria’s shared sequencer network is a middleware blockchain with its own decentralized sequencer set which accepts transactions from multiple rollups. These transactions are ordered into a single block and written to the base layer without executing them.
+
+![Shared Sequencers](assets/shared_sequencer.png)

docs/overview-of-astria/3-cross-rollup-composability.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 3
+---
+
+# Croll-Rollup Composability
+
+Because Astria handles the transaction ordering for multiple rollups, it’s able to provide guarantees that transactions are only included as part of an atomic bundle. This allows users to specify that a transaction on Rollup A can be included in a block if and only if a different transaction on Rollup B is also included in the same block. By enabling such conditional transaction inclusion, Astria unlocks exciting possibilities such as atomic cross-rollup arbitrage.

docs/overview-of-astria/4-maintain-sovereignty.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 4
+---
+
+# Maintain Sovereignty
+
+Sovereignty is important, so rollups must be able to receive the benefits of
+Astria without fear of being locked in. That’s why swapping out the sequencing
+layer is as simple as updating a rollup node’s software to use a different fork
+choice rule at a chosen block height. Transaction data is stored on the base
+layer (eg. Celestia), and rollup full nodes hold the state and perform
+execution, this means there’s nothing that Astria can do to hold the rollup
+hostage.

docs/overview-of-astria/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Overview of Astria",
+  "position": 1,
+  "link": {
+    "type": "doc",
+    "id": "overview-of-astria/introduction"
+  }
+}

docs/overview-of-astria/architecture/1-overview.md

@@ -0,0 +1,25 @@
+---
+sidebar_position: 1
+---
+
+# Architecture Overview
+
+At a high level, Astria breaks out all of the components that are historically
+combined together in monolithic blockchains into individual components. This
+results in a modular ecosystem that allows users to swap out components to fit
+their specific needs.
+
+![Astria Architecture](../assets/astria-architecture.png)
+
+Given this architecture, rollups can retrieve blocks from Astria immediately after they’re created, without waiting for the base layer to include them. The economic weight of Astria’s decentralized sequencer set provides confidence that this transaction order is final. This “soft commitment” allows rollups to provide their end users with fast block confirmations. Alternatively, rollups can wait for blocks to be included by the base layer, giving them the strongest finality. All transactions still get this “firm commitment” at the speed of the base layer, fast pre-confirmations are just an additional feature that Astria provides to rollups if they choose to use it.
+
+To generate a new state root, a rollup’s full nodes retrieve a block from either
+Astria or the base layer, check it against Astria’s fork choice rule, filter out
+transactions from other rollups, and apply the resultant subset of transactions
+to their previous state. Headers can then be generated from this state root and
+gossiped to light clients. Rollups of this style are termed ‘Lazy Rollups’, a
+nod to the [Lazy
+Evaluation](https://en.wikipedia.org/wiki/Lazy_evaluation?ref=blog.astria.org)
+principle found in programming language theory.
+
+See the [Astria repo here.](https://github.com/astriaorg/astria)

docs/overview-of-astria/architecture/2-transaction-flow.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 2
+---
+
+# Transaction Flow
+
+The full transaction flow through the Astria stack is as follows:
+
+![Astria Transaction Flow](../assets/transaction-flow.png)

docs/overview-of-astria/architecture/3-rollup.md

@@ -0,0 +1,22 @@
+---
+sidebar_position: 3
+---
+
+# Rollups
+
+Astria is designed for permissionless rollup integration and takes advantage of [lazy](https://en.wikipedia.org/wiki/Lazy_evaluation?ref=blog.astria.org) shared sequencing. This means that rollup developers have total sovereignty over their own execution state and can swap out sequencing layers without fear of being locked in. You do not need to ask for permission or go through a governance process to gain access. A rollup simply needs to satisfy the following interfaces:
+
+Write Interface (Rollup <-> Composer):
+- For transaction submissions.
+
+Read Interface (Rollup <-> Conductor):
+- For receiving blocks from the shared sequencer network.
+
+![Single Rollup](../assets/single-rollup.png)
+
+The Composer and Conductor are explained in more detail in future sections.
+
+Both composer and conductor expose [gRPC](https://grpc.io/) interfaces. See the [astria-protos](https://github.com/astriaorg/astria/tree/main/crates/astria-proto) repo for specific implementation details.
+
+Astria currently deploys a fork of
+[Geth](https://github.com/astriaorg/go-ethereum) as an EVM rollup.