feat: add network readiness

[gpevnev]

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

[Copilot]

Pull Request Overview

This PR adds network readiness functionality to the builder-playground, allowing users to verify when networks are ready to accept transactions by checking that blocks are being produced. The implementation includes a /readyz HTTP endpoint and a CLI command to wait for network readiness.

Key changes:

• Introduces NetworkReadyChecker interface for recipes to implement network-level readiness checks
• Adds /readyz HTTP endpoint that returns network readiness status
• Implements wait-ready CLI command to poll the readiness endpoint until the network is ready

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
playground/watchers.go	Adds helper functions to check if chains are producing blocks and wait for first block
playground/manifest.go	Defines NetworkReadyChecker interface for network readiness checks
playground/readyz.go	Implements HTTP server for /readyz endpoint
playground/recipe_l1.go	Implements NetworkReadyChecker interface for L1 recipe
playground/recipe_opstack.go	Implements NetworkReadyChecker interface for OP stack recipe with L1/L2 checks
playground/recipe_buildernet.go	Implements NetworkReadyChecker interface by delegating to L1 recipe
playground/cmd/wait_ready.go	Adds CLI command to poll readiness endpoint
main.go	Integrates readyz server and network readiness wait into main execution flow
README.md	Documents the new network readiness features

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[metachris]

while at it, might also be useful to add a /livez handler that always returns 200, just to indicate that it's running, but maybe not yet ready. see also https://github.com/flashbots/go-template/blob/3cbb5ff225ce89f828c56a959d03b93ae58b70aa/httpserver/server.go#L74

[ferranbt]

What is the utility of this server? In the previous iteration, Playground was meant to work as a template engine, not as a long live instance.

[gpevnev]

Right now it also works as runner for docker-compose, and this is just more correct way to actually ensure readiness for processing transactions. Example use case: we need to understand when we can start working with network in a CI job and when it's considered ready

[ferranbt]

I agree that it would be useful to have a way to ensure the playground is ready and healthy before doing other actions. But, I am not sure I follow what the intended workflow is.

Is the ready server running forever after the deployment is ready and healthy? Or it just stops alongside the deployment command?

Why is this workflow better than just using the wait-ready flag? I would find the ready server useful if it were to take minutes to deploy anything but it takes seconds right now.

[ferranbt]

How is this different from the watchdog functionality? A component can implement a ready check which can be use to determine whether the whole recipe is ready or not. (here)

[gpevnev]

How is this different from the watchdog functionality? A component can implement a ready check which can be use to determine whether the whole recipe is ready or not. (here)

Watchdog functionality doesn't have a readiness check as I see, it's more about continuously monitor health of a particular service. But we need one time readiness indicator (basically that the network started producing blocks) in order to delay next CI steps until the block production is started.
Ready check from

type ServiceReady interface {
	Ready(instance *instance) error
}

is one another thing I was looking to implement this feature, but problem it that it is readiness for a specific service, not recipe and generally it makes more sense to me to make it recipe based, so it will be more flexible.

[ferranbt]

My bad, it was not the watchdog but the service ReadyCheck. Internally this is used to create dependencies between services. You can extend this concept easily and a recipe is not ready until all the ready checks are ok.

it makes more sense to me to make it recipe based, so it will be more flexible.

Do you have any use case in mind for this? I cannot think of any in which it is not enough to validate the readiness of each service and not the recipe as a whole.

[gpevnev]

The only problem I can think of can be ordering. ex: for opstack it makes sense to first check readiness of L1 and only after that check L2.

I think it won't be critical, bc in the end we need all of readiness checks to pass anyway. I think we can make service level check work for now and redo it later to recipe level if some edge case arises

[ferranbt]

The only problem I can think of can be ordering. ex: for opstack it makes sense to first check readiness of L1 and only after that check L2.

This can be achieved with the DependsOnHealthy function.