Merge branch 'main' into feature/more-prefunded-accounts

Author: maoueh

.github/workflows/checks.yaml

@@ -49,21 +49,3 @@ jobs:
           name: playground-logs-${{ matrix.flags }}
           path: /tmp/playground-logs
           retention-days: 5
-
-  artifacts:
-    name: Artifacts
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-13]
-    runs-on: ${{ matrix.os }}
-    steps:
-      - name: Check out code
-        uses: actions/checkout@v2
-
-      - name: Set up Go
-        uses: actions/setup-go@v2
-        with:
-          go-version: 1.24
-
-      - name: Download and test artifacts
-        run: go run main.go artifacts-all

.gitignore

@@ -1,3 +1,4 @@
 local-testnet
 output
 builder-playground
+**/.DS_Store

README.md

@@ -91,6 +91,64 @@ The following addresses are pre-funded on L1 and to L2 (if present), all with a
 - `0x23618e81e3f5cdf7f54c3d65f7fbc0abf5b21e8f` (Private key `0xdbda1821b80551c9d65939329250298aa3472ba22feea921c0cf5d620ea67b97`)
 - `0xa0ee7a142d267c1f36714e4a8f75612f20a79720` (Private key `0x2a871d0798f97d79848a013d4936a73bf4cc922c825d33c1cf7073dff6d409c6`)
 
+## Network Readiness
+
+The playground can expose a `/readyz` HTTP endpoint to check if the network is ready to accept transactions (i.e., blocks are being produced).
+
+### Readyz Endpoint
+
+Enable the readyz server with the `--readyz-port` flag:
+
+```bash
+$ builder-playground cook l1 --readyz-port 8080
+```
+
+Then check readiness:
+
+```bash
+$ curl http://localhost:8080/readyz
+{"ready":true}
+```
+
+Returns:
+- `200 OK` with `{"ready": true}` when the network is producing blocks
+- `503 Service Unavailable` with `{"ready": false, "error": "..."}` otherwise
+
+### Wait-Ready Command
+
+Use the `wait-ready` command to block until the network is ready:
+
+```bash
+$ builder-playground wait-ready [flags]
+```
+
+Flags:
+- `--url` (string): readyz endpoint URL. Defaults to `http://localhost:8080/readyz`
+- `--timeout` (duration): Maximum time to wait. Defaults to `60s`
+- `--interval` (duration): Poll interval. Defaults to `1s`
+
+Example:
+
+```bash
+# In terminal 1: Start the playground with readyz enabled
+$ builder-playground cook l1 --readyz-port 8080
+
+# In terminal 2: Wait for the network to be ready
+$ builder-playground wait-ready --timeout 120s
+Waiting for http://localhost:8080/readyz (timeout: 2m0s, interval: 1s)
+  [1s] Attempt 1: 503 Service Unavailable
+  [2s] Attempt 2: 503 Service Unavailable
+  [3s] Ready! (200 OK)
+```
+
+This is useful for CI/CD pipelines or scripts that need to wait for the network before deploying contracts.
+
+Alternatively, use a bash one-liner:
+
+```bash
+$ timeout 60 bash -c 'until curl -sf http://localhost:8080/readyz | grep -q "\"ready\":true"; do sleep 1; done'
+```
+
 ## Inspect
 
 Builder-playground supports inspecting the connection of a service to a specific port.

main.go

@@ -13,6 +13,7 @@ import (
 	"time"
 
 	"github.com/flashbots/builder-playground/playground"
+	"github.com/flashbots/builder-playground/playground/cmd"
 	"github.com/spf13/cobra"
 )
 
@@ -34,6 +35,7 @@ var contenderEnabled bool
 var contenderArgs []string
 var contenderTarget string
 var prefundedAccounts []string
+var readyzPort int
 
 var rootCmd = &cobra.Command{
 	Use:   "playground",
@@ -56,73 +58,6 @@ var cookCmd = &cobra.Command{
 	},
 }
 
