diff --git a/README.md b/README.md index 0fc2093..7108f16 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ BUDs or **Blossom Upgrade Documents** are short documents that outline an additi - [BUD-04: Mirroring blobs](./buds/04.md) - [BUD-05: Media optimization](./buds/05.md) - [BUD-06: Upload requirements](./buds/06.md) +- [BUD-07: Payment required](./buds/07.md) - [BUD-08: Nostr File Metadata Tags](./buds/08.md) - [BUD-09: Blob Report](./buds/09.md) diff --git a/buds/07.md b/buds/07.md new file mode 100644 index 0000000..af8e278 --- /dev/null +++ b/buds/07.md @@ -0,0 +1,105 @@ +BUD-07 +====== + +Paid upload and download +--------------- + +`draft` `optional` + +Payment requirements for blob storage. + +## Payment Required + +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. + +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. + +## Server headers + +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: + +- `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. + +Schema: + +```http +HTTP/1.1 402 Payment Required +X-{payment_method}: "" +``` + +### `X-Cashu` Header + +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: + +```http +HTTP/1.1 402 Payment Required +X-Cashu: creqApWF0gaNhdGVub3N0cmFheKlucHJvZmlsZTFxeTI4d3VtbjhnaGo3dW45ZDNzaGp0bnl2OWtoMnVld2Q5aHN6OW1od2RlbjV0ZTB3ZmprY2N0ZTljdXJ4dmVuOWVlaHFjdHJ2NWhzenJ0aHdkZW41dGUwZGVoaHh0bnZkYWtxcWd5ZGFxeTdjdXJrNDM5eWtwdGt5c3Y3dWRoZGh1NjhzdWNtMjk1YWtxZWZkZWhrZjBkNDk1Y3d1bmw1YWeBgmFuYjE3YWloYjdhOTAxNzZhYQphdWNzYXRhbYF4Imh0dHBzOi8vbm9mZWVzLnRlc3RudXQuY2FzaHUuc3BhY2U +``` + +### `X-Lightning` Header + +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: + +```http +HTTP/1.1 402 Payment Required +X-Lightning: lnbc30n1pnnmw3lpp57727jjq8zxctahfavqacymellq56l70f7lwfkmhxfjva6dgul2zqhp5w48l28v60yvythn6qvnpq0lez54422a042yaw4kq8arvd68a6n7qcqzzsxqyz5vqsp5sqezejdfaxx5hge83tf59a50h6gagwah59fjn9mw2d5mn278jkys9qxpqysgqt2q2lhjl9kgfaqz864mhlsspftzdyr642lf3zdt6ljqj6wmathdhtgcn0e6f4ym34jl0qkt6gwnllygvzkhdlpq64c6yv3rta2hyzlqp8k28pz +``` + +### Client implementation + +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: + +- 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: + +```http +X-{payment_method}: "" +``` + +Example for Cashu: + +```http +X-Cashu: cashuBo2F0gqJhaUgA_9SLj17PgGFwgaNhYQFhc3hAYWNjMTI0MzVlN2I4NDg0YzNjZjE4NTAxNDkyMThhZjkwZjcxNmE1MmJmNGE1ZWQzNDdlNDhlY2MxM2Y3NzM4OGFjWCECRFODGd5IXVW +``` + +Example for Lightning: + +```http +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. + +### 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. + +### 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 the specific payment details. + +New methods MUST adhere their own specification, which MUST be publicly available and linked in the header.