blossom/buds/07.md

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 Www-Authenticate header when the payment is required.

• HEAD /upload
• PUT /upload
• HEAT /
• GET /

Authenticate header

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, the Www-Authenticate header can be used to request payment for specific blobs.

The Www-Authenticate header contains the macaroon and invoice fields for servers and the macaroon and preimage fields for clients.

• macaroon A base64 encoded string containing the macaroon, see L402 macaroons.
• invoice A string containing LN the payment request.
• preimage A string containing the payment preimage.

Server implementation

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 for all requests related to the blob:

Schema:

HTTP/1.1 402 Payment Required
Www-Authenticate: L402 macaroon="<macaroon>",invoice="<invoice>"

Example:

HTTP/1.1 402 Payment Required
Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",invoice="lnbc30n1pnvscg5pp56rft56xqcdamm59epsvmes06ymctq7gjt3nfnu3mjaw6fmfuhweqhp5w48l28v60yvythn6qvnpq0lez54422a042yaw4kq8arvd68a6n7qcqzzsxqyz5vqsp5a5tz8qqf897a2psdh3gc8m72tkpfwf03p8j95tgvkwm0jx97ypqs9qxpqysgqxuv6h48rzmguqkyxdyegrwf2m9890st2mty7z68acvcp9s8ukpx5daja0tdfq4tn2lmt443kua45zh6dzuy90grz02hcfauqx999g4gpf9lqhw"

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.

Schema:

Www-Authenticate: L402 macaroon="<macaroon>",preimage="<preimage>"

Example:

Www-Authenticate: L402 macaroon="eyJJRCI6IjMyMGQyMDAwZjVjODQ0NmQ3OTgyMjBlYTMxOGY5ZDg0MmM5MWZkMjYyMTliODZhYWE2ODEzMDBjYjc4YTI2YWEiLCJ2ZXJzaW9uIjoiMCIsInBheW1lbnRfaGFzaCI6IjQzN2Q2YTg1Y2M2ZDQxMzNiYWIzZTEwNWM0NjViZjMzNTQ4ODNjNmVkNzNkZmFhODA3MDQ1ZmIyMTI4MTRmMjYiLCJ0b2tlbl9pZCI6IjExMzIiLCJsb2NhdGlvbiI6Ii9hcGkvdjIvbWVkaWEvNjZiMGU3NzFlYTM0ZDE0MTBkNTM4Nzk3MjQ0NGRiN2RkNjU3OGE5OTBhZDhmMjRjZjFiZTE1OWUwYmVkODdmYy8wNmQwM2FmYzJjZTJkYzY2ODUxMjFmNTFhZjM5ZDUyNjM2OWY5NjgyZTFhOWNiNGRiZGFlZDhlOWI1ZTJiNDI3Lm1wNCIsImNhdmVhdHMiOlsiIl19",preimage="3e590d1336f241e858359c865802b4883ca91d47379c840af66785e2143bad22"

Unpaid Uploads

Some servers MAY accept unpaid uploads and require payment after the upload is completed. In this case, the server MUST return a 402 Payment Required status code along with a Www-Authenticate header containing the macaroon and payment request fields using the L402 protocol for the endpoints described in #payment-required.

For backward compatibility, the server SHOULD display a QR code, JSON file, or other useful information instead of the blob in the response body. When the payment is completed, the server MUST replace this information with the actual uploaded file.