laantungir/blossom
1
0
Fork 0
mirror of https://github.com/hzrd149/blossom.git synced 2025-12-08 22:58:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update BUD-07 for multiple L2; discard L402

Browse Source
This commit is contained in:
Quentin
2024-11-01 10:55:49 +01:00
parent cd778dec22
commit 942fb60e97
1 changed files with 63 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
buds/07.md
View File

@@ -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 /<sha256>](./01.md#head-sha256---has-blob)
- [GET /<sha256>](./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="<macaroon>",invoice="<invoice>"
```
Example:
```http
HTTP/1.1 402 Payment Required
Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",invoice="lnbc30n1pnvscg5pp56rft56xqcdamm59epsvmes06ymctq7gjt3nfnu3mjaw6fmfuhweqhp5w48l28v60yvythn6qvnpq0lez54422a042yaw4kq8arvd68a6n7qcqzzsxqyz5vqsp5a5tz8qqf897a2psdh3gc8m72tkpfwf03p8j95tgvkwm0jx97ypqs9qxpqysgqxuv6h48rzmguqkyxdyegrwf2m9890st2mty7z68acvcp9s8ukpx5daja0tdfq4tn2lmt443kua45zh6dzuy90grz02hcfauqx999g4gpf9lqhw"
X-Payment: "<base64_encoded_server_json>"
```
### 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="<macaroon>",preimage="<preimage>"
X-Payment: "<base64_encoded_client_json>"
```
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.