chainntnfs: add a pkscript notifier stream

[hieblmi]

This PR adds a pkScript notifier stream for clients that need to watch confirmed on-chain activity for output
scripts without knowing the funding transaction or outpoint ahead of time.

The feature is exposed in two layers:

• chainntnfs.PkScriptNotifier for in-process notifier users.
• chainrpc.RegisterPkScriptNtfn as a bidirectional chain notifier RPC.

Behavior

A client opens one long-lived stream, sends an initial register request, then dynamically mutates the
watched script set with add and remove requests.

For each watched pkScript, clients can choose to receive:

• confirmation notifications,
• spend notifications,
• partial confirmation progress updates,
• raw transaction bytes,
• raw block bytes.

The notifier tracks future chain activity only. An add acknowledgment means the scripts were accepted for
future blocks; it does not perform historical backfill. Clients that need historical discovery should scan
their own history first, then add scripts that must remain watched for future confirmations, spends, and
reorgs.

Reorg invalidations are delivered on the same response stream by setting disconnected=true on the
notification being invalidated.

Resource Bounds

The notifier enforces limits for:

• active pkScript streams,
• scripts per mutation,
• script bytes per mutation,
• scripts and script bytes per registration,
• scripts and script bytes across all registrations,
• queued notifications per registration.

A client that stops reading responses can have its registration canceled once its bounded queue is exhausted.

Backend Support

The pkScript notifier is wired through the bitcoind, btcd, and neutrino chain notifier backends.

For neutrino, watched scripts must be convertible into compact filter watch addresses. Unsupported scripts
are rejected.

Documentation

This PR adds docs/pkscriptnotifier.md, covering RPC semantics, future-only watching, reorg handling,
resource bounds, examples, and backend support.

Tests

Covered by unit tests, RPC tests, and integration tests for:

• future-only registration,
• dynamic add/remove,
• partial confirmation updates,
• spend notifications,
• same-block receive/spend handling,
• multi-stream behavior,
• validation and resource limits,
• reorg invalidation behavior.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request implements a robust, stream-based interface for monitoring Bitcoin script activity. By moving away from single-target notifications to a script-based subscription model, it enables more efficient and flexible chain monitoring. The changes include backend support for bitcoind, btcd, and neutrino, along with a comprehensive gRPC API for external clients to leverage these new capabilities.

Highlights

• New PkScript Notifier Interface: Introduced chainntnfs.PkScriptNotifier and RegisterPkScriptNotifier to allow for flexible, stream-based monitoring of multiple pkScripts for confirmations and spends.
• Dynamic Script Management: Added support for dynamically adding and removing pkScripts from an active notification stream, including optional historical backfilling.
• RPC API Expansion: Exposed the new functionality via a new bidirectional gRPC stream RegisterPkScriptNtfn in the chainrpc subserver, complete with support for historical scans and reorg invalidations.
• Resource Management: Implemented strict resource bounds for registrations, watch counts, and queued notifications to ensure system stability.

New Features

🧠 You can now enable Memory (public preview) to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new PkScriptNotifier interface and implementation, allowing clients to watch for confirmation and spend events on specific output scripts. The changes include support for historical scans, resource limiting, and a new bidirectional gRPC stream in chainrpc. The reviewer suggested refactoring the duplicated historical dispatch logic across the bitcoind, btcd, and neutrino backends into a shared helper and noted that an error in completeHistoricalPkScriptDispatchLocked should be explicitly handled.

[github-actions]

🔴 PR Severity: CRITICAL

🤖 Automated severity classification | 16 non-test files | ~4,938 lines changed (excluding tests and auto-generated)

🟠 High (9 files — base severity)

• chainntnfs/bitcoindnotify/bitcoind.go - Chain notification backend (bitcoind), part of chainntnfs/*
• chainntnfs/btcdnotify/btcd.go - Chain notification backend (btcd), part of chainntnfs/*
• chainntnfs/interface.go - Core chain notifications interface, part of chainntnfs/*
• chainntnfs/neutrinonotify/neutrino.go - Chain notification backend (neutrino), part of chainntnfs/*
• chainntnfs/pkscriptnotifier.go - New pkscript notifier (2379 lines, new file), part of chainntnfs/*
• chainntnfs/txnotifier.go - Transaction notifier, part of chainntnfs/*
• lnrpc/chainrpc/chain_server.go - Chain RPC server (587 lines added), part of lnrpc/*
• lnrpc/chainrpc/config_active.go - Chain RPC configuration, part of lnrpc/*
• lnrpc/chainrpc/driver.go - Chain RPC driver, part of lnrpc/*

🟡 Medium (5 files)

• chainreg/no_chain_backend.go - Chain registry backend stub
• lnrpc/chainrpc/chainnotifier.proto - Protocol buffer API definition (*.proto)
• lnrpc/chainrpc/chainnotifier.swagger.json - API swagger spec
• lnrpc/chainrpc/chainnotifier.yaml - API YAML config
• subrpcserver_config.go - Sub-RPC server configuration

🟢 Low (2 files — excluded from count)

• docs/pkscriptnotifier.md - Documentation
• docs/release-notes/release-notes-0.22.0.md - Release notes

⬛ Excluded from counting (test/auto-generated files)

• chainntnfs/neutrinonotify/neutrino_test.go — test file
• chainntnfs/pkscriptnotifier_internal_test.go — test file
• chainntnfs/pkscriptnotifier_test.go — test file
• chainntnfs/test/test_interface.go — test support directory
• itest/list_on_test.go — itest/*
• itest/lnd_chain_notifier_pkscript_test.go — itest/*
• lnrpc/chainrpc/chain_server_test.go — test file
• lnrpc/chainrpc/chainnotifier.pb.go — auto-generated (*.pb.go)
• lnrpc/chainrpc/chainnotifier.pb.gw.go — auto-generated (*.pb.gw.go)
• lnrpc/chainrpc/chainnotifier_grpc.pb.go — auto-generated (*.pb.go)
• lntest/rpc/chain_notifier.go — lntest/*

Analysis

Base severity: HIGH — The PR touches chainntnfs/* (chain notification backends and interfaces) and lnrpc/* (RPC/API definitions), both classified as HIGH severity packages.

Bumped to CRITICAL — The PR has approximately 4,938 lines changed in non-test, non-auto-generated files, well exceeding the 500-line threshold that triggers a one-level severity bump.

The core of this PR introduces a new pkscriptnotifier.go (2,379 lines) implementing a PkScript-based chain notification interface, along with modifications to all three chain backends (bitcoind, btcd, neutrino) to wire in the new notifier, extensive changes to chainntnfs/interface.go, and 587 lines added to the chain RPC server to expose the new functionality via gRPC. This is a substantial new feature touching critical chain notification infrastructure and requires expert review.

---

_{To override, add a severity-override-{critical,high,medium,low} label.}
<!-- pr-severity-bot -->

[lightninglabs-deploy]

@starius: review reminder
@hieblmi, remember to re-request review from reviewers when ready