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"

Backward compatibility

For backward compatibility, when a client requests an unpaid blob, the server SHOULD return alternative information, such as a QR code, a JSON file, or other useful data in the response body. This serves as a placeholder, clearly indicating that the actual file is unavailable until payment is made. Once the payment is completed, the server MUST replace this placeholder with the actual blob in subsequent requests. This ensures that legacy clients still receive meaningful responses without breaking functionality, while supporting the new payment logic.