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

Refactored to clarify payment header encoding and method-specific requirements

Browse Source
This commit is contained in:
Quentin
2024-11-20 12:14:00 +01:00
parent 18a57e361c
commit 0aa5a9dd6f
1 changed files with 28 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
buds/07.md
View File

@@ -17,140 +17,82 @@ Some servers MAY require payment for file storage. In such cases, these endpoint
- [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.
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:
- `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.
- `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
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.
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:
```json
{
"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-Cashu: creqApWF0gaNhdGVub3N0cmFheKlucHJvZmlsZTFxeTI4d3VtbjhnaGo3dW45ZDNzaGp0bnl2OWtoMnVld2Q5aHN6OW1od2RlbjV0ZTB3ZmprY2N0ZTljdXJ4dmVuOWVlaHFjdHJ2NWhzenJ0aHdkZW41dGUwZGVoaHh0bnZkYWtxcWd5ZGFxeTdjdXJrNDM5eWtwdGt5c3Y3dWRoZGh1NjhzdWNtMjk1YWtxZWZkZWhrZjBkNDk1Y3d1bmw1YWeBgmFuYjE3YWloYjdhOTAxNzZhYQphdWNzYXRhbYF4Imh0dHBzOi8vbm9mZWVzLnRlc3RudXQuY2FzaHUuc3BhY2U
```
### `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.
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:
```json
{
"identifier": "23537",
"amount": "300",
"payment_request": "lnbc300n1pw4..:",
}
```
```http
HTTP/1.1 402 Payment Required
X-Lightning: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAiYW1vdW50IjogIjMwMCIsCiAgInBheW1lbnRfcmVxdWVzdCI6ICJsbmJjMzAwbjFwdzQuLjoiLAp9
X-Lightning: lnbc30n1pnnmw3lpp57727jjq8zxctahfavqacymellq56l70f7lwfkmhxfjva6dgul2zqhp5w48l28v60yvythn6qvnpq0lez54422a042yaw4kq8arvd68a6n7qcqzzsxqyz5vqsp5sqezejdfaxx5hge83tf59a50h6gagwah59fjn9mw2d5mn278jkys9qxpqysgqt2q2lhjl9kgfaqz864mhlsspftzdyr642lf3zdt6ljqj6wmathdhtgcn0e6f4ym34jl0qkt6gwnllygvzkhdlpq64c6yv3rta2hyzlqp8k28pz
```
Schema:
```http
HTTP/1.1 402 Payment Required
X-Payment-{payment_method}: "<base64-UrlSafe_encoded_server_json>"
```
### 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 appropiate `X-Payment-{payment_method}` header.
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.
- `X-{payment_method}-Payment`: Base64 UrlSafe encoded JSON with the client payment proof.
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:
- `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)
- 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:
```json
{
"identifier": "23537",
"payment_proof": "c3b9e2..."
}
```
```http
X-Cashu-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJjM2I5ZTIiCn0
X-Cashu: cashuBo2F0gqJhaUgA_9SLj17PgGFwgaNhYQFhc3hAYWNjMTI0MzVlN2I4NDg0YzNjZjE4NTAxNDkyMThhZjkwZjcxNmE1MmJmNGE1ZWQzNDdlNDhlY2MxM2Y3NzM4OGFjWCECRFODGd5IXVW
```
Example for Lightning:
```json
{
"identifier": "23537",
"payment_proof": "lnbc300n1pw4..."
}
```
```http
X-Lightning-Payment: ewogICJpZGVudGlmaWVyIjogIjIzNTM3IiwKICAicGF5bWVudF9wcm9vZiI6ICJsbmJjMzAwbjFwdzQuLjoiCn0
```
Schema:
```http
X-{payment_method}-Payment: "<base64-UrlSafe_encoded_client_json>"
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 Base64 UrlSafe encoded JSON.
New methods MUST use a unique `X-{payment_method}` header containing the specific payment details.
**Required Fields:**
- `identifier`: Unique reference for the payment.
- `amount`: Payment amount in the method’s smallest unit.
New methods MUST adhere their own specification, which MUST be publicly available and linked in the header.