diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index bf80c59..56e651a 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -4,7 +4,7 @@ const { BASE: base = "/" } = process.env; // https://vitepress.dev/reference/site-config export default defineConfig({ title: "Astria", - description: "The Shared Sequencer Network", + description: "The Sequencing Layer Network", lastUpdated: true, cleanUrls: true, ignoreDeadLinks: true, @@ -47,22 +47,21 @@ function sidebar() { text: 'What is Astria?', collapsed: true, items: [ - { text: 'Overview', link: '/overview/1-introduction' }, - { text: 'Why Decentralized Sequencers?', link: '/overview/2-why-decentralized-sequencers' }, - { text: 'Cross-Rollup Composability', link: '/overview/3-cross-rollup-composability' }, - + { text: 'Overview', link: '/overview/introduction' }, + { text: 'How Rollups Work', link: '/overview/how-rollups-work'}, + { text: 'The Astria Sequencer Network', link: '/overview/the-astria-sequencer-network' }, + { text: 'Bridging', link: '/overview/bridging' }, + { text: 'Transaction Flow', link: '/overview/transaction-flow' }, { - text: 'Architecture', + text: 'Components', collapsed: true, items: [ - { text: 'Overview', link: '/overview/architecture/1-overview' }, - { text: 'Transaction Flow', link: '/overview/architecture/2-transaction-flow' }, - { text: 'Rollups', link: '/overview/architecture/3-rollup' }, - { text: 'Composer', link: '/overview/architecture/4-composer' }, - { text: 'The Astria Sequencer', link: '/overview/architecture/5-the-astria-sequencer' }, - { text: 'Relayer', link: '/overview/architecture/6-relayer' }, - { text: 'Conductor', link: '/overview/architecture/7-conductor' }, - { text: 'Data Availability Layer', link: '/overview/architecture/8-data-availability-layer' }, + { text: 'Composer', link: '/overview/components/composer' }, + { text: 'The Astria Sequencer', link: '/overview/components/the-astria-sequencer' }, + { text: 'Relayer', link: '/overview/components/relayer' }, + { text: 'Data Availability Layer', link: '/overview/components/data-availability-layer' }, + { text: 'Conductor', link: '/overview/components/conductor' }, + ] }, ] @@ -77,14 +76,6 @@ function sidebar() { text: 'Tutorials', collapsed: true, items: [ - { text: 'Deploy a Local Rollup', link: '/local-rollup/1-introduction' }, - { - text: 'Deploy a Cloud Rollup', - collapsed: true, - items: [ - { text: 'Digital Ocean', link: '/cloud-rollup/digital-ocean' }, - ] - }, { text: 'Using the Astria cli', collapsed: true, @@ -141,8 +132,8 @@ function nav() { { text: "Join the network", items: [ - { text: "Learn", link: "/overview/1-introduction" }, - { text: "Developers", link: "/local-rollup/1-introduction" }, + { text: "Learn", link: "/overview/introduction" }, + { text: "Developers", link: "/developer/tutorials/1-using-astria-cli-go" }, { text: "Community", link: '/community/1-overview' }, ], }, diff --git a/docs/astria-evm/overview.md b/docs/astria-evm/overview.md index dcd49b3..2741ffd 100644 --- a/docs/astria-evm/overview.md +++ b/docs/astria-evm/overview.md @@ -8,28 +8,32 @@ sidebar_position: 1 | Property | Value | |-----|-----| -| Network Name | dusk-3 | -| RPC URL | [https://rpc.evm.dusk-3.devnet.astria.org](https://rpc.evm.dusk-3.devnet.astria.org) | +| Network Name | dusk-7 | +| RPC URL | [https://rpc.evm.dusk-7.devnet.astria.org](https://rpc.evm.dusk-7.devnet.astria.org) | | Chain ID | 912559 | | Currency Symbol | RIA | | Dora | [https://www.ondora.xyz/network/astria-devnet](https://www.ondora.xyz/network/astria-devnet) | -| Faucet | [https://faucet.evm.dusk-3.devnet.astria.org](https://faucet.evm.dusk-3.devnet.astria.org) | -| Block Scout | [https://explorer.evm.dusk-3.devnet.astria.org/](https://explorer.evm.dusk-3.devnet.astria.org/) | +| Faucet | [https://faucet.evm.dusk-7.devnet.astria.org](https://faucet.evm.dusk-7.devnet.astria.org) | +| Block Scout | [https://explorer.evm.dusk-7.devnet.astria.org/](https://explorer.evm.dusk-7.devnet.astria.org/) | ## Adding to Metamask Follow Metamask's official documentation to [manually add a custom network.](https://support.metamask.io/hc/en-us/articles/360043227612-How-to-add-a-custom-network-RPC#h_01G63GGJ83DGDRCS2ZWXM37CV5) -Your settings should look like the image below +Your settings should be the following: -![Metamask](assets/metamask-dusk2.png) +* Network Name: `dusk-7` +* New RPC URL: `https://rpc.evm.dusk-7.devnet.astria.org` +* Chain ID: `912559` +* Currency symbol: `RIA` +* Block Explorer URL: `` ## Using Cast Set your `ETH_RPC_URL`: ```bash -export ETH_RPC_URL=https://rpc-archive.evm.dusk-3.devnet.astria.org/ +export ETH_RPC_URL=https://rpc-archive.evm.dusk-7.devnet.astria.org/ ``` ```bash diff --git a/docs/cloud-rollup/assets/a-record.png b/docs/cloud-rollup/assets/a-record.png deleted file mode 100644 index d300a6b..0000000 Binary files a/docs/cloud-rollup/assets/a-record.png and /dev/null differ diff --git a/docs/cloud-rollup/assets/cname-record-example.png b/docs/cloud-rollup/assets/cname-record-example.png deleted file mode 100644 index e20df5c..0000000 Binary files a/docs/cloud-rollup/assets/cname-record-example.png and /dev/null differ diff --git a/docs/cloud-rollup/assets/do-setup.png b/docs/cloud-rollup/assets/do-setup.png deleted file mode 100644 index 0874855..0000000 Binary files a/docs/cloud-rollup/assets/do-setup.png and /dev/null differ diff --git a/docs/cloud-rollup/assets/doctl-screenshot.png b/docs/cloud-rollup/assets/doctl-screenshot.png deleted file mode 100644 index 25623ba..0000000 Binary files a/docs/cloud-rollup/assets/doctl-screenshot.png and /dev/null differ diff --git a/docs/cloud-rollup/assets/sequencer-faucet.png b/docs/cloud-rollup/assets/sequencer-faucet.png deleted file mode 100644 index 732c627..0000000 Binary files a/docs/cloud-rollup/assets/sequencer-faucet.png and /dev/null differ diff --git a/docs/cloud-rollup/digital-ocean.md b/docs/cloud-rollup/digital-ocean.md deleted file mode 100644 index 49b282a..0000000 --- a/docs/cloud-rollup/digital-ocean.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Digital Ocean - -This guide will walk you through deploying a rollup full node on -a Kubernetes cluster on Digital Ocean which uses the Astria shared sequencer network. - -## Local Dependencies - - - - - -## Dusknet Endpoints - - - - - -## Create a New Cluster - -This guide assumes you're using Digital Ocean's Kubernetes (K8s) service. - -Install and configure `doctl`: [https://docs.digitalocean.com/reference/doctl/how-to/install/](https://docs.digitalocean.com/reference/doctl/how-to/install/) - -Follow the instructions in Digital Ocean's [Quick Start Guide](https://docs.digitalocean.com/products/kubernetes/getting-started/) -to create a new cluster in the region of your choosing. - -:::tip -The celestia pod has a minimum requirement of 1vCPU and 4GB RAM and will not start if the -cluster has no nodes that meet those requirements. You will need a node with >1vCPU and >4GB RAM. -::: - -## Configure `kubectl` with `doctl` - -Once your k8s cluster is created configure `kubectl`. - -![doctl screenshot](assets/do-setup.png) - -## Deploy Ingress Nginx Controller - -We use the Nginx Ingress Controller, documentation can be found [here](https://kubernetes.github.io/ingress-nginx/deploy/#digital-ocean/) - -To install it run: - -```bash -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.2/deploy/static/provider/do/deploy.yaml -``` - -This will create several Kubernetes (k8s) resources and a Digital Ocean loadbalancer. - -## Verify Loadbalancer with external IP - -You should see a new loadbalancer being created in the Digital Ocean console: [https://cloud.digitalocean.com/networking/load_balancers](https://cloud.digitalocean.com/networking/load_balancers) - -You can also check that your Digital Ocean load balancer was created with: - -```bash -kubectl get svc -n ingress-nginx -``` - -It may take a few minutes for the `EXTERNAL-IP` field to be populated, -you should eventually see something like this: - -```bash -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -ingress-nginx-controller LoadBalancer 10.245.63.28 161.35.240.50 80:32656/TCP,443:30158/TCP 44h -ingress-nginx-controller-admission ClusterIP 10.245.106.99 443/TCP 44h -``` - -## Create an `A` Record - -:::tip -You must configure a DNS record because our ingress configuration uses name -based virtual routing. - -More info can be found [here](https://kubernetes.io/docs/concepts/services-networking/ingress/#name-based-virtual-hosting) -::: - -How you create an `A` record will depend on where you manage your domain. - -An example for Google domains can be seen here: [https://support.google.com/a/answer/2579934?hl=en](https://support.google.com/a/answer/2579934?hl=en) - -Create a wildcard record `*` pointing to the `EXTERNAL-IP` of your `ingress-nginx-controller`: - -![a record screenshot](assets/a-record.png) - -## Create your Rollup Genesis Account(s) - -:::danger -__NEVER__ use a private key you use on a live network. -::: - -Specify the accounts which will be funded at the genesis block of your EVM rollup. - -You can create an account using: - -```bash -cast w new -``` - -```bash -Successfully created new keypair. -Address: 0xfFe9...5f8b # -Private key: 0x332e...a8fb # -``` - -Export the genesis private key, -this will be used by the faucet included with the rollup: - -```bash -export ROLLUP_FAUCET_PRIV_KEY= -``` - -Export the genesis address alongside with your desired initial balance in Wei. -We recommend using a value of `100000000000000000000` or larger: - -```bash -export ROLLUP_GENESIS_ACCOUNTS=: -``` - -You can specify multiple accounts to be funded at genesis as - comma deliminated tuples of `
:` - -```bash -export ROLLUP_GENESIS_ACCOUNTS=:,: -``` - -## Create Rollup Config - -Create the configuration manifest for your rollup. - -Replace the tags in the commands and env vars below, as follows: - -| Var Name | Var Type | Description | -|-----|-----|-----| -| `` | String | The name of your rollup. This must be alphanumeric, `-` is allowed, this will be included in URLs. Must not be more than 21 characters.| -| `` | u64 | The id of your network. Pick a > 6 digit number (eg. `123456`) | -| `` | String | The chosen hostname for your network (eg. `astria.org`) | - -You can use environment variables to set the configuration for the rollup -config creation. Replace all the `<>` tags with their corresponding values. - -```bash -export ROLLUP_NAME= -export ROLLUP_NETWORK_ID= -export ROLLUP_HOSTNAME= -``` - -Run the config create command: - -```sh -astria-cli rollup config create -``` - -Export the config file name as an env vars: - -```bash -export ROLLUP_CONF_FILE=$ROLLUP_NAME-rollup-conf.yaml -``` - -Verify the config - -```bash -cat $ROLLUP_CONF_FILE -``` - -```bash -global: - namespace: astria-dev-cluster - useTTY: false - logLevel: debug -config: - rollup: - name: - chainId: -chain - networkId: '' - genesisAccounts: - - address: - balance: '' - sequencer: - initialBlockHeight: - websocket: wss://rpc.sequencer.dusk-3.devnet.astria.org/websocket - rpc: https://rpc.sequencer.dusk-3.devnet.astria.org -ingress: - hostname: -celestia-node: - config: - labelPrefix: -``` - -## Create new sequencer account - -Create an account on the Astria shared sequencer network - for your rollup to submit transactions. - -```bash -astria-cli sequencer account create -``` - -```bash -Create Sequencer Account - -Private Key: "5562...1622" # -Public Key: "ec20...f613" # -Address: "8a2f...5f68" # -``` - -Export your sequencer private key and address as environment variables: - -```bash -export SEQUENCER_PRIV_KEY=5562...1622 -export SEQUENCER_ACCOUNT_ADDRESS=8a2f...5f68 -``` - -## Fund your Sequencer Account - -Navigate to [https://faucet.sequencer.dusk-3.devnet.astria.org/](https://faucet.sequencer.dusk-3.devnet.astria.org/) -to view the sequencer faucet. - -Enter your `` into the text box - to send funds to your account: - -![Sequencer Faucet](assets/sequencer-faucet.png) - -Verify your account received the funds - -```bash -astria-cli sequencer account balance $SEQUENCER_ACCOUNT_ADDRESS -``` - -## Deploy the Rollup Node - -Use the `astria-cli` to deploy the rollup node - -```bash -astria-cli rollup deployment create \ - --config $ROLLUP_CONF_FILE \ - --faucet-private-key $ROLLUP_FAUCET_PRIV_KEY \ - --sequencer-private-key $SEQUENCER_PRIV_KEY -``` - -## Watch for rollup startup - -You can watch for the Kubernetes pods of the rollup to start with: - -```bash -kubectl get pods -n astria-dev-cluster -w -``` - -```bash -NAME READY STATUS RESTARTS AGE --blockscout-647745c66d-vz4ks 6/6 Running 1 (56s ago) 72s --celestia-node-light-mocha-4-0 2/2 Running 1 (56s ago) 72s --faucet-68667bd895-pwqmz 1/1 Running 0 72s --geth-755cb8dd97-k5xp8 3/3 Running 0 72s -``` - -## Your Rollup Endpoints - -Your rollup will automatically be configured with -several public endpoints using the DNS you configured: - -| Utility | URL | -|-----|-----| -| Block Explorer | `http://blockscout../` | -| Faucet | `http://faucet../` | -| RPC | `http://executor../` | - -## Interact with your Rollup - -```bash -export ETH_RPC_URL=http://executor.$ROLLUP_NAME.$ROLLUP_HOSTNAME/ -``` - -```bash -cast block 0 -``` - -Use an address of your choice. - -```bash -export REC_ADDR= -``` - -```bash -cast balance $REC_ADDR -``` - -```bash -cast send $REC_ADDR --value 10000000000000000000 --private-key $ROLLUP_FAUCET_PRIV_KEY -``` - -```bash -cast balance $REC_ADDR -``` diff --git a/docs/components/_astria-rust-cli-install.md b/docs/components/_astria-rust-cli-install.md index ea3738e..1e5411d 100644 --- a/docs/components/_astria-rust-cli-install.md +++ b/docs/components/_astria-rust-cli-install.md @@ -1,6 +1,3 @@ - -### Install the latest [astria cli](https://github.com/astriaorg/astria/releases/tag/cli-v0.2.2) - ::: code-group ```bash [ARM Mac] @@ -28,46 +25,8 @@ ::: - -You'll also need to install the following tools: - -:::warning -There is a bug in the latest Docker desktop release for MacOS -Please install the following release: [https://docs.docker.com/desktop/release-notes/#4252](https://docs.docker.com/desktop/release-notes/#4252) -For more details see [here](https://github.com/docker/for-mac/issues/7100) -::: diff --git a/docs/components/_cli-cloud.md b/docs/components/_cli-cloud.md deleted file mode 100644 index 6e58a22..0000000 --- a/docs/components/_cli-cloud.md +++ /dev/null @@ -1,4 +0,0 @@ - - -- kubectl - [https://kubernetes.io/docs/tasks/tools/](https://kubernetes.io/docs/tasks/tools/) -- helm - [https://helm.sh/docs/intro/install/](https://helm.sh/docs/intro/install/) diff --git a/docs/components/_cli-local.md b/docs/components/_cli-local.md deleted file mode 100644 index c445f7e..0000000 --- a/docs/components/_cli-local.md +++ /dev/null @@ -1,9 +0,0 @@ - - -- docker - [https://docs.docker.com/get-docker/](https://docs.docker.com/get-docker/) -- kubectl - [https://kubernetes.io/docs/tasks/tools/](https://kubernetes.io/docs/tasks/tools/) -- helm - [https://helm.sh/docs/intro/install/](https://helm.sh/docs/intro/install/) -- kind - [https://kind.sigs.k8s.io/docs/user/quick-start/#installation](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) -- just - [https://just.systems/man/en/chapter_4.html](https://just.systems/man/en/chapter_4.html) -- Foundry Cast and Forge tools - - [https://book.getfoundry.sh/getting-started/installation](https://book.getfoundry.sh/getting-started/installation) diff --git a/docs/components/_remote-endpoints.md b/docs/components/_remote-endpoints.md index 34588d0..5db3db3 100644 --- a/docs/components/_remote-endpoints.md +++ b/docs/components/_remote-endpoints.md @@ -1,6 +1,7 @@ -The endpoints for the remote shared sequencer are: +The endpoints for the remote sequencer are: -| NAME | HOSTS | ADDRESS | -|-----|-----|-----| -| Sequencer RPC | rpc.sequencer.dusk-3.devnet.astria.org | 34.111.73.187 | -| Sequencer Faucet | faucet.sequencer.dusk-3.devnet.astria.org | 34.36.8.102 | +| Name | Endpoint | +|---|---| +| Sequencer RPC | [https://rpc.sequencer.dusk-7.devnet.astria.org](https://rpc.sequencer.dusk-7.devnet.astria.org) | +| Sequencer gRPC | [https://grpc.sequencer.dusk-7.devnet.astria.org](https://grpc.sequencer.dusk-7.devnet.astria.org) | +| Sequencer Faucet | [https://faucet.sequencer.dusk-7.devnet.astria.org](https://faucet.sequencer.dusk-7.devnet.astria.org) | diff --git a/docs/index.md b/docs/index.md index 32af4aa..8e3cc26 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ layout: home hero: name: "Astria" - text: "The Shared Sequencer Network" + text: "The Sequencing Layer Network" tagline: The easiest way to deploy decentralized rollups. image: src: /hero-img.svg @@ -12,19 +12,18 @@ hero: actions: - theme: brand text: Just Deploy - link: /local-rollup/1-introduction + link: /developer/tutorials/install-the-cli - theme: alt text: Introduction - link: /overview/1-introduction + link: /overview/introduction features: - title: Learn - details: Astria is a shared sequencing network that allows many rollups to share a single decentralized network of sequencers. - link: /overview/1-introduction + details: Astria is a sequencing layer that allows many rollups to share a single decentralized network of sequencers. + link: /overview/introduction icon: - title: Developers details: Use the Astria stack to create, integrate and build your own modular rollups. - link: /developer/tutorials/1-using-astria-go-cli + link: /developer/tutorials/install-the-cli icon: --- - diff --git a/docs/local-rollup/1-introduction.md b/docs/local-rollup/1-introduction.md deleted file mode 100644 index 92e4848..0000000 --- a/docs/local-rollup/1-introduction.md +++ /dev/null @@ -1,257 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Overview - -This guide will walk you through deploying a rollup full node on -a local Kubernetes cluster which uses the Astria shared sequencer network. - -:::tip -If you would like to deploy a rollup on a remote Kubernetes cluster, - please see the [remote deployment guide](/cloud-rollup/digital-ocean) here. -::: - -## Local Dependencies - -:::info -This guide has been tested on MacOS and Linux but not Windows -::: - -### Clone the Astria [dev-cluster](https://github.com/astriaorg/dev-cluster/tree/main) - -```bash -git clone --branch dusk-3 https://github.com/astriaorg/dev-cluster.git -``` - - -## Dusknet Endpoints - - - -## Setup Local Environment - -We use the [Astria -dev-cluster](https://github.com/astriaorg/dev-cluster) to setup a local -Kubernetes (k8s) cluster where we will deploy our local rollup. - -:::tip -Make sure that Docker is running before continuing. -::: - -In the __dev-cluster__ repo, run: - -```sh -just create-cluster -just deploy-ingress-controller -``` - -This sets up a local environment compatible with our helm charts. - -## Create your Rollup Genesis Account(s) - -:::danger -__NEVER__ use a private key you use on a live network. -::: - -Specify the accounts which will be funded at the genesis block of your EVM rollup. - -You can create an account using: - -```bash -cast w new -``` - -```bash -Successfully created new keypair. -Address: 0xfFe9...5f8b # -Private key: 0x332e...a8fb # -``` - -Export the genesis private key, this will be used by the - faucet included with the rollup: - -```bash -export ROLLUP_FAUCET_PRIV_KEY= -``` - -Export the genesis address alongside with your desired initial balance in Wei. -We recommend using a value of `100000000000000000000` or larger: - -```bash -export ROLLUP_GENESIS_ACCOUNTS=: -``` - -You can specify multiple accounts to be funded at - genesis as comma deliminated tuples of `
:` - -```bash -export ROLLUP_GENESIS_ACCOUNTS=:,: -``` - -## Create Rollup Config - -Create the configuration manifest for your rollup. - -Replace the tags in the commands and env vars below, as follows: - -| Var Name | Var Type | Description | -|-----|-----|-----| -| `` | String | The name of your rollup. This must be lowercase alphanumeric, `-` is allowed, this will be included in your rollup's URLs.| -| `` | u64 | The id of your network. You must select an id that has not already been claimed. You can view claimed chain IDs [here](https://chainlist.org/).| - -You can use environment variables to set the configuration for the rollup -config creation. Replace all the `<>` tags with their corresponding values. - -```bash -export ROLLUP_NAME= -export ROLLUP_NETWORK_ID= -``` - -Run the config create command: - -```sh -astria-cli rollup config create -``` - -Export the config file name as an env vars: - -```bash -export ROLLUP_CONF_FILE=$ROLLUP_NAME-rollup-conf.yaml -``` - -Verify the config - -```bash -cat $ROLLUP_CONF_FILE -``` - -```bash -global: - namespace: astria-dev-cluster - useTTY: false - logLevel: debug -config: - rollup: - name: - chainId: -chain - networkId: '' - genesisAccounts: - - address: - balance: '' - sequencer: - initialBlockHeight: - websocket: wss://rpc.sequencer.dusk-3.devnet.astria.org/websocket - rpc: https://rpc.sequencer.dusk-3.devnet.astria.org -ingress: - hostname: localdev.me -celestia-node: - config: - labelPrefix: -``` - -## Create a New Sequencer Account - -Create an account on the Astria shared sequencer network - for your rollup to submit transactions. - -```bash -astria-cli sequencer account create -``` - -```bash -Create Sequencer Account - -Private Key: "5562...1622" # -Public Key: "ec20...f613" # -Address: "8a2f...5f68" # -``` - -Export your sequencer private key and address as environment variables: - -```bash -export SEQUENCER_PRIV_KEY=5562...1622 -export SEQUENCER_ACCOUNT_ADDRESS=8a2f...5f68 -``` - -## Fund your Sequencer Account - -Navigate to < > to view the - sequencer faucet. - -Enter your `` into the text box to send - funds to your account: - -![Sequencer Faucet](assets/sequencer-faucet.png) - -Verify your account received the funds - -```bash -astria-cli sequencer account balance $SEQUENCER_ACCOUNT_ADDRESS -``` - -## Deploy the Rollup Node - -Use the `astria-cli` to deploy the rollup node - -```bash -astria-cli rollup deployment create \ - --config $ROLLUP_CONF_FILE \ - --faucet-private-key $ROLLUP_FAUCET_PRIV_KEY \ - --sequencer-private-key $SEQUENCER_PRIV_KEY -``` - -## Watch for rollup startup - -You can watch for the Kubernetes pods of the rollup to start with: - -```bash -kubectl get pods -n astria-dev-cluster -w -``` - -```bash -NAME READY STATUS RESTARTS AGE --blockscout-647745c66d-vz4ks 6/6 Running 1 (56s ago) 72s --celestia-node-light-mocha-4-0 2/2 Running 1 (56s ago) 72s --faucet-68667bd895-pwqmz 1/1 Running 0 72s --geth-755cb8dd97-k5xp8 3/3 Running 0 72s -``` - -## Your Rollup Endpoints - -Your rollup will automatically be configured -with the several locally accessible endpoints: - -| Utility | URL | -|-----|-----| -| Block Explorer | `http://blockscout..localdev.me/` | -| Faucet | `http://faucet..localdev.me/` | -| RPC | `http://executor..localdev.me/` | - -## Interact with your Rollup - -```bash -export ETH_RPC_URL=http://executor.$ROLLUP_NAME.localdev.me/ -``` - -```bash -cast block 0 -``` - -Use an address of your choice. - -```bash -export REC_ADDR= -``` - -```bash -cast balance $REC_ADDR -``` - -```bash -cast send $REC_ADDR --value 10000000000000000000 --private-key $ROLLUP_FAUCET_PRIV_KEY -``` - -```bash -cast balance $REC_ADDR -``` diff --git a/docs/local-rollup/2-astria-cli-go.md b/docs/local-rollup/2-astria-cli-go.md deleted file mode 100644 index ac68da5..0000000 --- a/docs/local-rollup/2-astria-cli-go.md +++ /dev/null @@ -1,97 +0,0 @@ -# The Astria CLI - -The `astria-go` cli is a tool designed to make local rollup development as -simple and dependency free as possible. It provides functionality to easily run -the Astria stack and interact with the Sequencer. - -## Install and Run CLI from GitHub release - -The CLI binaries are available for download from the -[releases page](https://github.com/astriaorg/astria-cli-go/releases). There are -binaries available for macOS and Linux, for both x86_64 and arm64 architectures. - -```bash -# download the binary for your platform, e.g. macOS silicon -curl -L https://github.com/astriaorg/astria-cli-go/releases/download/v0.3.0/astria-cli-v0.3.0-darwin-arm64.tar.gz \ - --output astria-go.tar.gz -# extract the binary -tar -xzvf astria-go.tar.gz -# run the binary and check version -./astria-go version - -# you can move the binary to a location in your PATH if you'd like -mv astria-go /usr/local/bin/ -``` - -## Locally Build and Run the CLI - -Dependencies: (only required for development) - -- [GO](https://go.dev/doc/install) -- [just](https://github.com/casey/just) - -```bash -git clone git@github.com:astriaorg/astria-cli-go.git -cd astria-cli-go -just build -just run "dev init" -just run "dev run" -``` - -This will download, configure, and run the following binaries of these -applications: - -| App | Version | -| ---------------- | ------- | -| Cometbft | v0.37.4 | -| Astria-Sequencer | v0.9.0 | -| Astria-Conductor | v0.12.0 | -| Astria-Composer | v0.4.0 | - -And place them in a `local-dev-astria` directory, along with several other -configuration files for everything. - -The cli runs the minimum viable components for testing a rollup against the -Astria stack, allowing developers to confirm that their rollup interacts with -Astria's apis correctly. - -## Development - -Requires go version 1.20 or newer. - -You may also need to update your `gopls` settings in your editor for build tags -to allow for correct parsing of the build tags in the code. This will depend on -your IDE, but for VS Code you can open your settings and add: - -```json -{ - "gopls": { - "buildFlags": ["-tags=darwin arm64 amd64 linux"] - } -} -``` - -The cli is built using [Cobra](https://github.com/spf13/cobra). Once you've -pulled the repo you can install the `cobra-cli` as follows to add new commands -for development: - -```bash -# install cobra-cli -go install github.com/spf13/cobra-cli@latest -# add new command, e.g. `run` -cobra-cli add -``` - -### Available Commands - -| Command | Description | -|----------------------------|-------------------------------------------------------------------------------------| -| `version` | Prints the cli version. | -| `help` | Show help. | -| `dev` | Root command for cli development functionality. | -| `dev init` | Downloads binaries and initializes the local environment. | -| `dev run` | Runs a minimal, local Astria stack. | -| `dev clean` | Deletes the local data for the Astria stack. | -| `dev clean all` | Deletes the local data, downloaded binaries, and config files for the Astria stack. | -| `sequencer create-account` | Generate an account for the Sequencer. | -| `sequencer get-balance` | Get the balance of an account on the Sequencer. | diff --git a/docs/local-rollup/assets/a-record.png b/docs/local-rollup/assets/a-record.png deleted file mode 100644 index d300a6b..0000000 Binary files a/docs/local-rollup/assets/a-record.png and /dev/null differ diff --git a/docs/local-rollup/assets/cname-record-example.png b/docs/local-rollup/assets/cname-record-example.png deleted file mode 100644 index e20df5c..0000000 Binary files a/docs/local-rollup/assets/cname-record-example.png and /dev/null differ diff --git a/docs/local-rollup/assets/doctl-screenshot.png b/docs/local-rollup/assets/doctl-screenshot.png deleted file mode 100644 index 25623ba..0000000 Binary files a/docs/local-rollup/assets/doctl-screenshot.png and /dev/null differ diff --git a/docs/local-rollup/assets/sequencer-faucet.png b/docs/local-rollup/assets/sequencer-faucet.png deleted file mode 100644 index 732c627..0000000 Binary files a/docs/local-rollup/assets/sequencer-faucet.png and /dev/null differ diff --git a/docs/overview/1-introduction.md b/docs/overview/1-introduction.md deleted file mode 100644 index fc4a149..0000000 --- a/docs/overview/1-introduction.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -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. - -## What should I read? - -Want to learn more about the sequencer? check out the [Astria overview section](/overview/2-why-decentralized-sequencers.md) -If you're a developer eager to get started, you should go straight to our Quick Start guide, which will walk you through deploying a rollup full node on a local Kubernetes cluster which uses the Astria shared sequencer network. Once you've gone through the Quick Start, you can move on to running on cloud. -You can find our endpoints and FAQ [here](/astria-evm/overview.md) - -## What If I Need More Help? - -While this documentation should include everything you need, if you can't find what you're looking for, please reach out to us on [Twitter](https://twitter.com/AstriaOrg) or check the [Astria repository](https://github.com/astriaorg/astria). diff --git a/docs/overview/2-why-decentralized-sequencers.md b/docs/overview/2-why-decentralized-sequencers.md deleted file mode 100644 index 13585bf..0000000 --- a/docs/overview/2-why-decentralized-sequencers.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -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) diff --git a/docs/overview/3-cross-rollup-composability.md b/docs/overview/3-cross-rollup-composability.md deleted file mode 100644 index d2216a8..0000000 --- a/docs/overview/3-cross-rollup-composability.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Cross-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. diff --git a/docs/overview/architecture/1-overview.md b/docs/overview/architecture/1-overview.md deleted file mode 100644 index e5e7061..0000000 --- a/docs/overview/architecture/1-overview.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -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) diff --git a/docs/overview/architecture/2-transaction-flow.md b/docs/overview/architecture/2-transaction-flow.md deleted file mode 100644 index 5b8f5a1..0000000 --- a/docs/overview/architecture/2-transaction-flow.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -sidebar_position: 2 ---- - -# Transaction Flow - - - - - -The full transaction flow through the Astria stack is as follows: - -![Astria Transaction Flow](../assets/transaction-flow.png) diff --git a/docs/overview/architecture/3-rollup.md b/docs/overview/architecture/3-rollup.md deleted file mode 100644 index f3d2f00..0000000 --- a/docs/overview/architecture/3-rollup.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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 to Composer): -- For transaction submissions. - -Read Interface (Rollup to 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. diff --git a/docs/overview/architecture/4-composer.md b/docs/overview/architecture/4-composer.md deleted file mode 100644 index e4ef5a9..0000000 --- a/docs/overview/architecture/4-composer.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -sidebar_position: 4 ---- - -# Composer - - - - - -The Composer is an in-house abstraction over the potential actors in Astria's -MEV supply chain. It currently contains a naive implementations of the role a -searcher will fulfill, with the intention of having working examples that -economically incentivized third parties can use as a starting point for their -own implementations. As we progress from design to implementation of Astria's -proposer-builder separation it will also include an example implementation of a -naive builder. The abstractions serves the goal of acting as a forcing function -on our architecture design by stubbing out the roles and requiring other -components to interact with them through an interface. - -While a real searcher implementation would create profit-generating bundles of rollup transactions and submit them to a builder, the Composer implementation simply bundles every rollup transaction it receives into a sequencer transaction and submits it to the sequencer. As our approach to proposer-builder separation is still in its design phase, there is currently no explicit builder role in the MEV supply chain and transactions are submitted directly to validator nodes' CometBFT mempool. - -Once Astria's block builder design moves to its implementation phase, the Composer will include a reference builder implementation as well. Similarly to the searcher, while a real builder implementation would run a profit-generating auction, the composer implementation will simply run a FIFO queue that will add all the sequencer transactions it receives and submits a block to the sequencer's proposer. - -See the [Conductor code -here.](https://github.com/astriaorg/astria/tree/main/crates/astria-conductor) diff --git a/docs/overview/architecture/6-relayer.md b/docs/overview/architecture/6-relayer.md deleted file mode 100644 index 1d731f0..0000000 --- a/docs/overview/architecture/6-relayer.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -sidebar_position: 6 ---- - -# Relayer - - - - - -The Relayer's responsibility is to take validated blocks from the sequencer and -pass them along to both the Conductor and the DA layer. Because the sequencer's -block times are much faster than those of the DA, the relayer also collects a -queue of ordered sequencer blocks before wrapping them for submission to DA. - -The individual sequencer blocks are sent immediately to the Conductor to enable -fast finality for an improved UX and also act as soft commits for the execution -layer. The collections of blocks sent to the DA layer are used as a source of -truth and are ultimately pulled from the DA to be used as firm commits for -finality in the rolllups. - -See the [Relayer code -here.](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer-relayer) diff --git a/docs/overview/architecture/7-conductor.md b/docs/overview/architecture/7-conductor.md deleted file mode 100644 index f432ad3..0000000 --- a/docs/overview/architecture/7-conductor.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -sidebar_position: 7 ---- - -# Conductor - - - - - -Conductor's role is to drive the deterministic execution of sequencer blocks to -rollups. - -It abstracts away the logic required to read data from the DA and the -Sequencer, tracking firm and soft commitments, block and header shapes, as well -as verification of the data. The rollup implements the Execution API server, and -runs the Conductor alongside to drive deterministic execution. The Conductor is -effectively stateless but does ephemerally store some information about the -blocks it has seen and passed on to be executed. - -It filters the transactions that are relevant to the given rollup it is running -along side, out of the sequencer blocks for execution. The data that it does store is -for sending commitment updates to the rollup. - -As mentioned in the -[Relayer](/docs/overview/architecture/6-relayer.mdx) section, any data -received by the Conductor directly from the Relayer is considered a soft commit. -This data is filtered using the rollup's namespace and only transactions that -are relevant to the rollup are passed on as blocks for execution. These blocks -are also marked as "safe" withing the rollup. The Conductor regularly polls Celestia for new data -and when it sees the same blocks in Celestia that it has already seen from the -Relayer, it sends a firm commit message to the rollup to update that block to -"finalized." - -See the [Conductor code -here.](https://github.com/astriaorg/astria/tree/main/crates/astria-conductor) diff --git a/docs/overview/assets/astria-architecture-old.png b/docs/overview/assets/astria-architecture-old.png new file mode 100644 index 0000000..ff464b0 Binary files /dev/null and b/docs/overview/assets/astria-architecture-old.png differ diff --git a/docs/overview/assets/astria-architecture.png b/docs/overview/assets/astria-architecture.png index ff464b0..c410b46 100644 Binary files a/docs/overview/assets/astria-architecture.png and b/docs/overview/assets/astria-architecture.png differ diff --git a/docs/overview/assets/rollup-full-node-architecture.png b/docs/overview/assets/rollup-full-node-architecture.png new file mode 100644 index 0000000..6ebdf9b Binary files /dev/null and b/docs/overview/assets/rollup-full-node-architecture.png differ diff --git a/docs/overview/assets/rollups-with-a-decentralized-sequencer.png b/docs/overview/assets/rollups-with-a-decentralized-sequencer.png new file mode 100644 index 0000000..491f4db Binary files /dev/null and b/docs/overview/assets/rollups-with-a-decentralized-sequencer.png differ diff --git a/docs/overview/bridging.md b/docs/overview/bridging.md new file mode 100644 index 0000000..c131b96 --- /dev/null +++ b/docs/overview/bridging.md @@ -0,0 +1,54 @@ +# Bridging on Astria + +## Fee payments + +With a sequencing layer, transaction data touches three different chains: the +sequencer chain, the data availability chain, and the rollup chain. Each of +these requires a fee payment for DoS prevention. If each chain requires a +different token for fee payment, this causes a poor UX. Many rollups built on +Ethereum allow for bridged ETH to be used to pay fees, alleviating UX concerns, +as users only need to obtain one, widely-available token (ETH). + +We can do something similar with the sequencer network. Assuming the data +availability network’s token is the most easily accessible and established, we +can bridge the DA token to the sequencer network to use as fee payment, and also +bridge the DA token to the rollup via the usual rollup bridging (deposit +derivation) method. In our case, this means bridging TIA (Celestia) to Astria +via IBC, and allowing it to be used for fee payments. Then, a rollup can +optionally choose to accept (IBC-)TIA as a token for fee payments as well. + +## Rollup bridging + +To bridge tokens to a rollup built on Astria, the rollup needs to add the +ability to derive deposit transactions from the sequencer or DA network. In +general, rollup deposits work as follows: + +on the L1, tokens are transferred to some escrow account/contract. +the rollup consensus node, which derives the L2 transactions from L1 data, sees +these deposits, and includes a corresponding “deposit” transaction in the next +L2 block, which is a distinct transaction type. +the L2 node executes these deposit transactions, minting synthetic funds on the +L2 to the respective account. +A rollup on Astria would have to implement something like this to bridge from +the sequencer/DA to it. + +Bridging back to the L1 requires proving rollup block state roots on the L1. +This is the “optimistic” or “ZK” parts of the rollup. To implement bridging from +a rollup on Astria back to the sequencer or DA network, we need to add +functionality to verify rollup state rollups on them. On the sequencer, this +would mean enshrining some sort of state root verification actor in the +sequencer’s state machine, which could be instantiated by the rollup and used to +bridge to the sequencer. Since we’re using Celestia as DA, which does not +support any sort of programmability, the only way to bridge from the rollup to +Celestia would be first through the sequencer, then back to Celestia through +IBC. + +## IBC + +IBC (inter-blockchain communication) is a standard used by Cosmos/CometBFT +chains to pass messages between each other in a trust-minimized way. Since +Astria uses CometBFT, it is IBC-enabled and able to bridge tokens between other +IBC-enabled chains. To see more details about IBC, see the spec. + +Celestia is also IBC-enabled, and we expect to bridge TIA from Celestia to +Astria for fee payments. diff --git a/docs/overview/components/composer.md b/docs/overview/components/composer.md new file mode 100644 index 0000000..2c22614 --- /dev/null +++ b/docs/overview/components/composer.md @@ -0,0 +1,48 @@ +# The Astria Composer +As a sequencing layer, Astria is designed to provide lazy sequencing for multiple +rollups. This requires abstracting rollup-specific order flow via the sequencer +network's transactions, which operate on opaque bytes that are not executed. By +remaining agnostic to rollup-specific transaction formats, the sequencer network +is able to provide a robust MEV supply chain for rollups built on top of it, +with features like native bundle support. + +While the sequencing layer provides a powerful tool for sophisticated users, +supporting a wider range of users requires additional tooling. The Astria Composer +is "gas station" side car that makes it easier for ordinary users to easily +use rollups that support more complex order flow mechanisms. + +## The Composer as a UX solution +While sophisticated users, such as arbitrageurs, can leverage the sequencing layer +directly to pay for better transaction ordering guarantees, most users will not +require (or be interested) in this level of control. Specifically, interacting +directly with the sequencing layer requires users to hold sequencer tokens and +to maintain a sequencer wallet, both of which result in a poor user experience. + +Instead, we provide rollup operators with tooling to abstract this complexity +away using the Astria Composer. Rollup operators run the Composer as side-car +software to their nodes. The Composer can be described as a "gas station", +underwriting the sequencing costs for users' rollup transactions. + +This allows order-agnostic users to simply pay for transaction execution in the +rollup's native gas token without needing to maintain a sequencer wallet, as long +as the operator keeps the Composer funded. The Composer then bundles these +transactions and submits them to the sequencer network on the user's behalf. + +## Heterogenous order flow support +This allows Astria-based rollups to support a wide range of users, from those +who want to pay for better transaction ordering to those with no explicit +sequencing preferences. + +Sophisticated users can submit their transactions directly to the sequencing +layer, controlling the order by which their transactions are bundled and the +fees they pay for bundle ordering. + +In contrast, regular users are able to route their transactions through the +rollup node, which will run the Composer as a sidecar to underwrite the cost +of inclusion but with no control over the ordering. + +## Naive ordering preferences +The Composer provides users with no ordering guarantees, bundling transactions +by the order they are received. Bundles are capped in size to ensure they fit +in a sequencer block, and are submitted to the sequencer network in a timely +manner to ensure they can be included in the next sequencer block. diff --git a/docs/overview/components/conductor.md b/docs/overview/components/conductor.md new file mode 100644 index 0000000..3ef1568 --- /dev/null +++ b/docs/overview/components/conductor.md @@ -0,0 +1,82 @@ +# The Astria Conductor + +The Conductor can be thought of as the consensus implementation of a rollup full +node, similar to op-node within the OP Stack. Conductor is the counterpart to +the execution engine, which together make up a full rollup node. Its role is +to connect the sequencer and Data Availability layers to the rollup execution +layer by extracting the transactions belonging to the rollup node from each +sequencer block, and forwarding them to the execution layer. + +The conductor’s flow is as follows: + +* For each sequencer block, extract the relevant rollup data it needs +* validate the batch of rollup data; this includes verifying that the + corresponding sequencer block was finalized, as well as verifying that the + rollup data it extracted is complete (there are no rollup transactions + missing), correct (there are no rollup transactions in the batch that + shouldn’t be), and properly-ordered (the ordering of the rollup transactions + matches what was finalized by the sequencer chain). It is able to do this by + verifying the data against the rollup data commitment included in the + sequencer block. +* Once it has validated the rollup data, it turns it into a list of + transactions, which are passed to the execution engine. + +Note that the conductor, like the sequencer, is agnostic to the rollup’s +transaction format and execution engine; it simply treats transactions as an +arbitrary byte array. + +## Data verification + +The conductor needs to verify the data it receives before passing it to the +rollup. Specifically, it needs to verify that the data is actually what was +sequenced by the sequencer in the correct order, that there is no data missing, +and that there is no additional data added. The conductor wishes to do this +without pulling the entire set of sequenced data or the entire sequencer block, +as this is additional data it doesn’t need. + +This is achieved by placing a commitment to the entire set of sequenced data in +every sequencer block. This commitment is the Merkle root of a tree where each +leaf is a commitment to the data for one specific rollup. This commitment is +checked by every validator node on the sequencer network, thus has the majority +of stake backing it. Then, the conductor can verify the rollup data received is +correct by validating: + +* the commitment to the entire set of sequenced data was committed by the + network, via the set of validator signatures on the block +* the commitment to its specific rollup data is included in that, via a merkle + proof of inclusion +* the rollup data it receives corresponds to the commitment for that rollup + data, via recalculating the commitment + +After all of these steps are done, the conductor can be certain that the rollup +data is actually what was sequenced. + +There is an additional verification step needed: since the conductor doesn’t +pull an entire block’s data, there needs to be consensus over what rollup IDs +were sequenced in a sequencer block. It’s possible that a sequencer node doesn’t +advertise that a rollup ID was included (i.e. by not posting it to the data +availability layer). Then, the conductor would think that it simply had no +sequenced data in a certain block when it actually did. + +This is fixed by having a commitment to all the rollup IDs sequenced inside each +sequencer block, which is checked and voted on by every validator. Then, the +conductor receives a list of all the rollup IDs sequenced in a block and +verifies that against the rollup IDs commitment to be certain as to whether a +block had data for it or not. + +## Soft and Firm Commitments + +The Conductor also retrieves the soft commitments from the sequencer, and firm +commitments from the data availability layer. + +The soft commitments act as fast pre-confirmations and are implicitly verified +by the Conductor via a fully trusted connection to the sequencer. All data +retried from the sequencer is automatically considered a soft commitment because +that data can't be added to the sequencer chain unless validated by the +sequencer network. + +The firm commitments that are retrieved from the data availability layer are +considered finalized, and are explicitly verified by the conductor before +passing onto the rollup. Data that can be retrieved from the data availability +layer is considered widely available and all historical syncing of data for +rollups is retrieved in this way. diff --git a/docs/overview/architecture/8-data-availability-layer.md b/docs/overview/components/data-availability-layer.md similarity index 65% rename from docs/overview/architecture/8-data-availability-layer.md rename to docs/overview/components/data-availability-layer.md index 0f48a57..f2ce08e 100644 --- a/docs/overview/architecture/8-data-availability-layer.md +++ b/docs/overview/components/data-availability-layer.md @@ -1,14 +1,6 @@ ---- -sidebar_position: 8 ---- - # Data Availability Layer - - - - -The dev-cluster uses [Celestia](https://github.com/celestiaorg) as the data +Astria uses [Celestia](https://github.com/celestiaorg) as the data availability layer and is the ultimate destination of all data that has been ordered by the sequencer network. Once written to Celestia, the transaction order is considered final and it is where all data will be pulled from when a diff --git a/docs/overview/components/relayer.md b/docs/overview/components/relayer.md new file mode 100644 index 0000000..e37a49f --- /dev/null +++ b/docs/overview/components/relayer.md @@ -0,0 +1,12 @@ +# Relayer + +The relayer's responsibility is to fetch validated blocks from the sequencer and +pass them along to the DA layer. Because the sequencer's block times are much +faster than those of the DA, the relayer batches the ordered data from multiple +sequencer blocks before compressing it and submitting it to the DA. + +The individual sequencer blocks can also be fetched by the Conductor before the +relayer has submitted them to the DA. This enables fast finality for an improved +UX, acting as soft commits for the execution layer. The collections of data sent +to the DA layer by the relayer are used as a source of truth and are ultimately +pulled from the DA to be used as firm commits for finality in the rollups. diff --git a/docs/overview/architecture/5-the-astria-sequencer.md b/docs/overview/components/the-astria-sequencer.md similarity index 57% rename from docs/overview/architecture/5-the-astria-sequencer.md rename to docs/overview/components/the-astria-sequencer.md index 98c568d..cdb32c6 100644 --- a/docs/overview/architecture/5-the-astria-sequencer.md +++ b/docs/overview/components/the-astria-sequencer.md @@ -1,24 +1,14 @@ ---- -sidebar_position: 5 ---- +# The Astria Sequencing Layer -# The Astria Sequencer +The Astria Sequencing Layer is a decentralized network of nodes utilizing CometBFT that come to consensus on an ordered set of transactions (ie. it is a blockchain). The unique feature of the sequencer is that the transactions it includes are not executed (lazy sequencing), and are destined for another execution engine (ie. a rollup). This excludes “sequencer native” transactions, such as transfers of tokens within the sequencer chain. Transactions from any given rollup are only ordered on the sequencer, not executed. - - - - -The Astria Shared Sequencer is a decentralized network of nodes utilizing CometBFT that come to consensus on an ordered set of transactions (ie. it is a blockchain). The unique feature of the sequencer is that the transactions it includes are not executed (lazy sequencing), and are destined for another execution engine (ie. a rollup). This excludes “sequencer native” transactions, such as transfers of tokens within the sequencer chain. Transactions from any given rollup are only ordered on the sequencer, not executed. - -The sequencer can optionally act as a “validator”, meaning it actively +The sequencer node can optionally act as a “validator”, meaning it actively participates in the production and finalization of new blocks. ![Astria Shared Sequencer](../assets/shared-sequencer-overview.png) -Components of note that are not shown in the above diagram are the [Composer](/docs/overview/architecture/4-composer.mdx), -[Relayer](/docs/overview/architecture/6-relayer.mdx), and [Conductor](/docs/overview/architecture/7-conductor.mdx). +Components of note that are not shown in the above diagram are the [Composer](composer.md), +[Relayer](relayer.md), and [Conductor](conductor.md). These components facilitate the delivery transactions, batches, and different commits shown above, back to the users. - -See the [Sequencer code here.](https://github.com/astriaorg/astria/tree/main/crates/astria-sequencer) diff --git a/docs/overview/how-rollups-work.md b/docs/overview/how-rollups-work.md new file mode 100644 index 0000000..f0bfd0f --- /dev/null +++ b/docs/overview/how-rollups-work.md @@ -0,0 +1,146 @@ +# How Rollups Work + +A rollup is a blockchain that consists of a state transition function executed +over some subset of data contained in another blockchain, the L1. Bridging +to/from the L1 (by enshrining the rollup’s state transition in the L1) is +implemented by non-sovereign rollups. + +## Rollup full node architecture + +A rollup needs to perform the following: + +* read relevant subsets of data from the L1 +* turn this data into rollup transactions +* execute these transactions to form a rollup block + +The first two points are part of “rollup consensus” while the last is “rollup +execution”. + +![Rollup Full Node Architecture](./assets/rollup-full-node-architecture.png) + +The main component required for rollup consensus is an L1 derivation function, +which derives the transactions for a rollup block deterministically from the +data on the L1. This data generally looks like calldata or blob data posted to +the chain and/or events emitted from a contract. This data is extracted and +turned into rollup transactions. + +After the set of rollup transactions for a block has been derived, they are +passed to the rollup execution layer, which executes the transactions and +updates the rollup state. After execution, a new rollup state root is created. + +Unlike L1 nodes, rollup nodes do not necessarily need to form a p2p network and +communicate with each other for consensus. The chain’s consensus is provided by +the L1, and all (properly-functioning) rollup nodes will deterministically +derive the same state given the same L1 state. + +However, rollup nodes may still wish to form a p2p network for two reasons: fast +confirmations, which can be received from the sequencer, or for rollup light +nodes. + +## Rollup sequencers + +In the above section, we discussed how a rollup derives its transactions, but +how does the rollup data end up on L1? + +A simple solution is to have users post their rollup transactions to the L1 +directly. However, this is not ideal because there is not as much of an economic +benefit (users have to pay for L1 inclusion, plus L2 execution) for them to do +so. As well, users need to wait for L1 blocks to know if their transaction was +included. + +A more cost- and time-effective solution is to use a sequencer. Rollup +sequencers are akin to block producers on L1. They have the privilege of +determining ordering and inclusion for rollup blocks. The sequencer collects a +set of rollup transactions, batches them, optionally compresses them, and posts +them to L1. Compression has the benefit of reducing the L1 inclusion cost for +each rollup transaction. Sequencers also provide “pre-confirmations” or “fast +confirmations”, meaning the sequencer can provide a commitment to the user that +their transaction will end up in a specific rollup block before the +corresponding L1 block has actually been published. + +Sequencers to date have been implemented as a centralized service, generally run +by rollup teams themselves. This means there is one party responsible for rollup +transaction ordering and inclusion, leading to a monopoly on MEV extraction and +the potential for transaction censorship. While there is always the “escape +hatch” by which users post their rollup transactions directly to the L1 for +inclusion on the rollup, this is a poor UX alternative. + +## Decentralized sequencers + +A decentralized sequencer network is an alternative to the centralized service, +where multiple sequencer nodes each have the ability to propose a batch of +rollup transactions. + +The flow would then look like: + +* a proposer proposes some transaction batch, or commitment to some transaction + batch the network reaches consensus over this batch +* the transaction batch data is made available to rollup nodes + +A simple solution is to have a permissioned set, where only batches signed by a +key from the chosen set are allowed to be derived into rollup blocks. To make +this permissionless, we need to allow anyone to join the sequencer node set - +eg. through proof-of-stake. By putting up some stake, anyone can join the +sequencer network as a consensus node, and have the privilege of proposing +transaction batches. + +There are a few options regarding the asset(s) used as stake on the sequencer +network. The first is to create a native asset on the sequencer network to be +used for staking, as well as for transaction fees. The second is to use the +asset of an underlying data availability layer for staking and transaction fees. + +## Sequencing Layers + +![Rollups with a decentralized sequencing layer](./assets/rollups-with-a-decentralized-sequencer.png) + +Currently, sequencers are implemented for one specific rollup. Instead of this, +we can have a sequencer batch transactions for many rollups. With data +compression, this allows for greater cost savings when posting data to L1. A +sequencer network that is decentralized and shared incentivizes actors from +multiple rollup ecosystems to potentially act as validators on the sequencer +network. + +Current sequencer implementations generally execute the transactions that it +sequences as well. By allowing the sequencer to sequence many rollups, it can +either execute the transactions for each rollup it sequences for, or have it not +execute any transactions at all, and remain ignorant of the rollup state +machines it’s sequencing for (known as lazy sequencing). + +The downside to executing the transactions for each rollup is that it’s much +more difficult to add new rollups to the sequencing layer, as the sequencer +needs to be forked and made aware of a new state machine. Additionally, as the +state of the rollups grows, the sequencer execution time gets slower and slower +(the same way state bloat affects L1s), but it’s potentially even worse over +time since many states are involved. + +The better solution is the second, where the sequencing layer’s function is +reduced to only sequencing and not executing. In this model, the sequencing +layer batches and orders generic transaction data, where the data is tagged +with the rollup it’s destined for, and only after the sequencer commits to the +batch is the data executed by rollup nodes. + +## Rollup light nodes + +Rollup light nodes, like normal L1 light nodes, follow the consensus of the main +chain and verify and sync its headers, without executing the full transaction +data of the chain. A rollup light node needs to do a few more things to verify +headers than an L1 light node. + +A rollup light node needs to: + +* implement an L1 consensus light client +* implement an L2 consensus light client +* ensure that the transaction data for each L2 block was published + +A light node of a rollup that uses a sequencing layer needs to verify the +consensus of the sequencer chain, as the sequencer acts as the equivalent of the +L1 - i.e. it’s where transaction inclusion and ordering is finalized. It needs +to follow the headers and verify consensus of the sequencer chain. Since light +nodes don’t store the blockchain state, to verify if a rollup transaction was +included in some rollup block X, the light node first needs a Merkle proof that +the rollup transaction was included in the transactions/data root of some +sequencer chain header. Then, if it follows that rollup block X was derived from +sequencer block Y (using the rollup derivation function), it knows that the +transaction should be included in rollup block X. The light node also needs to +check that the block data was published, which it can do via data availability +sampling (for example, when using Celestia). diff --git a/docs/overview/introduction.md b/docs/overview/introduction.md new file mode 100644 index 0000000..a76b274 --- /dev/null +++ b/docs/overview/introduction.md @@ -0,0 +1,62 @@ +# Introduction + +![Astria Architecture](./assets/astria-architecture.png) + +Astria is building a decentralized sequencer network that can be shared by many rollups. + +At a high level, the Astria stack performs the following functions: + +* sequences arbitrary data for usage by multiple rollups +* makes this data available to rollup nodes +* allows rollup nodes to easily fetch and verify sequenced data +* batches rollup blocks and posts these batches to Celestia + +The first two are mandatory, while the last is implemented more for the +developer experience, allowing rollup developers to focus only on the +rollup-specific application logic, as opposed to the other aspects such as +rollup consensus. + +The first requirement (sequencing of arbitrary data for rollups) is implemented +by the Astria sequencer network, a PoS network of sequencer nodes that use +CometBFT for consensus. The sequencer network comes to consensus on the ordering +and inclusion of rollup transactions of the form (rollup_id, tx_bytes). The +rollup_id can be any arbitrary string; it’s used only by rollup nodes to +determine which data is for them. The second (making data available to rollup +nodes) is achieved by publishing the sequenced data via Celestia. + +The third (allowing rollup nodes to easily fetch and verify sequenced data) is +achieved by the Astria “Conductor”, which works similarly to existing rollup +“consensus nodes”, such as op-node within the OP Stack. The conductor obtains +the sequenced data, verifies it, and derives the transactions for a specific +rollup, all while remaining agnostic to the transaction format and state +transition function of the rollup execution node. It then passes the derived +transactions to the rollup execution node for processing. + +The Astria sequencer network is a lazy sequencer. This means that data is +sequenced and committed, but execution is delayed until necessary, and is left +to the rollup. This de-couples the execution logic from the consensus logic, +removing consensus bottlenecks and allowing for more flexibility for rollup +developers. For example, since the data is executed lazily, a rollup may choose +to have 2 rollup blocks per Astria block, or 1 rollup block per Astria block. +The rollup’s consensus and execution logic is not enshrined in the sequencer. + +## What should I read? + +Want to learn more about about rollups or the sequencer? Check out the [How +Rollups Work](/overview/how-rollups-work) or [The Astria Sequencer +Network](/overview/the-astria-sequencer-network). + +If you're a rollup developer eager to get started, you should go straight to our +[`astria-go` cli tutorials](../developer/tutorials/dev-cluster-local-rollup). + +For more advanced development, you can read about deploying a rollup full using +a local Kubernetes cluster [here](../local-rollup/1-introduction.md). + +You can find our endpoints and FAQ [here](/astria-evm/overview.md) + +## What If I Need More Help? + +While this documentation hopefully includes everything you need, if you can't +find what you're looking for, please reach out to us on +[Twitter](https://twitter.com/AstriaOrg) or check the [Astria +repository](https://github.com/astriaorg/astria). diff --git a/docs/overview/the-astria-sequencer-network.md b/docs/overview/the-astria-sequencer-network.md new file mode 100644 index 0000000..659fe1b --- /dev/null +++ b/docs/overview/the-astria-sequencer-network.md @@ -0,0 +1,39 @@ +# The Astria Sequencer Network + +The Astria sequencer network uses CometBFT (formerly Tendermint) as its +consensus algorithm. At a minimum, the sequencer network needs to implement a +decentralized leader selection algorithm which rotates between proposers. +Ideally, it is also able to provide single-slot (“fast”) finality, which +prevents forks from occurring, allowing for simplified chain derivation logic on +the rollups which use it. CometBFT is able to provide both of these. +Additionally, CometBFT is battle-tested and has been used in production, on many +chains, for years. It allows blockchain applications (application, in this case, +meaning the chain’s execution logic) which implement ABCI (Application +Blockchain Interface) to easily use it as their consensus layer. Additionally, +CometBFT-enabled chains have the ability to support IBC (inter-blockchain +communication), meaning they have the potential to bridge between many other +chains. + +Astria sequencer’s execution logic is implemented as a CometBFT application, +written in Rust. The application logic allows for three main functions: + +* sequencing of rollup data +* value transfers +* validator set changes + +During the consensus phase of the sequencer network, the proposer decides on the +transactions for the block and creates a commitment to the rollup data for each +rollup_id. This is then verified and only finalized if agreed upon by the +majority of other nodes. This allows for rollups to only pull the data necessary +for their rollup, checking that the commitment to it matches what was finalized +by the sequencer chain, without needing to pull the entire sequencer block’s +data. + +The sequencer network also needs to make its block data available to rollup +nodes. During the consensus process, the block data needs to be made available +to all validators, so that they can verify and vote on the rollup data +commitments (ie. they need to ensure the commitments match the block data). +After the consensus process, the data is made more widely available via a data +availability layer. Celestia is used for DA, as it supports data availability +sampling via light nodes, meaning a light node is able to check if data was made +available. diff --git a/docs/overview/transaction-flow.md b/docs/overview/transaction-flow.md new file mode 100644 index 0000000..656c84c --- /dev/null +++ b/docs/overview/transaction-flow.md @@ -0,0 +1,5 @@ +# Transaction Flow + +The full transaction flow through the Astria stack is as follows: + +![Astria Transaction Flow](./assets/transaction-flow.png)