From 51aa4ce53d1a4793d912be3a96de20a40f0b8d1a Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Tue, 10 Jun 2025 22:45:18 -0400 Subject: [PATCH 01/13] Adding support for main bolt12 commands to NIP-47 --- 47.md | 199 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 198 insertions(+), 1 deletion(-) diff --git a/47.md b/47.md index 84f710e2ba..7a56283f99 100644 --- a/47.md +++ b/47.md @@ -413,6 +413,203 @@ Response: } ``` +### `make_offer` + +Request: +```jsonc +{ + "method": "make_offer", + "params": { + "amount": 123, // minimum value in msats, optional + "description": "string", // offer's description, 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 + "amount": 123, // minimum value in msats, optional + "offer_id": "string", // the id of the offer + "active": true, // whether the offer is enabled + "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 + "updated_at": unixtimestamp // offer update time + } +} +``` + +### `lookup_offer` + +Request: +```jsonc +{ + "method": "lookup_offer", + "params": { + "offer_id": "string", // the id of the offer + } +} +``` + +Response: +```jsonc +{ + "result_type": "lookup_offer", + "result": { + "offer": "lno1pgx...", // encoded offer + "description": "string", // offer's description, optional + "amount": 123, // minimum value in msats, optional + "offer_id": "string", // the id of the offer + "active": true, // whether the offer is enabled + "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 + "updated_at": unixtimestamp // offer update time + } +} +``` + +Errors: +- `NOT_FOUND`: The offer could not be found by the given parameters. + +### `enable_offer` + +Request: +```jsonc +{ + "method": "enable_offer", + "params": { + "offer_id": "string", // the id of the offer +} +} +``` + +Response: +```jsonc +{ + "result_type": "enable_offer", + "result": { + "offer_id": "string", // the id of the offer + "active": true, // the offer is enabled, always true +} +} +``` + +Errors: +- `NOT_FOUND`: The offer could not be found by the given parameters. + +### `disable_offer` + +Request: +```jsonc +{ + "method": "disable_offer", + "params": { + "offer_id": "string", // the id of the offer +} +} +``` + +Response: +```jsonc +{ + "result_type": "disable_offer", + "result": { + "offer_id": "string", // the id of the offer + "active": false, // the offer is enable, always false +} +} +``` + +Errors: +- `NOT_FOUND`: The offer could not be found by the given parameters. + +### `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. + +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 + "active": true, // whether the offer is enabled, 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", + "result": { + "offers": [ + { + "offer": "lno1pgx...", // encoded offer + "description": "string", // offer's description, optional + "amount": 123, // minimum value in msats, optional + "offer_id": "string", // the id of the offer + "active": true, // whether the offer is enabled + "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 + "updated_at": unixtimestamp // offer update time + } + ], + }, +} +``` + +### `fetch_invoice` + +Request: +```jsonc +{ + "method": "fetch_invoice", + "params": { + "offer": "lno1pgx...", // encoded offer + "amount": 123, // value in msats, optional + "payer_note": "string", // note to be included in fetched invoice, optional + } +} +``` + +Response: +```jsonc +{ + "result_type": "fetch_invoice", + "result": { + "invoice": "lni1qqg...", // encoded bolt12 invoice + "description": "string", // invoice's description, optional + "description_hash": "string", // invoice's description hash, optional + "payer_note": "string", // note from payer included in fetched invoice, optional + "payment_hash": "string", // Payment hash for the payment + "amount": 123, // value in msats, optional + "offer_id": "string", // the id of the offer + "created_at": unixtimestamp, // invoice/payment creation time + "expires_at": unixtimestamp, // invoice expiration time, optional if not applicable + } +} +``` + +Errors: +- `FETCH_INVOICE_FAILED`: The invoice fetching failed. This may be due to an invalid offer, a timeout, or another issue. + ### `get_info` Request: @@ -434,7 +631,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", "make_offer", "lookup_offer", "enable_offer", "disable_offer", "list_offers", "fetch_invoice", "get_info"], // list of supported methods for this connection "notifications": ["payment_received", "payment_sent"], // list of supported notifications for this connection, optional. } } From 114f8a0358995f55337e3e2b2b6c8a46f8c4febe Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Tue, 10 Jun 2025 23:11:50 -0400 Subject: [PATCH 02/13] -Generalising the description of invoice strings (from bolt11 to bolt11/bolt12) for the existing pay commands --- 47.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/47.md b/47.md index 7a56283f99..06f602de86 100644 --- a/47.md +++ b/47.md @@ -146,7 +146,7 @@ Request: { "method": "pay_invoice", "params": { - "invoice": "lnbc50n1...", // bolt11 invoice + "invoice": "lnbc50n1...", // bolt11/bolt12 invoice "amount": 123, // invoice amount in msats, optional } } @@ -176,7 +176,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/bolt12 invoice and amount in msats, amount is optional {"id":"3da52c32a1", "invoice": "lnbc50n1..."}, ], } From 00acfb4c9896005845fbf31a8e6ba010d7d272aa Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Tue, 17 Jun 2025 09:48:14 -0400 Subject: [PATCH 03/13] -Removing the fetch_invoice command as it is not needed. -Modified the pay_invoice command to supports bolt12 offers as an input -Adding get_offer_info command so decoded info get be retrieved (as only nodes currently support decoding) --- 47.md | 48 ++++++++++++++++++++++++++---------------------- 1 file changed, 26 insertions(+), 22 deletions(-) diff --git a/47.md b/47.md index 06f602de86..7b0211e70b 100644 --- a/47.md +++ b/47.md @@ -146,8 +146,9 @@ Request: { "method": "pay_invoice", "params": { - "invoice": "lnbc50n1...", // bolt11/bolt12 invoice - "amount": 123, // invoice amount in msats, optional + "invoice": "lnbc50n1...", // bolt11 invoice/bolt12 offer + "amount": 123, // invoice amount in msats, optional if the bolt11 invoice or the bolt12 offer contains an amount + "payer_note": "string", // note to be included for a bolt12 invoice, optional } } ``` @@ -176,7 +177,7 @@ Request: "method": "multi_pay_invoice", "params": { "invoices": [ - {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11/bolt12 invoice and amount in msats, amount is optional + {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11 invoice/bolt12 offer and amount in msats, amount is optional {"id":"3da52c32a1", "invoice": "lnbc50n1..."}, ], } @@ -331,6 +332,7 @@ Response: "invoice": "string", // encoded invoice, optional "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, 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 "amount": 123, // value in msats @@ -379,6 +381,7 @@ Response: "invoice": "string", // encoded invoice, optional "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, 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 "amount": 123, // value in msats @@ -441,7 +444,8 @@ Response: "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 - "updated_at": unixtimestamp // offer update time + "updated_at": unixtimestamp, // offer update time + "expires_at": unixtimestamp // offer absolute expiry time, optional } } ``` @@ -471,7 +475,8 @@ Response: "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 - "updated_at": unixtimestamp // offer update time + "updated_at": unixtimestamp, // offer update time + "expires_at": unixtimestamp // offer absolute expiry time, optional } } ``` @@ -568,23 +573,22 @@ Response: "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 - "updated_at": unixtimestamp // offer update time + "updated_at": unixtimestamp, // offer update time + "expires_at": unixtimestamp // offer absolute expiry time, optional } ], }, } ``` -### `fetch_invoice` +### `get_offer_info` Request: ```jsonc { - "method": "fetch_invoice", + "method": "get_offer_info", "params": { - "offer": "lno1pgx...", // encoded offer - "amount": 123, // value in msats, optional - "payer_note": "string", // note to be included in fetched invoice, optional + "offer_id": "string", // the id of the offer } } ``` @@ -592,23 +596,21 @@ Request: Response: ```jsonc { - "result_type": "fetch_invoice", + "result_type": "get_offer_info", "result": { - "invoice": "lni1qqg...", // encoded bolt12 invoice - "description": "string", // invoice's description, optional - "description_hash": "string", // invoice's description hash, optional - "payer_note": "string", // note from payer included in fetched invoice, optional - "payment_hash": "string", // Payment hash for the payment - "amount": 123, // value in msats, optional + "offer": "lno1pgx...", // encoded offer + "description": "string", // offer's description, 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 - "created_at": unixtimestamp, // invoice/payment creation time - "expires_at": unixtimestamp, // invoice expiration time, optional if not applicable + "expires_at": unixtimestamp // offer absolute expiry time, optional } } ``` Errors: -- `FETCH_INVOICE_FAILED`: The invoice fetching failed. This may be due to an invalid offer, a timeout, or another issue. +- `DECODING_FAILED`: The offer could not be decoded by the given parameters. ### `get_info` @@ -631,7 +633,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", "make_offer", "lookup_offer", "enable_offer", "disable_offer", "list_offers", "fetch_invoice", "get_info"], // list of supported methods for this connection + "methods": ["pay_invoice", "get_balance", "make_invoice", "lookup_invoice", "list_transactions", "make_offer", "lookup_offer", "enable_offer", "disable_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. } } @@ -652,6 +654,7 @@ Notification: "invoice": "string", // encoded invoice "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, 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 @@ -677,6 +680,7 @@ Notification: "invoice": "string", // encoded invoice "description": "string", // invoice's description, optional "description_hash": "string", // invoice's description hash, 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 From a155602f253d31e0a6ba5bdf873a1e7136ea48ba Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Tue, 17 Jun 2025 10:13:59 -0400 Subject: [PATCH 04/13] -Adding offer issuer field where applicable --- 47.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/47.md b/47.md index 7b0211e70b..8253252be5 100644 --- a/47.md +++ b/47.md @@ -332,6 +332,7 @@ 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 @@ -381,6 +382,7 @@ 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 @@ -425,6 +427,7 @@ Request: "params": { "amount": 123, // minimum value in msats, 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 } @@ -438,6 +441,7 @@ Response: "result": { "offer": "lno1pgx...", // encoded offer "description": "string", // offer's description, optional + "issuer": "string", // offer's issuer, optional "amount": 123, // minimum value in msats, optional "offer_id": "string", // the id of the offer "active": true, // whether the offer is enabled @@ -469,6 +473,7 @@ Response: "result": { "offer": "lno1pgx...", // encoded offer "description": "string", // offer's description, optional + "issuer": "string", // offer's issuer, optional "amount": 123, // minimum value in msats, optional "offer_id": "string", // the id of the offer "active": true, // whether the offer is enabled @@ -567,6 +572,7 @@ Response: { "offer": "lno1pgx...", // encoded offer "description": "string", // offer's description, optional + "issuer": "string", // offer's issuer, optional "amount": 123, // minimum value in msats, optional "offer_id": "string", // the id of the offer "active": true, // whether the offer is enabled @@ -600,6 +606,7 @@ Response: "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 @@ -654,6 +661,7 @@ 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 @@ -680,6 +688,7 @@ 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 From 3de36b44d5e136b8374f21be3c94158360ca3bbe Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Tue, 17 Jun 2025 10:19:32 -0400 Subject: [PATCH 05/13] -Adding support for other currencies when making and listing offers, for overall consistency. --- 47.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/47.md b/47.md index 8253252be5..f7e5474857 100644 --- a/47.md +++ b/47.md @@ -425,7 +425,9 @@ Request: { "method": "make_offer", "params": { - "amount": 123, // minimum value in msats, 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 "description": "string", // offer's description, optional "issuer": "string", // offer's issuer, optional "absolute_expiry": unixtimestamp, // absolute expiry time of the offer, optional @@ -442,7 +444,9 @@ Response: "offer": "lno1pgx...", // encoded offer "description": "string", // offer's description, optional "issuer": "string", // offer's issuer, optional - "amount": 123, // minimum value in msats, 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 "active": true, // whether the offer is enabled "single_use": false, // whether the offer can only be used once @@ -474,7 +478,9 @@ Response: "offer": "lno1pgx...", // encoded offer "description": "string", // offer's description, optional "issuer": "string", // offer's issuer, optional - "amount": 123, // minimum value in msats, 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 "active": true, // whether the offer is enabled "single_use": false, // whether the offer can only be used once @@ -573,7 +579,9 @@ Response: "offer": "lno1pgx...", // encoded offer "description": "string", // offer's description, optional "issuer": "string", // offer's issuer, optional - "amount": 123, // minimum value in msats, 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 "active": true, // whether the offer is enabled "single_use": false, // whether the offer can only be used once From 1cffc22f8176b2d36ad0fae80b557d17e4cbcef0 Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Tue, 17 Jun 2025 10:34:39 -0400 Subject: [PATCH 06/13] -Adding offer_id field for bolt12 invoices, when applicable. --- 47.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/47.md b/47.md index f7e5474857..7bac463bd0 100644 --- a/47.md +++ b/47.md @@ -336,6 +336,7 @@ Response: "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 @@ -386,6 +387,7 @@ Response: "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 @@ -673,6 +675,7 @@ Notification: "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 From c9938b5696d270a4b908827bd36cb7e2219f0aef Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Tue, 17 Jun 2025 10:49:39 -0400 Subject: [PATCH 07/13] -multi_pay_invoice: -Update description for amount -Adding an optional payer_note field for a bolt12 offer --- 47.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/47.md b/47.md index 7bac463bd0..a152e0a703 100644 --- a/47.md +++ b/47.md @@ -177,7 +177,7 @@ Request: "method": "multi_pay_invoice", "params": { "invoices": [ - {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123}, // bolt11 invoice/bolt12 offer and amount in msats, amount is optional + {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123, "payer_note": "string"}, // bolt11 invoice/bolt12 offer, amount in msats and payer_note, amount is optional if the bolt11 invoice or the bolt12 offer contains an amount, payer_note only applies for bolt12 and is optional {"id":"3da52c32a1", "invoice": "lnbc50n1..."}, ], } From eb3b4b9052e21882e1840f3f81b66c2c69d3b38c Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Fri, 25 Jul 2025 19:53:39 -0400 Subject: [PATCH 08/13] get_offer_info: Fixing the input parameter (offer instead of offer_id). lookup_offer and get_offer_info: Adding descriptions. --- 47.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/47.md b/47.md index a152e0a703..89dc8d14a4 100644 --- a/47.md +++ b/47.md @@ -462,6 +462,8 @@ Response: ### `lookup_offer` +Description: Look for a known offer generated by the wallet service. + Request: ```jsonc { @@ -599,12 +601,14 @@ Response: ### `get_offer_info` +Description: Decode any offer and provide the main offer fields. + Request: ```jsonc { "method": "get_offer_info", "params": { - "offer_id": "string", // the id of the offer + "offer": "lno1pgx...", // encoded offer } } ``` From bcc18d3cbfe8da548b171ea8b94695dadcac252e Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Sat, 26 Jul 2025 15:03:06 -0400 Subject: [PATCH 09/13] -Dropping the lookup_offer method. Integrating the functionality into list_offers -Dropping the updated_at offer field -Dropping the offer_id field from the response of the get_offer_info method. --- 47.md | 49 ++++--------------------------------------------- 1 file changed, 4 insertions(+), 45 deletions(-) diff --git a/47.md b/47.md index 89dc8d14a4..fb4c833b54 100644 --- a/47.md +++ b/47.md @@ -454,51 +454,11 @@ Response: "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 - "updated_at": unixtimestamp, // offer update time "expires_at": unixtimestamp // offer absolute expiry time, optional } } ``` -### `lookup_offer` - -Description: Look for a known offer generated by the wallet service. - -Request: -```jsonc -{ - "method": "lookup_offer", - "params": { - "offer_id": "string", // the id of the offer - } -} -``` - -Response: -```jsonc -{ - "result_type": "lookup_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 - "active": true, // whether the offer is enabled - "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 - "updated_at": unixtimestamp, // offer update time - "expires_at": unixtimestamp // offer absolute expiry time, optional - } -} -``` - -Errors: -- `NOT_FOUND`: The offer could not be found by the given parameters. - ### `enable_offer` Request: @@ -554,8 +514,8 @@ Errors: ### `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 `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 @@ -566,6 +526,7 @@ Request: "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 "active": true, // whether the offer is enabled, optional "single_use": false, // whether the offer can only be used once, optional "used": false // whether the offer has been used, optional @@ -591,7 +552,6 @@ Response: "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 - "updated_at": unixtimestamp, // offer update time "expires_at": unixtimestamp // offer absolute expiry time, optional } ], @@ -624,7 +584,6 @@ Response: "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 "expires_at": unixtimestamp // offer absolute expiry time, optional } } @@ -654,7 +613,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", "make_offer", "lookup_offer", "enable_offer", "disable_offer", "list_offers", "get_offer_info", "get_info"], // list of supported methods for this connection + "methods": ["pay_invoice", "get_balance", "make_invoice", "lookup_invoice", "list_transactions", "make_offer", "enable_offer", "disable_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. } } From 7b743aa885129ff8c22926c4f8598805000aa0b3 Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Mon, 28 Jul 2025 15:42:45 -0400 Subject: [PATCH 10/13] -Splitting the pay_invoice and multi_pay_invoice methods into pay_invoice/pay_offer and multi_pay_invoice/multi_pay_offer methods. --- 47.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 67 insertions(+), 5 deletions(-) diff --git a/47.md b/47.md index fb4c833b54..de6d1aab36 100644 --- a/47.md +++ b/47.md @@ -146,9 +146,8 @@ Request: { "method": "pay_invoice", "params": { - "invoice": "lnbc50n1...", // bolt11 invoice/bolt12 offer - "amount": 123, // invoice amount in msats, optional if the bolt11 invoice or the bolt12 offer contains an amount - "payer_note": "string", // note to be included for a bolt12 invoice, optional + "invoice": "lnbc50n1...", // bolt11 invoice + "amount": 123, // invoice amount in msats, optional if the bolt11 invoice contains an amount } } ``` @@ -177,7 +176,7 @@ Request: "method": "multi_pay_invoice", "params": { "invoices": [ - {"id":"4da52c32a1", "invoice": "lnbc1...", "amount": 123, "payer_note": "string"}, // bolt11 invoice/bolt12 offer, amount in msats and payer_note, amount is optional if the bolt11 invoice or the bolt12 offer contains an amount, payer_note only applies for bolt12 and 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..."}, ], } @@ -420,6 +419,69 @@ 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 + } +} +``` + +Errors: +- `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar. + +### `multi_pay_offer` + +Description: Requests payment for multiple offers. + +Request: +```jsonc +{ + "method": "multi_pay_offefr", + "params": { + "offers": [ + {"id":"4da52c32a1", "offer": "lno1pgx...", "amount": 123, "payer_note": "string"}, // bolt12 offer, amount in msats and payer_note, amount is optional if the bolt12 offer contains an amount, payer_note is optional + {"id":"3da52c32a1", "invoice": "lno50n1..."}, + ], + } +} +``` + +Response: + +For every invoice in the request, a separate response event is sent. To differentiate between the responses, each +response event contains a `d` tag with the id of the invoice it is responding to; if no id was given, then the +payment hash of the invoice should be used. + +```jsonc +{ + "result_type": "multi_pay_offer", + "result": { + "preimage": "0123456789abcdef...", // preimage of the payment + "fees_paid": 123, // value in msats, optional + } +} +``` + ### `make_offer` Request: @@ -613,7 +675,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", "make_offer", "enable_offer", "disable_offer", "list_offers", "get_offer_info", "get_info"], // list of supported methods for this connection + "methods": ["pay_invoice", "get_balance", "make_invoice", "lookup_invoice", "list_transactions", "pay_offer", "make_offer", "enable_offer", "disable_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. } } From 6c69b2cfbdcce18f3b72b6ef96f82b4cd208c0ae Mon Sep 17 00:00:00 2001 From: hodlbod Date: Wed, 12 Nov 2025 08:57:46 -0800 Subject: [PATCH 11/13] Update 47.md --- 47.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/47.md b/47.md index de6d1aab36..aabe63fe9c 100644 --- a/47.md +++ b/47.md @@ -456,7 +456,7 @@ Description: Requests payment for multiple offers. Request: ```jsonc { - "method": "multi_pay_offefr", + "method": "multi_pay_offer", "params": { "offers": [ {"id":"4da52c32a1", "offer": "lno1pgx...", "amount": 123, "payer_note": "string"}, // bolt12 offer, amount in msats and payer_note, amount is optional if the bolt12 offer contains an amount, payer_note is optional From e62d13249df8520e5c924127c9b4961ffb285f49 Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Tue, 18 Nov 2025 10:27:53 -0500 Subject: [PATCH 12/13] -Removing multi_pay_offer as these multi_* methods are not used -Removing get_offer_info so that bolt12 offers are decoded locally --- 47.md | 66 ----------------------------------------------------------- 1 file changed, 66 deletions(-) diff --git a/47.md b/47.md index 5d9cf48cd4..0cd4d589fa 100644 --- a/47.md +++ b/47.md @@ -494,39 +494,6 @@ Response: Errors: - `PAYMENT_FAILED`: The payment failed. This may be due to a timeout, exhausting all routes, insufficient capacity or similar. -### `multi_pay_offer` - -Description: Requests payment for multiple offers. - -Request: -```jsonc -{ - "method": "multi_pay_offer", - "params": { - "offers": [ - {"id":"4da52c32a1", "offer": "lno1pgx...", "amount": 123, "payer_note": "string"}, // bolt12 offer, amount in msats and payer_note, amount is optional if the bolt12 offer contains an amount, payer_note is optional - {"id":"3da52c32a1", "invoice": "lno50n1..."}, - ], - } -} -``` - -Response: - -For every invoice in the request, a separate response event is sent. To differentiate between the responses, each -response event contains a `d` tag with the id of the invoice it is responding to; if no id was given, then the -payment hash of the invoice should be used. - -```jsonc -{ - "result_type": "multi_pay_offer", - "result": { - "preimage": "0123456789abcdef...", // preimage of the payment - "fees_paid": 123, // value in msats, optional - } -} -``` - ### `make_offer` Request: @@ -666,39 +633,6 @@ Response: } ``` -### `get_offer_info` - -Description: Decode any offer and provide the main offer fields. - -Request: -```jsonc -{ - "method": "get_offer_info", - "params": { - "offer": "lno1pgx...", // encoded offer - } -} -``` - -Response: -```jsonc -{ - "result_type": "get_offer_info", - "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 - "expires_at": unixtimestamp // offer absolute expiry time, optional - } -} -``` - -Errors: -- `DECODING_FAILED`: The offer could not be decoded by the given parameters. - ### `get_info` Request: From 5041c0dc319e9a06cd4859961bd3d4a83c4ec0de Mon Sep 17 00:00:00 2001 From: 21M4TW <21m4tw@proton.me> Date: Fri, 5 Dec 2025 20:12:45 -0500 Subject: [PATCH 13/13] -Removing the possibility of activating/disabling an offer. -make_offer: Returning an error if the offer already existed. --- 47.md | 56 ++------------------------------------------------------ 1 file changed, 2 insertions(+), 54 deletions(-) diff --git a/47.md b/47.md index 0cd4d589fa..b0b4d7464b 100644 --- a/47.md +++ b/47.md @@ -524,7 +524,6 @@ Response: "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 - "active": true, // whether the offer is enabled "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 @@ -533,57 +532,8 @@ Response: } ``` -### `enable_offer` - -Request: -```jsonc -{ - "method": "enable_offer", - "params": { - "offer_id": "string", // the id of the offer -} -} -``` - -Response: -```jsonc -{ - "result_type": "enable_offer", - "result": { - "offer_id": "string", // the id of the offer - "active": true, // the offer is enabled, always true -} -} -``` - -Errors: -- `NOT_FOUND`: The offer could not be found by the given parameters. - -### `disable_offer` - -Request: -```jsonc -{ - "method": "disable_offer", - "params": { - "offer_id": "string", // the id of the offer -} -} -``` - -Response: -```jsonc -{ - "result_type": "disable_offer", - "result": { - "offer_id": "string", // the id of the offer - "active": false, // the offer is enable, always false -} -} -``` - Errors: -- `NOT_FOUND`: The offer could not be found by the given parameters. +- `EXISTED_ALREADY`: The offer could not be created because it already existed. ### `list_offers` @@ -601,7 +551,6 @@ Request: "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 - "active": true, // whether the offer is enabled, optional "single_use": false, // whether the offer can only be used once, optional "used": false // whether the offer has been used, optional } @@ -622,7 +571,6 @@ Response: "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 - "active": true, // whether the offer is enabled "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 @@ -654,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", "pay_offer", "make_offer", "enable_offer", "disable_offer", "list_offers", "get_offer_info", "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. } }