mirror of
https://github.com/hzrd149/blossom.git
synced 2025-12-09 07:08:50 +00:00
113 lines
5.0 KiB
Markdown
113 lines
5.0 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.
|
|
|
|
## 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-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.
|
|
|
|
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"
|
|
```
|
|
|
|
### 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 **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.
|
|
|
|
New methods MAY have a Nostr event type for recurring payments, which MUST be linked in the Recurring Payments section.
|