Skip to content

multi: lnd package relay (WalletKit.SubmitPackage) + itest harness support - #873

Merged
ellemouton merged 3 commits into
mainfrom
ellemouton/lnd-package-submitter
Jul 8, 2026
Merged

ellemouton merged 3 commits into
mainfrom
ellemouton/lnd-package-submitter

Conversation

@ellemouton

@ellemouton ellemouton commented Jul 7, 2026 •

Copy link
Copy Markdown
Contributor

Combines the two client-side package-relay changes into one PR for review
(previously split across #873 and #734). Two commits:

1. multi: relay v3 packages via lnd WalletKit.SubmitPackage

Adds the lnd-backed package submitter — the consumer of the merged
lndclient.WalletKit.SubmitPackage (lndclient #280).
chainbackends/lndsubmitter is a chainbackends.PackageSubmitter that assembles
the parents-first/child-last package, forwards it to lnd, and maps lndclient's
native SubmitPackageResult → btcjson.SubmitPackageResult. Wired into
darepod/server.go as the lnd chain backend's default submitter when no
explicit (bitcoind) submitter is injected. Lets an lnd-backed darepod relay its
zero-fee unilateral-exit v3/TRUC packages through lnd's own chain connection —
no separate bitcoind RPC or Esplora endpoint (darepo-client #590 / #678). Unit
tests cover assembly order, result mapping, and fee-rate forwarding.

2. harness: add neutrino chain-backend option for lnd nodes

Adds a per-client lnd chain-backend option to the itest harness so package-relay
itests can drive an lnd node against a neutrino backend. Consumed by the server
package-relay itest matrix (darepo #564).

Depends only on merged upstream. Builds + vets green.

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces lndsubmitter, which implements chainbackends.PackageSubmitter using lnd's WalletKit.SubmitPackage RPC. This allows a darepod using an lnd wallet to relay zero-fee unilateral-exit v3/TRUC packages through lnd's chain connection without requiring a separate bitcoind RPC or Esplora endpoint. Feedback highlights a critical bug in SubmitPackage where the maxFeeRate (provided in BTC/kvB) is directly cast to sat/vByte without conversion, which would result in an extremely low fee rate and package rejection. A conversion factor of 100,000 needs to be applied, and the corresponding test should be updated.

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.

Comment thread chainbackends/lndsubmitter/submitter.go Resolved
@ellemouton ellemouton changed the title multi: relay v3 packages via lnd WalletKit.SubmitPackage multi: lnd package relay (WalletKit.SubmitPackage) + itest harness support Jul 7, 2026
@ellemouton
ellemouton force-pushed the ellemouton/lnd-package-submitter branch from 334cf3d to 9019d29 Compare July 7, 2026 17:48
@ellemouton

Copy link
Copy Markdown
Contributor Author

@claude review

@claude

claude Bot commented Jul 7, 2026 •

Copy link
Copy Markdown

Claude finished @ellemouton's task in 3m 15s —— View job


PR Review

  • Read changed files
  • Review lndsubmitter implementation
  • Review server wiring & harness changes
  • Post review feedback

Overall this is clean and well-documented — the walletKitSubmitter narrowing for testability, the parents-first/child-last assembly, and the result mapping all read well. The BTC/kvB → sat/vByte fix from the earlier round looks correct (0.00012 * 1e8 / 1000 = 12). One design concern worth resolving before merge, plus a couple of minor notes.

🟠 The lnd submitter doesn't disable the fee-rate ceiling like the bitcoind one does

This is the main thing I'd want to confirm. Look at how the two submitters treat the max-fee-rate ceiling:

  • bitcoind (chainbackends/bitcoindrpc/package_submitter.go) deliberately sends maxfeerate=0 to disable the per-tx ceiling, with an explicit comment:

    "The CPFP child intentionally has a high feerate to pay for the zero-fee parent, and the default maxfeerate (0.10 BTC/kvB) would reject it."

  • lnd (chainbackends/lndsubmitter/submitter.go:66-72): when maxFeeRate == nil, it forwards nil, which the code documents as "the node default unchanged".

The only caller today, LNDBackend.SubmitPackage (chainbackends/lnd.go:219-221), always passes nil:

result, err := b.packageSubmitter.SubmitPackage(
    ctx, parents, child, nil,
)

So the two backends handle the same package differently: the bitcoind path removes the ceiling, the lnd path keeps lnd's default. If lnd applies a non-trivial default max fee rate to SubmitPackage, the exact high-feerate CPFP child that the bitcoind path went out of its way to allow could be rejected on the lnd path — which defeats the point of this feature for the zero-fee-parent case.

Worth verifying: what does lndclient.WalletKit.SubmitPackage do with a nil / 0 fee rate — is there a default ceiling, and does SatPerVByte(0) mean "unlimited" (as in bitcoind) or "reject everything"? If lnd does impose a default, the submitter should mirror bitcoind and pass an explicit "disabled" value when maxFeeRate == nil. If lnd's default is genuinely unbounded, a one-line comment saying so would save the next reader this same investigation.

Investigate this →

🟡 Minor — fee-rate conversion truncates toward zero

chainbackends/lndsubmitter/submitter.go:68-71:

satPerVByte := chainfee.SatPerVByte(
    *maxFeeRate * satoshiPerBTC / vBytesPerKvB,
)

chainfee.SatPerVByte is an integer, so the float result is truncated. For a ceiling, truncating down makes it stricter than requested (e.g. a caller-intended 12.9 sat/vByte becomes 12), which could reject a package that should have passed. Not exercised today since nil is always passed, but if/when a real ceiling flows through, math.Round (or a documented floor) would be more predictable.

🟡 Minor — mapResult is intentionally lossy

mapResult copies only TxID and Error per tx. That matches what the consumer in lnd.go reads (txResult.TxID / txResult.Error), so this is fine — just flagging that any future consumer of per-tx Vsize/Fees would need the mapping extended. A short "we only surface the fields the backend consumes" note would make the omission look deliberate rather than accidental.

✅ Harness change looks good

The neutrino option is backward-compatible (default stays bitcoind via LNDChainBackendBitcoind), and the regtest bitcoind is already started with -blockfilterindex=1, -peerblockfilters=1, and -bind=0.0.0.0:18444 (harness/harness.go:1233-1238), so --neutrino.connect=<bitcoind>:18444 will sync against its P2P + compact-filter interface. Flag threading through startLNDInstance / StartAdditionalLNDWithBackend is consistent.

Nits

  • Consider a small test for the res == nil guard (submitter.go:78-80) and the error passthrough from walletKit.SubmitPackage, so the error branches aren't uncovered.

· branch ellemouton/lnd-package-submitter

@ellemouton

Copy link
Copy Markdown
Contributor Author

/gemini review

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces the lndsubmitter package, enabling darepod to relay zero-fee unilateral-exit v3/TRUC packages via LND's WalletKit.SubmitPackage RPC. It also updates the test harness to support Neutrino as an LND chain backend. The review feedback suggests adding defensive nil checks for transactions to prevent panics, and rounding the converted fee rate to the nearest integer to avoid precision loss and an unintended lowering of the fee ceiling.

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.

Comment thread chainbackends/lndsubmitter/submitter.go Resolved
Comment thread chainbackends/lndsubmitter/submitter.go Resolved
@ellemouton
ellemouton force-pushed the ellemouton/lnd-package-submitter branch 2 times, most recently from ef1f474 to eeb3131 Compare July 7, 2026 22:54
Add chainbackends/lndsubmitter, a PackageSubmitter backed by
lndclient's WalletKit.SubmitPackage RPC, and wire it as the default for
the lnd chain backend when no explicit (bitcoind) submitter is injected.
This lets an lnd-backed darepod relay its zero-fee unilateral-exit
v3/TRUC packages through lnd's own chain connection, needing no separate
bitcoind RPC or Esplora endpoint (darepo-client#590/#678).

The submitter maps lndclient's native SubmitPackageResult back to the
btcjson.SubmitPackageResult that chainbackends.PackageSubmitter returns.
Add an optional neutrino chain backend for harness lnd nodes, selected
via lndConfig.chainBackend (LNDChainBackendBitcoind default, or
LNDChainBackendNeutrino). Neutrino mode runs lnd with
--bitcoin.node=neutrino --neutrino.connect=<bitcoind>:18444, syncing
and broadcasting over the regtest bitcoind's P2P interface and compact
block filters.

This lets integration tests exercise lnd's native SPV / 1p1c broadcast
path -- broadcasting a zero-fee v3 anchor parent plus its CPFP child
over P2P and relying on the peer's 1p1c package relay -- instead of
bitcoind's synchronous mempool acceptance. StartAdditionalLNDWithBackend
exposes the choice to callers; StartAdditionalLND keeps the bitcoind
default.
lndsubmitter became the default lnd package submitter, so an
lnd-on-neutrino daemon now routes its exit packages through
WalletKit.SubmitPackage. A neutrino-backed lnd has no mempool and cannot
return a package-accept verdict; it broadcasts each tx individually over
P2P (a peer's 1p1c relay reassembles the package) and reports the
"broadcast-unverified" sentinel instead of "success".

LNDBackend.SubmitPackage treated any non-"success" PackageMsg as a
rejection, so it turned that best-effort broadcast into an error and
failed exits that lnd had in fact already broadcast. Recognize the
sentinel (with no per-tx errors) as a successful submit and let the
confirmation watch decide the outcome.
@ellemouton
ellemouton force-pushed the ellemouton/lnd-package-submitter branch from c461bc9 to 5d3c23d Compare July 7, 2026 23:38

@Roasbeef Roasbeef left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 🥬

// WalletKit.SubmitPackage RPC, and maps the lndclient-native result back to
// the btcjson type callers expect.
func (s *Submitter) SubmitPackage(ctx context.Context, parents []*wire.MsgTx,
child *wire.MsgTx, maxFeeRate *float64) (*btcjson.SubmitPackageResult,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More customary to use fn.Option here

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed it's the more idiomatic shape. The maxFeeRate *float64 here is dictated by the existing chainbackends.PackageSubmitter interface (chainbackends/lnd.go), which the bitcoindrpc submitter also implements and which mirrors bitcoind's optional maxfeerate — so I kept this impl consistent with the interface rather than diverging it. Happy to migrate the whole interface (interface + both submitters + the LNDBackend/btcwbackend call sites, which all currently pass nil) to fn.Option[float64] — I'd prefer a small focused follow-up so this approved PR stays scoped to the lnd submitter. Will open that next unless you'd rather it ride here.

@ellemouton
ellemouton merged commit e4c5722 into main Jul 8, 2026
37 of 38 checks passed
@ellemouton
ellemouton deleted the ellemouton/lnd-package-submitter branch July 8, 2026 01:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants