feat: add network readiness (#210)

### Add Network Readiness Checking

**Problem**
After all services start and Docker healthchecks pass, the network may
not yet be producing blocks. This makes it inconvenient for users who
need to wait before deploying contracts or running tests, as they have
to manually check when the network is actually ready for transactions.

**Solution**
Implemented network-level readiness checking that ensures the blockchain
is producing blocks, not just that services are responsive.

Closes #204

Author: gpevnev

README.md

@@ -75,6 +75,64 @@ $ builder-playground cook l1 --latest-fork --output ~/my-builder-testnet --genes
 
 To stop the playground, press `Ctrl+C`.
 
+## 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"
 )
 
@@ -33,6 +34,7 @@ var platform string
 var contenderEnabled bool
 var contenderArgs []string
 var contenderTarget string
+var readyzPort int
 
 var rootCmd = &cobra.Command{
 	Use:   "playground",
@@ -185,6 +187,7 @@ func main() {
 		recipeCmd.Flags().BoolVar(&contenderEnabled, "contender", false, "spam nodes with contender")
 		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().IntVar(&readyzPort, "readyz-port", 0, "port for readyz HTTP endpoint (0 to disable)")
 
 		cookCmd.AddCommand(recipeCmd)
 	}
@@ -193,10 +196,13 @@ func main() {
 	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)
@@ -296,6 +302,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)
@@ -327,10 +343,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/cmd/wait_ready.go

@@ -0,0 +1,93 @@
+package cmd
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"time"
+
+	"github.com/flashbots/builder-playground/playground"
+	"github.com/spf13/cobra"
+)
+
+var waitReadyURL string
+var waitReadyTimeout time.Duration
+var waitReadyInterval time.Duration
+
+var WaitReadyCmd = &cobra.Command{
+	Use:   "wait-ready",
+	Short: "Wait for the network to be ready for transactions",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		return waitForReady()
+	},
+}
+
+func InitWaitReadyCmd() {
+	WaitReadyCmd.Flags().StringVar(&waitReadyURL, "url", "http://localhost:8080/readyz", "readyz endpoint URL")
+	WaitReadyCmd.Flags().DurationVar(&waitReadyTimeout, "timeout", 60*time.Second, "maximum time to wait")
+	WaitReadyCmd.Flags().DurationVar(&waitReadyInterval, "interval", 1*time.Second, "poll interval")
+}
+
+func waitForReady() error {
+	fmt.Printf("Waiting for %s (timeout: %s, interval: %s)\n", waitReadyURL, waitReadyTimeout, waitReadyInterval)
+
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, os.Interrupt)
+
+	ctx, cancel := context.WithCancel(context.Background())
+	go func() {
+		<-sig
+		cancel()
+	}()
+
+	client := &http.Client{
+		Timeout: 5 * time.Second,
+	}
+
+	deadline := time.Now().Add(waitReadyTimeout)
+	attempt := 0
+
+	for time.Now().Before(deadline) {
+		select {
+		case <-ctx.Done():
+			return fmt.Errorf("interrupted")
+		default:
+		}
+
+		attempt++
+		elapsed := time.Since(deadline.Add(-waitReadyTimeout))
+
+		resp, err := client.Get(waitReadyURL)
+		if err != nil {
+			fmt.Printf("  [%s] Attempt %d: connection error: %v\n", elapsed.Truncate(time.Second), attempt, err)
+			time.Sleep(waitReadyInterval)
+			continue
+		}
+
+		var readyzResp playground.ReadyzResponse
+		if err := json.NewDecoder(resp.Body).Decode(&readyzResp); err != nil {
+			resp.Body.Close()
+			fmt.Printf("  [%s] Attempt %d: failed to parse response: %v\n", elapsed.Truncate(time.Second), attempt, err)
+			time.Sleep(waitReadyInterval)
+			continue
+		}
+		resp.Body.Close()
+
+		if resp.StatusCode == http.StatusOK && readyzResp.Ready {
+			fmt.Printf("  [%s] Ready! (200 OK)\n", elapsed.Truncate(time.Second))
+			return nil
+		}
+
+		errMsg := ""
+		if readyzResp.Error != "" {
+			errMsg = fmt.Sprintf(" - %s", readyzResp.Error)
+		}
+		fmt.Printf("  [%s] Attempt %d: %d %s%s\n", elapsed.Truncate(time.Second), attempt, resp.StatusCode, http.StatusText(resp.StatusCode), errMsg)
+		time.Sleep(waitReadyInterval)
+	}
+
+	return fmt.Errorf("timeout waiting for readyz after %s", waitReadyTimeout)
+}

playground/components.go

@@ -382,7 +382,13 @@ func (o *OpGeth) Name() string {
 	return "op-geth"
 }
 
