Awesome
Welcome to Optimism Package
The default package for Optimism. The kurtosis package uses op-deployer to manage the L2 chains and all associated artifacts such as contract deployments.
optimism_package:
chains:
- participants:
- el_type: op-geth
cl_type: op-node
- el_type: op-reth
- el_type: op-erigon
- el_type: op-nethermind
ethereum_package:
network_params:
preset: minimal
genesis_delay: 5
additional_preloaded_contracts: '
{
"0x4e59b44847b379578588920cA78FbF26c0B4956C": {
"balance": "0ETH",
"code": "0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3",
"storage": {},
"nonce": "1"
}
}
'
Please note, by default your network will be running a minimal preset Ethereum network. Click here to learn more about minimal preset. You can customize the L1 Ethereum network by modifying the ethereum_package configuration.
You can also completely remove ethereum_package from your configuration in which case it will default to a minimal preset Ethereum network.
Quickstart
Run with your own configuration
Kurtosis packages are parameterizable, meaning you can customize your network and its behavior to suit your needs by storing parameters in a file that you can pass in at runtime like so:
kurtosis run github.com/ethpandaops/optimism-package --args-file https://raw.githubusercontent.com/ethpandaops/optimism-package/main/network_params.yaml
For --args-file parameters file, you can pass a local file path or a URL to a file.
To clean up running enclaves and data, you can run:
kurtosis clean -a
This will stop and remove all running enclaves and delete all data.
Run with changes to the optimism package
If you are attempting to test any changes to the package code, you can point to the directory as the run argument
cd ~/go/src/github.com/ethpandaops/optimism-package
kurtosis run . --args-file ./network_params.yaml
L2 Contract deployer
The enclave will automatically deploy an optimism L2 contract on the L1 network. The contract address will be printed in the logs. You can use this contract address to interact with the L2 network.
Please refer to this Dockerfile if you want to see how the contract deployer image is built: Dockerfile
Configuration
To configure the package behaviour, you can modify your network_params.yaml file and use that as the input to --args-file.
The full YAML schema that can be passed in is as follows with the defaults provided:
optimism_package:
# An array of L2 networks to run
chains:
# Specification of the optimism-participants in the network
- participants:
# EL(Execution Layer) Specific flags
# The type of EL client that should be started
# Valid values are:
# op-geth
# op-reth
# op-erigon
# op-nethermind
# op-besu
- el_type: op-geth
# The Docker image that should be used for the EL client; leave blank to use the default for the client type
# Defaults by client:
# - op-geth: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-geth:latest
# - op-reth: parithoshj/op-reth:latest
# - op-erigon: testinprod/op-erigon:latest
# - op-nethermind: nethermindeth/nethermind:op-c482d56
# - op-besu: ghcr.io/optimism-java/op-besu:latest
el_image: ""
# The log level string that this participant's EL client should log at
# If this is emptystring then the global `logLevel` parameter's value will be translated into a string appropriate for the client (e.g. if
# global `logLevel` = `info` then Geth would receive `3`, Besu would receive `INFO`, etc.)
# If this is not emptystring, then this value will override the global `logLevel` setting to allow for fine-grained control
# over a specific participant's logging
el_log_level: ""
# A list of optional extra env_vars the el container should spin up with
el_extra_env_vars: {}
# A list of optional extra labels the el container should spin up with
# Example; el_extra_labels: {"ethereum-package.partition": "1"}
el_extra_labels: {}
# A list of optional extra params that will be passed to the EL client container for modifying its behaviour
el_extra_params: []
# A list of tolerations that will be passed to the EL client container
# Only works with Kubernetes
# Example: el_tolerations:
# - key: "key"
# operator: "Equal"
# value: "value"
# effect: "NoSchedule"
# toleration_seconds: 3600
# Defaults to empty
el_tolerations: []
# Persistent storage size for the EL client container (in MB)
# Defaults to 0, which means that the default size for the client will be used
# Default values can be found in /src/package_io/constants.star VOLUME_SIZE
el_volume_size: 0
# Resource management for el containers
# CPU is milicores
# RAM is in MB
# Defaults to 0, which results in no resource limits
el_min_cpu: 0
el_max_cpu: 0
el_min_mem: 0
el_max_mem: 0
# CL(Consensus Layer) Specific flags
# The type of CL client that should be started
# Valid values are:
# op-node
# hildr
cl_type: op-node
# The Docker image that should be used for the CL client; leave blank to use the default for the client type
# Defaults by client:
# - op-node: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:develop
# - hildr: ghcr.io/optimism-java/hildr:latest
cl_image: ""
# The log level string that this participant's CL client should log at
# If this is emptystring then the global `logLevel` parameter's value will be translated into a string appropriate for the client (e.g. if
# If this is not emptystring, then this value will override the global `logLevel` setting to allow for fine-grained control
# over a specific participant's logging
cl_log_level: ""
# A list of optional extra env_vars the cl container should spin up with
cl_extra_env_vars: {}
# A list of optional extra labels that will be passed to the CL client Beacon container.
# Example; cl_extra_labels: {"ethereum-package.partition": "1"}
cl_extra_labels: {}
# A list of optional extra params that will be passed to the CL client Beacon container for modifying its behaviour
# If the client combines the Beacon & validator nodes (e.g. Teku, Nimbus), then this list will be passed to the combined Beacon-validator node
cl_extra_params: []
# A list of tolerations that will be passed to the CL client container
# Only works with Kubernetes
# Example: el_tolerations:
# - key: "key"
# operator: "Equal"
# value: "value"
# effect: "NoSchedule"
# toleration_seconds: 3600
# Defaults to empty
cl_tolerations: []
# Persistent storage size for the CL client container (in MB)
# Defaults to 0, which means that the default size for the client will be used
# Default values can be found in /src/package_io/constants.star VOLUME_SIZE
cl_volume_size: 0
# Resource management for cl containers
# CPU is milicores
# RAM is in MB
# Defaults to 0, which results in no resource limits
cl_min_cpu: 0
cl_max_cpu: 0
cl_min_mem: 0
cl_max_mem: 0
# Builder client specific flags
# The type of builder EL client that should be started
# Valid values are:
# op-geth
# op-reth
el_builder_type: ""
# The Docker image that should be used for the builder EL client; leave blank to use the default for the client type
# Defaults by client:
# - op-geth: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-geth:latest
# - op-reth: parithoshj/op-reth:latest
el_builder_image: ""
# The type of builder CL client that should be started
# Valid values are:
# op-node
# hildr
cl_builder_type: ""
# The Docker image that should be used for the builder CL client; leave blank to use the default for the client type
# Defaults by client:
# - op-node: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:develop
# - hildr: ghcr.io/optimism-java/hildr:latest
cl_builder_image: ""
# Participant specific flags
# Node selector
# Only works with Kubernetes
# Example: node_selectors: { "disktype": "ssd" }
# Defaults to empty
node_selectors: {}
# A list of tolerations that will be passed to the EL/CL/validator containers
# This is to be used when you don't want to specify the tolerations for each container separately
# Only works with Kubernetes
# Example: tolerations:
# - key: "key"
# operator: "Equal"
# value: "value"
# effect: "NoSchedule"
# toleration_seconds: 3600
# Defaults to empty
tolerations: []
# Count of nodes to spin up for this participant
# Default to 1
count: 1
# Default configuration parameters for the network
network_params:
# Network name, used to enable syncing of alternative networks
# Defaults to "kurtosis"
network: "kurtosis"
# The network ID of the network.
# Must be unique for each network (if you run multiple networks)
# Defaults to "2151908"
network_id: "2151908"
# Seconds per slots
seconds_per_slot: 2
# Name of your rollup.
# Must be unique for each rollup (if you run multiple rollups)
# Defaults to "op-kurtosis"
name: "op-kurtosis"
# Triggering future forks in the network
# Fjord fork
# Defaults to 0 (genesis activation) - decimal value
# Offset is in seconds
fjord_time_offset: 0
# Granite fork
# Defaults to 0 (genesis activation) - decimal value
# Offset is in seconds
granite_time_offset: 0
# Holocene fork
# Defaults to None - not activated - decimal value
# Offset is in seconds
holocene_time_offset: ""
# Isthmus fork
# Defaults to None - not activated - decimal value
# Offset is in seconds
isthmus_time_offset: ""
# Interop fork
# Defaults to None - not activated - decimal value
# Offset is in seconds
interop_time_offset: ""
# Whether to fund dev accounts on L2
# Defaults to True
fund_dev_accounts: true
# Default batcher configuration
batcher_params:
# The Docker image that should be used for the batcher; leave blank to use the default op-batcher image
image: ""
# A list of optional extra params that will be passed to the batcher container for modifying its behaviour
extra_params: []
# Default MEV configuration
mev_params:
# The Docker image that should be used for rollup boost; leave blank to use the default rollup-boost image
# Defaults to "flashbots/rollup-boost:latest"
rollup_boost_image: ""
# The host of an external builder
builder_host: ""
# The port of an external builder
builder_port: ""
# Additional services to run alongside the network
# Defaults to []
# Available services:
# - blockscout
# - rollup-boost
additional_services: []
# L2 contract deployer configuration - used for all L2 networks
# The docker image that should be used for the L2 contract deployer
op_contract_deployer_params:
image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-deployer:v0.0.7
l1_artifacts_locator: https://storage.googleapis.com/oplabs-contract-artifacts/artifacts-v1-9af7366a7102f51e8dbe451dcfa22971131d89e218915c91f420a164cc48be65.tar.gz
l2_artifacts_locator: https://storage.googleapis.com/oplabs-contract-artifacts/artifacts-v1-9af7366a7102f51e8dbe451dcfa22971131d89e218915c91f420a164cc48be65.tar.gz
# The global log level that all clients should log at
# Valid values are "error", "warn", "info", "debug", and "trace"
# This value will be overridden by participant-specific values
global_log_level: "info"
# Global node selector that will be passed to all containers (unless overridden by a more specific node selector)
# Only works with Kubernetes
# Example: global_node_selectors: { "disktype": "ssd" }
# Defaults to empty
global_node_selectors: {}
# Global tolerations that will be passed to all containers (unless overridden by a more specific toleration)
# Only works with Kubernetes
# Example: tolerations:
# - key: "key"
# operator: "Equal"
# value: "value"
# effect: "NoSchedule"
# toleration_seconds: 3600
# Defaults to empty
global_tolerations: []
# Whether the environment should be persistent; this is WIP and is slowly being rolled out accross services
# Defaults to false
persistent: false
# Ethereum package configuration
ethereum_package:
network_params:
# The Ethereum network preset to use
preset: minimal
# The delay in seconds before the genesis block is mined
genesis_delay: 5
# Preloaded contracts for the Ethereum network
additional_preloaded_contracts: '
{
"0x4e59b44847b379578588920cA78FbF26c0B4956C": {
"balance": "0ETH",
"code": "0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3",
"storage": {},
"nonce": "1"
}
}
'
Additional configuration recommendations
L1 customization
It is required you to launch an L1 Ethereum node to interact with the L2 network. You can use the ethereum_package to launch an Ethereum node. The ethereum_package configuration is as follows:
optimism_package:
chains:
- participants:
- el_type: op-geth
cl_type: op-node
additional_services:
- blockscout
ethereum_package:
participants:
- el_type: geth
- el_type: reth
network_params:
preset: minimal
genesis_delay: 5
additional_preloaded_contracts: '
{
"0x4e59b44847b379578588920cA78FbF26c0B4956C": {
"balance": "0ETH",
"code": "0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3",
"storage": {},
"nonce": "1"
}
}
'
additional_services:
- dora
- blockscout
L2 customization with Hard Fork transitions
To spin up an L2 chain with specific hard fork transition blocks and any local docker image to run the EL/CL components,
use the network_params section of your arguments file to specify the hard fork transitions and custom images.
optimism_package:
chains:
- participants:
- el_type: op-geth
el_image: "us-docker.pkg.dev/oplabs-tools-artifacts/images/op-geth:<tag>"
cl_type: op-node
cl_image: "us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:<tag>"
- el_type: op-geth
el_image: "us-docker.pkg.dev/oplabs-tools-artifacts/images/op-geth:<tag>"
cl_type: op-node
cl_image: "us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:<tag>"
network_params:
fjord_time_offset: 0
granite_time_offset: 0
holocene_time_offset: 4
isthmus_time_offset: 8
Multiple L2 chains
Additionally, you can spin up multiple L2 networks by providing a list of L2 configuration parameters like so:
optimism_package:
chains:
- participants:
- el_type: op-geth
network_params:
name: op-rollup-one
network_id: "3151909"
additional_services:
- blockscout
- participants:
- el_type: op-geth
network_params:
name: op-rollup-two
network_id: "3151910"
additional_services:
- blockscout
ethereum_package:
participants:
- el_type: geth
- el_type: reth
network_params:
preset: minimal
genesis_delay: 5
additional_preloaded_contracts: '
{
"0x4e59b44847b379578588920cA78FbF26c0B4956C": {
"balance": "0ETH",
"code": "0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe03601600081602082378035828234f58015156039578182fd5b8082525050506014600cf3",
"storage": {},
"nonce": "1"
}
}
'
additional_services:
- dora
- blockscout
Note: if configuring multiple L2s, make sure that the network_id and name are set to differentiate networks.
Rollup Boost for External Block Building
Rollup Boost is a sidecar to the sequencer op-node that allows blocks to be built by an external builder on the L2 network.
To use rollup boost, you can add rollup-boost as an additional service and configure the mev_params section of your arguments file to specify the rollup boost image. Optionally, you can specify the host and port of an external builder outside of the Kurtosis enclave.
optimism_package:
chains:
- participants:
- el_builder_type: op-geth
cl_builder_type: op-node
mev_params:
rollup_boost_image: "flashbots/rollup-boost:latest"
builder_host: "localhost"
builder_port: "8545"
additional_services:
- rollup-boost
Run tx-fuzz to send l2 transactions
Compile https://github.com/MariusVanDerWijden/tx-fuzz locally per instructions in the repo. Run tx-fuzz against the l2 EL client's RPC URL and using the pre-funded wallet
./livefuzzer spam --sk "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80" --rpc http://127.0.0.1:<port> --slot-time 2
Additional configurations
Please find examples of additional configurations in the test folder.
Useful Kurtosis commands
Inspect enclave -- Container/Port information
- List information about running containers and open ports
kurtosis enclave ls
kurtosis enclave inspect <enclave-name>
- Inspect chain state.
kurtosis files inspect <enclave-name> op-deployer-configs
- Dump all files generated by kurtosis to disk (for inspecting chain state/deploy configs/contract addresses etc.). A file that contains an exhaustive
set of information about the current deployment is
files/op-deployer-configs/state.json. Deployed contract address, roles etc can all be found here.
kurtosis enclave dump <enclave-name> -- dumps all files to a enclave-name prefixed directory under the current directory
kurtosis files download <enclave-name> op-deployer-configs <where-to-download>
- Get logs for running services
kurtosis service logs <enclave-name> <service-name> -f . (-f tails the log)
- Stop/Start running service (restart sequencer/batcher/op-geth etc.)
kurtosis service stop <enclave-name> <service-name>
kurtosis service start <enclave-name> <service-name>
Contributing
If you have made changes and would like to submit a PR, test locally and make sure to run lint on your changes
kurtosis lint --format .