feat(node): add halt_height config field for coordinated chain upgrades

[moul]

Summary

Adds a halt height mechanism for coordinated chain upgrades. The node stops after committing the specified block height.

How to set it

gnoland config set halt_height 352922

Or edit config.toml directly:

halt_height = 352922

How it works

1. After finalizeCommit, consensus checks if height >= halt_height
2. If so, calls osm.Kill() for a graceful shutdown
3. The check is at the consensus level (not ABCI), following the same pattern as WithEarlyStart

Scope and future direction

This is a temporary coordination tool for the current chain upgrade. For the gnoland1 → gnoland-1 hard fork, validators set halt_height in their config, all nodes stop at the same block, then validators swap binary + config and restart.

After the upgrade, the proper mechanism will be GovDAO-based halting (#5368), which adds:

• On-chain halt_height param set via governance proposal (no manual config needed)
• halt_min_version — prevents old binaries from restarting after halt
• Version guard at startup so validators can't accidentally run the wrong binary

Once #5368 is merged and active, halt_height in config becomes a node operator tool (e.g., "stop my node at height X for maintenance") rather than a coordination mechanism. Coordination should happen through governance.

No CLI flag — config only

Per @tbruyelle's suggestion, there's no --halt-height CLI flag. Config file is the single source of truth. This avoids the risk of validators missing the flag in duplicated command setups across their infrastructure.

Related

• feat(node): add GovDAO-based chain halt via r/sys/params #5368 — GovDAO-based halt height + version guard (Phase 2, replaces this for coordination)
• WIP feat(deployments): gnoland-1.x hardfork content #5376 — gnoland-1 chain config
• feat(gnoland): chain hardfork mechanism #5411 — chain upgrade genesis replay

Contributors' checklist

• Added new tests, or not needed, or not feasible
• Provided an example (e.g. screenshot) to aid review or the PR is self-explanatory
• Updated the official documentation or not needed
• No breaking changes were made, or a BREAKING CHANGE: xxx message was included in the description
• Added benchmarks label to the PR or not needed

[Gno2D2]

🛠 PR Checks Summary

All Automated Checks passed. ✅

Manual Checks (for Reviewers):

• IGNORE the bot requirements for this PR (force green CI check)

Read More

🤖 This bot helps streamline PR reviews by verifying automated checks and providing guidance for contributors and reviewers.

✅ Automated Checks (for Contributors):

No automated checks match this pull request.

☑️ Contributor Actions:

1. Fix any issues flagged by automated checks.
2. Follow the Contributor Checklist to ensure your PR is ready for review.
   • Add new tests, or document why they are unnecessary.
   • Provide clear examples/screenshots, if necessary.
   • Update documentation, if required.
   • Ensure no breaking changes, or include BREAKING CHANGE notes.
   • Link related issues/PRs, where applicable.

☑️ Reviewer Actions:

1. Complete manual checks for the PR, including the guidelines and additional checks if applicable.

📚 Resources:

• Report a bug with the bot.
• View the bot’s configuration file.

Debug

Manual Checks

**IGNORE** the bot requirements for this PR (force green CI check)

If

🟢 Condition met
└── 🟢 On every pull request

Can be checked by

• Any user with comment edit permission

[codecov]

Codecov Report

❌ Patch coverage is 50.00000% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
gno.land/cmd/gnoland/start.go	0.00%	3 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[moul]

Note: tm2/pkg/sdk/baseapp.go already has haltHeight and haltTime fields with halt logic in Commit(), but they're never set from outside — there's no flag or setter to configure them.

This PR adds the halt mechanism at the consensus level (finalizeCommit in state.go) instead, which is arguably more appropriate since it's a node operation concern, not an app concern. The approach follows the same Option pattern as WithEarlyStart.

If preferred, I can alternatively just add a setter on BaseApp and wire the flag through the existing ABCI-level halt. Let me know which approach you prefer.

[moul]

Historical context: baseapp.go had setHaltHeight() and setHaltTime() methods that were removed by @zivkovicmilos in PR #2229 (feat: add valset injection through r/sys/validators, Jul 2024). The fields remain but are unreachable. This PR re-adds the capability at the consensus level.

[aeddi]

Tested locally and it works fine 👍

[tbruyelle]

Suggestion: moves this setting into a config file (or allows to set it in a config file as well).

Rational: I believe that in a validator infrastructure setup, a config file change is more persistent that adding flag in a command. A command can be duplicated accross the infra setup, and a validator might miss to add the flag everywhere. If that happens for more than one third of the valset, the upgrade will take more time because a valid snapshot will have to be created and shared across those who haven't stopped their node at the expected height.

[thehowl]

Note, there is an existing, half implemented mechanism for chain halts:

gno/tm2/pkg/sdk/baseapp.go

Lines 68 to 72 in c59fc2e

	// block height at which to halt the chain and gracefully shutdown
	haltHeight uint64
	// minimum block time (in Unix seconds) at which to halt the chain and gracefully shutdown
	haltTime uint64

gno/tm2/pkg/sdk/baseapp.go

Lines 906 to 917 in c59fc2e

	switch {
	case app.haltHeight > 0 && uint64(header.GetHeight()) >= app.haltHeight:
	halt = true
	case app.haltTime > 0 && header.GetTime().Unix() >= int64(app.haltTime):
	halt = true
	}
	if halt {
	app.halt()
	// Note: State is not actually committed when halted. Logs from Tendermint

gno/tm2/pkg/sdk/baseapp.go

Lines 952 to 966 in c59fc2e

	// halt attempts to gracefully shutdown the node via SIGINT and SIGTERM falling
	// back on os.Exit if both fail.
	func (app *BaseApp) halt() {
	app.logger.Info("halting node per configuration", "height", app.haltHeight, "time", app.haltTime)
	p, err := os.FindProcess(os.Getpid())
	if err == nil {
	// attempt cascading signals in case SIGINT fails (os dependent)
	sigIntErr := p.Signal(syscall.SIGINT)
	sigTermErr := p.Signal(syscall.SIGTERM)
	if sigIntErr == nil || sigTermErr == nil {
	return
	}
	}

The thing is that there is no setter or mechanism to actually modify these variables.

Overall this system looks to be slightly better? (Happens after finalization of a commit, not during a commit). But then we should remove the related code to the existing system, as duplicate

[tbruyelle]

Overall this system looks to be slightly better? (Happens after finalization of a commit, not during a commit). But then we should remove the related code to the existing system, as duplicate

This implementation which comes from the SDK has a non-deterministic bug cosmos/cosmos-sdk#16638. Essentially the current impl uses unix signal to kill the process, but signals are asynchronous and some additional blocks can be processed after the halt height apparently.

The fix is here and should be backported IMO. cosmos/cosmos-sdk#16639
The halt check is moved to FinalizeBlock (not sure yet what is the corresponding function in gno), and just returns an error instead of using unix signals.

I've also noticed an important change related to haltTime, even though this PR is not about using this param, it is no longer compared to header time but to node time. Which is strange btw... Not sure if we should follow this as well.

Conclusion, I think it's better to use the existing code like @thehowl suggested, but it needs to be fixed.

[moul]

Refactored based on @thehowl and @tbruyelle's feedback:

Moved halt logic to baseapp, removed the duplicate consensus-level implementation (state.go), now using the existing baseapp.go mechanism.

Fixed commit-before-halt bug, the original baseapp code called halt() and returned before committing state (return abci.ResponseCommit{}). State was lost. Now the halt check runs after the full commit cycle (MultiWrite → cms.Commit → header save → check state reset).

Fixed signal non-determinism (cosmos/cosmos-sdk#16638), replaced syscall.SIGINT/SIGTERM signals (which are async and can let extra blocks through) with osm.Kill().

Added SetHaltHeight setter on BaseApp, wired from config.toml via gnoland config set halt_height N.