Add stateless BOLT 12 payer proof support

[vincenzopalazzo]

Supersedes #845, reworked per the review feedback there: no payment-store persistence, and the API is stateless so we stay free to change or drop it once the verification side is worked out.

Summary

Exposes Bolt12Payment::create_payer_proof, which builds a BOLT 12 payer proof for a payment this node made:

let proof = node.bolt12_payment().create_payer_proof(
payment_id,// from Event::PaymentSuccessful
payment_preimage,// from Event::PaymentSuccessful
paid_invoice,// Event::PaymentSuccessful::bolt12_invoiceSome(options),)?;

PayerProofOptions controls which optional invoice fields are selectively disclosed (offer description, offer issuer, invoice amount, invoice creation time, plus arbitrary extra TLV types) and lets the payer attach a note. A proof always commits to the payer id, payment hash, and issuer signing pubkey.

Nothing is persisted: PaymentKind and the payment store are untouched, so there's no serialization change and no compatibility note. Callers hold on to the invoice themselves if they want to build a proof later.

Payments settled via a static invoice, i.e., async payments, can't be proven this way and are rejected with PayerProofUnavailable.

Why a node-side method at all

It was suggested that, since the invoice is already exposed on Event::PaymentSuccessful, we could skip the API and just document building a proof with LDK's methods directly. That doesn't work today — both LDK entry points need key material LDK Node deliberately doesn't expose:

• PaidBolt12Invoice::prove_payer_derived(preimage, expanded_key, payment_id, secp) takes an &ExpandedKey.
• PaidBolt12Invoice::prove_payer(preimage) avoids that, but returns an UnsignedPayerProof that must be signed with the derived payer key, which means Bolt12Invoice::derive_payer_signing_keys(expanded_key, secp) — ExpandedKey again.

In LDK Node ExpandedKey is only reachable via KeysManager, which is pub(crate), and Node::sign_message is a node-key BIP137 message signer, so it's no help here. Hence one thin method that supplies the expanded key; everything else is caller-provided.

Happy to expose a lower-level signing hook instead if that's preferred.

Test plan

• cargo fmt --all -- --check
• cargo check --lib --tests, cargo check --lib --features uniffi
• cargo clippy --lib -- -A warnings -D clippy::unwrap_used -A clippy::tabs_in_doc_comments
• cargo test --lib
• cargo test --test integration_tests_rust simple_bolt12_send_receive — extended to build a proof from values captured off the event, asserting the preimage, disclosed amount and note, and that undisclosed fields stay absent
• Python UniFFI bindings generate

Disclosure

This PR was prepared with AI assistance (Claude Code).

🤖 Generated with Claude Code

[ldk-reviews-bot]

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[tnull]

One question, otherwise LGTM

Feel free to undraft.

[tnull]

LGTM.

Two non-blocking nits: commit description still mentions PayerProofUnavailable and the commit shows as 'Unverified' here on Github, might want to start signing commits.

[vincenzopalazzo]

Supersedes #845, reworked per the review feedback there: no payment-store persistence, and the API is stateless so we stay free to change or drop it once the verification side is worked out.

Summary

Exposes Bolt12Payment::create_payer_proof, which builds a BOLT 12 payer proof for a payment this node made:

let proof = node.bolt12_payment().create_payer_proof(
payment_id,// from Event::PaymentSuccessful
payment_preimage,// from Event::PaymentSuccessful
paid_invoice,// Event::PaymentSuccessful::bolt12_invoiceSome(options),)?;

PayerProofOptions controls which optional invoice fields are selectively disclosed (offer description, offer issuer, invoice amount, invoice creation time, plus arbitrary extra TLV types) and lets the payer attach a note. A proof always commits to the payer id, payment hash, and issuer signing pubkey.

Nothing is persisted: PaymentKind and the payment store are untouched, so there's no serialization change and no compatibility note. Callers hold on to the invoice themselves if they want to build a proof later.

Payments settled via a static invoice, i.e., async payments, can't be proven this way and are rejected with PayerProofUnavailable.

Why a node-side method at all

It was suggested that, since the invoice is already exposed on Event::PaymentSuccessful, we could skip the API and just document building a proof with LDK's methods directly. That doesn't work today — both LDK entry points need key material LDK Node deliberately doesn't expose:

• PaidBolt12Invoice::prove_payer_derived(preimage, expanded_key, payment_id, secp) takes an &ExpandedKey.
• PaidBolt12Invoice::prove_payer(preimage) avoids that, but returns an UnsignedPayerProof that must be signed with the derived payer key, which means Bolt12Invoice::derive_payer_signing_keys(expanded_key, secp) — ExpandedKey again.

In LDK Node ExpandedKey is only reachable via KeysManager, which is pub(crate), and Node::sign_message is a node-key BIP137 message signer, so it's no help here. Hence one thin method that supplies the expanded key; everything else is caller-provided.

Happy to expose a lower-level signing hook instead if that's preferred.

Test plan

• cargo fmt --all -- --check
• cargo check --lib --tests, cargo check --lib --features uniffi
• cargo clippy --lib -- -A warnings -D clippy::unwrap_used -A clippy::tabs_in_doc_comments
• cargo test --lib
• cargo test --test integration_tests_rust simple_bolt12_send_receive — extended to build a proof from values captured off the event, asserting the preimage, disclosed amount and note, and that undisclosed fields stay absent
• Python UniFFI bindings generate

Disclosure

This PR was prepared with AI assistance (Claude Code).

🤖 Generated with Claude Code

[ldk-reviews-bot]

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[tnull]

One question, otherwise LGTM

Feel free to undraft.

[tnull]

LGTM.

Two non-blocking nits: commit description still mentions PayerProofUnavailable and the commit shows as 'Unverified' here on Github, might want to start signing commits.

[vincenzopalazzo]

Supersedes #845, reworked per the review feedback there: no payment-store persistence, and the API is stateless so we stay free to change or drop it once the verification side is worked out.

Summary

Exposes Bolt12Payment::create_payer_proof, which builds a BOLT 12 payer proof for a payment this node made:

let proof = node.bolt12_payment().create_payer_proof(
payment_id,// from Event::PaymentSuccessful
payment_preimage,// from Event::PaymentSuccessful
paid_invoice,// Event::PaymentSuccessful::bolt12_invoiceSome(options),)?;

PayerProofOptions controls which optional invoice fields are selectively disclosed (offer description, offer issuer, invoice amount, invoice creation time, plus arbitrary extra TLV types) and lets the payer attach a note. A proof always commits to the payer id, payment hash, and issuer signing pubkey.

Nothing is persisted: PaymentKind and the payment store are untouched, so there's no serialization change and no compatibility note. Callers hold on to the invoice themselves if they want to build a proof later.

Payments settled via a static invoice, i.e., async payments, can't be proven this way and are rejected with PayerProofUnavailable.

Why a node-side method at all

It was suggested that, since the invoice is already exposed on Event::PaymentSuccessful, we could skip the API and just document building a proof with LDK's methods directly. That doesn't work today — both LDK entry points need key material LDK Node deliberately doesn't expose:

• PaidBolt12Invoice::prove_payer_derived(preimage, expanded_key, payment_id, secp) takes an &ExpandedKey.
• PaidBolt12Invoice::prove_payer(preimage) avoids that, but returns an UnsignedPayerProof that must be signed with the derived payer key, which means Bolt12Invoice::derive_payer_signing_keys(expanded_key, secp) — ExpandedKey again.

In LDK Node ExpandedKey is only reachable via KeysManager, which is pub(crate), and Node::sign_message is a node-key BIP137 message signer, so it's no help here. Hence one thin method that supplies the expanded key; everything else is caller-provided.

Happy to expose a lower-level signing hook instead if that's preferred.

Test plan

• cargo fmt --all -- --check
• cargo check --lib --tests, cargo check --lib --features uniffi
• cargo clippy --lib -- -A warnings -D clippy::unwrap_used -A clippy::tabs_in_doc_comments
• cargo test --lib
• cargo test --test integration_tests_rust simple_bolt12_send_receive — extended to build a proof from values captured off the event, asserting the preimage, disclosed amount and note, and that undisclosed fields stay absent
• Python UniFFI bindings generate

Disclosure

This PR was prepared with AI assistance (Claude Code).

🤖 Generated with Claude Code

[ldk-reviews-bot]

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[tnull]

One question, otherwise LGTM

Feel free to undraft.

[tnull]

LGTM.

Two non-blocking nits: commit description still mentions PayerProofUnavailable and the commit shows as 'Unverified' here on Github, might want to start signing commits.

[vincenzopalazzo]

Supersedes #845, reworked per the review feedback there: no payment-store persistence, and the API is stateless so we stay free to change or drop it once the verification side is worked out.

Summary

Exposes Bolt12Payment::create_payer_proof, which builds a BOLT 12 payer proof for a payment this node made:

let proof = node.bolt12_payment().create_payer_proof(
payment_id,// from Event::PaymentSuccessful
payment_preimage,// from Event::PaymentSuccessful
paid_invoice,// Event::PaymentSuccessful::bolt12_invoiceSome(options),)?;

PayerProofOptions controls which optional invoice fields are selectively disclosed (offer description, offer issuer, invoice amount, invoice creation time, plus arbitrary extra TLV types) and lets the payer attach a note. A proof always commits to the payer id, payment hash, and issuer signing pubkey.

Nothing is persisted: PaymentKind and the payment store are untouched, so there's no serialization change and no compatibility note. Callers hold on to the invoice themselves if they want to build a proof later.

Payments settled via a static invoice, i.e., async payments, can't be proven this way and are rejected with PayerProofUnavailable.

Why a node-side method at all

It was suggested that, since the invoice is already exposed on Event::PaymentSuccessful, we could skip the API and just document building a proof with LDK's methods directly. That doesn't work today — both LDK entry points need key material LDK Node deliberately doesn't expose:

• PaidBolt12Invoice::prove_payer_derived(preimage, expanded_key, payment_id, secp) takes an &ExpandedKey.
• PaidBolt12Invoice::prove_payer(preimage) avoids that, but returns an UnsignedPayerProof that must be signed with the derived payer key, which means Bolt12Invoice::derive_payer_signing_keys(expanded_key, secp) — ExpandedKey again.

In LDK Node ExpandedKey is only reachable via KeysManager, which is pub(crate), and Node::sign_message is a node-key BIP137 message signer, so it's no help here. Hence one thin method that supplies the expanded key; everything else is caller-provided.

Happy to expose a lower-level signing hook instead if that's preferred.

Test plan

• cargo fmt --all -- --check
• cargo check --lib --tests, cargo check --lib --features uniffi
• cargo clippy --lib -- -A warnings -D clippy::unwrap_used -A clippy::tabs_in_doc_comments
• cargo test --lib
• cargo test --test integration_tests_rust simple_bolt12_send_receive — extended to build a proof from values captured off the event, asserting the preimage, disclosed amount and note, and that undisclosed fields stay absent
• Python UniFFI bindings generate

Disclosure

This PR was prepared with AI assistance (Claude Code).

🤖 Generated with Claude Code

[ldk-reviews-bot]

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[tnull]

One question, otherwise LGTM

Feel free to undraft.

[tnull]

LGTM.

Two non-blocking nits: commit description still mentions PayerProofUnavailable and the commit shows as 'Unverified' here on Github, might want to start signing commits.

[vincenzopalazzo]

Supersedes #845, reworked per the review feedback there: no payment-store persistence, and the API is stateless so we stay free to change or drop it once the verification side is worked out.

Summary

Exposes Bolt12Payment::create_payer_proof, which builds a BOLT 12 payer proof for a payment this node made:

let proof = node.bolt12_payment().create_payer_proof(
payment_id,// from Event::PaymentSuccessful
payment_preimage,// from Event::PaymentSuccessful
paid_invoice,// Event::PaymentSuccessful::bolt12_invoiceSome(options),)?;

PayerProofOptions controls which optional invoice fields are selectively disclosed (offer description, offer issuer, invoice amount, invoice creation time, plus arbitrary extra TLV types) and lets the payer attach a note. A proof always commits to the payer id, payment hash, and issuer signing pubkey.

Nothing is persisted: PaymentKind and the payment store are untouched, so there's no serialization change and no compatibility note. Callers hold on to the invoice themselves if they want to build a proof later.

Payments settled via a static invoice, i.e., async payments, can't be proven this way and are rejected with PayerProofUnavailable.

Why a node-side method at all

It was suggested that, since the invoice is already exposed on Event::PaymentSuccessful, we could skip the API and just document building a proof with LDK's methods directly. That doesn't work today — both LDK entry points need key material LDK Node deliberately doesn't expose:

• PaidBolt12Invoice::prove_payer_derived(preimage, expanded_key, payment_id, secp) takes an &ExpandedKey.
• PaidBolt12Invoice::prove_payer(preimage) avoids that, but returns an UnsignedPayerProof that must be signed with the derived payer key, which means Bolt12Invoice::derive_payer_signing_keys(expanded_key, secp) — ExpandedKey again.

In LDK Node ExpandedKey is only reachable via KeysManager, which is pub(crate), and Node::sign_message is a node-key BIP137 message signer, so it's no help here. Hence one thin method that supplies the expanded key; everything else is caller-provided.

Happy to expose a lower-level signing hook instead if that's preferred.

Test plan

• cargo fmt --all -- --check
• cargo check --lib --tests, cargo check --lib --features uniffi
• cargo clippy --lib -- -A warnings -D clippy::unwrap_used -A clippy::tabs_in_doc_comments
• cargo test --lib
• cargo test --test integration_tests_rust simple_bolt12_send_receive — extended to build a proof from values captured off the event, asserting the preimage, disclosed amount and note, and that undisclosed fields stay absent
• Python UniFFI bindings generate

Disclosure

This PR was prepared with AI assistance (Claude Code).

🤖 Generated with Claude Code

[ldk-reviews-bot]

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[tnull]

One question, otherwise LGTM

Feel free to undraft.

[tnull]

LGTM.

Two non-blocking nits: commit description still mentions PayerProofUnavailable and the commit shows as 'Unverified' here on Github, might want to start signing commits.

[vincenzopalazzo]

Supersedes #845, reworked per the review feedback there: no payment-store persistence, and the API is stateless so we stay free to change or drop it once the verification side is worked out.

Summary

Exposes Bolt12Payment::create_payer_proof, which builds a BOLT 12 payer proof for a payment this node made:

let proof = node.bolt12_payment().create_payer_proof(
payment_id,// from Event::PaymentSuccessful
payment_preimage,// from Event::PaymentSuccessful
paid_invoice,// Event::PaymentSuccessful::bolt12_invoiceSome(options),)?;

PayerProofOptions controls which optional invoice fields are selectively disclosed (offer description, offer issuer, invoice amount, invoice creation time, plus arbitrary extra TLV types) and lets the payer attach a note. A proof always commits to the payer id, payment hash, and issuer signing pubkey.

Nothing is persisted: PaymentKind and the payment store are untouched, so there's no serialization change and no compatibility note. Callers hold on to the invoice themselves if they want to build a proof later.

Payments settled via a static invoice, i.e., async payments, can't be proven this way and are rejected with PayerProofUnavailable.

Why a node-side method at all

It was suggested that, since the invoice is already exposed on Event::PaymentSuccessful, we could skip the API and just document building a proof with LDK's methods directly. That doesn't work today — both LDK entry points need key material LDK Node deliberately doesn't expose:

• PaidBolt12Invoice::prove_payer_derived(preimage, expanded_key, payment_id, secp) takes an &ExpandedKey.
• PaidBolt12Invoice::prove_payer(preimage) avoids that, but returns an UnsignedPayerProof that must be signed with the derived payer key, which means Bolt12Invoice::derive_payer_signing_keys(expanded_key, secp) — ExpandedKey again.

In LDK Node ExpandedKey is only reachable via KeysManager, which is pub(crate), and Node::sign_message is a node-key BIP137 message signer, so it's no help here. Hence one thin method that supplies the expanded key; everything else is caller-provided.

Happy to expose a lower-level signing hook instead if that's preferred.

Test plan

• cargo fmt --all -- --check
• cargo check --lib --tests, cargo check --lib --features uniffi
• cargo clippy --lib -- -A warnings -D clippy::unwrap_used -A clippy::tabs_in_doc_comments
• cargo test --lib
• cargo test --test integration_tests_rust simple_bolt12_send_receive — extended to build a proof from values captured off the event, asserting the preimage, disclosed amount and note, and that undisclosed fields stay absent
• Python UniFFI bindings generate

Disclosure

This PR was prepared with AI assistance (Claude Code).

🤖 Generated with Claude Code

[ldk-reviews-bot]

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[tnull]

One question, otherwise LGTM

Feel free to undraft.

[tnull]

LGTM.

Two non-blocking nits: commit description still mentions PayerProofUnavailable and the commit shows as 'Unverified' here on Github, might want to start signing commits.

[vincenzopalazzo]

Supersedes #845, reworked per the review feedback there: no payment-store persistence, and the API is stateless so we stay free to change or drop it once the verification side is worked out.

Summary

Exposes Bolt12Payment::create_payer_proof, which builds a BOLT 12 payer proof for a payment this node made:

let proof = node.bolt12_payment().create_payer_proof(
payment_id,// from Event::PaymentSuccessful
payment_preimage,// from Event::PaymentSuccessful
paid_invoice,// Event::PaymentSuccessful::bolt12_invoiceSome(options),)?;

PayerProofOptions controls which optional invoice fields are selectively disclosed (offer description, offer issuer, invoice amount, invoice creation time, plus arbitrary extra TLV types) and lets the payer attach a note. A proof always commits to the payer id, payment hash, and issuer signing pubkey.

Nothing is persisted: PaymentKind and the payment store are untouched, so there's no serialization change and no compatibility note. Callers hold on to the invoice themselves if they want to build a proof later.

Payments settled via a static invoice, i.e., async payments, can't be proven this way and are rejected with PayerProofUnavailable.

Why a node-side method at all

It was suggested that, since the invoice is already exposed on Event::PaymentSuccessful, we could skip the API and just document building a proof with LDK's methods directly. That doesn't work today — both LDK entry points need key material LDK Node deliberately doesn't expose:

• PaidBolt12Invoice::prove_payer_derived(preimage, expanded_key, payment_id, secp) takes an &ExpandedKey.
• PaidBolt12Invoice::prove_payer(preimage) avoids that, but returns an UnsignedPayerProof that must be signed with the derived payer key, which means Bolt12Invoice::derive_payer_signing_keys(expanded_key, secp) — ExpandedKey again.

In LDK Node ExpandedKey is only reachable via KeysManager, which is pub(crate), and Node::sign_message is a node-key BIP137 message signer, so it's no help here. Hence one thin method that supplies the expanded key; everything else is caller-provided.

Happy to expose a lower-level signing hook instead if that's preferred.

Test plan

• cargo fmt --all -- --check
• cargo check --lib --tests, cargo check --lib --features uniffi
• cargo clippy --lib -- -A warnings -D clippy::unwrap_used -A clippy::tabs_in_doc_comments
• cargo test --lib
• cargo test --test integration_tests_rust simple_bolt12_send_receive — extended to build a proof from values captured off the event, asserting the preimage, disclosed amount and note, and that undisclosed fields stay absent
• Python UniFFI bindings generate

Disclosure

This PR was prepared with AI assistance (Claude Code).

🤖 Generated with Claude Code

[ldk-reviews-bot]

👋 Thanks for assigning @tnull as a reviewer!
I'll wait for their review and will help manage the review process.
Once they submit their review, I'll check if a second reviewer would be helpful.

[tnull]

One question, otherwise LGTM

Feel free to undraft.

[tnull]

LGTM.

Two non-blocking nits: commit description still mentions PayerProofUnavailable and the commit shows as 'Unverified' here on Github, might want to start signing commits.