feat: add BIP353 DNS payment instructions by sdmg15 · Pull Request #236 · bitcoindevkit/bdk-cli

sdmg15 · 2026-01-07T22:18:27Z

Description

This PR adds support for BIP353 payment instructions.
The following notable changes are done:

Adding of an option resolve_dns_recipient which receives a Human Readable Name (HRN) and returns the associated address
Modify the create_tx for it to support user specifying recipients as HRN.

Notes to the reviewers

Here is a list of HRN that could be used to test the implementation:

pay@dunxen.dev: Supports BOLT 12 Payment method only
send.some@satsto.me: Supports BOLT 12 payment and On Chain
Testing resolving: bdk-cli -n bitcoin resolve_dns_recipient send.some@satsto.me
Testing create tx: bdk-cli -n bitcoin wallet -w regtest_default_wallet create_tx --to "bcrt1qe497k549sgw9trzym50tdlegq3xx4apjqynjqm:1000" --to_dns "send.some@satsto.me:5000"

Changelog notice

Add top level command resolve_dns_recipient to resolve the DNS payment instructions
Add option --to_dns to create_tx command to allow sending to a Human Readable Name (HRN)

Checklists

All Submissions:

I've signed all my commits
I followed the contribution guidelines
I ran cargo fmt and cargo clippy before committing

New Features:

I've added tests for the new feature
I've added docs for the new feature
I've updated CHANGELOG.md

va-an · 2026-02-07T20:13:21Z

@sdmg15 Hi! Could you make it compile?

coveralls · 2026-02-09T14:38:13Z

Pull Request Test Coverage Report for Build 21818410493

Details

0 of 120 (0.0%) changed or added relevant lines in 3 files are covered.
1 unchanged line in 1 file lost coverage.
Overall coverage decreased (-0.5%) to 10.237%

Changes Missing Coverage	Changed/Added Lines	%
src/utils.rs	15	0.0%
src/handlers.rs	36	0.0%
src/dns_payment_instructions.rs	69	0.0%

Files with Coverage Reduction	New Missed Lines	%
src/handlers.rs	1	12.57%

Totals
Change from base Build 21153868360:	-0.5%
Covered Lines:	268
Relevant Lines:	2618

💛 - Coveralls

sdmg15 · 2026-02-11T04:53:07Z

@va-an Thanks for taking a look. I think it should be resolved now.

va-an

Thanks for working on this @sdmg15!
I have left a few suggestions, please have a look.

sdmg15 · 2026-02-13T09:35:00Z

@va-an Applied some reviews and recommendation on 6724be5

I've also updated the PR description.

va-an

@sdmg15 thanks for update and for the detailed description!
Please take a look at the comments.

va-an

@sdmg15 thanks for update!
I've added some suggestions, pls have a look.

va-an · 2026-03-28T21:34:18Z

@sdmg15 thanks for updates!
Could you rebase?

va-an

Thanks for addressing the previous round of feedback. Before tackling more changes - branch has merge conflicts with master, would you mind rebasing first? A few more comments below.

Payment struct design

Payment is shared between two flows with different needs.

In the send flow (process_instructions -> call site in handlers.rs) only receiving_addr is read, everything else is built and discarded. .unwrap() is needed only because the field is Option<Address> despite always being Some here.

In the resolve flow (resolve_dns_recipient) the same struct is filled with the opposite subset: receiving_addr/expected_amount always None, metadata fields populated for display. So every Option<T> here is "always Some" in one flow and "always None" in the other - the type system encodes nullability that doesn't actually exist in either path.

Suggested split:

// resolve flow - display only
pub struct ResolvedPaymentInfo {
    pub hrn: String,
    pub payment_methods: Vec<PaymentMethod>,
    pub description: Option<String>,
    pub min_amount: Option<Amount>,
    pub max_amount: Option<Amount>,
    pub notes: String,
}
// `display(pretty)` moves here

// send flow - return what's actually used
pub async fn process_instructions(...) -> Result<(Address, Amount), Error>

This resolves several inline comments:

unwrap on receiving_addr
the FixedAmount amount mismatch
both unwraps on human_readable_name().

One small process note: please leave review threads open after addressing them - the convention in this repo is for the reviewer to resolve them once they confirm the fix.

va-an · 2026-05-15T10:52:51Z

+        let mut methods: Vec<String> = Vec::new();
+        self.payment_methods.iter().for_each(|pm| match pm {
+            bitcoin_payment_instructions::PaymentMethod::LightningBolt11(bolt11) => {
+                methods.push(format!("Bolt 11 invoice ({})", shorten(bolt11, 20, 15)))
+            }
+            bitcoin_payment_instructions::PaymentMethod::LightningBolt12(offer) => {
+                methods.push(format!("Bolt 12 invoice ({})", shorten(offer, 20, 15)))
+            }
+            bitcoin_payment_instructions::PaymentMethod::OnChain(address) => {
+                methods.push(format!("On chain ({})", address))
+            }
+            bitcoin_payment_instructions::PaymentMethod::Cashu(csh) => {
+                methods.push(format!("Cashu payment ({})", shorten(csh, 20, 15)))
+            }
+        });


