Skip to content

Adding support for main bolt12 commands to NIP-47 #1952

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
21M4TW wants to merge 18 commits into
base: master
Choose a base branch
from
Open

Adding support for main bolt12 commands to NIP-47 #1952

Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
51aa4ce
Adding support for main bolt12 commands to NIP-47
21M4TW Jun 11, 2025
114f8a0
-Generalising the description of invoice strings (from bolt11 to
21M4TW Jun 11, 2025
00acfb4
-Removing the fetch_invoice command as it is not needed.
21M4TW Jun 17, 2025
a155602
-Adding offer issuer field where applicable
21M4TW Jun 17, 2025
3de36b4
-Adding support for other currencies when making and listing offers, for
21M4TW Jun 17, 2025
1cffc22
-Adding offer_id field for bolt12 invoices, when applicable.
21M4TW Jun 17, 2025
c9938b5
-multi_pay_invoice: -Update description for amount
21M4TW Jun 17, 2025
50ea1c1
Merge branch 'nostr-protocol:master' into nip47_add_bolt12_support
21M4TW Jul 12, 2025
e1a6c01
Merge branch 'nostr-protocol:master' into nip47_add_bolt12_support
21M4TW Jul 25, 2025
eb3b4b9
get_offer_info: Fixing the input parameter (offer instead of offer_id).
21M4TW Jul 25, 2025
bcc18d3
-Dropping the lookup_offer method. Integrating the functionality into
21M4TW Jul 26, 2025
7b743aa
-Splitting the pay_invoice and multi_pay_invoice methods into
21M4TW Jul 28, 2025
6c69b2c
Update 47.md
staab Nov 12, 2025
98dbb60
Merge branch 'master' into nip47_add_bolt12_support
21M4TW Nov 18, 2025
e62d132
-Removing multi_pay_offer as these multi_* methods are not used
21M4TW Nov 18, 2025
3a4633d
Merge branch 'nostr-protocol:master' into nip47_add_bolt12_support
21M4TW Dec 2, 2025
5041c0d
-Removing the possibility of activating/disabling an offer.
21M4TW Dec 6, 2025
687154a
Merge branch 'master' into nip47_add_bolt12_support
21M4TW Dec 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 131 additions & 3 deletions 47.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,7 @@ Request:
"method": "pay_invoice",
"params": {
"invoice": "lnbc50n1...", // bolt11 invoice
"amount": 123, // invoice amount in msats, optional
"amount": 123, // invoice amount in msats, optional if the bolt11 invoice contains an amount
"metadata": {} // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc, optional
}
}
Expand Down Expand Up @@ -217,7 +217,7 @@ Request:
"method": "multi_pay_invoice",
"params": {
"invoices": [
{"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11 invoice and amount in msats, amount is optional
{"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11 invoice and amount in msats, amount is optional if the bolt11 invoice contains an amount
{"id":"3da52c32a1", "invoice": "lnbc50n1...", "metadata": {} }, // generic metadata that can be used to add things like zap/boostagram details for a payer name/comment/etc, optional
],
}
Expand Down Expand Up @@ -375,8 +375,11 @@ Response:
"invoice": "string", // encoded invoice, optional
"description": "string", // invoice's description, optional
"description_hash": "string", // invoice's description hash, optional
"offer_issuer": "string", // offer's issuer for a bolt12 transaction, optional
"payer_note": "string", // note from payer for a bolt12 transaction, optional
"preimage": "string", // payment's preimage, optional if unpaid
"payment_hash": "string", // Payment hash for the payment
"offer_id": "string", // the id of the offer, for a bolt12 invoice, optional
"amount": 123, // value in msats
"fees_paid": 123, // value in msats
"created_at": unixtimestamp, // invoice/payment creation time
Expand Down Expand Up @@ -424,8 +427,11 @@ Response:
"invoice": "string", // encoded invoice, optional
"description": "string", // invoice's description, optional
"description_hash": "string", // invoice's description hash, optional
"offer_issuer": "string", // offer's issuer for a bolt12 transaction, optional
"payer_note": "string", // note from payer for a bolt12 transaction, optional
"preimage": "string", // payment's preimage, optional if unpaid
"payment_hash": "string", // Payment hash for the payment
"offer_id": "string", // the id of the offer, for a bolt12 invoice, optional
"amount": 123, // value in msats
"fees_paid": 123, // value in msats
"created_at": unixtimestamp, // invoice/payment creation time
Expand Down Expand Up @@ -458,6 +464,123 @@ Response:
}
```

### `pay_offer`

Description: Requests payment of an invoice.

Request:
```jsonc
{
"method": "pay_offer",
"params": {
"offer": "lno1pgx...", // bolt12 offer
"amount": 123, // invoice amount in msats, optional if the bolt12 offer contains an amount
"payer_note": "string", // note to be included for the bolt12 invoice, optional
}
}
```

Response:
```jsonc
{
"result_type": "pay_offer",
"result": {
"preimage": "0123456789abcdef...", // preimage of the payment
"fees_paid": 123, // value in msats, optional
Copy link
Copy Markdown

@TheBlueMatt TheBlueMatt Dec 9, 2025

Choose a reason for hiding this comment

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

Might make sense to go ahead and define a field for lightning/bolts#1295 noting that its optional temporarily until all the spec lands but will be required in the future?

Copy link
Copy Markdown
Collaborator

@vitorpamplona vitorpamplona Dec 9, 2025

Choose a reason for hiding this comment

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

Maybe leave this to a separate PR. We need to know who would want to use those proofs on Nostr.

Copy link
Copy Markdown

@TheBlueMatt TheBlueMatt Dec 9, 2025

Choose a reason for hiding this comment

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

Well first of all they'll be the basis for BOLT 12 zaps :). Though for that we'll need to figure out how to also request a signature over the zapper information as a part of the PoP, but should be as simple as an extra field to request a signed message from the payer key.

}
}
```

Errors:
- `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar.

### `make_offer`

Request:
```jsonc
{
"method": "make_offer",
"params": {
"currency": "ABC", // ISO 4217 code of the currency (3 characters), optional (missing means msat)
"currency_minor_unit": 123, // number of decimals to apply to the amount, for currency different than msat, optional
"amount": 123, // minimum amount value, after adjustment by currency_minor_unit if applicable, optional
"description": "string", // offer's description, optional
"issuer": "string", // offer's issuer, optional
"absolute_expiry": unixtimestamp, // absolute expiry time of the offer, optional
"single_use": false // only allow the offer to be used once, optional, default false
}
}
```

Response:
```jsonc
{
"result_type": "make_offer",
"result": {
"offer": "lno1pgx...", // encoded offer
"description": "string", // offer's description, optional
"issuer": "string", // offer's issuer, optional
"currency": "ABC", // ISO 4217 code of the currency (3 characters), optional (missing means msat)
"currency_minor_unit": 123, // number of decimals to apply to the amount, for currency different than msat, optional
"amount": 123, // minimum amount value, after adjustment by currency_minor_unit if applicable, optional
"offer_id": "string", // the id of the offer
"single_use": false, // whether the offer can only be used once
"used": false, // whether the offer has been used
Comment thread
21M4TW marked this conversation as resolved.
"created_at": unixtimestamp, // offer creation time
"expires_at": unixtimestamp // offer absolute expiry time, optional
}
}
```

Errors:
- `EXISTED_ALREADY`: The offer could not be created because it already existed.

### `list_offers`

Lists offers. The `from` and `until` parameters are timestamps in seconds since epoch. If `from` is not specified, it defaults to 0.
If `until` is not specified, it defaults to the current time. Offers are returned in descending order of creation time. If none of these
parameters, as well as the "offset" parameter are not used, an offer can also be optionally selected using the `offer_id` parameter.

Request:
```jsonc
{
"method": "list_offers",
"params": {
"from": 1693876973, // starting timestamp in seconds since epoch (inclusive), optional
"until": 1703225078, // ending timestamp in seconds since epoch (inclusive), optional
"limit": 10, // maximum number of invoices to return, optional
"offset": 0, // offset of the first invoice to return, optional
"offer_id": "string", // the id of the offer to get details for, optional
"single_use": false, // whether the offer can only be used once, optional
"used": false // whether the offer has been used, optional
}
}
```

Response:
```jsonc
{
"result_type": "list_offers",
Comment thread
21M4TW marked this conversation as resolved.
"result": {
"offers": [
{
"offer": "lno1pgx...", // encoded offer
"description": "string", // offer's description, optional
"issuer": "string", // offer's issuer, optional
"currency": "ABC", // ISO 4217 code of the currency (3 characters), optional (missing means msat)
"currency_minor_unit": 123, // number of decimals to apply to the amount, for currency different than msat, optional
"amount": 123, // minimum amount value, after adjustment by currency_minor_unit if applicable, optional
"offer_id": "string", // the id of the offer
"single_use": false, // whether the offer can only be used once
"used": false, // whether the offer has been used
"created_at": unixtimestamp, // offer creation time
"expires_at": unixtimestamp // offer absolute expiry time, optional
}
],
},
}
```

### `get_info`

Request:
Expand All @@ -479,7 +602,7 @@ Response:
"network": "string", // mainnet, testnet, signet, or regtest
"block_height": 1,
"block_hash": "hex string",
"methods": ["pay_invoice", "get_balance", "make_invoice", "lookup_invoice", "list_transactions", "get_info"], // list of supported methods for this connection
"methods": ["pay_invoice", "get_balance", "make_invoice", "lookup_invoice", "list_transactions", "pay_offer", "make_offer", "list_offers", "get_offer_info", "get_info"], // list of supported methods for this connection
"notifications": ["payment_received", "payment_sent"], // list of supported notifications for this connection, optional.
}
}
Expand All @@ -501,8 +624,11 @@ Notification:
"invoice": "string", // encoded invoice
"description": "string", // invoice's description, optional
"description_hash": "string", // invoice's description hash, optional
"offer_issuer": "string", // offer's issuer for a bolt12 transaction, optional
"payer_note": "string", // note from payer for a bolt12 transaction, optional
"preimage": "string", // payment's preimage
"payment_hash": "string", // Payment hash for the payment
"offer_id": "string", // the id of the offer, for a bolt12 invoice, optional
"amount": 123, // value in msats
"fees_paid": 123, // value in msats
"created_at": unixtimestamp, // invoice/payment creation time
Expand All @@ -527,6 +653,8 @@ Notification:
"invoice": "string", // encoded invoice
"description": "string", // invoice's description, optional
"description_hash": "string", // invoice's description hash, optional
"offer_issuer": "string", // offer's issuer for a bolt12 transaction, optional
"payer_note": "string", // note from payer for a bolt12 transaction, optional
"preimage": "string", // payment's preimage
"payment_hash": "string", // Payment hash for the payment
"amount": 123, // value in msats
Expand Down