mirror of
https://github.com/hzrd149/blossom.git
synced 2025-12-08 14:58:49 +00:00
using different headers for each payment method
This commit is contained in:
Quentin
148
buds/07.md
148
buds/07.md
@@ -10,93 +10,155 @@ 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.
|
||||
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)
|
||||
- [HEAD /upload](./01.md#head-sha256---has-blob) (Optional, if [BU-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)
|
||||
|
||||
## Server header
|
||||
When payment is required, the server MUST include one or more `X-{payment_method}` header(s), each corresponding to a supported payment method.
|
||||
|
||||
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:
|
||||
## Server headers
|
||||
|
||||
- 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 `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:
|
||||
|
||||
Each payment method has its own requirements and the server SHOULD provide the necessary information for the client to complete the payment.
|
||||
- `X-{payment_method}`: Base64 UrlSafe encoded JSON with the payment details.
|
||||
|
||||
Supported payment methods:
|
||||
|
||||
- `X-Cashu`: Payment details for the cashu payment method.
|
||||
- `X-Lightning`: Payment details for the lightning payment method.
|
||||
|
||||
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.
|
||||
|
||||
### `X-Cashu` Header
|
||||
|
||||
Fields included in the X-Cashu header:
|
||||
|
||||
- identifier: The unique identifier for the payment.
|
||||
- amount: The amount of ecash being requested
|
||||
- mints: An array of mints that this server uses
|
||||
- unit: The cashu `unit` from the `mints`
|
||||
- pubkey: (optional) a 33 byte pubkey to lock the tokens too. see [NUT-11](https://github.com/cashubtc/nuts/blob/main/11.md)
|
||||
|
||||
The `identifier` field is a unique reference to a specific payment request. It allows the server to distinguish between different payments for the same file or blob. The server MUST ensure that each identifier is unique and link it internally to the relevant file or blob.
|
||||
|
||||
Example for cashu:
|
||||
|
||||
```json
|
||||
{
|
||||
"blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644",
|
||||
"payment_method": "cashu",
|
||||
"payment_details": {
|
||||
"amount": "300",
|
||||
"mints": "https://example.com",
|
||||
"unit": "sat",
|
||||
"pubkey": "0a3bce8b6005175d25432244340912dfa431a0d62681d9720cda9196398d7222"
|
||||
}
|
||||
"identifier": "23537",
|
||||
"amount": "300",
|
||||
"mints": ["https://example.com", "https://example2.com"],
|
||||
"unit": "sat",
|
||||
"pubkey": "0a3bce8b6005175d25432244340912dfa431a0d62681d9720cda9196398d7222"
|
||||
}
|
||||
```
|
||||
|
||||
```http
|
||||
HTTP/1.1 402 Payment Required
|
||||
X-Cashu: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAiYW1vdW50IjogIjMwMCIsCiAgIm1pbnRzIjogWyJodHRwczovL2V4YW1wbGUuY29tIiwgImh0dHBzOi8vZXhhbXBsZTIuY29tIl0sCiAgInVuaXQiOiAic2F0IiwKICAicHVia2V5IjogIjBhM2JjZThiNjAwNTE3NWQyNTQzMjI0NDM0MDkxMmRmYTQzMWEwZDYyNjgxZDk3MjBjZGE5MTk2Mzk4ZDcyMjIiCn0
|
||||
```
|
||||
|
||||
### `X-Lightning` Header
|
||||
|
||||
Fields included in the X-Lightning header:
|
||||
|
||||
- identifier: The unique identifier for the payment.
|
||||
- amount: The amount to be paid.
|
||||
- payment_request: The lightning payment request.
|
||||
|
||||
The `identifier` field is a unique reference to a specific payment request. It allows the server to distinguish between different payments for the same file or blob. The server MUST ensure that each identifier is unique and link it internally to the relevant file or blob.
|
||||
|
||||
Example for lightning:
|
||||
|
||||
```json
|
||||
{
|
||||
"blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644",
|
||||
"identifier": "23537",
|
||||
"amount": "300",
|
||||
"payment_method": "lightning",
|
||||
"payment_details": {
|
||||
"payment_request": "lnbc300n1pw4..:",
|
||||
}
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
```http
|
||||
HTTP/1.1 402 Payment Required
|
||||
X-Lightning: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAiYW1vdW50IjogIjMwMCIsCiAgInBheW1lbnRfcmVxdWVzdCI6ICJsbmJjMzAwbjFwdzQuLjoiLAp9
|
||||
```
|
||||
|
||||
Schema:
|
||||
|
||||
```http
|
||||
HTTP/1.1 402 Payment Required
|
||||
X-Payment: "<base64_encoded_server_json>"
|
||||
X-Payment-{payment_method}: "<base64-UrlSafe_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:
|
||||
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 appropiate `X-Payment-{payment_method}` header.
|
||||
|
||||
- blob: The paid blob.
|
||||
- payment_proof: The payment proof. (e.g., preimage for cashu and lightning, txid for liquid).
|
||||
- `X-{payment_method}-Payment`: Base64 UrlSafe encoded JSON with the client payment proof.
|
||||
|
||||
- identifier: The unique identifier for the payment.
|
||||
- payment_proof: The proof of payment, specific to the method:
|
||||
|
||||
- For cashu the payment 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 should be the preimage of the payment request according to [BOLT-11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
|
||||
|
||||
Example for Cashu:
|
||||
|
||||
```json
|
||||
{
|
||||
"blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644",
|
||||
"identifier": "23537",
|
||||
"payment_proof": "c3b9e2..."
|
||||
}
|
||||
|
||||
```http
|
||||
X-Cashu-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJjM2I5ZTIiCn0
|
||||
```
|
||||
|
||||
Example for Lightning:
|
||||
|
||||
```json
|
||||
{
|
||||
"identifier": "23537",
|
||||
"payment_proof": "lnbc300n1pw4..."
|
||||
}
|
||||
|
||||
```http
|
||||
X-Lightning-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJsbmJjMzAwbjFwdzQuLjoiCn0
|
||||
```
|
||||
|
||||
Schema:
|
||||
|
||||
```http
|
||||
X-Payment: "<base64_encoded_client_json>"
|
||||
X-{payment_method}-Payment: "<base64-UrlSafe_encoded_client_json>"
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
Header Format:
|
||||
|
||||
New methods MUST use a unique `X-{payment_method}` header containing Base64 UrlSafe encoded JSON.
|
||||
|
||||
Required Fields:
|
||||
|
||||
- identifier: Unique reference for the payment.
|
||||
- amount: Payment amount in the method’s smallest unit.
|
||||
|
||||
Backward Compatibility:
|
||||
|
||||
Servers and clients MUST ignore unknown X-{payment_method} headers.
|
||||
|
||||
Documentation:
|
||||
|
||||
Any new payment method added in the future MUST follow the same structure as existing methods, ensuring that the `identifier` and `amount` fields are always present and well-defined. This consistency allows seamless integration of new methods without breaking compatibility for existing clients and servers.
|
||||
|
||||
Reference in New Issue
Block a user