Running Scroll SDK Devnet
Overview
This guide should get you started with running a local Scroll SDK devnet. Additionally, it has specific asides for running is on macos.
This guide assumes you have access to the scroll-sdk github repo using your local machine.
We’ve written this guide because local deployments for Kubernetes clusters can be finicky.
By the end of the guide, you should have a Scroll SDK running with a block explorer, RPC, webUI, monitoring and metrics, and a local L1. These are all accessible to wallets, browsers, and applications running on your local machine.
Updates to the Guide
- August 26, 2024
- Changes for repository refactor, including new CLI tool commands.
- July 31, 2024
- Adding additional
make
commands andminikube
config
- Adding additional
- June 26, 2024
- Minor typography fixes i.e.
docker v
todocker -v
- Minor typography fixes i.e.
- June 19, 2024
- Removed external
bjw-s
dependency and prerequisite - Removed manual modification of
.env.frontends
- Updated docker image name used in generating config files
- Removed external
- June 18, 2024
- Fixed
minikube addons enable
commands (missing “addons”)
- Fixed
Prerequisites
- Install dependencies (using
brew
is strongly recommended):- Brew (optional)
/bin/bash -c "$(curl -fsSL [https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh](https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh))"
- Docker (Docker Desktop)
brew install --cask docker
- kubectl
brew install kubectl
- minikube
brew install minikube
- Helm
brew install helm
- docker-mac-net-connect (macOS ARM64 only)
brew install chipmk/tap/docker-mac-net-connect
- Brew (optional)
- Optional: Install dependencies for support CLI tool:
- node >=18
brew install nvm
nvm install node
- scroll-sdk-cli (Experimental, APIs may change)
npm install -g scroll-sdk-cli
- node >=18
- You should now be able to open a terminal and run the following:
docker -v
kubectl version
minikube status
helm version
node -v
scrollsdk
- Or, in one step:
scrollsdk test dependencies
Starting minikube
To start minikube, run:
Getting minikube to work with custom DNS names on MacOS
Now run the following commands:
Installing Scroll SDK
-
Clone the
scroll-sdk
repo and finddevnet
directoryYou’ll need If you need repo access, reach out to
@dghelm
on Telegram. -
Bootstrap
Now we’ll install Helm chart dependencies, generate additional config files for our services, and create our
genesis.json
file. -
Optional: Configure
values.yaml
andconfig.toml
This is the time to adjust what services run on your stack and their configuration. I’d suggest not altering these on your first installation, but see
charts/scroll-sdk/values.yaml
(view on Github) andconfig.toml
(view on Github).If you do make changes, you’ll need to run
make config
to regenerate the additional configuration files. -
Launch the chain!
Your chain is now starting! Run
kubectl get pods
to check in on their progress. In the next section we’ll expose the chain to your local machine so you can interact with the stack.
After Launching the Stack
Funding SDK Addresses
You will need to provide funds to the following accounts:
DEPLOYER_ADDR
(only needs funded on L1)- In the default configuration, this account is pre-funded by Anvil. If changed, you’ll need to relaunch the contracts pod after funding to deploy the contracts.
L1_COMMIT_SENDER_ADDR
L1_FINALIZE_SENDER_ADDR
L1_GAS_ORACLE_SENDER_ADDR
L2_GAS_ORACLE_SENDER_ADDR
(funded after L2 chain deployment)
If you installed the necessary prerequisites, you can run the cli helper command after Pointing DNS Requests to the Cluster. (Note: this command only works for L1 accounts)
Other Useful Commands
kubectl get pods
will show all the active pods and their status.
kubectl get ingress
will show all the exposed services and URIs.
make delete
will stop all services. You wil also need to run kubectl delete pvc data-l2-rpc-0
to delete the remaining pvc.
minikube dashboard
launches a WebUI for exploring the kubernetes cluster and the various pods, volumes and ingresses without learning all the CLI commands. k9s
is also a CLI great tool for exploring running pods and quickly looking at their logs.
If you need to update a specific service’s config file:
- Make any necessary changes to the config or helm charts
- Run
make install
- Delete the running pod by running
kubectl delete pod [pod-name]
Pointing DNS Requests to the Cluster (MacOS on ARM64)
Running kubectl get ingress
should show all the domains setup within the cluster, like the following:
Now, we’ll follow the instructions from the minikube docs for setting up our local machine to use our cluster to resolve all .scrollsdk
domain requests.
Take note of the ADDRESS
in your output (it should match the result of running minikube ip
).
You’ll want to create the following file at /etc/resolver/minikube-scrollsdk
(will require sudo
access).
If you prefer, this can be done in one command that creates the directory and file and then outputs the required info:
Lastly, flush your DNS:
Testing Ingress DNS
Try running:
nslookup frontends.scrollsdk $(minikube ip)
curl frontends.scrollsdk
- If those work, visit
http://frontends.scrollsdk
in your browser.- If those do not work, try resetting your machine and running through the instructions in Getting minikube to work with custom DNS names on MacOS and above again. It may help to run
minikube stop
andminikube start
again.
- If those do not work, try resetting your machine and running through the instructions in Getting minikube to work with custom DNS names on MacOS and above again. It may help to run
Testing & Interacting with the Chain
scroll-sdk-CLI
The scroll-sdk-cli tool has many helper commands. Run it in the same directory as your config.toml
file in the ./devnet/scroll-sdk
folder.
scrollsdk test ingress
will test if your ingress is configured correctly and host urls are accessible from your machine.scrollsdk test contracts
will check that essential contracts are deployed, initialized and have the correct owner.scrollsdk helper fund-accounts --dev -a [account-address]
will fund any account.scrollsdk helper activity -o -t
will generate activity on both layer one and layer two to help produce blocks and batches.
End-To-End Test
The scrollsdk test e2e
command will walk you through generating the following tests on your chain:
- Generate a new wallet
- Fund it from the Deployer address on L1
- Deposit funds to the L2
- Deploying an ERC20 and depositing them to the L2
- Deploying an ERC20 on the L2
- Bridging ETH and ERC20 from L2 back to L1
- Executing the withdrawal claim on L1
If any step fails, you can restart where you left off by adding the --resume
flag.
Web UIs
You should now be able to explore the stack on your local machine and using your web browser. All links below assume default configuration and working Ingress DNS.
- Block Explorers (Blockscout)
- L2 Explorer
- L1 Explorer (this is scanning Anvil and can be a bit buggy)
- Bridge
- Until some activity on the network has started, gas errors may occur.
- Rollup Explorer
- Shows committed batches and finalized batches
- Granfana Dashboards
- Login
- User:
admin
- Pass:
scroll-sdk
- User:
- See “Scroll” dashboards on this page.
- Login
Connecting to the RPC using a Wallet
To connect directly to an RPC or using MetaMask, use:
Network | Scroll SDK Chain | Scroll SDK L1 |
---|---|---|
RPC URL | http://l2-rpc.scrollsdk | http://l1-devnet.scrollsdk |
Chain ID | 221122 | 111111 |
Currency Symbol | ETH | ETH |
Block Explorer URL | http://blockscout.scrollsdk | http://l1-devnet-explorer.scrollsdk |
Helpful Commands
Anvil has a lot of useful methods that can manipulate the L1. Proper documentation for using them is available in the Hardhat docs (replacing hardhat_
with anvil_
)
Set L1 Token Balance of an Account
In params, change first item to a wallet, and second to hex of wei. This config uses 1000 ETH.
See docs for details.
Mine some L1 Block
See docs for details.
Troubleshooting
ingress-dns
issues
Getting ingress-dns
can be tricky across different machines, operating systems and network configurations.
Directly editing etc/hosts
has worked for some users, adding all ingress hosts pointing to the minikube IP address.
Follow the template below, being sure to create one value for every ingress in your configuration. Also, be sure to try the IP of your minikube deployment.
For VPN users, we’ve seen the following work:
-
Execute command
sudo minikube tunnel
-
Open file
/etc/hosts
and add: -
Turn off VPN when visiting in browser