Skip to content

Commit

Permalink
review technical-stack docs, pt 1
Browse files Browse the repository at this point in the history
  • Loading branch information
@dghelm
dghelm committed Oct 28, 2024
1 parent 5012a40 commit bf2c9c1
Show file tree
Hide file tree
Showing 3 changed files with 202 additions and 59 deletions.
107 changes: 92 additions & 15 deletions src/content/docs/en/sdk/technical-stack/configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import Aside from "../../../../../components/Aside.astro"

Initial change configuration is made by modifying `config.toml`. All other config files are auto-generated from this file. For automating changes to your configuration for production deployments, see the [scroll-sdk-cli](/en/sdk/technical-stack/scroll-sdk-cli) tool.

For new production deployments, we recommend using the [example template](https://github.com/scroll-tech/scroll-sdk/blob/develop/examples/config.toml.example).
For new production deployments, we recommend using the [example template](https://github.com/scroll-tech/scroll-sdk/blob/develop/examples/config.toml.example), which the `scroll-sdk-cli` tool is designed to work with. You can reference the default devnet configuration [here](https://github.com/scroll-tech/scroll-sdk/blob/develop/charts/scroll-sdk/config.toml).

<Aside type="note">
Although most values don't need modified between subsequent deployments, you may want change the contracts section's `DEPLOYMENT_SALT` in order to have newly initialized contracts on your basechain.
Expand All @@ -22,6 +22,8 @@ Local Devnet defaults shown.

### General

Contained in the `[general]` section.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| L1_RPC_ENDPOINT | Specifies the HTTP endpoint for the L1 RPC server. | `http://l1-devnet:8545` |
Expand All @@ -35,6 +37,10 @@ Local Devnet defaults shown.

### Accounts

Contained in the `[accounts]` section.

{/* TODO: Add link to where these roles are documented. */}

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| DEPLOYER_PRIVATE_KEY | Private key for the deployer account. | `0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80` |
Expand All @@ -43,14 +49,16 @@ Local Devnet defaults shown.
| L1_GAS_ORACLE_SENDER_PRIVATE_KEY | Private key for the L1 gas oracle sender account. | `0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6` |
| L2_GAS_ORACLE_SENDER_PRIVATE_KEY | Private key for the L2 gas oracle sender account. | `0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80` |
| DEPLOYER_ADDR | Address of the deployer account. | `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266` |
| OWNER_ADDR | Address of the owner account. | `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266` |
| OWNER_ADDR | Address of the owner account. Should be a multi-sig wallet. | `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266` |
| L1_COMMIT_SENDER_ADDR | Address of the L1 commit sender account. | `0x70997970C51812dc3A010C7d01b50e0d17dc79C8` |
| L1_FINALIZE_SENDER_ADDR | Address of the L1 finalize sender account. | `0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC` |
| L1_GAS_ORACLE_SENDER_ADDR | Address of the L1 gas oracle sender account. | `0x90F79bf6EB2c4f870365E785982E1f101E93b906` |
| L2_GAS_ORACLE_SENDER_ADDR | Address of the L2 gas oracle sender account. | `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266` |

### Database

Contained in the `[db]` section.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| ADMIN_SYSTEM_DB_CONNECTION_STRING | Connection string for the Admin System database. | `""` |
Expand All @@ -63,8 +71,58 @@ Local Devnet defaults shown.
| ROLLUP_NODE_DB_CONNECTION_STRING | Connection string for the Rollup Node database. | `postgres://postgres:qwerty12345@postgresql:5432/scroll?sslmode=disable` |
| ROLLUP_EXPLORER_DB_CONNECTION_STRING | Connection string for the Rollup Explorer database. | `""` |

### Gas Token

Contained in the `[gas-token]` section.

{/* TODO: Add link to where these modes are documented. */}

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| ALTERNATIVE_GAS_TOKEN_ENABLED | Enables using an alternative gas token instead of ETH. | false |
| EXAMPLE_GAS_TOKEN_DECIMAL | Decimal places for the example gas token. | 6 |
| L1_GAS_TOKEN | Address of the L1 ERC20 gas token contract. | `0x68a041e7c20Afa4784b5d9C63246c89545Ac0E66` |
| GAS_ORACLE_INCORPORATE_TOKEN_EXCHANGE_RATE_ENANBLED | Enables incorporating token exchange rates in gas oracle. | false |
| EXCHANGE_RATE_UPDATE_MODE | Mode for updating exchange rates. | `Fixed` |
| FIXED_EXCHANGE_RATE | Fixed exchange rate value when using Fixed mode. | `0.01` |
| TOKEN_SYMBOL_PAIR | Symbol pair for the token exchange. | `UNIETH` |

### Sequencer

Contained in the `[sequencer]` section.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| L2_GETH_STATIC_PEERS | Static peers for L2 Geth nodes, as an array of sequencer enode URLs. | `[""]` |
| L2GETH_SIGNER_ADDRESS | Address of the primary sequencer's L2 Geth signer account. | `""` |
| L2GETH_KEYSTORE | Keystore file for the primary sequencer's L2 Geth signer account. | `""` |
| L2GETH_PASSWORD | Password for the primary sequencer's L2 Geth keystore. | `""` |
| L2GETH_NODEKEY | Node key for the primary sequencer's L2 Geth node. | `""` |

### Additional Sequencer Instances

Contained in the `[sequencer.sequencer-1]` section and incrementing for each additional sequencer instance.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| L2GETH_SIGNER_ADDRESS | Address of the L2 Geth signer account for this sequencer instance. | `0xE8fFE623460e54e546E54B1a0C93A968aF6295bb` |
| L2GETH_KEYSTORE | Keystore file for this sequencer instance's signer account. | `{"address":"e8ffe623460e54e546e54b1a0c93a968af6295bb","id":"deef9b4a-a085-4f02-af36-afaa19da4132",...}` |
| L2GETH_PASSWORD | Password for this sequencer instance's keystore. | `second` |
| L2GETH_NODEKEY | Node key for this sequencer instance. | `bd347890c9d308957207379679e8ed548d015ef05588c228d13f92ea0288a35b` |

### Bootnode Instances

Contained in the `[bootnode.bootnode-0]` section and incrementing for each additional bootnode instance.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| L2GETH_NODEKEY | Node key for this bootnode instance. | `""` |


### Rollup

Contained in the `[rollup]` section.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| MAX_TX_IN_CHUNK | Sets the maximum number of transactions in a chunk. | 100 |
Expand All @@ -75,15 +133,34 @@ Local Devnet defaults shown.
| TEST_ENV_MOCK_FINALIZE_ENABLED | Enables mock finalization for testing environments. | true |
| TEST_ENV_MOCK_FINALIZE_TIMEOUT_SEC | Sets the timeout for mock finalization in seconds. | 300 |

### Frontend

Contained in the `[frontend]` section.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| EXTERNAL_RPC_URI_L1 | External RPC URI for L1. | `http://l1-devnet.scrollsdk` |
| EXTERNAL_RPC_URI_L2 | External RPC URI for L2. | `http://l2-rpc.scrollsdk` |
| BRIDGE_API_URI | URI for the Bridge API. | `http://bridge-history-api.scrollsdk/api` |
| ROLLUPSCAN_API_URI | URI for the Rollupscan API. | `http://rollup-explorer-backend.scrollsdk/api` |
| EXTERNAL_EXPLORER_URI_L1 | External Explorer URI for L1. | `http://l1-explorer.scrollsdk` |
| EXTERNAL_EXPLORER_URI_L2 | External Explorer URI for L2. | `http://blockscout.scrollsdk` |
| ADMIN_SYSTEM_DASHBOARD_URI | URI for the Admin System Dashboard. | `http://admin-system-dashboard.scrollsdk` |
| GRAFANA_URI | URI for Grafana. | `http://grafana.scrollsdk` |

### Genesis

Contained in the `[genesis]` section.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| L2_MAX_ETH_SUPPLY | Sets the maximum ETH supply for the L2 network. | `226156424291633194186662080095093570025917938800079226639565593765455331328` |
| L2_DEPLOYER_INITIAL_BALANCE | Sets the initial balance for the L2 deployer account. | 1000000000000000000 |

### Contracts

Contained in the `[contracts]` section.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| DEPLOYMENT_SALT | Salt used for contract deployment. | `salt-000` |
Expand All @@ -92,6 +169,8 @@ Local Devnet defaults shown.

### Contracts Overrides

Contained in the `[contracts.overrides]` section.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| L2_MESSAGE_QUEUE | Override address for the L2 message queue contract. | `0x5300000000000000000000000000000000000000` |
Expand All @@ -102,28 +181,22 @@ Local Devnet defaults shown.

### Coordinator

Contained in the `[coordinator]` section.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| CHUNK_COLLECTION_TIME_SEC | Time in seconds for chunk collection. | 3600 |
| BATCH_COLLECTION_TIME_SEC | Time in seconds for batch collection. | 1800 |
| BUNDLE_COLLECTION_TIME_SEC | Time in seconds for bundle collection. | 600 |
| COORDINATOR_JWT_SECRET_KEY | Secret key used for JWT authentication in the coordinator. | `e788b62d39254928a821ac1c76b274a8c835aa1e20ecfb6f50eb10e87847de44` |

### Frontend

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| EXTERNAL_RPC_URI_L1 | External RPC URI for L1. | `http://l1-devnet.scrollsdk` |
| EXTERNAL_RPC_URI_L2 | External RPC URI for L2. | `http://l2-rpc.scrollsdk` |
| BRIDGE_API_URI | URI for the Bridge API. | `http://bridge-history-api.scrollsdk/api` |
| ROLLUPSCAN_API_URI | URI for the Rollupscan API. | `http://rollup-explorer-backend.scrollsdk/api` |
| EXTERNAL_EXPLORER_URI_L1 | External Explorer URI for L1. | `http://l1-explorer.scrollsdk` |
| EXTERNAL_EXPLORER_URI_L2 | External Explorer URI for L2. | `http://blockscout.scrollsdk` |
| ADMIN_SYSTEM_DASHBOARD_URI | URI for the Admin System Dashboard. | `http://admin-system-dashboard.scrollsdk` |
| GRAFANA_URI | URI for Grafana. | `http://grafana.scrollsdk` |

### Ingress

Contained in the `[ingress]` section.

Ingress values are not used by the configuration generation scripts, but used by the `scroll-sdk-cli` to configure hosts and TLS settings in the values files for each chart.

| Config Variable | Description | Default Value |
|-----------------|-------------|---------------|
| FRONTEND_HOST | Host for the frontend. | `frontends.scrollsdk` |
Expand All @@ -132,9 +205,13 @@ Local Devnet defaults shown.
| COORDINATOR_API_HOST | Host for the Coordinator API. | `coordinator-api.scrollsdk` |
| RPC_GATEWAY_HOST | Host for the RPC Gateway. | `l2-rpc.scrollsdk` |
| BLOCKSCOUT_HOST | Host for Blockscout. | `blockscout.scrollsdk` |
| BLOCKSCOUT_BACKEND_HOST | Host for Blockscout Backend. | `blockscout-backend.scrollsdk` |
| ADMIN_SYSTEM_DASHBOARD_HOST | Host for the Admin System Dashboard. | `admin-system-dashboard.scrollsdk` |
| L1_DEVNET_HOST | Host for the L1 Devnet. | `l1-devnet.scrollsdk` |
| L1_EXPLORER_HOST | Host for the L1 Explorer. | `l1-explorer.scrollsdk` |
| GRAFANA_HOST | Host for the Grafana frontend. | `grafana.scrollsdk` |

{/* TODO: Check Blockscout backend host after PR is merged. */}

## Sepolia Deployment

Expand All @@ -144,7 +221,7 @@ The `scroll-sdk-cli` tool has a command for generating new accounts setting the

### Generating Accounts

To generate new test accounts quickly, run the following command on a machine with Foundry installed.
To generate new test accounts quickly without using the `scroll-sdk-cli`, run the following command on a machine with Foundry installed.

```bash
cast wallet new --number 6 --json
Expand Down
26 changes: 17 additions & 9 deletions src/content/docs/en/sdk/technical-stack/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,35 +19,43 @@ The articles in this section will be focus on the various parts a Scroll SDK cha

### Scroll SDK Repo & Charts

Scroll SDK can be found [on GitHub](https://github.com/scroll-tech/scroll-sdk). The SDK built around Kubernetes and is designed to be easy to launch and maintain for anyone familiar with Kubernetes and Helm.
Scroll SDK can be found [on GitHub](https://github.com/scroll-tech/scroll-sdk). The SDK built is leveraging Kubernetes and is designed to be easy to launch and maintain for anyone familiar with Kubernetes and Helm.

The repo consists of these major components:
1. Example config files for preparing your network *(see [Configuration](/en/sdk/technical-stack/configuration))*
1. Helm charts for deploying the necessary services and contracts *(see [Services](/en/sdk/technical-stack/services))*
1. A docker image for building the correct configuration files for these services *(see [Smart Contracts](/en/sdk/technical-stack/contracts))*
1. An Ansible playbook for setting up a zk prover *(see [Proof Generation](/en/sdk/technical-stack/proof-generation))*
1. A docker image for building the correct configuration files for these services and gathering smart contract addresses before deployment *(see [Smart Contracts](/en/sdk/technical-stack/contracts))*
1. An Ansible playbook for setting up a zk prover if not using a third party proof generation service *(see [Proof Generation](/en/sdk/technical-stack/proof-generation))*

<Aside type="tip">
Although Scroll SDK is somewhat opinionated towards Kubernetes, it is designed to be easy to modify and extend, and every chart also lists the underlying Docker image and container commands.
Although Scroll SDK is somewhat opinionated towards Kubernetes, it is designed to be easy to modify and extend. Every chart lists the underlying Docker image and container commands.
</Aside>

### Scroll SDK CLI

Additionally, a [scroll-sdk-cli](https://github.com/scroll-tech/scroll-sdk-cli) tool is available to help with common automations and testing tasks.
Additionally, the [scroll-sdk-cli](https://github.com/scroll-tech/scroll-sdk-cli) tool is available to help with common automations and testing tasks. It greatly simplifies the process of creating a new Scroll SDK chain and includes a number of helpful commands for interacting with your chain.

It also supports custom plugins using the [oclif framework](https://oclif.com/docs/plugins).

## Scroll Proving SDK

The Scroll Proving SDK is a Rust crate for integrating Scroll SDK support into your prover services. The proof generation providers should use this SDK to build their own Helm charts, allowing SDK operators to out-source proof generation.

For an example service built using `scroll-proving-sdk`, see the `cloud.rs` example in the[Scroll Proving SDK](https://github.com/scroll-tech/scroll-proving-sdk/blob/haoyu/sindri_tokio/examples/cloud.rs) repo.

{/* TODO: check if this branch has been merged into main */}

## Deployment Process

Scroll SDK has two deployment options: a local devnet and a production deployment.

When deploying a local Devnet, all services are deployed by a single "chart". Configuration is minimal, and the deployment includes additional services like a hosting a database in the cluster. We assume users are working inside the `devnet` directory of a `scroll-sdk` clone.
When deploying a local Devnet, all services are deployed by a single "chart". Configuration is minimal, and the deployment includes additional services like a hosting a database in the cluster. We assume users are working inside the `devnet` directory of a `scroll-sdk` cloned repo.

In production deployments, each service is an independent chart. This is often more natural for tight control over upgrades and configuration. Production deployments assume that services like a database or monitoring stacks will be provided by the chain operator. Because of the additional modularity and flexibility, additional configuration is needed and some knowledge of Kubernetes may be required. We also assume users will create a new repo for storing their production workflow and configuration files.
In production deployments, each service is deployed as an independent chart. This is often more natural for tight control over upgrades and configuration. Production deployments assume that services like a database or monitoring stacks will be provided by the chain operator. Because of the additional modularity and flexibility, additional configuration is needed and some knowledge of Kubernetes is required. We also assume users will create a new repo for storing their production workflow and configuration files.

### Devnet

For a full devnet walkthrough, see the [Devnet Deployment](/en/sdk/guides/devnet-deployment) guide.
For a full devnet deployment walkthrough, see the [Devnet Deployment](/en/sdk/guides/devnet-deployment) guide.

#### PreReqs

Expand Down Expand Up @@ -118,4 +126,4 @@ In addition, you'll want to prepare the following items:
- A Kubernetes Ingress Controller (i.e. Nginx)
- A Secret Store for storing sensitive information (i.e. AWS Secrets, Hashicorp Vault) and a way to access it from Kubernetes using [External Secrets](https://external-secrets.io/latest/)

More information on choosing and setting up these services for various cloud providers will be provided in the [Guides](/en/sdk/guides) section.
More information on choosing and setting up these services for various cloud providers is provided in the [Guides](/en/sdk/guides) section.
Loading

0 comments on commit bf2c9c1

Please sign in to comment.