From 2bd04954a41489afa66825662dbbe200227b4a9d Mon Sep 17 00:00:00 2001 From: Quentin Date: Tue, 10 Sep 2024 10:41:34 +0200 Subject: [PATCH 01/30] Paid storage --- README.md | 1 + buds/07.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+) create mode 100644 buds/07.md diff --git a/README.md b/README.md index 9c9c85c..7ca334b 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,7 @@ See the [BUDs](./buds) folder and specifically [BUD-01](./buds/01.md) and [BUD-0 - [BUD-02: Blob upload and management](./buds/02.md) - [BUD-03: User Server List](./buds/03.md) - [BUD-04: Mirroring blobs](./buds/04.md) +- [BUD-07: Paid storage](./buds/07.md) ## Event kinds diff --git a/buds/07.md b/buds/07.md new file mode 100644 index 0000000..64a74d5 --- /dev/null +++ b/buds/07.md @@ -0,0 +1,69 @@ +BUD-07 +====== + +Paid storage +--------------- + +`draft` `optional` + +Payment requirements for blob storage. + +## Payment Required + +Some servers **MAY** require payment for file storage. In that case, these endpoints **MUST** return a **402 Payment Required** status code and a `Www-Authenticate` header when the payment is required. + +- [HEAD /upload](./01.md#head-sha256---has-blob) +- [PUT /upload](./02.md#put-upload---upload-blob) +- [HEAT /](./01.md#head-sha256---has-blob) +- [GET /](./01.md#get-sha256---get-blob) + + +## Authenticate header + +The `Www-Authenticate` header is a standard HTTP header field that defines the authentication method that should be used to gain access to a resource. It is used by the server to challenge the client to authenticate itself. Using the [L402 protocol](https://github.com/lightninglabs/L402), the `Www-Authenticate` header can be used to request payment for specific blobs. + +The `Www-Authenticate` header contains the `macaroon` and `invoice` fields for servers and the `macaroon` and `preimage` fields for clients. + +- `macaroon` A base64 encoded string containing the macaroon, see [L402 macaroons](https://github.com/lightninglabs/L402/blob/master/macaroons.md). +- `invoice` A string containing LN the payment request. +- `preimage` A string containing the payment preimage. + +### Server implementation + +Servers **MUST** return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the `macaroon` and `invoice` fields using the [L402 protocol](https://github.com/lightninglabs/L402) for all requests related to the blob: + +Schema: + +```http +HTTP/1.1 402 Payment Required +Www-Authenticate: L402 macaroon="",invoice="" +``` + +Example: + +```http +HTTP/1.1 402 Payment Required +Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",invoice="lnbc30n1pnvscg5pp56rft56xqcdamm59epsvmes06ymctq7gjt3nfnu3mjaw6fmfuhweqhp5w48l28v60yvythn6qvnpq0lez54422a042yaw4kq8arvd68a6n7qcqzzsxqyz5vqsp5a5tz8qqf897a2psdh3gc8m72tkpfwf03p8j95tgvkwm0jx97ypqs9qxpqysgqxuv6h48rzmguqkyxdyegrwf2m9890st2mty7z68acvcp9s8ukpx5daja0tdfq4tn2lmt443kua45zh6dzuy90grz02hcfauqx999g4gpf9lqhw" +``` + +### Client implementation + +Clients `SHOULD` check the `Www-Authenticate` header recieved from the server and display the payment request to the user. If the payment is done, the client `SHOULD` use *the same macaroon* and the payment `preimage`to create a new `Www-Authenticate` header to be used in the next requests. + +Schema: + +```http +Www-Authenticate: L402 macaroon="",preimage="" +``` + +Example: + +```http +Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",preimage="3e590d1336f241e858359c865802b4883ca91d47379c840af66785e2143bad22" +``` + +### Unpaid Uploads + +Some servers `MAY` accept unpaid uploads and require payment after the upload is completed. In this case, the server `MUST` return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the macaroon and payment request fields using the [L402 protocol](https://github.com/lightninglabs/L402) for the endpoints described in [#payment-required](#payment-required). + +For backward compatibility, the server `SHOULD` display a QR code, JSON file, or other useful information instead of the blob in the response body. When the payment is completed, the server `MUST` replace this information with the actual uploaded file. From 17d6814fd0a01b379dbc13be8ad33aa3e3416711 Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Thu, 12 Sep 2024 09:48:05 +0200 Subject: [PATCH 02/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 64a74d5..c9c9023 100644 --- a/buds/07.md +++ b/buds/07.md @@ -48,7 +48,7 @@ Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY ### Client implementation -Clients `SHOULD` check the `Www-Authenticate` header recieved from the server and display the payment request to the user. If the payment is done, the client `SHOULD` use *the same macaroon* and the payment `preimage`to create a new `Www-Authenticate` header to be used in the next requests. +Clients SHOULD check the `Www-Authenticate` header received from the server and display the payment request to the user. When the payment is complete the client should use *the same macaroon* and the payment `preimage` to create a new `Www-Authenticate` header to be used in the next request. Schema: From c3f7a5da0d495cae8bee9aa0c8f3c3f9ae66a552 Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Thu, 12 Sep 2024 09:48:20 +0200 Subject: [PATCH 03/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index c9c9023..9c498b4 100644 --- a/buds/07.md +++ b/buds/07.md @@ -30,7 +30,7 @@ The `Www-Authenticate` header contains the `macaroon` and `invoice` fields for s ### Server implementation -Servers **MUST** return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the `macaroon` and `invoice` fields using the [L402 protocol](https://github.com/lightninglabs/L402) for all requests related to the blob: +Servers MUST return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the `macaroon` and `invoice` fields using the [L402 protocol](https://github.com/lightninglabs/L402) for all requests related to the blob: Schema: From b6bd9b9a943491e93974574f405a4c77c9d48c91 Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Thu, 12 Sep 2024 09:48:26 +0200 Subject: [PATCH 04/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 9c498b4..e712794 100644 --- a/buds/07.md +++ b/buds/07.md @@ -10,7 +10,7 @@ Payment requirements for blob storage. ## Payment Required -Some servers **MAY** require payment for file storage. In that case, these endpoints **MUST** return a **402 Payment Required** status code and a `Www-Authenticate` header when the payment is required. +Some servers MAY require payment for file storage. In that case, these endpoints MUST return a **402 Payment Required** status code and a `Www-Authenticate` header when the payment is required. - [HEAD /upload](./01.md#head-sha256---has-blob) - [PUT /upload](./02.md#put-upload---upload-blob) From f0ac329e9062c20466dd5123c027b7cc3cf3dd49 Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Thu, 12 Sep 2024 09:48:34 +0200 Subject: [PATCH 05/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index e712794..4d5e02b 100644 --- a/buds/07.md +++ b/buds/07.md @@ -64,6 +64,6 @@ Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY ### Unpaid Uploads -Some servers `MAY` accept unpaid uploads and require payment after the upload is completed. In this case, the server `MUST` return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the macaroon and payment request fields using the [L402 protocol](https://github.com/lightninglabs/L402) for the endpoints described in [#payment-required](#payment-required). +Some servers MAY accept unpaid uploads and require payment after the upload is completed. In this case, the server MUST return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the macaroon and payment request fields using the [L402 protocol](https://github.com/lightninglabs/L402) for the endpoints described in [#payment-required](#payment-required). For backward compatibility, the server `SHOULD` display a QR code, JSON file, or other useful information instead of the blob in the response body. When the payment is completed, the server `MUST` replace this information with the actual uploaded file. From 7a57b0c19a8e1e65aecf988b525925664bd729bf Mon Sep 17 00:00:00 2001 From: quentintaranpino Date: Thu, 12 Sep 2024 10:00:58 +0200 Subject: [PATCH 06/30] Backward compatibility proposal --- buds/07.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/buds/07.md b/buds/07.md index 4d5e02b..34feb59 100644 --- a/buds/07.md +++ b/buds/07.md @@ -62,8 +62,6 @@ Example: Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",preimage="3e590d1336f241e858359c865802b4883ca91d47379c840af66785e2143bad22" ``` -### Unpaid Uploads +### Backward compatibility -Some servers MAY accept unpaid uploads and require payment after the upload is completed. In this case, the server MUST return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the macaroon and payment request fields using the [L402 protocol](https://github.com/lightninglabs/L402) for the endpoints described in [#payment-required](#payment-required). - -For backward compatibility, the server `SHOULD` display a QR code, JSON file, or other useful information instead of the blob in the response body. When the payment is completed, the server `MUST` replace this information with the actual uploaded file. +For backward compatibility, when a client requests an unpaid blob, the server `SHOULD` return alternative information, such as a QR code, a JSON file, or other useful data in the response body. This serves as a placeholder, clearly indicating that the actual file is unavailable until payment is made. Once the payment is completed, the server `MUST` replace this placeholder with the actual blob in subsequent requests. This ensures that legacy clients still receive meaningful responses without breaking functionality, while supporting the new payment logic. \ No newline at end of file From 40a7cd943cb42fa43bb833615232a3d54a7f5ee6 Mon Sep 17 00:00:00 2001 From: quentintaranpino Date: Thu, 12 Sep 2024 10:04:30 +0200 Subject: [PATCH 07/30] fix typos --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 34feb59..a9aa3f2 100644 --- a/buds/07.md +++ b/buds/07.md @@ -64,4 +64,4 @@ Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY ### Backward compatibility -For backward compatibility, when a client requests an unpaid blob, the server `SHOULD` return alternative information, such as a QR code, a JSON file, or other useful data in the response body. This serves as a placeholder, clearly indicating that the actual file is unavailable until payment is made. Once the payment is completed, the server `MUST` replace this placeholder with the actual blob in subsequent requests. This ensures that legacy clients still receive meaningful responses without breaking functionality, while supporting the new payment logic. \ No newline at end of file +For backward compatibility, when a client requests an unpaid blob, the server SHOULD return alternative information, such as a QR code, a JSON file, or other useful data in the response body. This serves as a placeholder, clearly indicating that the actual file is unavailable until payment is made. Once the payment is completed, the server MUST replace this placeholder with the actual blob in subsequent requests. This ensures that legacy clients still receive meaningful responses without breaking functionality, while supporting the new payment logic. \ No newline at end of file From cd778dec22d2ef529b7ab46e3bb8531a60a14525 Mon Sep 17 00:00:00 2001 From: quentintaranpino Date: Mon, 16 Sep 2024 09:22:58 +0200 Subject: [PATCH 08/30] change backward compatibility text --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index a9aa3f2..ecc639c 100644 --- a/buds/07.md +++ b/buds/07.md @@ -64,4 +64,4 @@ Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY ### Backward compatibility -For backward compatibility, when a client requests an unpaid blob, the server SHOULD return alternative information, such as a QR code, a JSON file, or other useful data in the response body. This serves as a placeholder, clearly indicating that the actual file is unavailable until payment is made. Once the payment is completed, the server MUST replace this placeholder with the actual blob in subsequent requests. This ensures that legacy clients still receive meaningful responses without breaking functionality, while supporting the new payment logic. \ No newline at end of file +For backward compatibility with image and video uploads, the server MAY return an image or video displaying a QR code or other useful information instead of the original blob. When the payment is completed, the server SHOULD replace this information with the original uploaded blob. \ No newline at end of file From 942fb60e976c83eecd938d950cfc69d67a07ff8c Mon Sep 17 00:00:00 2001 From: Quentin Date: Fri, 1 Nov 2024 10:55:49 +0100 Subject: [PATCH 09/30] Update BUD-07 for multiple L2; discard L402 --- buds/07.md | 93 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 63 insertions(+), 30 deletions(-) diff --git a/buds/07.md b/buds/07.md index ecc639c..0ee6ae9 100644 --- a/buds/07.md +++ b/buds/07.md @@ -10,58 +10,91 @@ Payment requirements for blob storage. ## Payment Required -Some servers MAY require payment for file storage. In that case, these endpoints MUST return a **402 Payment Required** status code and a `Www-Authenticate` header when the payment is required. +Some servers MAY require payment for file storage. In that case, these endpoints MUST return a **402 Payment Required** status code and a `X-Payment` header when the payment is required. - [HEAD /upload](./01.md#head-sha256---has-blob) - [PUT /upload](./02.md#put-upload---upload-blob) - [HEAT /](./01.md#head-sha256---has-blob) - [GET /](./01.md#get-sha256---get-blob) +## Server header -## Authenticate header +The `X-Payment` header is used by the server to inform the client that payment is required for the requested operation, MUST contain the following fields: -The `Www-Authenticate` header is a standard HTTP header field that defines the authentication method that should be used to gain access to a resource. It is used by the server to challenge the client to authenticate itself. Using the [L402 protocol](https://github.com/lightninglabs/L402), the `Www-Authenticate` header can be used to request payment for specific blobs. +- blob: The blob to be paid. +- amount: The amount to be paid (*optional*). +- payment_method: The payment system to be used (e.g., cashu, lightning, liquid). +- payment_details: L2 specific payment details. -The `Www-Authenticate` header contains the `macaroon` and `invoice` fields for servers and the `macaroon` and `preimage` fields for clients. +Each payment method has its own requirements and the server SHOULD provide the necessary information for the client to complete the payment. -- `macaroon` A base64 encoded string containing the macaroon, see [L402 macaroons](https://github.com/lightninglabs/L402/blob/master/macaroons.md). -- `invoice` A string containing LN the payment request. -- `preimage` A string containing the payment preimage. +Example for cashu: -### Server implementation +```json +{ + "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644", + "payment_method": "cashu", + "payment_details": { + "amount": "300", + "mints": "https://example.com", + "unit": "sat", + "pubkey": "0a3bce8b6005175d25432244340912dfa431a0d62681d9720cda9196398d7222" + } +} +``` -Servers MUST return a **402 Payment Required** status code along with a `Www-Authenticate` header containing the `macaroon` and `invoice` fields using the [L402 protocol](https://github.com/lightninglabs/L402) for all requests related to the blob: +Example for lightning: + +```json +{ + "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644", + "amount": "300", + "payment_method": "lightning", + "payment_details": { + "payment_request": "lnbc300n1pw4..:", + } +} + +Example for liquid: + +```json +{ + "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644", + "payment_method": "liquid", + "payment_details": { + "payment_request": { + "address": "VJLgF1s3...", + "asset_id": "6f0279e9ed...", + "amount": 0.000300, + "memo": "test" + } + } +} +``` Schema: ```http HTTP/1.1 402 Payment Required -Www-Authenticate: L402 macaroon="",invoice="" -``` - -Example: - -```http -HTTP/1.1 402 Payment Required -Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",invoice="lnbc30n1pnvscg5pp56rft56xqcdamm59epsvmes06ymctq7gjt3nfnu3mjaw6fmfuhweqhp5w48l28v60yvythn6qvnpq0lez54422a042yaw4kq8arvd68a6n7qcqzzsxqyz5vqsp5a5tz8qqf897a2psdh3gc8m72tkpfwf03p8j95tgvkwm0jx97ypqs9qxpqysgqxuv6h48rzmguqkyxdyegrwf2m9890st2mty7z68acvcp9s8ukpx5daja0tdfq4tn2lmt443kua45zh6dzuy90grz02hcfauqx999g4gpf9lqhw" +X-Payment: "" ``` ### Client implementation -Clients SHOULD check the `Www-Authenticate` header received from the server and display the payment request to the user. When the payment is complete the client should use *the same macaroon* and the payment `preimage` to create a new `Www-Authenticate` header to be used in the next request. +Clients MUST check the `X-Payment` header received from the server and display the payment request to the user. When the payment is complete the client MUST use the same header to inform the server that the payment was successful using this structure: + +- blob: The paid blob. +- payment_proof: The payment proof. (e.g., preimage for cashu and lightning, txid for liquid). + +```json +{ + "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644", + "payment_proof": "c3b9e2..." +} +``` Schema: - + ```http -Www-Authenticate: L402 macaroon="",preimage="" +X-Payment: "" ``` - -Example: - -```http -Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",preimage="3e590d1336f241e858359c865802b4883ca91d47379c840af66785e2143bad22" -``` - -### Backward compatibility - -For backward compatibility with image and video uploads, the server MAY return an image or video displaying a QR code or other useful information instead of the original blob. When the payment is completed, the server SHOULD replace this information with the original uploaded blob. \ No newline at end of file From 5c0ecbb4fab8b4017d867b9523e103ee6965ea34 Mon Sep 17 00:00:00 2001 From: Quentin Date: Tue, 12 Nov 2024 10:01:43 +0100 Subject: [PATCH 10/30] fix typo --- buds/07.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/buds/07.md b/buds/07.md index 0ee6ae9..c76c389 100644 --- a/buds/07.md +++ b/buds/07.md @@ -55,6 +55,8 @@ Example for lightning: } } +``` + Example for liquid: ```json From bf417ae115dd8e735afd5f559478ea69a55b951b Mon Sep 17 00:00:00 2001 From: Quentin Date: Mon, 18 Nov 2024 12:28:43 +0100 Subject: [PATCH 11/30] using different headers for each payment method --- buds/07.md | 148 +++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 105 insertions(+), 43 deletions(-) diff --git a/buds/07.md b/buds/07.md index c76c389..880c04a 100644 --- a/buds/07.md +++ b/buds/07.md @@ -10,93 +10,155 @@ Payment requirements for blob storage. ## Payment Required -Some servers MAY require payment for file storage. In that case, these endpoints MUST return a **402 Payment Required** status code and a `X-Payment` header when the payment is required. +Some servers MAY require payment for file storage. In such cases, these endpoints MUST return a **402 Payment Required** status code: -- [HEAD /upload](./01.md#head-sha256---has-blob) +- [HEAD /upload](./01.md#head-sha256---has-blob) (Optional, if [BU-06](./06.md) is implemented) - [PUT /upload](./02.md#put-upload---upload-blob) - [HEAT /](./01.md#head-sha256---has-blob) - [GET /](./01.md#get-sha256---get-blob) -## Server header +When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method. -The `X-Payment` header is used by the server to inform the client that payment is required for the requested operation, MUST contain the following fields: +## Server headers -- blob: The blob to be paid. -- amount: The amount to be paid (*optional*). -- payment_method: The payment system to be used (e.g., cashu, lightning, liquid). -- payment_details: L2 specific payment details. +The `X-{payment_method}` header is used by the server to inform the client that payment is required for the requested operation. The server MUST provide specific headers for each supported payment method, using the following conventions: -Each payment method has its own requirements and the server SHOULD provide the necessary information for the client to complete the payment. +- `X-{payment_method}`: Base64 UrlSafe encoded JSON with the payment details. + +Supported payment methods: + +- `X-Cashu`: Payment details for the cashu payment method. +- `X-Lightning`: Payment details for the lightning payment method. + +If a server supports multiple payment methods, it MAY send multiple `X-{payment_method}` headers in the same response. The client MUST choose one of the provided methods and proceed with the payment accordingly. + +### `X-Cashu` Header + +Fields included in the X-Cashu header: + +- identifier: The unique identifier for the payment. +- amount: The amount of ecash being requested +- mints: An array of mints that this server uses +- unit: The cashu `unit` from the `mints` +- pubkey: (optional) a 33 byte pubkey to lock the tokens too. see [NUT-11](https://github.com/cashubtc/nuts/blob/main/11.md) + +The `identifier` field is a unique reference to a specific payment request. It allows the server to distinguish between different payments for the same file or blob. The server MUST ensure that each identifier is unique and link it internally to the relevant file or blob. Example for cashu: ```json { - "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644", - "payment_method": "cashu", - "payment_details": { - "amount": "300", - "mints": "https://example.com", - "unit": "sat", - "pubkey": "0a3bce8b6005175d25432244340912dfa431a0d62681d9720cda9196398d7222" - } + "identifier": "23537", + "amount": "300", + "mints": ["https://example.com", "https://example2.com"], + "unit": "sat", + "pubkey": "0a3bce8b6005175d25432244340912dfa431a0d62681d9720cda9196398d7222" } ``` +```http +HTTP/1.1 402 Payment Required +X-Cashu: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAiYW1vdW50IjogIjMwMCIsCiAgIm1pbnRzIjogWyJodHRwczovL2V4YW1wbGUuY29tIiwgImh0dHBzOi8vZXhhbXBsZTIuY29tIl0sCiAgInVuaXQiOiAic2F0IiwKICAicHVia2V5IjogIjBhM2JjZThiNjAwNTE3NWQyNTQzMjI0NDM0MDkxMmRmYTQzMWEwZDYyNjgxZDk3MjBjZGE5MTk2Mzk4ZDcyMjIiCn0 +``` + +### `X-Lightning` Header + +Fields included in the X-Lightning header: + +- identifier: The unique identifier for the payment. +- amount: The amount to be paid. +- payment_request: The lightning payment request. + +The `identifier` field is a unique reference to a specific payment request. It allows the server to distinguish between different payments for the same file or blob. The server MUST ensure that each identifier is unique and link it internally to the relevant file or blob. + Example for lightning: ```json { - "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644", + "identifier": "23537", "amount": "300", - "payment_method": "lightning", - "payment_details": { - "payment_request": "lnbc300n1pw4..:", - } + "payment_request": "lnbc300n1pw4..:", } ``` -Example for liquid: - -```json -{ - "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644", - "payment_method": "liquid", - "payment_details": { - "payment_request": { - "address": "VJLgF1s3...", - "asset_id": "6f0279e9ed...", - "amount": 0.000300, - "memo": "test" - } - } -} +```http +HTTP/1.1 402 Payment Required +X-Lightning: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAiYW1vdW50IjogIjMwMCIsCiAgInBheW1lbnRfcmVxdWVzdCI6ICJsbmJjMzAwbjFwdzQuLjoiLAp9 ``` Schema: ```http HTTP/1.1 402 Payment Required -X-Payment: "" +X-Payment-{payment_method}: "" ``` + ### Client implementation -Clients MUST check the `X-Payment` header received from the server and display the payment request to the user. When the payment is complete the client MUST use the same header to inform the server that the payment was successful using this structure: +Clients MUST parse and validate all available `X-{payment_method}` headers received from the server. The client SHOULD provide a way for the user to complete the payment and retry the request using the appropiate `X-Payment-{payment_method}` header. -- blob: The paid blob. -- payment_proof: The payment proof. (e.g., preimage for cashu and lightning, txid for liquid). +- `X-{payment_method}-Payment`: Base64 UrlSafe encoded JSON with the client payment proof. + +- identifier: The unique identifier for the payment. +- payment_proof: The proof of payment, specific to the method: + + - For cashu the payment should be a serialized cashu token according to [NUT-00](https://github.com/cashubtc/nuts/blob/main/00.md#v4-tokens) + - For lightning the payment should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) + +Example for Cashu: ```json { - "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644", + "identifier": "23537", "payment_proof": "c3b9e2..." } + +```http +X-Cashu-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJjM2I5ZTIiCn0 +``` + +Example for Lightning: + +```json +{ + "identifier": "23537", + "payment_proof": "lnbc300n1pw4..." +} + +```http +X-Lightning-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJsbmJjMzAwbjFwdzQuLjoiCn0 ``` Schema: ```http -X-Payment: "" +X-{payment_method}-Payment: "" ``` + +### Error handling + +If the client fails to provide the payment proof (expired invoice, invalid token, etc.) the server MUST respond with **402 Payment Required** status code and include the relevant `X-{payment_method}` header(s) with updated payment details. + + +### Extending with Future Payment Methods + +To support future payment methods (e.g., other Layer 2 solutions), the specification allows the addition of new X-{payment_method} headers. Each new method MUST adhere to the following: + +Header Format: + +New methods MUST use a unique `X-{payment_method}` header containing Base64 UrlSafe encoded JSON. + +Required Fields: + +- identifier: Unique reference for the payment. +- amount: Payment amount in the method’s smallest unit. + +Backward Compatibility: + +Servers and clients MUST ignore unknown X-{payment_method} headers. + +Documentation: + +Any new payment method added in the future MUST follow the same structure as existing methods, ensuring that the `identifier` and `amount` fields are always present and well-defined. This consistency allows seamless integration of new methods without breaking compatibility for existing clients and servers. From 3524b81baca9052a33dcff091ad3ed849afbf427 Mon Sep 17 00:00:00 2001 From: Quentin Date: Mon, 18 Nov 2024 12:37:37 +0100 Subject: [PATCH 12/30] fix typos --- buds/07.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/buds/07.md b/buds/07.md index 880c04a..33f13c0 100644 --- a/buds/07.md +++ b/buds/07.md @@ -12,7 +12,7 @@ Payment requirements for blob storage. Some servers MAY require payment for file storage. In such cases, these endpoints MUST return a **402 Payment Required** status code: -- [HEAD /upload](./01.md#head-sha256---has-blob) (Optional, if [BU-06](./06.md) is implemented) +- [HEAD /upload](./01.md#head-sha256---has-blob) (Optional, if [BUD-06](./06.md) is implemented) - [PUT /upload](./02.md#put-upload---upload-blob) - [HEAT /](./01.md#head-sha256---has-blob) - [GET /](./01.md#get-sha256---get-blob) @@ -36,11 +36,11 @@ If a server supports multiple payment methods, it MAY send multiple `X-{payment_ Fields included in the X-Cashu header: -- identifier: The unique identifier for the payment. -- amount: The amount of ecash being requested -- mints: An array of mints that this server uses -- unit: The cashu `unit` from the `mints` -- pubkey: (optional) a 33 byte pubkey to lock the tokens too. see [NUT-11](https://github.com/cashubtc/nuts/blob/main/11.md) +- `identifier`: The unique identifier for the payment. +- `amount`: The amount of ecash being requested +- `mints`: An array of mints that this server uses +- `unit`: The cashu `unit` from the `mints` +- `pubkey`: (optional) a 33 byte pubkey to lock the tokens too. see [NUT-11](https://github.com/cashubtc/nuts/blob/main/11.md) The `identifier` field is a unique reference to a specific payment request. It allows the server to distinguish between different payments for the same file or blob. The server MUST ensure that each identifier is unique and link it internally to the relevant file or blob. @@ -65,9 +65,9 @@ X-Cashu: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAiYW1vdW50IjogIjMwMCIsCiAgIm1pbnR Fields included in the X-Lightning header: -- identifier: The unique identifier for the payment. -- amount: The amount to be paid. -- payment_request: The lightning payment request. +- `identifier`: The unique identifier for the payment. +- `amount`: The amount to be paid. +- `payment_request`: The lightning payment request. The `identifier` field is a unique reference to a specific payment request. It allows the server to distinguish between different payments for the same file or blob. The server MUST ensure that each identifier is unique and link it internally to the relevant file or blob. @@ -101,8 +101,8 @@ Clients MUST parse and validate all available `X-{payment_method}` headers recei - `X-{payment_method}-Payment`: Base64 UrlSafe encoded JSON with the client payment proof. -- identifier: The unique identifier for the payment. -- payment_proof: The proof of payment, specific to the method: +- `identifier`: The unique identifier for the payment. +- `payment_proof`: The proof of payment, specific to the method: - For cashu the payment should be a serialized cashu token according to [NUT-00](https://github.com/cashubtc/nuts/blob/main/00.md#v4-tokens) - For lightning the payment should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) @@ -114,6 +114,7 @@ Example for Cashu: "identifier": "23537", "payment_proof": "c3b9e2..." } +``` ```http X-Cashu-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJjM2I5ZTIiCn0 @@ -152,8 +153,8 @@ New methods MUST use a unique `X-{payment_method}` header containing Base64 UrlS Required Fields: -- identifier: Unique reference for the payment. -- amount: Payment amount in the method’s smallest unit. +- `identifier`: Unique reference for the payment. +- `amount`: Payment amount in the method’s smallest unit. Backward Compatibility: From b450680b00b79544f648301b33ec13d7ae2aaf73 Mon Sep 17 00:00:00 2001 From: Quentin Date: Mon, 18 Nov 2024 12:39:10 +0100 Subject: [PATCH 13/30] fix typo --- buds/07.md | 1 + 1 file changed, 1 insertion(+) diff --git a/buds/07.md b/buds/07.md index 33f13c0..071f6e9 100644 --- a/buds/07.md +++ b/buds/07.md @@ -127,6 +127,7 @@ Example for Lightning: "identifier": "23537", "payment_proof": "lnbc300n1pw4..." } +``` ```http X-Lightning-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJsbmJjMzAwbjFwdzQuLjoiCn0 From 8a4728e3e6085157867be9562832561dff1d9372 Mon Sep 17 00:00:00 2001 From: Quentin Date: Mon, 18 Nov 2024 12:41:43 +0100 Subject: [PATCH 14/30] remove some texts --- buds/07.md | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/buds/07.md b/buds/07.md index 071f6e9..37355f9 100644 --- a/buds/07.md +++ b/buds/07.md @@ -148,19 +148,9 @@ If the client fails to provide the payment proof (expired invoice, invalid token To support future payment methods (e.g., other Layer 2 solutions), the specification allows the addition of new X-{payment_method} headers. Each new method MUST adhere to the following: -Header Format: - New methods MUST use a unique `X-{payment_method}` header containing Base64 UrlSafe encoded JSON. -Required Fields: +**Required Fields:** - `identifier`: Unique reference for the payment. -- `amount`: Payment amount in the method’s smallest unit. - -Backward Compatibility: - -Servers and clients MUST ignore unknown X-{payment_method} headers. - -Documentation: - -Any new payment method added in the future MUST follow the same structure as existing methods, ensuring that the `identifier` and `amount` fields are always present and well-defined. This consistency allows seamless integration of new methods without breaking compatibility for existing clients and servers. +- `amount`: Payment amount in the method’s smallest unit. \ No newline at end of file From 970fc2b072818d8b10ec892262ec991412eefed1 Mon Sep 17 00:00:00 2001 From: Quentin Date: Mon, 18 Nov 2024 12:41:51 +0100 Subject: [PATCH 15/30] fix typo --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 37355f9..3876e9b 100644 --- a/buds/07.md +++ b/buds/07.md @@ -153,4 +153,4 @@ New methods MUST use a unique `X-{payment_method}` header containing Base64 UrlS **Required Fields:** - `identifier`: Unique reference for the payment. -- `amount`: Payment amount in the method’s smallest unit. \ No newline at end of file +- `amount`: Payment amount in the method’s smallest unit. From 0aa5a9dd6f033ce5be4bbc29663ac4e5e255500b Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 20 Nov 2024 12:14:00 +0100 Subject: [PATCH 16/30] Refactored to clarify payment header encoding and method-specific requirements --- buds/07.md | 114 +++++++++++++---------------------------------------- 1 file changed, 28 insertions(+), 86 deletions(-) diff --git a/buds/07.md b/buds/07.md index 3876e9b..aad8b53 100644 --- a/buds/07.md +++ b/buds/07.md @@ -17,140 +17,82 @@ Some servers MAY require payment for file storage. In such cases, these endpoint - [HEAT /](./01.md#head-sha256---has-blob) - [GET /](./01.md#get-sha256---get-blob) -When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method. +When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method. The client MUST choose one of the provided methods and proceed with the payment accordingly. ## Server headers The `X-{payment_method}` header is used by the server to inform the client that payment is required for the requested operation. The server MUST provide specific headers for each supported payment method, using the following conventions: -- `X-{payment_method}`: Base64 UrlSafe encoded JSON with the payment details. - Supported payment methods: -- `X-Cashu`: Payment details for the cashu payment method. -- `X-Lightning`: Payment details for the lightning payment method. +- `X-Cashu`: Payment details for the cashu payment method, adhering to the [NUT-18](https://github.com/cashubtc/nuts/blob/main/18.md) standard. +- `X-Lightning`: Payment details for the lightning payment method, adhering to the [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) standard. If a server supports multiple payment methods, it MAY send multiple `X-{payment_method}` headers in the same response. The client MUST choose one of the provided methods and proceed with the payment accordingly. +Schema: + +```http +HTTP/1.1 402 Payment Required +X-Payment-{payment_method}: "" +``` + ### `X-Cashu` Header -Fields included in the X-Cashu header: - -- `identifier`: The unique identifier for the payment. -- `amount`: The amount of ecash being requested -- `mints`: An array of mints that this server uses -- `unit`: The cashu `unit` from the `mints` -- `pubkey`: (optional) a 33 byte pubkey to lock the tokens too. see [NUT-11](https://github.com/cashubtc/nuts/blob/main/11.md) - -The `identifier` field is a unique reference to a specific payment request. It allows the server to distinguish between different payments for the same file or blob. The server MUST ensure that each identifier is unique and link it internally to the relevant file or blob. +When using the X-Cashu header, the server MUST adhere to the [NUT-18](https://github.com/cashubtc/nuts/blob/main/18.md) standard. Example for cashu: -```json -{ - "identifier": "23537", - "amount": "300", - "mints": ["https://example.com", "https://example2.com"], - "unit": "sat", - "pubkey": "0a3bce8b6005175d25432244340912dfa431a0d62681d9720cda9196398d7222" -} -``` - ```http HTTP/1.1 402 Payment Required -X-Cashu: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAiYW1vdW50IjogIjMwMCIsCiAgIm1pbnRzIjogWyJodHRwczovL2V4YW1wbGUuY29tIiwgImh0dHBzOi8vZXhhbXBsZTIuY29tIl0sCiAgInVuaXQiOiAic2F0IiwKICAicHVia2V5IjogIjBhM2JjZThiNjAwNTE3NWQyNTQzMjI0NDM0MDkxMmRmYTQzMWEwZDYyNjgxZDk3MjBjZGE5MTk2Mzk4ZDcyMjIiCn0 +X-Cashu: creqApWF0gaNhdGVub3N0cmFheKlucHJvZmlsZTFxeTI4d3VtbjhnaGo3dW45ZDNzaGp0bnl2OWtoMnVld2Q5aHN6OW1od2RlbjV0ZTB3ZmprY2N0ZTljdXJ4dmVuOWVlaHFjdHJ2NWhzenJ0aHdkZW41dGUwZGVoaHh0bnZkYWtxcWd5ZGFxeTdjdXJrNDM5eWtwdGt5c3Y3dWRoZGh1NjhzdWNtMjk1YWtxZWZkZWhrZjBkNDk1Y3d1bmw1YWeBgmFuYjE3YWloYjdhOTAxNzZhYQphdWNzYXRhbYF4Imh0dHBzOi8vbm9mZWVzLnRlc3RudXQuY2FzaHUuc3BhY2U ``` ### `X-Lightning` Header -Fields included in the X-Lightning header: - -- `identifier`: The unique identifier for the payment. -- `amount`: The amount to be paid. -- `payment_request`: The lightning payment request. - -The `identifier` field is a unique reference to a specific payment request. It allows the server to distinguish between different payments for the same file or blob. The server MUST ensure that each identifier is unique and link it internally to the relevant file or blob. - +When using the X-Lightning header, the server MUST adhere to the [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) standard. Example for lightning: -```json -{ - "identifier": "23537", - "amount": "300", - "payment_request": "lnbc300n1pw4..:", -} - -``` - ```http HTTP/1.1 402 Payment Required -X-Lightning: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAiYW1vdW50IjogIjMwMCIsCiAgInBheW1lbnRfcmVxdWVzdCI6ICJsbmJjMzAwbjFwdzQuLjoiLAp9 +X-Lightning: lnbc30n1pnnmw3lpp57727jjq8zxctahfavqacymellq56l70f7lwfkmhxfjva6dgul2zqhp5w48l28v60yvythn6qvnpq0lez54422a042yaw4kq8arvd68a6n7qcqzzsxqyz5vqsp5sqezejdfaxx5hge83tf59a50h6gagwah59fjn9mw2d5mn278jkys9qxpqysgqt2q2lhjl9kgfaqz864mhlsspftzdyr642lf3zdt6ljqj6wmathdhtgcn0e6f4ym34jl0qkt6gwnllygvzkhdlpq64c6yv3rta2hyzlqp8k28pz ``` -Schema: - -```http -HTTP/1.1 402 Payment Required -X-Payment-{payment_method}: "" -``` - - ### Client implementation -Clients MUST parse and validate all available `X-{payment_method}` headers received from the server. The client SHOULD provide a way for the user to complete the payment and retry the request using the appropiate `X-Payment-{payment_method}` header. +Clients MUST parse and validate all available `X-{payment_method}` headers received from the server. The client SHOULD provide a way for the user to complete the payment and retry the request using the same `X-{payment_method}` header. -- `X-{payment_method}-Payment`: Base64 UrlSafe encoded JSON with the client payment proof. +The client MUST provide the payment proof in the request headers using the same `X-{payment_method}` header that was chosen. The payment proof MUST aling with the payment method specification: -- `identifier`: The unique identifier for the payment. -- `payment_proof`: The proof of payment, specific to the method: - - - For cashu the payment should be a serialized cashu token according to [NUT-00](https://github.com/cashubtc/nuts/blob/main/00.md#v4-tokens) - - For lightning the payment should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) +- For cashu the payment proof should be a serialized cashu token according to [NUT-00](https://github.com/cashubtc/nuts/blob/main/00.md#v4-tokens) +- For lightning the payment proof should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) + +Schema: + +```http +X-{payment_method}: "" +``` Example for Cashu: -```json -{ - "identifier": "23537", - "payment_proof": "c3b9e2..." -} -``` - ```http -X-Cashu-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJjM2I5ZTIiCn0 +X-Cashu: cashuBo2F0gqJhaUgA_9SLj17PgGFwgaNhYQFhc3hAYWNjMTI0MzVlN2I4NDg0YzNjZjE4NTAxNDkyMThhZjkwZjcxNmE1MmJmNGE1ZWQzNDdlNDhlY2MxM2Y3NzM4OGFjWCECRFODGd5IXVW ``` Example for Lightning: -```json -{ - "identifier": "23537", - "payment_proof": "lnbc300n1pw4..." -} -``` - ```http -X-Lightning-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJsbmJjMzAwbjFwdzQuLjoiCn0 -``` - -Schema: - -```http -X-{payment_method}-Payment: "" +X-Lightning: "966fcb8f153339372f9a187f725384ff4ceae0047c25b9ce607488d7c7e93bba" ``` ### Error handling If the client fails to provide the payment proof (expired invoice, invalid token, etc.) the server MUST respond with **402 Payment Required** status code and include the relevant `X-{payment_method}` header(s) with updated payment details. - ### Extending with Future Payment Methods To support future payment methods (e.g., other Layer 2 solutions), the specification allows the addition of new X-{payment_method} headers. Each new method MUST adhere to the following: -New methods MUST use a unique `X-{payment_method}` header containing Base64 UrlSafe encoded JSON. +New methods MUST use a unique `X-{payment_method}` header containing the specific payment details. -**Required Fields:** - -- `identifier`: Unique reference for the payment. -- `amount`: Payment amount in the method’s smallest unit. +New methods MUST adhere their own specification, which MUST be publicly available and linked in the header. From 8600dbecfc44f89b21cd08cfeae9215a67bd6bfa Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 20 Nov 2024 12:35:18 +0100 Subject: [PATCH 17/30] Recurring payments. --- buds/07.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/buds/07.md b/buds/07.md index aad8b53..19d6293 100644 --- a/buds/07.md +++ b/buds/07.md @@ -85,6 +85,18 @@ Example for Lightning: X-Lightning: "966fcb8f153339372f9a187f725384ff4ceae0047c25b9ce607488d7c7e93bba" ``` +### Recurring Payments + +Servers MAY accept recurring payments for blob storage using the following Nostr event types: + +- **Cashu**: Using [NIP-61](https://github.com/nostr-protocol/nips/blob/master/61.md) for details. + +- **Lightning**: Using [NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md) for details. + +The event MUST include a custom `x` tag containing the hash of the blob being paid for. + +- `x`: A string that represents the blob's SHA-256 hash. + ### Error handling If the client fails to provide the payment proof (expired invoice, invalid token, etc.) the server MUST respond with **402 Payment Required** status code and include the relevant `X-{payment_method}` header(s) with updated payment details. @@ -96,3 +108,5 @@ To support future payment methods (e.g., other Layer 2 solutions), the specifica New methods MUST use a unique `X-{payment_method}` header containing the specific payment details. New methods MUST adhere their own specification, which MUST be publicly available and linked in the header. + +New methods MAY have a Nostr event type for recurring payments, which MUST be linked in the Recurring Payments section. From e003b22318a3ff9533944f961baea47c83118002 Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 20 Nov 2024 12:40:39 +0100 Subject: [PATCH 18/30] Fix typos. --- buds/07.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/buds/07.md b/buds/07.md index 19d6293..227e4ba 100644 --- a/buds/07.md +++ b/buds/07.md @@ -21,7 +21,7 @@ When payment is required, the server MUST include one or more `X-{payment_method ## Server headers -The `X-{payment_method}` header is used by the server to inform the client that payment is required for the requested operation. The server MUST provide specific headers for each supported payment method, using the following conventions: +The `X-{payment_method}` header is used by the server to inform the client that payment is required for the requested operation. The server MUST provide specific headers for each supported payment method. Supported payment methods: @@ -64,9 +64,9 @@ Clients MUST parse and validate all available `X-{payment_method}` headers recei The client MUST provide the payment proof in the request headers using the same `X-{payment_method}` header that was chosen. The payment proof MUST aling with the payment method specification: -- For cashu the payment proof should be a serialized cashu token according to [NUT-00](https://github.com/cashubtc/nuts/blob/main/00.md#v4-tokens) -- For lightning the payment proof should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) - +- For cashu the payment proof should be a serialized cashu token according to [NUT-00](https://github.com/cashubtc/nuts/blob/main/00.md#v4-tokens). +- For lightning the payment proof should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md). + Schema: ```http @@ -89,9 +89,9 @@ X-Lightning: "966fcb8f153339372f9a187f725384ff4ceae0047c25b9ce607488d7c7e93bba" Servers MAY accept recurring payments for blob storage using the following Nostr event types: -- **Cashu**: Using [NIP-61](https://github.com/nostr-protocol/nips/blob/master/61.md) for details. +- **Cashu**: Using [NIP-61](https://github.com/nostr-protocol/nips/blob/master/61.md) standard. -- **Lightning**: Using [NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md) for details. +- **Lightning**: Using [NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md) standard. The event MUST include a custom `x` tag containing the hash of the blob being paid for. From cda53cf47afb31d2747fead6fef8a8ab1e6e85a5 Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Wed, 20 Nov 2024 16:25:33 +0100 Subject: [PATCH 19/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 227e4ba..6e539de 100644 --- a/buds/07.md +++ b/buds/07.md @@ -17,7 +17,7 @@ Some servers MAY require payment for file storage. In such cases, these endpoint - [HEAT /](./01.md#head-sha256---has-blob) - [GET /](./01.md#get-sha256---get-blob) -When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method. The client MUST choose one of the provided methods and proceed with the payment accordingly. +When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method. ## Server headers From 0d039843a0989af58756d2cb92e5ddeb9994b42f Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Wed, 20 Nov 2024 16:25:58 +0100 Subject: [PATCH 20/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 6e539de..8c180c5 100644 --- a/buds/07.md +++ b/buds/07.md @@ -21,7 +21,7 @@ When payment is required, the server MUST include one or more `X-{payment_method ## Server headers -The `X-{payment_method}` header is used by the server to inform the client that payment is required for the requested operation. The server MUST provide specific headers for each supported payment method. +The 402 status code and `X-{payment_method}` header is used by the server to inform the client that a payment is required for the requested operation. The server MUST provide specific headers for each supported payment method. Supported payment methods: From ffe55bbffcce6413ab8b95325911cfba9bd31783 Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Wed, 20 Nov 2024 16:26:17 +0100 Subject: [PATCH 21/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 8c180c5..4a8b7f3 100644 --- a/buds/07.md +++ b/buds/07.md @@ -28,7 +28,7 @@ Supported payment methods: - `X-Cashu`: Payment details for the cashu payment method, adhering to the [NUT-18](https://github.com/cashubtc/nuts/blob/main/18.md) standard. - `X-Lightning`: Payment details for the lightning payment method, adhering to the [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) standard. -If a server supports multiple payment methods, it MAY send multiple `X-{payment_method}` headers in the same response. The client MUST choose one of the provided methods and proceed with the payment accordingly. +If a server supports multiple payment methods, it MAY send multiple `X-{payment_method}` headers in the same response. Schema: From 8f95ad746819281d1d772cc5172a841fcb59b58a Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Wed, 20 Nov 2024 16:27:35 +0100 Subject: [PATCH 22/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 4a8b7f3..62fb9fe 100644 --- a/buds/07.md +++ b/buds/07.md @@ -1,7 +1,7 @@ BUD-07 ====== -Paid storage +Paid upload and download --------------- `draft` `optional` From 38274c6a5e263f59dd415b8eb49bbf22f69b0a42 Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Wed, 20 Nov 2024 16:28:13 +0100 Subject: [PATCH 23/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 62fb9fe..c414721 100644 --- a/buds/07.md +++ b/buds/07.md @@ -14,7 +14,7 @@ Some servers MAY require payment for file storage. In such cases, these endpoint - [HEAD /upload](./01.md#head-sha256---has-blob) (Optional, if [BUD-06](./06.md) is implemented) - [PUT /upload](./02.md#put-upload---upload-blob) -- [HEAT /](./01.md#head-sha256---has-blob) +- [HEAD /](./01.md#head-sha256---has-blob) - [GET /](./01.md#get-sha256---get-blob) When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method. From f9f44fc592c1407b836ea94ced6a6a829e48a77b Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Wed, 20 Nov 2024 16:32:04 +0100 Subject: [PATCH 24/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index c414721..bb07c09 100644 --- a/buds/07.md +++ b/buds/07.md @@ -62,7 +62,7 @@ X-Lightning: lnbc30n1pnnmw3lpp57727jjq8zxctahfavqacymellq56l70f7lwfkmhxfjva6dgul Clients MUST parse and validate all available `X-{payment_method}` headers received from the server. The client SHOULD provide a way for the user to complete the payment and retry the request using the same `X-{payment_method}` header. -The client MUST provide the payment proof in the request headers using the same `X-{payment_method}` header that was chosen. The payment proof MUST aling with the payment method specification: +The client MUST provide the payment proof when re-trying the request using the same `X-{payment_method}` header that was chosen. The payment proof MUST align with the payment method specification: - For cashu the payment proof should be a serialized cashu token according to [NUT-00](https://github.com/cashubtc/nuts/blob/main/00.md#v4-tokens). - For lightning the payment proof should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md). From 73fcfbfbd3c399915ece48ca9941a8a64c945d42 Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 20 Nov 2024 20:57:46 +0100 Subject: [PATCH 25/30] update BUD-07 --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index bb07c09..516c093 100644 --- a/buds/07.md +++ b/buds/07.md @@ -60,7 +60,7 @@ X-Lightning: lnbc30n1pnnmw3lpp57727jjq8zxctahfavqacymellq56l70f7lwfkmhxfjva6dgul ### Client implementation -Clients MUST parse and validate all available `X-{payment_method}` headers received from the server. The client SHOULD provide a way for the user to complete the payment and retry the request using the same `X-{payment_method}` header. +Clients MUST parse and validate the `X-{payment_method}` header received from the server. The client SHOULD provide a way for the user to complete the payment and retry the request using the same `X-{payment_method}` header. The client MUST provide the payment proof when re-trying the request using the same `X-{payment_method}` header that was chosen. The payment proof MUST align with the payment method specification: From 463f28da7b879be42e4948eb60c7b4e9ee9f131c Mon Sep 17 00:00:00 2001 From: Quentin Date: Wed, 20 Nov 2024 21:22:20 +0100 Subject: [PATCH 26/30] error handling 402->400. Special note for Head requests --- buds/07.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 516c093..8b5dde3 100644 --- a/buds/07.md +++ b/buds/07.md @@ -85,6 +85,10 @@ Example for Lightning: X-Lightning: "966fcb8f153339372f9a187f725384ff4ceae0047c25b9ce607488d7c7e93bba" ``` +**Special Note on HEAD Requests** + +The HEAD endpoints are only used to retrieve blob or server information. They MUST NOT be retried with payment proof. Instead, clients should complete the payment and proceed with the `PUT` or `GET` request. + ### Recurring Payments Servers MAY accept recurring payments for blob storage using the following Nostr event types: @@ -99,7 +103,7 @@ The event MUST include a custom `x` tag containing the hash of the blob being pa ### Error handling -If the client fails to provide the payment proof (expired invoice, invalid token, etc.) the server MUST respond with **402 Payment Required** status code and include the relevant `X-{payment_method}` header(s) with updated payment details. +If the client fails to provide the payment proof (expired invoice, invalid token, etc.) the server MUST respond with **400 Bad request** status code and include a `X-Reason` header with a human-readable message. The client SHOULD inform the user about the error and provide a way to retry the request. ### Extending with Future Payment Methods From 4d9b22a96c3c8ed76bb6001a7898d4c864fcdb0d Mon Sep 17 00:00:00 2001 From: quentintaranpino Date: Tue, 3 Dec 2024 13:03:23 +0100 Subject: [PATCH 27/30] remove recurring payments --- buds/07.md | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/buds/07.md b/buds/07.md index 8b5dde3..8b4bb3e 100644 --- a/buds/07.md +++ b/buds/07.md @@ -89,18 +89,6 @@ X-Lightning: "966fcb8f153339372f9a187f725384ff4ceae0047c25b9ce607488d7c7e93bba" The HEAD endpoints are only used to retrieve blob or server information. They MUST NOT be retried with payment proof. Instead, clients should complete the payment and proceed with the `PUT` or `GET` request. -### Recurring Payments - -Servers MAY accept recurring payments for blob storage using the following Nostr event types: - -- **Cashu**: Using [NIP-61](https://github.com/nostr-protocol/nips/blob/master/61.md) standard. - -- **Lightning**: Using [NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md) standard. - -The event MUST include a custom `x` tag containing the hash of the blob being paid for. - -- `x`: A string that represents the blob's SHA-256 hash. - ### Error handling If the client fails to provide the payment proof (expired invoice, invalid token, etc.) the server MUST respond with **400 Bad request** status code and include a `X-Reason` header with a human-readable message. The client SHOULD inform the user about the error and provide a way to retry the request. @@ -111,6 +99,4 @@ To support future payment methods (e.g., other Layer 2 solutions), the specifica New methods MUST use a unique `X-{payment_method}` header containing the specific payment details. -New methods MUST adhere their own specification, which MUST be publicly available and linked in the header. - -New methods MAY have a Nostr event type for recurring payments, which MUST be linked in the Recurring Payments section. +New methods MUST adhere their own specification, which MUST be publicly available and linked in the header. \ No newline at end of file From 8e12280410443029cbae882450d5714fef930414 Mon Sep 17 00:00:00 2001 From: quentintaranpino Date: Tue, 3 Dec 2024 13:06:04 +0100 Subject: [PATCH 28/30] fix typo --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 8b4bb3e..5c88aab 100644 --- a/buds/07.md +++ b/buds/07.md @@ -34,7 +34,7 @@ Schema: ```http HTTP/1.1 402 Payment Required -X-Payment-{payment_method}: "" +X-{payment_method}: "" ``` ### `X-Cashu` Header From 542c654045f858852dedd39b763d1b9fc40b7e39 Mon Sep 17 00:00:00 2001 From: Quentin <125748180+quentintaranpino@users.noreply.github.com> Date: Sun, 20 Apr 2025 18:37:03 +0200 Subject: [PATCH 29/30] Update buds/07.md Co-authored-by: hzrd149 <8001706+hzrd149@users.noreply.github.com> --- buds/07.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buds/07.md b/buds/07.md index 5c88aab..f996045 100644 --- a/buds/07.md +++ b/buds/07.md @@ -39,7 +39,7 @@ X-{payment_method}: "" ### `X-Cashu` Header -When using the X-Cashu header, the server MUST adhere to the [NUT-18](https://github.com/cashubtc/nuts/blob/main/18.md) standard. +When using the X-Cashu header, the server MUST adhere to the [NUT-23](https://github.com/cashubtc/nuts/pull/239) standard. Example for cashu: From 90affdd4d9e87f4a82ed69e50ea7328ea2f821b4 Mon Sep 17 00:00:00 2001 From: hzrd149 <8001706+hzrd149@users.noreply.github.com> Date: Wed, 30 Jul 2025 12:55:58 -0500 Subject: [PATCH 30/30] Update to use cashu NUT-24 --- buds/07.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/buds/07.md b/buds/07.md index f996045..af8e278 100644 --- a/buds/07.md +++ b/buds/07.md @@ -10,12 +10,15 @@ Payment requirements for blob storage. ## Payment Required -Some servers MAY require payment for file storage. In such cases, these endpoints MUST return a **402 Payment Required** status code: +Some servers MAY require payment for uploads, downloads, or any other endpoint. In such cases, these endpoints MUST return a **402 Payment Required** status code. -- [HEAD /upload](./01.md#head-sha256---has-blob) (Optional, if [BUD-06](./06.md) is implemented) -- [PUT /upload](./02.md#put-upload---upload-blob) -- [HEAD /](./01.md#head-sha256---has-blob) -- [GET /](./01.md#get-sha256---get-blob) +Some endpoints a server may require payment for: + +- [`HEAD /upload`](./06.md) to signal that payment is required for the `PUT` request ( if [BUD-06](./06.md) is supported ) +- [`PUT /upload`](./02.md#put-upload---upload-blob) to require payment for uploads +- [`HEAD /`](./01.md#head-sha256---has-blob) to signal that payment is required for the `GET` request +- [`GET /`](./01.md#get-sha256---get-blob) to require payment for downloads ( maybe charge by MB downloaded? ) +- [`HEAD /media`](./05.md) and [`PUT /upload`](./05.md) to require payment for media optimizations ( if [BUD-06](./06.md) is supported ) When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method. @@ -25,7 +28,7 @@ The 402 status code and `X-{payment_method}` header is used by the server to inf Supported payment methods: -- `X-Cashu`: Payment details for the cashu payment method, adhering to the [NUT-18](https://github.com/cashubtc/nuts/blob/main/18.md) standard. +- `X-Cashu`: Payment details for the cashu payment method, adhering to the [NUT-24](https://github.com/cashubtc/nuts/blob/main/24.md) standard. - `X-Lightning`: Payment details for the lightning payment method, adhering to the [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md) standard. If a server supports multiple payment methods, it MAY send multiple `X-{payment_method}` headers in the same response. @@ -39,7 +42,7 @@ X-{payment_method}: "" ### `X-Cashu` Header -When using the X-Cashu header, the server MUST adhere to the [NUT-23](https://github.com/cashubtc/nuts/pull/239) standard. +When using the X-Cashu header, the server MUST adhere to the [NUT-24](https://github.com/cashubtc/nuts/blob/main/24.md) standard. Example for cashu: @@ -64,7 +67,7 @@ Clients MUST parse and validate the `X-{payment_method}` header received from th The client MUST provide the payment proof when re-trying the request using the same `X-{payment_method}` header that was chosen. The payment proof MUST align with the payment method specification: -- For cashu the payment proof should be a serialized cashu token according to [NUT-00](https://github.com/cashubtc/nuts/blob/main/00.md#v4-tokens). +- For cashu the payment proof should be a serialized `cashuB` token in the `X-Cashu` header according to [NUT-24](https://github.com/cashubtc/nuts/blob/main/24.md#client-payment). - For lightning the payment proof should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md). Schema: @@ -82,7 +85,7 @@ X-Cashu: cashuBo2F0gqJhaUgA_9SLj17PgGFwgaNhYQFhc3hAYWNjMTI0MzVlN2I4NDg0YzNjZjE4N Example for Lightning: ```http -X-Lightning: "966fcb8f153339372f9a187f725384ff4ceae0047c25b9ce607488d7c7e93bba" +X-Lightning: 966fcb8f153339372f9a187f725384ff4ceae0047c25b9ce607488d7c7e93bba ``` **Special Note on HEAD Requests** @@ -99,4 +102,4 @@ To support future payment methods (e.g., other Layer 2 solutions), the specifica New methods MUST use a unique `X-{payment_method}` header containing the specific payment details. -New methods MUST adhere their own specification, which MUST be publicly available and linked in the header. \ No newline at end of file +New methods MUST adhere their own specification, which MUST be publicly available and linked in the header.