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 on macOS and Ubuntu.
We’ve written this guide because local deployments of Kubernetes clusters can be finicky. Even the prerequisites can be tricky without help.
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
- October 30, 2024
- Updated for Scroll SDK v0.1.0
Prerequisites
-
Install dependencies (using
brew
is strongly recommended):- Brew (optional)
/bin/bash -c "$(curl -fsSL 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-tech/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 --dev
-
Update system packages:
-
Install Docker:
-
Install kubectl:
-
Install minikube:
-
Install Helm:
-
Install Node and scroll-sdk-cli:
-
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 --dev
Starting minikube
First, we need to allow minikube sufficient resources to run the devnet.
Next, we start minikube.
Mac requires extra commands as a work-around for ingress-dns
not working correctly on arm64 MacOS. Hopefully the issue will be resolved in later versions of minikube.
Add your user to the docker group.
Now you are ready to start minikube.
Installing Scroll SDK
-
Clone the
scroll-sdk
repo and finddevnet
directory -
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. We 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
after to regenerate the additional configuration files. No services directly read from theconfig.toml
file. -
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.The install process for the various containers can take several minutes as new docker images are downloaded and services wait on others to be online to start.
After Launching the Stack
Configuring DNS
Running kubectl get ingress
should show all the domains setup within the cluster, like the following:
To resolve the ingress domains, we need to add the minikube IP and our service hostnames to the hosts file.
-
Get your minikube IP address:
This should return something like
192.168.49.2
. -
Add this IP and our service hostnames to the hosts file:
-
Add the following entries to the file, replacing
192.168.49.2
with your minikube IP if different: -
Save the file by pressing
Ctrl+X
, thenY
, thenEnter
.
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
).
-
Create the following file at
/etc/resolver/minikube-scrollsdk
(will requiresudo
access).Alternatively, this can be done in one command that creates the directory and file and then outputs the required info:
-
Flush your DNS:
Testing Ingress DNS
Now, test ingress and your access to the services by running scrollsdk test ingress
.
If you aren’t using the CLI tool, you can manually test the ingress DNS by running:
-
nslookup frontends.scrollsdk $(minikube ip)
-
curl frontends.scrollsdk
-
If those work, visit
http://frontends.scrollsdk
in your browser. -
If those do not work:
- For MacOS: Try resetting your machine and running through the DNS setup instructions again. It may help to run
minikube stop
andminikube start
again. - For Ubuntu: Double check that your minikube IP matches what’s in your
/etc/hosts
file by runningminikube ip
.
- For MacOS: Try resetting your machine and running through the DNS setup instructions again. It may help to run
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 to fund the 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 (not the original config.toml
):
- Make any necessary changes to the config files or helm charts
- Run
make install
- Delete the running pod by running
kubectl delete pod [pod-name]
. Kubernetes will restart the pod with the updated config.
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 |
What’s Next?
If you’re a developer, you might want to try customizing specific sdk components.
If you’re looking to learn more about running a public testnet, try out a production deployment with our Digital Ocean guide or our AWS guide.
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