Merge branch 'main' into julien/catchup-base

Author: julienrbrt

docs/.vitepress/config.ts

@@ -269,6 +269,10 @@ function sidebarHome() {
               text: "Testnet",
               link: "/guides/deploy/testnet",
             },
+            {
+              text: "Mainnet",
+              link: "/guides/deploy/mainnet",
+            },
           ],
         },
         {

docs/guides/deploy/mainnet.md

@@ -0,0 +1,228 @@
+---
+description: Checklist and guide for launching an EVM mainnet using ev-node and ev-reth.
+---
+
+# EVM Mainnet Checklist
+
+This guide covers launching a mainnet using **ev-reth** and **ev-node**.
+
+## Ev-node
+
+Ev-node is the sequencer that creates blocks, propagates them to other peers, and submits them to the DA layer.
+
+### Chain ID
+
+- Pick a unique EVM chain ID for your network
+- Verify it does not collide with existing chains at [chainlist.org](https://chainlist.org)
+
+### Block Time
+
+- Pick a block time for your chain
+- **Optional:** Decide if you would like lazy blocks
+
+### Data Availability (DA)
+
+| Configuration | Description |
+|---|---|
+| Header Namespace | Required. Namespace for block headers. |
+| Data Namespace | Required. Namespace for block data. Two namespaces are recommended, but one can be used. |
+| Forced Inclusion Namespace | Optional. For censorship resistance. |
+| DA Block Time | Used for syncing with the DA layer. Set this to the block time of the underlying DA chain. |
+
+#### Batching Strategy
+
+Blob submission to the DA layer is controlled by the batching strategy, not the DA block time. Choose a strategy based on your latency vs. cost trade-off:
+
+| Strategy | Behavior |
+|---|---|
+| `immediate` | Submits as soon as any items are available. Lowest latency, highest cost. |
+| `size` | Waits until the batch reaches a size threshold (fraction of max blob size). |
+| `time` | Waits for a time interval (`batch_max_delay`) before submitting. Default strategy. |
+| `adaptive` | Submits when either the size threshold or the max delay is reached, whichever comes first. |
+
+Related configuration flags:
+
+- `da.batching_strategy` -- Strategy name (default: `time`)
+- `da.batch_size_threshold` -- Fraction of max blob size before submitting, 0.0-1.0 (default: 0.8). Applies to `size` and `adaptive`.
+- `da.batch_max_delay` -- Maximum wait time before submitting regardless of size (default: DA block time). Applies to `time` and `adaptive`.
+- `da.batch_min_items` -- Minimum items to accumulate before considering submission (default: 1).
+
+#### DA Account Funding
+
+The DA account needs tokens to submit blobs to the DA layer. If the account runs dry, blob submission stops and your chain halts.
+
+- Fund the DA account with sufficient tokens before launch
+- Set up balance monitoring with alerts at a threshold that gives you enough runway to top up (e.g. alert when balance drops below 48 hours of estimated submission costs)
+- Establish a process for topping up the DA account
+
+### Sequencer Key Management
+
+The sequencer signing key is the most security-critical component of your chain. A compromised key allows an attacker to produce arbitrary blocks.
+
+- Use an HSM or remote signer for the sequencer key in production -- do not store plaintext keys on disk
+- Restrict access to the sequencer machine to a minimal set of operators
+- Have a key rotation plan ready before launch
+
+### P2P
+
+- Configure p2p peers for a stable network
+- The sequencer should be connected to **at least two full nodes you control**
+- Third-party full nodes should connect to your full nodes, **not** directly to the sequencer
+
+### Network Security
+
+- Place the sequencer behind a firewall; only allow p2p connections from your own full nodes
+- Apply rate limiting on public RPC endpoints to prevent abuse
+- Consider DDoS mitigation (e.g. Cloudflare, HAProxy) in front of public-facing full nodes
+- Restrict SSH and management ports to a VPN or bastion host
+
+### Metrics and Monitoring
+
+- Set up a metric gathering system (Prometheus + Grafana recommended)
+- ev-metrics was created to help with basic metrics and alerting
+
+Key metrics to monitor:
+
+| Metric | Why |
+|---|---|
+| Block production rate | Detect if the sequencer has stalled |
+| DA submission lag / failures | Catch blob submission issues before they become critical |
+| Peer count | Ensure network connectivity is healthy |
+| Mempool depth | Detect congestion or spam |
+| Disk usage | Prevent nodes from running out of storage |
+| Sequencer balance | Ensure the sequencer can pay for DA submissions |
+| DA account balance | Chain halts if this runs dry |
+| RPC latency / error rate | Catch degraded user experience |
+
+### RPC
+
+- Use the full nodes connected to the sequencer for public/application RPCs
+- **Do not expose the sequencer directly**
+
+## Ev-reth
+
+Ev-reth is the execution engine. It uses reth as a library to make custom configurations for the Evolve use case. Changes are documented in the readme.
+
+### Precompiles
+
+Ev-reth comes with a set of optional precompiles:
+
+| Precompile | Description |
+|---|---|
+| Basefee Redirect | Redirects the basefee (burned under EIP-1559) to a specified address |
+| Native Mint & Burn | Allows minting and burning the native token. Can be used with a bridge like Hyperlane. |
+
+### Checklist
+
+- Decide which precompiles are needed
+- Set admin accounts for precompiles / basefee redirect
+- Decide if a proxy contract is needed (provided proxy contract)
+- Decide on EIP-1559 configurations
+- Configure basefee
+- Optional: Feevault contract
+
+### Backup and Recovery
+
+Establish a backup and recovery strategy before launch. See the [Reth State Backup](../evm/reth-backup.md) guide for detailed instructions.
+
+- Take periodic state snapshots (frequency depends on your RTO requirements)
+- Test the recovery procedure on a staging environment before mainnet launch
+- Keep at least one full node with archival state as a fallback
+- Document the recovery runbook so any operator can execute it
+
+### Upgrade Strategy
+
+Plan how you will ship new versions of ev-node and ev-reth to mainnet.
+
+- **Rolling restart order:** Upgrade full nodes first, then the sequencer. This ensures full nodes can handle the new version before the sequencer starts producing blocks with it.
+- **Hard fork coordination:** If a release includes consensus-breaking changes, coordinate an activation height with all node operators in advance.
+- **Rollback plan:** Know how to revert to the previous binary and state if an upgrade causes issues. Test this on a staging network.
+- **Communication:** Establish a channel (Telegram, Discord, etc.) to notify node operators of upcoming upgrades and activation heights.
+
+## Chain Startup Flow
+
+### Genesis
+
+Configuring the genesis is the first step to starting the chain.
+
+If using the proxy admin contract alongside both native mint/burn and basefee redirect, set the admin of those to the proxy contract. This allows the chain to modify the admin to a multisig later.
+
+#### Genesis Token Distribution
+
+Define the initial token supply and allocation before generating the genesis file.
+
+- Decide the total initial supply and how it is split (team, treasury, partners, bridge reserves, etc.)
+- Configure genesis balances in the `alloc` section of the genesis file
+- Ensure the sequencer EOA has enough balance to submit transactions
+- If using a bridge (e.g. Hyperlane), reserve sufficient supply for the bridge contract
+
+:::info
+All flows below assume usage of the proxy admin contract.
+:::
+
+### Flow 1: Full Setup
+
+**Basefee redirect + feevault + native mint/burn + bridge (Hyperlane)**
+
+#### Genesis Setup
+
+Embed the proxy contract with an EOA address as admin. The EOA must have at least one token to submit transactions. The proxy contract will have a predictable address, which is added to the `EvolveConfig` in the Chain Config as admin for feevault and native mint/burn.
+
+**Steps:**
+
+1. Pick an EOA as admin of the proxy contract
+2. Set EOA and create alloc of proxy contract for the genesis file
+3. Set the admin proxy contract as admin in Evolve config:
+
+```json
+{
+  "evolve": {
+    "baseFeeSink": "<EOA_to_receive_funds>",
+    "baseFeeRedirectActivationHeight": 0,
+    "mintAdmin": "<EOA_admin/proxyContract>",
+    "mintPrecompileActivationHeight": 0,
+    "contractSizeLimit": 131072,
+    "contractSizeLimitActivationHeight": 0
+  }
+}
+```
+
+4. Pick a max contract size (24kb default, 128kb is a safe upgrade)
+5. Pick EIP-1559 config:
+
+```json
+{
+  "baseFeeMaxChangeDenominator": 8,
+  "baseFeeElasticityMultiplier": 2,
+  "initialBaseFeePerGas": 1000000000
+}
+```
+
+#### Post Genesis
+
+- Deploy Hyperlane native mint contract (if using Hyperlane)
+- Provide funds to partner wallets deploying on your chain
+- Connect full nodes via reth p2p on top of the Evolve system (consult reth documentation for key discovery and connection)
+
+### Flow 2: Minimal Setup
+
+**Basefee redirect only, with an EOA receiving all funds.**
+
+#### Genesis Setup
+
+1. Set EOA address as the sink in the Evolve config
+2. Pick a max contract size (24kb default, 128kb is a safe upgrade)
+3. Pick EIP-1559 config:
+
+```json
+{
+  "baseFeeMaxChangeDenominator": 8,
+  "baseFeeElasticityMultiplier": 2,
+  "initialBaseFeePerGas": 1000000000
+}
+```
+
+#### Post Genesis
+
+- Provide funds to partner wallets deploying on your chain
+- Connect full nodes via reth p2p on top of the Evolve system (consult reth documentation for key discovery and connection)

execution/evm/test/execution_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 	"time"
 
+	tastoradocker "github.com/celestiaorg/tastora/framework/docker"
 	"github.com/ethereum/go-ethereum/common"
 	ethTypes "github.com/ethereum/go-ethereum/core/types"
 	"github.com/ethereum/go-ethereum/ethclient"
@@ -59,8 +60,10 @@ func TestEngineExecution(t *testing.T) {
 	genesisStateRoot := common.HexToHash(GENESIS_STATEROOT)
 	GenesisStateRoot := genesisStateRoot[:]
 
+	dockerClient, dockerNetworkID := tastoradocker.Setup(t)
+
 	t.Run("Build chain", func(tt *testing.T) {
-		rethNode := SetupTestRethNode(t)
+		rethNode := SetupTestRethNode(t, dockerClient, dockerNetworkID)
 
 		ni, err := rethNode.GetNetworkInfo(context.TODO())
 		require.NoError(tt, err)
@@ -158,7 +161,7 @@ func TestEngineExecution(t *testing.T) {
 
 	// start new container and try to sync
 	t.Run("Sync chain", func(tt *testing.T) {
-		rethNode := SetupTestRethNode(t)
+		rethNode := SetupTestRethNode(t, dockerClient, dockerNetworkID)
 
 		ni, err := rethNode.GetNetworkInfo(context.TODO())
 		require.NoError(tt, err)

execution/evm/test/test_helpers.go

@@ -9,11 +9,9 @@ import (
 	mathrand "math/rand"
 	"net/http"
 	"strings"
-	"sync"
 	"testing"
 	"time"
 
-	"github.com/celestiaorg/tastora/framework/docker"
 	"github.com/celestiaorg/tastora/framework/docker/evstack/reth"
 	"github.com/celestiaorg/tastora/framework/types"
 	"github.com/golang-jwt/jwt/v5"
@@ -22,12 +20,8 @@ import (
 	"go.uber.org/zap/zaptest"
 )
 
-// Test-scoped Docker client/network mapping to avoid conflicts between tests
-var (
-	dockerClients  = make(map[string]types.TastoraDockerClient)
-	dockerNetworks = make(map[string]string)
-	dockerMutex    sync.RWMutex
-)
+// RethNodeOpt allows tests to customize the reth node builder before building.
+type RethNodeOpt func(b *reth.NodeBuilder)
 
 const charset = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 
@@ -40,52 +34,36 @@ func randomString(n int) string {
 	return string(b)
 }
 
-// getTestScopedDockerSetup returns a Docker client and network ID that are scoped to the specific test.
-func getTestScopedDockerSetup(t testing.TB) (types.TastoraDockerClient, string) {
-	t.Helper()
-
-	testKey := t.Name()
-	dockerMutex.Lock()
-	defer dockerMutex.Unlock()
-
-	dockerCli, exists := dockerClients[testKey]
-	if !exists {
-		cli, netID := docker.Setup(t)
-		dockerClients[testKey] = cli
-		dockerNetworks[testKey] = netID
-		dockerCli = cli
-	}
-	dockerNetID := dockerNetworks[testKey]
-
-	return dockerCli, dockerNetID
-}
-
 // SetupTestRethNode creates a single Reth node for testing purposes.
-func SetupTestRethNode(t testing.TB) *reth.Node {
+func SetupTestRethNode(t testing.TB, client types.TastoraDockerClient, networkID string, opts ...RethNodeOpt) *reth.Node {
 	t.Helper()
 	ctx := context.Background()
 
-	dockerCli, dockerNetID := getTestScopedDockerSetup(t)
-
 	testName := fmt.Sprintf("%s-%s", t.Name(), randomString(6))
 	logger := zap.NewNop()
 	if testing.Verbose() {
 		logger = zaptest.NewLogger(t)
 	}
-	n, err := new(reth.NodeBuilder).
+	b := new(reth.NodeBuilder).
 		WithTestName(testName).
 		WithLogger(logger).
 		WithImage(reth.DefaultImage()).
 		WithBin("ev-reth").
-		WithDockerClient(dockerCli).
-		WithDockerNetworkID(dockerNetID).
-		WithGenesis([]byte(reth.DefaultEvolveGenesisJSON())).
-		Build(ctx)
+		WithDockerClient(client).
+		WithDockerNetworkID(networkID).
+		WithGenesis([]byte(reth.DefaultEvolveGenesisJSON()))
+
+	for _, opt := range opts {
+		if opt != nil {
+			opt(b)
+		}
+	}
+
+	n, err := b.Build(ctx)
+	require.NoError(t, err)
 	t.Cleanup(func() {
 		_ = n.Remove(context.Background())
 	})
-
-	require.NoError(t, err)
 	require.NoError(t, n.Start(ctx))
 
 	ni, err := n.GetNetworkInfo(ctx)

test/e2e/evm_contract_e2e_test.go

@@ -10,6 +10,7 @@ import (
 	"testing"
 	"time"
 
+	tastoradocker "github.com/celestiaorg/tastora/framework/docker"
 	"github.com/ethereum/go-ethereum"
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/common/hexutil"
@@ -243,7 +244,8 @@ func TestEvmContractEvents(t *testing.T) {
 func setupTestSequencer(t testing.TB, homeDir string, extraArgs ...string) (*ethclient.Client, string, func()) {
 	sut := NewSystemUnderTest(t)
 
-	genesisHash, seqEthURL := setupSequencerOnlyTest(t, sut, homeDir, extraArgs...)
+	dcli, netID := tastoradocker.Setup(t)
+	genesisHash, seqEthURL := setupSequencerOnlyTest(t, sut, homeDir, dcli, netID, extraArgs...)
 	t.Logf("Sequencer started at %s (Genesis: %s)", seqEthURL, genesisHash)
 
 	client, err := ethclient.Dial(seqEthURL)

test/e2e/evm_da_restart_e2e_test.go

@@ -24,6 +24,7 @@ import (
 	"testing"
 	"time"
 
+	tastoradocker "github.com/celestiaorg/tastora/framework/docker"
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/ethclient"
 	"github.com/stretchr/testify/require"
@@ -56,7 +57,8 @@ func TestEvmDARestartWithPendingBlocksE2E(t *testing.T) {
 	sut := NewSystemUnderTest(t)
 
 	// Setup sequencer and get genesis hash
-	genesisHash, seqURL := setupSequencerOnlyTest(t, sut, nodeHome)
+	dcli, netID := tastoradocker.Setup(t)
+	genesisHash, seqURL := setupSequencerOnlyTest(t, sut, nodeHome, dcli, netID)
 	t.Logf("Genesis hash: %s", genesisHash)
 
 	// Connect to EVM