fix: Record derivation paths for payjoin payments

[ValeraFinebits]

Summary

Payjoin reconciliation created the final Bitcoin payment without its wallet derivation metadata, causing the invoice to display Index: Unknown.

This change:

• resolves the settlement output’s derivation path through NBXplorer;
• records KeyPath and KeyIndex in the final payment details;
• treats lookup failures as non-fatal;
• avoids the lookup while reconciliation is waiting for confirmation;
• preserves an already recorded path across subsequent reconciliation polls.

[Copilot]

🟡 Changes recommended

Missing derivation metadata can abort new sessions and permanently fail pre-upgrade in-flight settlements.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds derivation metadata to reconciled Payjoin payments so invoices can display the correct wallet index.

Changes:

• Captures and persists settlement key paths.
• Records payment destination, KeyPath, and KeyIndex.
• Adds schema migration and coverage for hot, cold, and preserved destinations.

File summaries

File	Description
PayjoinReceiverStateProcessor.cs	Adds validation TODO.
PayjoinReceiverSessionProcessor.cs	Persists settlement key paths.
PayjoinReceiverProposalFinalizer.cs	Adds settlement-value TODOs.
PayjoinReceiverOutputBuilder.cs	Captures output derivation paths.
PayjoinAccountingPaymentService.cs	Records payment derivation metadata.
PayjoinAccountingBridgeService.cs	Carries and resets persisted paths.
PayjoinPluginDbContextModelSnapshot.cs	Updates the EF model snapshot.
20260822143644_AddSettlementKeyPath.Designer.cs	Defines the migration model.
20260822143644_AddSettlementKeyPath.cs	Adds the database column.
PayjoinPluginDbSchema.cs	Defines the path length limit.
PayjoinAccountingBridgeData.cs	Adds the persistence property.
PayjoinAccountingBridgeConfiguration.cs	Configures path storage.
PayjoinReceiverOutputBuilderTests.cs	Tests path propagation.
PayjoinAccountingPaymentServiceTests.cs	Tests recorded payment metadata.
PayjoinAccountingBridgeResetTests.cs	Tests path clearing.
PayjoinSettlementFlowTests.cs	Tests atomic path persistence.
PayjoinReceiverOutputBuilderIntegrationTests.cs	Verifies real wallet paths.
PayjoinPluginIntegrationTests.cs	Verifies preserved invoice paths.

Review details

Files not reviewed (1)

• BTCPayServer.Plugins.Payjoin/Migrations/20260822143644_AddSettlementKeyPath.Designer.cs: Generated file

• Files reviewed: 17/18 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.