lnwallet+walletrpc: add WalletKit.SubmitPackage for v3 CPFP package relay

[ellemouton]

Draft, pending btcsuite/btcwallet#1264. This depends on the new chain.Interface.SubmitPackage method added there. Until btcwallet releases it, go.mod temporarily replaces btcwallet with a fork commit that includes it; the replace will be dropped for a released version before this is taken out of draft.

Summary

Adds a WalletKit.SubmitPackage RPC, letting a client submit a package of
related transactions (topologically sorted, unconfirmed parents first and the
child last) to lnd's chain backend for atomic validation and acceptance.

This is what allows a v3/TRUC package to relay: a zero-fee parent carrying
an ephemeral (P2A) anchor is below the minimum relay fee and is rejected by a
standalone broadcast, but is accepted when submitted together with a
fee-paying CPFP child whose combined feerate clears policy. TestMempoolAccept
already exposes Core's testmempoolaccept this way; SubmitPackage is the
broadcasting counterpart for submitpackage.

Details

• New SubmitPackage method on the lnwallet.WalletController interface.
  BtcWallet forwards it to the chain backend's submitpackage for
  bitcoind/btcd; for neutrino (no mempool) it broadcasts each transaction over
  P2P and relies on the peer's 1p1c package relay.
• The WalletKit.SubmitPackage handler decodes the raw transactions, forwards
  an optional per-transaction max fee rate (negative = node default; 0 = no
  limit, which a high-feerate CPFP child needs), and maps the node result back
  to the proto response. It is gated by the onchain:write macaroon
  permission.
• A wallet submitpackage lncli command.
• Mock wallet controllers and the no-chain backend gain trivial
  implementations.

Testing

make rpc reproduces the generated stubs cleanly and cmd/lnd builds. Adds an
integration test (testSubmitPackage) that submits a zero-fee v3 parent plus a
fee-paying CPFP child and asserts the package is accepted — a zero-fee
transaction can only enter the mempool via package evaluation, so this
exercises the CPFP path end to end. submitpackage is a bitcoind RPC, so the
test runs on the bitcoind backend and skips on btcd/neutrino.

TODO before un-drafting

• Land chain: add SubmitPackage to the chain.Interface btcsuite/btcwallet#1264 and switch go.mod from the fork replace to a
  released btcwallet version.

[github-actions]

PR Severity: CRITICAL. Files in lnwallet/* (lnwallet/interface.go, lnwallet/btcwallet/btcwallet.go, lnwallet/mock.go) drive the CRITICAL classification. Also touches lnrpc/* (HIGH) and proto/other files (MEDIUM). 10 non-excluded files, ~250 non-excluded lines - no bump needed. <!-- pr-severity-bot -->

[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 introduces a new SubmitPackage RPC method to the WalletKit service, allowing clients to submit topologically sorted transaction packages to the chain backend. This capability is essential for supporting v3/TRUC package relay, which allows zero-fee parent transactions to be accepted when paired with a fee-paying CPFP child. The changes include updates to the wallet interface, backend implementations, and necessary gRPC/protobuf infrastructure.

Highlights

• New RPC Method: Added the WalletKit.SubmitPackage RPC method to enable atomic submission of transaction packages for v3/TRUC relay support.
• Interface Updates: Updated the WalletController interface to include SubmitPackage, ensuring consistency across wallet implementations.
• Implementation: Implemented SubmitPackage logic in BtcWallet and provided mock implementations for testing and development environments.
• API Definitions: Updated protobuf, gRPC, and Swagger definitions to expose the new SubmitPackage functionality to external clients.

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 SubmitPackage RPC endpoint to the WalletKit service, enabling the submission of a package of related transactions for atomic validation and acceptance. This feature is implemented across the wallet controller interface, mock implementations, and the btcwallet backend. The review feedback suggests several important improvements: adding a defensive nil check on the backend's returned result in walletkit_server.go to prevent a potential panic, documenting the stub implementation in no_chain_backend.go to comply with the repository style guide, and marking the max_fee_rate field as optional in the protobuf definition to safely distinguish between an omitted field and an explicit zero limit.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[ellemouton]

Thanks for the review — addressed all three:

• nil result check: the handler now returns an error if the wallet backend returns a nil result, before mapping its fields.
• NoChainSource.SubmitPackage doc: added a godoc comment beginning with the function name.
• max_fee_rate: changed to optional double so an explicit 0 (no limit) is distinguishable from an omitted value (node default); the handler passes the *float64 through directly.

Also fixed up the CI failures: added the missing REST annotation for the new RPC (POST /v2/wallet/tx/package) and a release-notes entry, plus added an lncli wallet submitpackage command and an integration test.

[sputn1ck]

could we also run it with neutrino? as the implementation would suggest it works there

[ellemouton]

good point — it does work on neutrino, but only against a package-aware miner. neutrino has no mempool, so SubmitPackage just broadcasts parent+child and leans on the peer's 1p1c relay — that needs the bitcoind miner (minerbackend=bitcoind, v28+); against the default btcd miner the zero-fee parent is simply rejected and never assembles. so a neutrino row would have to be gated on minerbackend=bitcoind and assert confirmation (the neutrino result itself is a synthetic best-effort one). afaict there's no backend=neutrino+minerbackend=bitcoind combo in CI today, so it'd be skipped everywhere unless we add that job. happy to add the gated test (+ the CI combo) if you think it's worth it — wdyt?