+func (o *OpGeth) Ready(instance *instance) error {
+	opGethURL := fmt.Sprintf("http://localhost:%d", instance.service.MustGetPort("http").HostPort)
+	return waitForFirstBlock(context.Background(), opGethURL, 60*time.Second)
+}
+
 var _ ServiceWatchdog = &OpGeth{}
+var _ ServiceReady = &OpGeth{}
 
 func (o *OpGeth) Watchdog(out io.Writer, instance *instance, ctx context.Context) error {
 	gethURL := fmt.Sprintf("http://localhost:%d", instance.service.MustGetPort("http").HostPort)
@@ -477,7 +483,13 @@ func (r *RethEL) Name() string {
 	return "reth"
 }
 
+func (r *RethEL) Ready(instance *instance) error {
+	elURL := fmt.Sprintf("http://localhost:%d", instance.service.MustGetPort("http").HostPort)
+	return waitForFirstBlock(context.Background(), elURL, 60*time.Second)
+}
+
 var _ ServiceWatchdog = &RethEL{}
+var _ ServiceReady = &RethEL{}
 
 func (r *RethEL) Watchdog(out io.Writer, instance *instance, ctx context.Context) error {
 	rethURL := fmt.Sprintf("http://localhost:%d", instance.service.MustGetPort("http").HostPort)

playground/manifest.go

@@ -608,7 +608,8 @@ func ReadManifest(outputFolder string) (*Manifest, error) {
 }
 
 func (svcManager *Manifest) RunContenderIfEnabled() {
-	if svcManager.ctx.Contender.Enabled {
+
+	if svcManager.ctx.Contender != nil && svcManager.ctx.Contender.Enabled {
 		svcManager.AddService("contender", svcManager.ctx.Contender.Contender())
 	}
 }

playground/manifest_test.go

@@ -26,7 +26,7 @@ func TestNodeRefString(t *testing.T) {
 			service:  "test",
 			port:     80,
 			user:     "test",
-			expected: "test@test:test",
+			expected: "test@test:80",
 		},
 		{
 			protocol: "http",
@@ -40,7 +40,7 @@ func TestNodeRefString(t *testing.T) {
 			service:  "test",
 			port:     80,
 			user:     "test",
-			expected: "http://test@test:test",
+			expected: "http://test@test:80",
 		},
 		{
 			protocol: "enode",

playground/readyz.go

@@ -0,0 +1,109 @@
+package playground
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"sync"
+)
+
+type ReadyzServer struct {
+	instances []*instance
+	port      int
+	server    *http.Server
+	mu        sync.RWMutex
+}
+
+type ReadyzResponse struct {
+	Ready bool   `json:"ready"`
+	Error string `json:"error,omitempty"`
+}
+
+func NewReadyzServer(instances []*instance, port int) *ReadyzServer {
+	return &ReadyzServer{
+		instances: instances,
+		port:      port,
+	}
+}
+
+func (s *ReadyzServer) Start() error {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/livez", s.handleLivez)
+	mux.HandleFunc("/readyz", s.handleReadyz)
+
+	s.server = &http.Server{
+		Addr:    fmt.Sprintf(":%d", s.port),
+		Handler: mux,
+	}
+
+	go func() {
+		if err := s.server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			fmt.Printf("Readyz server error: %v\n", err)
+		}
+	}()
+
+	return nil
+}
+
+func (s *ReadyzServer) Stop() error {
+	if s.server != nil {
+		return s.server.Shutdown(context.Background())
+	}
+	return nil
+}
+
+func (s *ReadyzServer) handleLivez(w http.ResponseWriter, r *http.Request) {
+	w.WriteHeader(http.StatusOK)
+	w.Write([]byte("OK")) //nolint:errcheck
+}
+
+func (s *ReadyzServer) handleReadyz(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	ready, err := s.isReady()
+
+	response := ReadyzResponse{
+		Ready: ready,
+	}
+
+	if err != nil {
+		response.Error = err.Error()
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+
+	if ready {
+		w.WriteHeader(http.StatusOK)
+	} else {
+		w.WriteHeader(http.StatusServiceUnavailable)
+	}
+
+	if err := json.NewEncoder(w).Encode(response); err != nil {
+		fmt.Printf("Failed to encode readyz response: %v\n", err)
+	}
+}
+
+func (s *ReadyzServer) isReady() (bool, error) {
+	ctx := context.Background()
+	for _, inst := range s.instances {
+		if _, ok := inst.component.(ServiceReady); ok {
+			elURL := fmt.Sprintf("http://localhost:%d", inst.service.MustGetPort("http").HostPort)
+			ready, err := isChainProducingBlocks(ctx, elURL)
+			if err != nil {
+				return false, err
+			}
+			if !ready {
+				return false, nil
+			}
+		}
+	}
+	return true, nil
+}
+
+func (s *ReadyzServer) Port() int {
+	return s.port
+}