mirror of
https://github.com/hzrd149/blossom.git
synced 2025-12-09 07:08:50 +00:00
99 lines
4.6 KiB
Markdown
99 lines
4.6 KiB
Markdown
BUD-07
|
|
======
|
|
|
|
Paid storage
|
|
---------------
|
|
|
|
`draft` `optional`
|
|
|
|
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:
|
|
|
|
- [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 /<sha256>](./01.md#head-sha256---has-blob)
|
|
- [GET /<sha256>](./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.
|
|
|
|
## 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:
|
|
|
|
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.
|
|
|
|
Schema:
|
|
|
|
```http
|
|
HTTP/1.1 402 Payment Required
|
|
X-Payment-{payment_method}: "<encoded_payload_according_to_{payment_method}_spec>"
|
|
```
|
|
|
|
### `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.
|
|
|
|
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 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:
|
|
|
|
- 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}: "<encoded_payment_proof_according_to_{payment_method}_spec>"
|
|
```
|
|
|
|
Example for Cashu:
|
|
|
|
```http
|
|
X-Cashu: cashuBo2F0gqJhaUgA_9SLj17PgGFwgaNhYQFhc3hAYWNjMTI0MzVlN2I4NDg0YzNjZjE4NTAxNDkyMThhZjkwZjcxNmE1MmJmNGE1ZWQzNDdlNDhlY2MxM2Y3NzM4OGFjWCECRFODGd5IXVW
|
|
```
|
|
|
|
Example for Lightning:
|
|
|
|
```http
|
|
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 the specific payment details.
|
|
|
|
New methods MUST adhere their own specification, which MUST be publicly available and linked in the header.
|