Consider map + collect here - drops the mutable accumulator and lets match return the String directly. Would need PaymentMethod::* in the use block.

Suggested change

let mut methods: Vec<String> = Vec::new();

self.payment_methods.iter().for_each(|pm| match pm {

bitcoin_payment_instructions::PaymentMethod::LightningBolt11(bolt11) => {

methods.push(format!("Bolt 11 invoice ({})", shorten(bolt11, 20, 15)))

}

bitcoin_payment_instructions::PaymentMethod::LightningBolt12(offer) => {

methods.push(format!("Bolt 12 invoice ({})", shorten(offer, 20, 15)))

}

bitcoin_payment_instructions::PaymentMethod::OnChain(address) => {

methods.push(format!("On chain ({})", address))

}

bitcoin_payment_instructions::PaymentMethod::Cashu(csh) => {

methods.push(format!("Cashu payment ({})", shorten(csh, 20, 15)))

}

});

let methods: Vec<String> = self

.payment_methods

.iter()

.map(|pm| match pm {

LightningBolt11(bolt11) => {

format!("Bolt 11 invoice ({})", shorten(bolt11, 20, 15))

}

LightningBolt12(offer) => format!("Bolt 12 invoice ({})", shorten(offer, 20, 15)),

OnChain(address) => format!("On chain ({})", address),

Cashu(csh) => format!("Cashu payment ({})", shorten(csh, 20, 15)),

})

.collect();

va-an · 2026-05-15T11:15:57Z

