Skip to content

Latest commit

 

History

History
233 lines (165 loc) · 13 KB

0105.md

File metadata and controls

233 lines (165 loc) · 13 KB
Raw

BRC-105: HTTP Service Monetization Framework

1. Abstract

This document specifies an HTTP-based micropayment framework that extends BRC-103 (mutual authentication and certificate exchange) and BRC-104 (HTTP transport for BRC-103). It defines how a server can advertise payment requirements for a given HTTP request and how a client can respond with a BSV transaction fulfilling these requirements. By leveraging:

  • HTTP 402 Payment Required responses
  • Nonce-based derivation prefixes (BRC-29)
  • BRC-103 Identity keys

this specification enables an authenticated, verifiable mechanism to monetize any web service with micropayments. The server could even cryptographically bind each payment to the mutual-authenticated session, ensuring that the payment correlates uniquely to the requested action.

2. Motivation

Current HTTP-based APIs often rely on subscription models or external billing/invoicing solutions. This approach can be cumbersome for fine-grained (micropayment-level) usage-based billing. By contrast, BSV Blockchain capabilities allow on-chain micropayments. However, bridging these seamlessly into existing HTTP flows requires:

  • Standardized BSV wallet functionality (BRC-100)
  • A standard approach to advertise payment requirements (HTTP 402)
  • A mechanism to tie a user’s payment to their session identity (via BRC-103 identity keys)
  • Nonce-based replay protection (ensuring the same payment is not reused maliciously)

BRC-105 addresses these needs by specifying how a BRC-103–authenticated server can request and verify a BSV payment from the client within a standard HTTP request–response cycle. Clients can use specialized 402-handling agents (e.g. AuthFetch or custom code) to automatically respond to 402 Payment Required, building and broadcasting a transaction on the user’s behalf.

3. Terminology & Definitions

  • Payer (or Client): The party sending the HTTP request, who must pay the server if required. They are already mutually authenticated to the server via BRC-103/104.
  • Payee (or Server): The HTTP endpoint receiving the request, which may respond with 402 Payment Required, specifying the needed payment details.
  • Derivation Prefix: A random nonce string used to derive or reference a unique public key / payment output. Defined in BRC-29.
  • Derivation Suffix: An additional, output/script-level field included by the client with the payment transaction that is used by the payee's wallet for verification. Also defined in BRC-29.
  • x-bsv-payment header: A custom header carrying JSON data, including the transaction references and derivation prefixes/suffixes.
  • internalizeAction(): A function defined by the payee’s wallet or server that finalizes the transaction acceptance logic (e.g., verifying the correct output script, ensuring the derivation prefix is valid, confirming the transaction is not a duplicate, etc.).

4. Relationship to BRC-103 and BRC-104

BRC-103 defines mutual authentication and certificate exchange but does not define how to handle micropayments. BRC-104 applies BRC-103 to HTTP, detailing how to wrap BRC-103 handshake data in HTTP messages.

BRC-105 sits on top of BRC-104, specifying a payment layer for monetizing HTTP endpoints. It reuses:

  • identityKey: The user’s 33-byte compressed public key from the BRC-103 session.
  • Nonce generation: The server can generate derivation prefixes that are cryptographically bound to its identity key, used by the parties to derive an ephemeral key pair for the payment.
  • HTTP 402 status code**: A recognized but typically unused code, repurposed here for BSV micropayments.

5. Payment Protocol Overview

5.1 Payment Steps Summary

  1. Client Authenticates

    • The client (payer) establishes a BRC-103 session with the server (payee) using BRC-104. This ensures both parties have authenticated and exchanged any necessary certificates to establish identity.

  2. Server Determines Price

    • The server calculates how many satoshis this request requires (if any). This can be a static fee, dynamic, or zero.

  3. 402 Payment Required (if fee > 0 and no valid payment provided)

    • If the client has not included a valid x-bsv-payment header, the server responds with HTTP status 402 and sets:
      • x-bsv-payment-satoshis-required: Number of satoshis required.
      • x-bsv-payment-derivation-prefix: A random nonce (BRC-29) for the transaction.

  4. Client Submits Payment

    • The client’s wallet or user agent sees the 402 response.
    • It constructs a BSV transaction paying the requested amount to the server’s derivation.
    • The client re-sends the request with a header x-bsv-payment containing JSON: 
      {
  "derivationPrefix": "AAAAA...",
  "derivationSuffix": "...",
  "transaction": "SGVsbG8s" // a BSV transaction in AtomicBEEF format encoded as base64
}

  5. Server Verifies Payment

    • The server checks the prefix (derivationPrefix) and suffix (derivationSuffix), ensures it matches what was advertised, and that the transaction properly pays the required amount.
    • If successful, the server considers the request to be funded.

  6. Server Continues

    • Assuming the payment is valid, the server proceeds with the requested operation and returns a normal success response (e.g., 200).

5.2 Payment Headers

  • x-bsv-payment-version
    • The current supported version is 1.0.
    • If a client does not explicitly support the server's indicated version, the client MUST NOT submit a payment.
  • x-bsv-payment-satoshis-required
    • Integer number of satoshis needed for this request.
    • Sent from server → client in 402 Payment Required.
  • x-bsv-payment-derivation-prefix
    • Payment-level nonce for deriving the payment output script.
    • Sent from server → client in 402 Payment Required.
  • x-bsv-payment
    • JSON structure containing the actual transaction data.
    • Sent from client → server in a subsequent request or retry after 402.

6. Detailed Protocol Flow