-var artifactsCmd = &cobra.Command{
-	Use:   "artifacts",
-	Short: "List available artifacts",
-	RunE: func(cmd *cobra.Command, args []string) error {
-		if len(args) != 1 {
-			return fmt.Errorf("please specify a service name")
-		}
-		serviceName := args[0]
-		component := playground.FindComponent(serviceName)
-		if component == nil {
-			return fmt.Errorf("service %s not found", serviceName)
-		}
-		releaseService, ok := component.(playground.ReleaseService)
-		if !ok {
-			return fmt.Errorf("service %s is not a release service", serviceName)
-		}
-		output := outputFlag
-		if output == "" {
-			homeDir, err := playground.GetHomeDir()
-			if err != nil {
-				return fmt.Errorf("failed to get home directory: %w", err)
-			}
-			output = homeDir
-		}
-		location, err := playground.DownloadRelease(output, releaseService.ReleaseArtifact())
-		if err != nil {
-			return fmt.Errorf("failed to download release: %w", err)
-		}
-		fmt.Println(location)
-		return nil
-	},
-}
-
-var artifactsAllCmd = &cobra.Command{
-	Use:   "artifacts-all",
-	Short: "Download all the artifacts available in the catalog (Used for testing purposes)",
-	RunE: func(cmd *cobra.Command, args []string) error {
-		fmt.Println("Downloading all artifacts...")
-
-		output := outputFlag
-		if output == "" {
-			homeDir, err := playground.GetHomeDir()
-			if err != nil {
-				return fmt.Errorf("failed to get home directory: %w", err)
-			}
-			output = homeDir
-		}
-		for _, component := range playground.Components {
-			releaseService, ok := component.(playground.ReleaseService)
-			if !ok {
-				continue
-			}
-			location, err := playground.DownloadRelease(output, releaseService.ReleaseArtifact())
-			if err != nil {
-				return fmt.Errorf("failed to download release: %w", err)
-			}
-
-			// make sure the artifact is valid to be executed on this platform
-			log.Printf("Downloaded %s to %s\n", releaseService.ReleaseArtifact().Name, location)
-			if err := isExecutableValid(location); err != nil {
-				return fmt.Errorf("failed to check if artifact is valid: %w", err)
-			}
-		}
-		return nil
-	},
-}
-
 var inspectCmd = &cobra.Command{
 	Use:   "inspect",
 	Short: "Inspect a connection between two services",
@@ -187,18 +122,16 @@ func main() {
 		recipeCmd.Flags().StringArrayVar(&contenderArgs, "contender.arg", []string{}, "add/override contender CLI flags")
 		recipeCmd.Flags().StringVar(&contenderTarget, "contender.target", "", "override the node that contender spams -- accepts names like \"el\"")
 		recipeCmd.Flags().StringArrayVar(&prefundedAccounts, "prefunded-account", []string{}, "Fund this account in addition to static prefunded accounts, the input should the account's private key in hexadecimal format prefixed with 0x, the account is added to L1 and to L2 (if present)")
+		recipeCmd.Flags().IntVar(&readyzPort, "readyz-port", 0, "port for readyz HTTP endpoint (0 to disable)")
 
 		cookCmd.AddCommand(recipeCmd)
 	}
 
-	// reuse the same output flag for the artifacts command
-	artifactsCmd.Flags().StringVar(&outputFlag, "output", "", "Output folder for the artifacts")
-	artifactsAllCmd.Flags().StringVar(&outputFlag, "output", "", "Output folder for the artifacts")
+	cmd.InitWaitReadyCmd()
 
 	rootCmd.AddCommand(cookCmd)
-	rootCmd.AddCommand(artifactsCmd)
-	rootCmd.AddCommand(artifactsAllCmd)
 	rootCmd.AddCommand(inspectCmd)
+	rootCmd.AddCommand(cmd.WaitReadyCmd)
 
 	if err := rootCmd.Execute(); err != nil {
 		fmt.Println(err)
@@ -233,15 +166,17 @@ func runIt(recipe playground.Recipe) error {
 		return err
 	}
 
-	// if contender.tps is set, assume contender is enabled
-	svcManager := recipe.Apply(&playground.ExContext{
+	exCtx := &playground.ExContext{
 		LogLevel: logLevel,
+		// if contender.tps is set, assume contender is enabled
 		Contender: &playground.ContenderContext{
 			Enabled:     contenderEnabled,
 			ExtraArgs:   contenderArgs,
 			TargetChain: contenderTarget,
 		},
-	}, artifacts)
+	}
+	svcManager := playground.NewManifest(exCtx, artifacts.Out)
+	recipe.Apply(svcManager)
 	if err := svcManager.Validate(); err != nil {
 		return fmt.Errorf("failed to validate manifest: %w", err)
 	}
@@ -299,6 +234,16 @@ func runIt(recipe playground.Recipe) error {
 		cancel()
 	}()
 
+	var readyzServer *playground.ReadyzServer
+	if readyzPort > 0 {
+		readyzServer = playground.NewReadyzServer(dockerRunner.Instances(), readyzPort)
+		if err := readyzServer.Start(); err != nil {
+			return fmt.Errorf("failed to start readyz server: %w", err)
+		}
+		defer readyzServer.Stop()
+		fmt.Printf("Readyz endpoint available at http://localhost:%d/readyz\n", readyzPort)
+	}
+
 	if err := dockerRunner.Run(); err != nil {
 		dockerRunner.Stop()
 		return fmt.Errorf("failed to run docker: %w", err)
@@ -330,10 +275,13 @@ func runIt(recipe playground.Recipe) error {
 		return fmt.Errorf("failed to wait for service readiness: %w", err)
 	}
 
+	fmt.Printf("\nWaiting for network to be ready for transactions...\n")
+	networkReadyStart := time.Now()
 	if err := playground.CompleteReady(dockerRunner.Instances()); err != nil {
 		dockerRunner.Stop()
-		return fmt.Errorf("failed to complete ready: %w", err)
+		return fmt.Errorf("network not ready: %w", err)
 	}
+	fmt.Printf("Network is ready for transactions (took %.1fs)\n", time.Since(networkReadyStart).Seconds())
 
 	// get the output from the recipe
 	output := recipe.Output(svcManager)

playground/artifacts.go

@@ -11,6 +11,7 @@ import (
 	"fmt"
 	"io"
 	"log"
+	"maps"
 	"math/big"
 	"os"
 	"path/filepath"
@@ -228,9 +229,7 @@ func (b *ArtifactsBuilder) Build() (*Artifacts, error) {
 		if err := json.Unmarshal(contents, &alloc); err != nil {
 			return nil, fmt.Errorf("failed to unmarshal opState: %w", err)
 		}
-		for addr, account := range alloc {
-			gen.Alloc[addr] = account
-		}
+		maps.Copy(gen.Alloc, alloc)
 	}
 
 	block := gen.ToBlock()

playground/catalog.go

@@ -28,12 +28,3 @@ func init() {
 	register(&BProxy{})
 	register(&WebsocketProxy{})
 }
-
-func FindComponent(name string) ServiceGen {
-	for _, component := range Components {
-		if component.Name() == name {
-			return component
-		}
-	}
-	return nil
-}

playground/catalog_test.go

@@ -0,0 +1,21 @@
+package playground
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestCatalogReleases(t *testing.T) {
+	out := newTestOutput(t)
+
+	tests := []*release{
+		opRethRelease,
+		rethELRelease,
+	}
+
+	for _, tc := range tests {
+		_, err := DownloadRelease(out.dst, tc)
+		require.NoError(t, err)
+	}
+}