Skip to content

07.md

Latest commit

 

History

History
103 lines (63 loc) · 5.16 KB

07.md

File metadata and controls

103 lines (63 loc) · 5.16 KB

BUD-07

Paid upload and download

draft optional

Payment requirements for blob storage.

Payment Required

Some servers MAY require payment for uploads, downloads, or any other endpoint. In such cases, these endpoints MUST return a 402 Payment Required status code.

Some endpoints a server may require payment for:

  • HEAD /upload to signal that payment is required for the PUT request ( if that optional endpoint is supported )
  • PUT /upload to require payment for uploads
  • HEAD /<sha256> to signal that payment is required for the GET request
  • GET /<sha256> to require payment for downloads ( maybe charge by MB downloaded? )
  • HEAD /media and PUT /media to require payment for media optimizations ( if the optional HEAD /media-style preflight is supported )

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-24 standard.
  • X-Lightning: Payment details for the lightning payment method, adhering to the BOLT-11 standard.

If a server supports multiple payment methods, it MAY send multiple X-{payment_method} headers in the same response.

Schema:

HTTP/1.1 402 Payment Required
X-{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-24 standard.

Example for cashu:

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 standard. Example for lightning:

HTTP/1.1 402 Payment Required
X-Lightning: lnbc30n1pnnmw3lpp57727jjq8zxctahfavqacymellq56l70f7lwfkmhxfjva6dgul2zqhp5w48l28v60yvythn6qvnpq0lez54422a042yaw4kq8arvd68a6n7qcqzzsxqyz5vqsp5sqezejdfaxx5hge83tf59a50h6gagwah59fjn9mw2d5mn278jkys9qxpqysgqt2q2lhjl9kgfaqz864mhlsspftzdyr642lf3zdt6ljqj6wmathdhtgcn0e6f4ym34jl0qkt6gwnllygvzkhdlpq64c6yv3rta2hyzlqp8k28pz

Client implementation

Clients MUST parse and validate the X-{payment_method} header 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 when re-trying the request using the same X-{payment_method} header that was chosen. The payment proof MUST align with the payment method specification:

  • For cashu the payment proof should be a serialized cashuB token in the X-Cashu header according to NUT-24.
  • For lightning the payment proof should be the preimage of the payment request according to BOLT-11.

Schema:

X-{payment_method}: "<encoded_payment_proof_according_to_{payment_method}_spec>"

Example for Cashu:

X-Cashu: cashuBo2F0gqJhaUgA_9SLj17PgGFwgaNhYQFhc3hAYWNjMTI0MzVlN2I4NDg0YzNjZjE4NTAxNDkyMThhZjkwZjcxNmE1MmJmNGE1ZWQzNDdlNDhlY2MxM2Y3NzM4OGFjWCECRFODGd5IXVW

Example for Lightning:

X-Lightning: 966fcb8f153339372f9a187f725384ff4ceae0047c25b9ce607488d7c7e93bba

Special Note on HEAD Requests

The HEAD endpoints are only used to retrieve blob or server information. They MUST NOT be retried with payment proof. Instead, clients should complete the payment and proceed with the PUT or GET request.

Error handling

If the client fails to provide the payment proof (expired invoice, invalid token, etc.) the server MUST respond with 400 Bad request status code and include a X-Reason header with a human-readable message. The client SHOULD inform the user about the error and provide a way to retry the request.

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.
⚡