Paymail Payment Destinations

Abstract

We specify the widely-used protocols for exchanging payments between users of the Paymail system within the Bitcoin SV network. Paymail is a user-friendly alternative to traditional Bitcoin addresses, leveraging human-readable names at a domain, such as john.galt@gateway.cash. This standard aims to provide a clear and concise specification for wallet implementers to facilitate incoming and outgoing payments using Paymail addresses. BRC-28 encompasses the pre-existing payment destination and payment exchange protocols, ensuring compatibility and interoperability across Bitcoin SV wallet applications.

Motivation

The primary motivation behind BRC-28 is to address the usability and complexity issues associated with traditional Bitcoin addresses. These addresses, comprised of long strings of alphanumeric characters, can be difficult to remember and prone to user errors when transcribing or sharing. By introducing the Paymail protocol, which replaces complex addresses with human-readable names, the overall user experience of Bitcoin SV transactions is significantly improved.

However, for Paymail to be widely adopted and to ensure seamless transactions across wallet applications, a standardized approach is necessary. BRC-28 aims to provide this standardization by specifying the payment destination and payment exchange protocols, allowing wallet implementers to incorporate Paymail support in a consistent and interoperable manner.

Furthermore, Paymail provides a scalable solution to the problem of blockchain scanning. With traditional addresses, the recipient must scan the blockchain to be notified about their incoming payments. With the peer-to-peer Paymail approach, transactions are handed directly from the sender to the recipient and subsequently broadcasted upon acceptance, removing the need for blockchain scanning services.

Specification

The BRC-28 specification comprises two main components: P2P Transactions and P2P Payment Destination. These components work in tandem to facilitate the exchange of Paymail transactions in a peer-to-peer manner, eliminating the need for blockchain scanning services and enabling scalable Bitcoin SV wallet applications.

P2P Transactions

1.1 Capability Discovery

The Paymail provider's .well-known/bsvalias document must be updated to include a declaration of the endpoint for receiving transactions:

{
  "bsvalias": "1.0",
  "capabilities": {
    "5f1323cddf31": "https://example.bsvalias.tld/api/receive-rawtx/{alias}@{domain.tld}"
  }
}

The capabilities.5f1323cddf31 field contains a URL where the sender must POST the transaction data.

1.2 Client Request

The sender must replace the {alias} and {domain.tld} placeholders in the URI template provided by capabilities.5f1323cddf31 with a valid Paymail handle. The client must then perform a POST HTTP request with the following body:

{
  "hex": "<raw_transaction_hex>",
  "metadata": {
    "sender": "<sender_paymail>",
    "pubkey": "<sender_public_key>",
    "signature": "<signature_of_txid>",
    "note": "<optional_human_readable_note>"
  },
  "reference": "<payment_reference>"
}

1.3 Server Response

The server must validate the transaction and respond with the accepted transaction ID and an optional human-readable note.

{
  "txid": "<accepted_txid>",
  "note": "<optional_human_readable_note>"
}

P2P Payment Destination

2.1 Capability Discovery

The Paymail provider's .well-known/bsvalias document must be updated to include a declaration of the endpoint for generating P2P payment destinations:

{
  "bsvalias": "1.0",
  "capabilities": {
    "2a40af698840": "https://example.bsvalias.tld/api/p2p-payment-destination/{alias}@{domain.tld}"
  }
}

The capabilities.2a40af698840 field contains a URL where the sender must POST the required satoshis for the transaction.

2.2 Client Request

The sender must replace the {alias} and {domain.tld} placeholders in the URI template provided by capabilities.2a40af698840 with a valid Paymail handle. The client must then perform a POST HTTP request with the following body:

{
  "satoshis": <number_of_satoshis>
}

2.3 Server Response

The server must generate a list of outputs and a reference number for the payment and respond with the following structure:

{
  "outputs": [
    {
      "script": "<locking_script_hex_1>",
      "satoshis": <satoshis_1>
    },
    {
      "script": "<locking_script_hex_2>",
      "satoshis": <satoshis_2>
    }
  ],
  "reference": "<payment_reference>"
}

The BRC-28 specification, encompassing P2P Transactions and P2P Payment Destination, provides a clear and concise protocol for wallet implementers to support Paymail-based transactions in a consistent and interoperable manner. By adhering to this specification, developers can create compatible implementations that facilitate seamless Paymail transactions, benefiting end-users.

Implementations

Various implementations have been created which facilitate Paymail payment destination discovery, and the hosting of Paymail servers:

Money Button Express Paymail is a server-side package that hosts a set of compatible endpoints.
Money Button Paymail Client is a JavaScript client for interacting with the Paymail protocol.
AtFinder is the Paymail client created by Project Babbage [deprecated (no longer in active use)].

Auxiliary Information on Host and Capability Discovery

In the interest of completeness, we provide some auxiliary information that may be useful for implementers wishing to run Paymail servers. While the main objective of BRC-28 is to define the specifications for peer-to-peer payment destinations and transaction submission, we provide this additional information about service and capability discovery so that future implementers can interoperate.

Paymail Addresses

Paymail addresses follow the format <alias>@<domain.tld>, similar to email addresses. The <alias> represents a user or an account within a domain, while <domain.tld> represents the domain owner's unique domain name. Paymail addresses must only contain alphanumeric characters, periods, and hyphens, with the @ symbol separating the alias from the domain.

Paymail Host Discovery

Paymail Host Discovery is the process of determining the appropriate host to query for Capability Discovery. Host Discovery relies on SRV DNS records to indicate the specific web host to interrogate. Domain owners can create an SRV record with specified parameters to delegate authority to a third-party Paymail service provider or to configure their own Paymail service:

SRV Record Attribute

Value

Service

_bsvalias

Proto

_tcp

Name

<domain>.<tld>.

TTL (Time to Live)

3600 (recommended for production deployments)

Class

IN

Priority

10

Weight

10

Port

443

Target

<endpoint-discovery-host>

Paymail Capability Discovery

Paymail Capability Discovery is the process by which a Paymail client learns the supported features of a Paymail service, as well as their respective endpoints and configurations. Capability Discovery uses a well-known file, a machine-readable JSON-formatted document placed in a predictable location on a web server.

The well-known file's location should be:

https://<host-discovery-target>:<host-discovery-port>/.well-known/bsvalias

This file contains the supported capabilities and their associated endpoints, with template strings {alias} and {domain.tld} used to represent the components of a Paymail address. Clients should replace these template strings with the actual values from the Paymail address.

To perform Capability Discovery, a Paymail client constructs an HTTP GET request to https://<target>:<port>/.well-known/bsvalias after retrieving a Target:Port pair from Host Discovery. A successful request provides the client with the necessary configuration information to interact with the Paymail service and access its supported extension protocols.

PreviousDirect Payment Protocol (DPP)NextSimple Authenticated BSV P2PKH Payment Protocol

Last updated 1 year ago