+        self.payment_methods.iter().for_each(|pm| match pm {
+            bitcoin_payment_instructions::PaymentMethod::LightningBolt11(bolt11) => {
+                methods.push(format!("Bolt 11 invoice ({})", shorten(bolt11, 20, 15)))
+            }
+            bitcoin_payment_instructions::PaymentMethod::LightningBolt12(offer) => {
+                methods.push(format!("Bolt 12 invoice ({})", shorten(offer, 20, 15)))
+            }
+            bitcoin_payment_instructions::PaymentMethod::OnChain(address) => {
+                methods.push(format!("On chain ({})", address))
+            }
+            bitcoin_payment_instructions::PaymentMethod::Cashu(csh) => {
+                methods.push(format!("Cashu payment ({})", shorten(csh, 20, 15)))
+            }


shorten runs before the if pretty check, so JSON output contains truncated Bolt 11 / Bolt 12 invoices and Cashu tokens - downstream tools can't use them.

Non-pretty output:

-> % cargo run --all-features -- -n bitcoin resolve_dns_recipient send.some@satsto.me { "description": null, "expected_amount_to_send": null, "hrn": "send.some@satsto.me", "max_amount": null, "min_amount": null, "notes": "This is configurable payment instructions. You must send an amount between min_amount and max_amount if set.", "payment_methods": [ "On chain (bc1qztwy6xen3zdtt7z0vrgapmjtfz8acjkfp5fp7l)", "Bolt 12 invoice (lno1zr5qyugqgskrk70k...ph4xrxtk2xc3lpq)" ] }

The shorten calls must be moved into the if pretty branch only.

va-an · 2026-05-15T11:37:45Z

+        dns_recipients: Vec<(String, u64)>,
+        #[cfg(feature = "dns_payment")]
+        /// Custom resolver DNS IP to be used for resolution.
+        #[arg(long = "dns_resolver", default_value = "8.8.8.8:53")]


The default DNS resolver value is inconsistent between the two commands:

ResolveDnsRecipient::resolver -> "8.8.8.8"

CreateTx::dns_resolver -> "8.8.8.8:53"

parse_dns_instructions already appends :53 when no port is present, so the :53 suffix in CreateTx is redundant. Drop it to keep the defaults aligned.

Also worth aligning the flag names themselves - --resolver in one command and --dns_resolver in the other forces users to remember two names for the same thing.

Same value also keeps getting renamed as it travels through the call stack. For the resolve command:

commands.rs -> resolver

handlers.rs::handle_resolve_dns_recipient_command(... resolver: String ...)

dns_payment_instructions.rs::resolve_dns_recipient(... ip: String)

dns_payment_instructions.rs::parse_dns_instructions(... resolver_ip: String)

Three different names for the same value makes the flow harder to follow. Use dns_resolver everywhere - both as the CLI flag (--dns_resolver) and as the field/parameter name across all functions.

va-an · 2026-05-15T20:02:51Z

+pub(crate) async fn parse_dns_instructions(
+    hrn: &str,
+    network: Network,
+    resolver_ip: String,


Take &str instead of String - format! already allocates, and it removes the need for dns_resolver.clone() at the call site.

va-an · 2026-05-15T20:53:11Z

+                    use crate::dns_payment_instructions::{
+                        parse_dns_instructions, process_instructions,
+                    };


Please move this use to the top of the file, next to the existing dns_payment_instructions import on line 16.

va-an · 2026-05-15T21:27:43Z

+                    .map_err(|e| Error::Generic(format!("Parsing error occured {e:#?}")))?;
+                    let payment = process_instructions(amount, &instructions, resolver).await?;
+
+                    recipients.push((payment.receiving_addr.unwrap().into(), amount));


Two issues here:

amount is the user-supplied value, not payment.expected_amount. For FixedAmount instructions the recipient sets an exact amount, and the tx silently goes out with whatever the user typed instead.

.unwrap() relies on process_instructions always setting receiving_addr: Some(...) - an implicit invariant across two files.

Both resolved by the structural change in the top-level comment.

va-an · 2026-05-15T21:52:03Z

@sdmg15 when addressing the comments, could you split the changes into separate commits per independent fix instead of squashing everything into one? It makes the review much easier to follow (each commit maps to one review thread), and helps with bisect/revert later if needed. They can always be squashed at merge time.

github-project-automation Bot added this to BDK-CLI Jan 7, 2026

sdmg15 force-pushed the feat/bip353-payment-instructions branch from ba3c713 to a0f3e9d Compare January 8, 2026 18:13

sdmg15 marked this pull request as ready for review January 9, 2026 08:39

sdmg15 force-pushed the feat/bip353-payment-instructions branch 2 times, most recently from 49154f3 to baf349b Compare February 9, 2026 08:51

sdmg15 force-pushed the feat/bip353-payment-instructions branch from baf349b to 0e9756e Compare February 11, 2026 04:52

va-an suggested changes Feb 11, 2026

View reviewed changes

sdmg15 force-pushed the feat/bip353-payment-instructions branch from 0e9756e to 6724be5 Compare February 13, 2026 09:21

sdmg15 force-pushed the feat/bip353-payment-instructions branch from 6724be5 to 20ef094 Compare February 13, 2026 11:46

va-an reviewed Feb 13, 2026

View reviewed changes

Comment thread src/dns_payment_instructions.rs Outdated

Comment thread src/handlers.rs Outdated

Comment thread src/handlers.rs Outdated

Comment thread src/handlers.rs Outdated

Comment thread src/handlers.rs Outdated

sdmg15 force-pushed the feat/bip353-payment-instructions branch 2 times, most recently from 977534a to 4852673 Compare February 17, 2026 20:12

va-an mentioned this pull request Feb 21, 2026

Human Readable Names Support bitcoindevkit/bdk_wallet#97

Open

va-an reviewed Feb 21, 2026

View reviewed changes

Comment thread src/utils.rs Outdated

Comment thread src/dns_payment_instructions.rs Outdated

Comment thread src/commands.rs Outdated

Comment thread src/dns_payment_instructions.rs Outdated

tvpeter moved this to In Progress in BDK-CLI Feb 23, 2026

sdmg15 force-pushed the feat/bip353-payment-instructions branch from 4852673 to 58798de Compare March 16, 2026 12:44

feat: integrate BIP 353 dns payment instructions

72656ec

sdmg15 force-pushed the feat/bip353-payment-instructions branch from 58798de to 72656ec Compare March 31, 2026 08:46

va-an suggested changes May 15, 2026

View reviewed changes

tvpeter assigned sdmg15 May 16, 2026

Conversation

sdmg15 commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Notes to the reviewers

Changelog notice

Checklists

All Submissions:

New Features:

Uh oh!

va-an commented Feb 7, 2026

Uh oh!

coveralls commented Feb 9, 2026

Pull Request Test Coverage Report for Build 21818410493

Details

💛 - Coveralls

Uh oh!

sdmg15 commented Feb 11, 2026

Uh oh!

va-an left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sdmg15 commented Feb 13, 2026

Uh oh!

va-an left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

va-an left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

va-an commented Mar 28, 2026

Uh oh!

va-an left a comment

Choose a reason for hiding this comment

Uh oh!

va-an May 15, 2026

Choose a reason for hiding this comment

Uh oh!

va-an May 15, 2026

Choose a reason for hiding this comment

Uh oh!

va-an May 15, 2026

Choose a reason for hiding this comment

Uh oh!

va-an May 15, 2026

Choose a reason for hiding this comment

Uh oh!

va-an May 15, 2026

Choose a reason for hiding this comment

Uh oh!

va-an May 15, 2026

Choose a reason for hiding this comment

Uh oh!

va-an commented May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sdmg15 commented Jan 7, 2026 •

edited

Loading