feat: add WithBlockWaitTimeout to ChainBuilder

[rootulp]

Summary

• Add configurable WithBlockWaitTimeout option to ChainBuilder so callers can override the hardcoded 120-second block wait timeout in Chain.Start()
• The default behavior is unchanged (120s) when WithBlockWaitTimeout is not called
• This is needed for state sync nodes that need extra time to sync before receiving blocks
• Use the caller's context (instead of context.Background()) for the block wait timeout so it respects the caller's cancellation and deadline

Closes celestiaorg/celestia-app#7017

Test plan

• Verify existing tests pass (default 120s timeout unchanged)
• Verify WithBlockWaitTimeout is usable from celestia-app's sync-to-tip test

🤖 Generated with Claude Code

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes introduce a configurable blockWaitTimeout field to the Chain struct and ChainBuilder class, enabling customization of the timeout duration when waiting for blocks after starting a blockchain. The builder propagates this timeout during construction with a 120-second fallback.

Changes

Cohort / File(s)	Summary
Chain Initialization framework/docker/cosmos/chain.go	Added blockWaitTimeout time.Duration field to Chain struct; modified block-wait logic to use this field with 120-second fallback instead of hardcoded timeout.
Chain Builder framework/docker/cosmos/chain_builder.go	Added blockWaitTimeout time.Duration field and exported WithBlockWaitTimeout(timeout time.Duration) fluent method to ChainBuilder; wired field propagation to Chain during Build(ctx).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 A timeout's now tunable, no longer so tight,
No more rushing through blocks in the dead of the night!
With a builder's soft touch and a field set with care,
Chain waits as it wishes—with flexibility rare! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a WithBlockWaitTimeout method to ChainBuilder for configurable block wait timeout configuration.
Linked Issues check	✅ Passed	The PR implements the tastora half of issue #7017 by adding WithBlockWaitTimeout to ChainBuilder and wiring it through to Chain. However, the celestia-app integration (using the new method) is out of scope for this PR.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the configurable block wait timeout feature; no unrelated or out-of-scope modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rootulp/block-wait-timeout

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

framework/docker/cosmos/chain_builder.go (1)

348-354: Keep timeout when cloning from an existing chain.

WithBlockWaitTimeout is added, but NewChainBuilderFromChain (Line 186 onward) does not copy chain.blockWaitTimeout, so this config can be dropped when rebuilding from an existing chain.

♻️ Proposed fix

 func NewChainBuilderFromChain(chain *Chain) *ChainBuilder {
 	cfg := &chain.Config
 	return NewChainBuilder(chain.t).
 		WithLogger(chain.log).
 		WithEncodingConfig(cfg.EncodingConfig).
 		WithName(cfg.Name).
 		WithChainID(cfg.ChainID).
 		WithBinaryName(cfg.Bin).
 		WithCoinType(cfg.CoinType).
 		WithGasPrices(cfg.GasPrices).
 		WithGasAdjustment(cfg.GasAdjustment).
 		WithBech32Prefix(cfg.Bech32Prefix).
 		WithDenom(cfg.Denom).
 		WithGenesis(cfg.GenesisFileBz).
 		WithImage(cfg.Image).
 		WithDockerClient(chain.Config.DockerClient).
 		WithDockerNetworkID(chain.Config.DockerNetworkID).
 		WithAdditionalStartArgs(cfg.AdditionalStartArgs...).
-		WithEnv(cfg.Env...)
+		WithEnv(cfg.Env...).
+		WithBlockWaitTimeout(chain.blockWaitTimeout)
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@framework/docker/cosmos/chain_builder.go` around lines 348 - 354,
NewChainBuilderFromChain currently doesn't copy the
ChainBuilder.blockWaitTimeout set via WithBlockWaitTimeout, so when cloning an
existing chain that timeout is lost; update NewChainBuilderFromChain to copy the
blockWaitTimeout field from the source chain into the new ChainBuilder (preserve
same behavior as other copied fields), referencing
ChainBuilder.blockWaitTimeout, the WithBlockWaitTimeout method, and the
NewChainBuilderFromChain constructor to locate where to add the assignment.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@framework/docker/cosmos/chain.go`:
- Around line 337-341: The block wait uses context.Background() which ignores
cancellations from the caller; in Start(ctx context.Context) replace
context.Background() with the incoming ctx when creating blockWaitCtx so the
block wait respects the caller's cancellation/deadline (adjust creation of
blockWaitCtx and cancel where blockWaitTimeout and blockWaitCtx are defined to
use ctx instead of context.Background()); ensure you still apply the timeout
derived from blockWaitTimeout via context.WithTimeout(ctx, blockWaitTimeout) and
propagate the returned cancel as before.

---

Nitpick comments:
In `@framework/docker/cosmos/chain_builder.go`:
- Around line 348-354: NewChainBuilderFromChain currently doesn't copy the
ChainBuilder.blockWaitTimeout set via WithBlockWaitTimeout, so when cloning an
existing chain that timeout is lost; update NewChainBuilderFromChain to copy the
blockWaitTimeout field from the source chain into the new ChainBuilder (preserve
same behavior as other copied fields), referencing
ChainBuilder.blockWaitTimeout, the WithBlockWaitTimeout method, and the
NewChainBuilderFromChain constructor to locate where to add the assignment.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c63073d1-7aee-418e-ba3e-ed964cd0cb61

📥 Commits

Reviewing files that changed from the base of the PR and between ebb954e and 9d58861.

📒 Files selected for processing (2)

• framework/docker/cosmos/chain.go
• framework/docker/cosmos/chain_builder.go