Crate bitcoin_payment_instructions

These days, there are many possible ways to communicate Bitcoin payment instructions. This crate attempts to unify them into a simple parser which can read text provided directly by a payer or via a QR code scan/URI open and convert it into payment instructions.

This crate doesn’t actually help you pay these instructions, but provides a unified way to parse them.

Payment instructions come in two versions -

• ConfigurableAmountPaymentInstructions represent instructions which can be paid with a configurable amount, but may require further resolution to convert them into a FixedAmountPaymentInstructions for payment.
• FixedAmountPaymentInstructions represent instructions for which the recipient wants a specific quantity of funds and needs no further resolution

In general, you should resolve a string (received either from a QR code scan, a system URI open call, a “recipient” text box, or a pasted “recipient” instruction) through PaymentInstructions::parse.

From there, if you receive a PaymentInstructions::FixedAmount you should check that you support at least one of the FixedAmountPaymentInstructions::methods and request approval from the wallet owner to complete the payment.

If you receive a PaymentInstructions::ConfigurableAmount instead, you should similarly check that that you support one of the ConfigurableAmountPaymentInstructions::methods using PossiblyResolvedPaymentMethod::method_type, then display an amount selection UI to the wallet owner. Once they’ve selected an amount, you should proceed with ConfigurableAmountPaymentInstructions::set_amount to fetch a finalized FixedAmountPaymentInstructions before moving to confirmation and payment.

Modules

amount

Because lightning uses “milli-satoshis” rather than satoshis for its native currency amount, parsing payment instructions requires amounts with sub-satoshi precision.

dns_resolver

A HrnResolver which uses any recursive DNS resolver to resolve Human Readable Names into bitcoin payment instructions.

hrn

A type for storing Human Readable Names (HRNs) which can be resolved using BIP 353 and the DNS or LNURL-Pay and LN-Address.

hrn_resolution

When encountering human-readable names of the form alice@domain, we should attempt to resolve them into concrete payment instructions which wallets can handle.

http_resolver

A HrnResolver which uses reqwest and dns.google (8.8.8.8) to resolve Human Readable Names into bitcoin payment instructions.

receive

These days, there are several possible ways to communicate Bitcoin receive instructions.

Structs

ConfigurableAmountPaymentInstructions

Parsed payment instructions representing a set of possible ways to pay a configurable quantity of Bitcoin, as well as some associated metadata.

FixedAmountPaymentInstructions

Parsed payment instructions representing a set of possible ways to pay a fixed quantity to a recipient, as well as some associated metadata.

Enums

ParseError

An error when parsing payment instructions into PaymentInstructions.

PaymentInstructions

Parsed payment instructions representing a set of possible ways to pay, as well as some associated metadata.

PaymentMethod

A method which can be used to make a payment

PaymentMethodType

The method that a PossiblyResolvedPaymentMethod will eventually resolve to.

PossiblyResolvedPaymentMethod

A payment method which may require further resolution once the amount we wish to pay is fixed.

Constants

MAX_AMOUNT_DIFFERENCE

The maximum amount requested that we will allow individual payment methods to differ in satoshis.