feat(zebrad): run a command on chain tip changes (block notify)#10726
Open
upbqdn wants to merge 3 commits into
Open
feat(zebrad): run a command on chain tip changes (block notify)#10726upbqdn wants to merge 3 commits into
upbqdn wants to merge 3 commits into
Conversation
arya2
previously approved these changes
Jun 23, 2026
Member
|
@upbqdn just a conflict to resolve to get this merged |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new zebrad runtime component that mirrors zcashd -blocknotify: when the best chain tip changes (and the node is close to the network tip), Zebra runs a configured shell command with %s substituted by the new tip hash.
Changes:
- Introduces a new
[notify]config section (notify.block_notify_command) and wires it intoZebradConfig. - Adds a
notifycomponent/task that listens forChainTipChange, gates onSyncStatus::wait_until_close_to_tip, and spawns/reaps the configured command asynchronously. - Updates
zebradstartup wiring, enables Tokio’sprocessfeature, adds tests/config snapshot, and documents the feature inCHANGELOG.md.
Note: the PR checklist indicates this change was not discussed with the team beforehand (per the PR template checkbox), even though it closes an issue.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| zebrad/tests/common/configs/v5.2.0.toml | Adds a new stored default config snapshot including an empty [notify] section. |
| zebrad/src/config.rs | Adds notify to the top-level ZebradConfig so it can be configured via TOML/env/defaults. |
| zebrad/src/components/notify.rs | New block-notify task implementation and config type. |
| zebrad/src/components/notify/tests.rs | Unit + tokio tests for substitution behavior and spawn path behavior. |
| zebrad/src/components.rs | Exposes the new notify component module. |
| zebrad/src/commands/start.rs | Spawns and supervises the block-notify task during zebrad start. |
| zebrad/Cargo.toml | Enables Tokio process feature required for async process spawning. |
| CHANGELOG.md | Documents the new [notify] block_notify_command option under Unreleased. |
arya2
previously approved these changes
Jun 25, 2026
Add a `[notify]` config section with a `block_notify_command` option, Zebra's equivalent of zcashd's `-blocknotify`. Whenever the best chain tip changes and the node is close to the network tip, the command is run via the system shell with every `%s` replaced by the new tip's block hash. The command is detached and never blocks block validation.
The spawn integration test uses /bin/sh command syntax, which fails under the Windows cmd /C branch. Gate it to non-Windows; render_command and the non-zero exit test still cover Windows.
stdout/stderr are redirected to `/dev/null`, so there is nothing to collect; `wait()` only needs the exit status and avoids the extra `Output` buffers.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Closes #10727
Solution
Adds a
[notify]config section with a singleblock_notify_commandoption. Abackground task (modeled on the existing block gossip task) waits for tip changes,
gates on
SyncStatus::wait_until_close_to_tip(Zebra's analogue of zcashdsuppressing the callback during initial block download), substitutes every
%swith the new tip's block hash (
getbestblockhashhex format), and runs the commandvia the system shell (
/bin/sh -con Unix,cmd /Con Windows). The command isdetached and reaped in a separate task, so a hung command never blocks block
validation; non-zero exits are logged like zcashd's
runCommand. Disabled (no-optask) when unset.
Matches zcashd's surface deliberately: no timeout, rate-limiting, or dedup. Note
that
ChainTipChangecoalesces bursts of commits, so under fast sync intermediatetip hashes may be skipped — only the current best tip fires (harmless for the
canonical use cases).
Tests
%ssubstitution (single/multiple/none) and an assertion that thesubstituted value is exactly the 64-char lowercase-hex
getbestblockhashformat(pins the command-injection-safety invariant).
Configtests: default-disabled, TOML round-trip,deny_unknown_fields.#[tokio::test]s drive the real spawn path: one proves the shell ran with thesubstituted hash (tempfile side-effect), one proves a non-zero exit (
false)neither panics nor blocks the caller.
zebrad/tests/common/configs/v5.2.0.toml;config_testspasses.
clippy --all-targets -D warningsandfmt --checkclean.Specifications & References
-blocknotify:BlockNotifyCallback(src/init.cpp), fired fromNotifyBlockTipafterActivateBestChain(src/main.cpp).AI Disclosure
tests, and wiring, and a multi-agent workflow to design/adversarially-review the
implementation. The contributor is the responsible author.
PR Checklist