6.1 Request

6.1.1 Normal Request With Potential Payment

A mutually authenticated request arrives (client has previously performed BRC-103 handshake). The request may or may not contain x-bsv-payment data:

  • If no payment is needed (the server’s calculateRequestPrice returns 0), proceed normally.
  • If the request has a non-zero price and the client did not supply x-bsv-payment, or the payment is invalid, the server responds with 402 Payment Required.

6.2 Server’s 402 Response

When the server determines a payment is needed but not yet provided or invalid:

  1. HTTP Status: 402 Payment Required.
  2. Headers:
    • x-bsv-payment-version: 1.0
    • x-bsv-payment-satoshis-required: <price in satoshis>
    • x-bsv-payment-derivation-prefix: <nonce> (often base64 or hex)
  3. Body: Optional JSON describing the error or instructions for convenience: 
    {
  "status": "error",
  "code": "ERR_PAYMENT_REQUIRED",
  "satoshisRequired": 200,
  "description": "A BSV payment is required..."
}

After receiving this, the client is expected to construct and broadcast a payment transaction referencing this prefix.

6.3 Client Payment Submission

Subsequent request includes the header x-bsv-payment, JSON:

{
  "derivationPrefix": "<prefix from server>",
  "derivationSuffix": "<optional suffix>",
  "transaction": "SGVsbG8s"
}
  • derivationPrefix: Must match what the server gave in the 402 response.
  • transaction: A fully signed transaction paying an output script derived from the prefix, acceptable on the BSV network.

6.4 Server Payment Verification

Upon receiving x-bsv-payment, the server:

  1. Ensures the prefix is the same as previously advertised (and not used before).
  2. Validates the transaction using wallet.internalizeAction() or similar. Steps might include:
    • Ensuring the output script pays to the correct derivation from derivationPrefix.
    • Checking if the amount is at least the required satoshisRequired.
    • Preventing double-spend or replay.

If validated, the server MUST proceed to handle the request logic, and is obliged to provide the requested service, according to what the client has paid for.

6.5 Response to Payment-Funded Request

If payment is successful, the server responds with a normal (e.g., 200 OK) plus any business logic response body. The server may add:

  • x-bsv-payment-satoshis-paid: <value>
  • Possibly additional data about the transaction or usage.

7. Example Implementation

7.1 Server-Side Steps

  1. Auth Check (BRC-103/104)

    • If not authenticated, respond 401 Unauthorized.

  2. Calculate Price

    • E.g., price = 200 satoshis.

  3. If x-bsv-payment Provided

    • Parse and verify. If valid, continue. If invalid, return 400 Bad Request.

  4. If Not Paid

    • Return 402 + x-bsv-payment-version + x-bsv-payment-derivation-prefix + x-bsv-payment-satoshis-required.

  5. If Paid

    • Proceed to business logic.

7.2 Client-Side Steps

  1. Send Request

    • If server returns 402, parse x-bsv-payment-version + x-bsv-payment-satoshis-required + x-bsv-payment-derivation-prefix.

  2. Construct Payment

    • Create transaction paying the server’s derivation.
    • Store it in x-bsv-payment JSON.

  3. Re-Send

    • Re-send the request with x-bsv-payment header.
    • If accepted, receives normal 200 OK.
    • If server fraudulently absconds with client funds:
      • Clients should request more robust identity certificates using BRC-103 in the future.
      • Do not use the service again.
      • Make reports to the issuers of the server's certificates to have them revoked.
      • Do not trust certifiers who are willing to issue certificates to fraudulent entities.
      • Contact your local police department.
      • File an IC3 complaint.

8. Security Considerations

  1. Replay Attacks

    • The server and its wallet must ensure each derivationPrefix can only be used once. Typically, this prefix is stored in a wallet database or in-memory structure. Once a valid transaction is processed, subsequent attempts to reuse the prefix or submit the same transaction for multiple requests must fail.

  2. Man-in-the-Middle

    • Because all requests are already mutually authenticated via BRC-103, a MITM cannot hijack the payment flow. Tampering with the transaction or the prefix invalidates the request and leads to cryptographic failure.

  3. Underpayment

    • The server should reject transactions that pay less than required. Or, if partial payments are allowed, the server must define how to handle partial coverage. Servers should set clear refund policies, and policies for services not used or partially paid. Generally, partial payment is prohibited.

  4. Double Spends

    • The server’s wallet.internalizeAction() logic must handle double-spend scenarios, ensuring the transaction is fully-signed, final and valid on the network.

  5. Data Confidentiality

    • BRC-105 does not itself encrypt data. Transport-level encryption (e.g., TLS) is recommended to protect transaction details and requests from eavesdroppers.

9. Extensibility & Future Work

  • Advanced Pricing: BRC-105 does not define how to calculate price. Implementation can adopt static or dynamic logic.
  • Refund Handling: Out of scope for this version. The server might store overpayments or offer on-chain refunds via additional flows.
  • Multi-Output Payments: Some use cases might require paying multiple outputs. The basic 402 flow still applies but must be extended with more sophisticated transaction logic.

10. References

11. Conclusion

BRC-105 introduces a standard approach to HTTP-based micropayment flows, leveraging the authentication and transport models defined in BRC-103 and BRC-104. By responding with 402 Payment Required and specifying a nonce-based derivation, the server ensures each payment is uniquely bound to the mutual-authenticated session and request. This framework enables straightforward pay-per-use APIs and extends the BSV ecosystem with a robust, standardized mechanism for monetizing web services at scale.