mirror of
https://github.com/hzrd149/blossom.git
synced 2025-12-09 23:18:50 +00:00
101 lines
2.5 KiB
Markdown
101 lines
2.5 KiB
Markdown
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 `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 /<sha256>](./01.md#head-sha256---has-blob)
|
|
- [GET /<sha256>](./01.md#get-sha256---get-blob)
|
|
|
|
## Server 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:
|
|
|
|
- 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.
|
|
|
|
Each payment method has its own requirements and the server SHOULD provide the necessary information for the client to complete the payment.
|
|
|
|
Example for cashu:
|
|
|
|
```json
|
|
{
|
|
"blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644",
|
|
"payment_method": "cashu",
|
|
"payment_details": {
|
|
"amount": "300",
|
|
"mints": "https://example.com",
|
|
"unit": "sat",
|
|
"pubkey": "0a3bce8b6005175d25432244340912dfa431a0d62681d9720cda9196398d7222"
|
|
}
|
|
}
|
|
```
|
|
|
|
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
|
|
X-Payment: "<base64_encoded_server_json>"
|
|
```
|
|
|
|
### 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:
|
|
|
|
- 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
|
|
X-Payment: "<base64_encoded_client_json>"
|
|
```
|