LogoLogo
  • README
  • Contribute
    • Discuss on Github
  • Example
    • Banana-Powered Bitcoin Wallet Control Protocol
  • Apps
    • The deployment-info.json Specification
  • Wallet
    • Transaction Creation
    • Data Encryption and Decryption
    • Digital Signature Creation and Verification
    • Input Redemption
    • HTTP Wallet Communications Substrate
    • XDM Wallet Communications Substrate
    • Window Wallet Communication Substrate
    • Wallet Transaction Output Tracking (Output Baskets)
    • Submitting Received Payments to a Wallet
    • Certificate Creation and Revelation
    • Unified Abstract Wallet-to-Application Messaging Layer
    • Transaction Labels and List Actions
    • Output Basket Removal and Certificate Deletion
    • Group Permissions for App Access
    • Extensible Proof-Type Format for Specific Key Linkage Claims
    • P Protocols: Allowing future wallet protocol permission schemes
    • P Baskets: Allowing Future Wallet Basket and Digital Asset Permission Schemes
    • Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface
  • Transactions
    • Everett-style Transaction Envelopes
    • Simplified Payment Verification
    • Merkle proof standardised format
    • TSC Proof Format with Heights
    • Raw Transaction Format
    • TXO Transaction Object Format
    • Transaction Extended Format (EF)
    • Merkle Path JSON format
    • Compound Merkle Path Format
    • Background Evaluation Extended Format (BEEF) Transactions
    • Simplified Payment Verification
    • Merkle Path Binary Format
    • BSV Unified Merkle Path (BUMP) Format
    • Graph Aware Sync Protocol
    • Scalable Transaction Processing in the BSV Network
    • Atomic BEEF Transactions
    • BEEF V2 Txid Only Extension
  • Scripts
    • Bitcoin Script Binary, Hex and ASM Formats
    • Bitcoin Script Assembly Language
    • Pay to Public Key Hash
    • Pay to R Puzzle Hash
    • Pay to False Return
    • Pay to True Return
    • Push TX
    • Bare Multi-Signature
    • Pay to Push Drop
  • Tokens
    • There is no BRC-20
    • Definition of UTXOs as Bitcoin Tokens
    • Token Exchange Protocol for UTXO-based Overlay Networks
    • Mandala Token Protocol
  • Overlays
    • Overlay Network Data Synchronization
    • Confederacy Host Interconnect Protocol (CHIP)
    • Overlay Network Lookup Services
    • Confederacy Lookup Availability Protocol (CLAP)
    • Universal Hash Resolution Protocol
    • Overlay Network Transaction History Tracking
    • Private Overlays with P2PKH Transactions
    • Standardized Naming Conventions for BRC-22 Topic Managers and BRC-24 Lookup Services
    • Overlay Services Synchronization Architecture
    • Diverse Facilitators and URL Protocols for SHIP and SLAP Overlay Advertisements
  • Payments
    • Direct Payment Protocol (DPP)
    • Paymail Payment Destinations
    • Simple Authenticated BSV P2PKH Payment Protocol
    • PacketPay HTTP Payment Mechanism
    • Hybrid Payment Mode for DPP
    • HTTPS Transport Mechanism for DPP
    • Paymail BEEF Transaction
    • HTTP Service Monetization Framework
  • Peer-to-Peer
    • Authrite Mutual Authentication
    • PeerServ Message Relay Interface
    • PeerServ Host Interconnect Protocol
    • Identity Certificates
    • Genealogical Identity Protocol
    • Publishing Trust Anchor Details at an Internet Domain
    • Message Signature Creation and Verification
    • Serialization Format for Portable Encrypted Messages
    • Defining a Scalable IPv6 Multicast Protocol for Blockchain Transaction Broadcast and Update Delivery
    • Proven Identity Key Exchange (PIKE)
    • Peer-to-Peer Mutual Authentication and Certificate Exchange Protocol
    • HTTP Transport for BRC-103 Mutual Authentication
  • Key Derivation
    • BIP32 Key Derivation Scheme
    • BSV Key Derivation Scheme (BKDS)
    • Security Levels, Protocol IDs, Key IDs and Counterparties
    • Admin-reserved and Prohibited Key Derivation Protocols
    • Revealing Key Linkages
    • Protecting BRC-69 Key Linkage Information in Transit
    • Mnemonic For Master Private Key
    • Linked Key Derivation Scheme
    • Bidirectionally Authenticated Derivation of Privacy Restricted Type 42 Keys
    • Limitations of BRC-69 Key Linkage Revelation
    • Verifiable Revelation of Shared Secrets Using Schnorr Protocol
  • Outpoints
    • Format for Bitcoin Outpoints
    • Spending Instructions Extension for UTXO Storage Format
  • Opinions
    • Users should never see an address
    • List of user experiences
    • Legitimate Uses for mAPI
    • Security and Scalability Benefits of UTXO-based Overlay Networks
    • Improving on MLD for BSV Multicast Services
    • Web 3.0 Standard (at a high level)
    • Thoughts on the Mandala Network
    • Outputs, Overlays, and Scripts in the Mandala Network
  • State Machines
    • Simplifying State Machine Event Chains in Bitcoin
Powered by GitBook
On this page
  • Abstract
  • Motivation
  • Specification
  • P2P Transactions
  • P2P Payment Destination
  • Implementations
  • Auxiliary Information on Host and Capability Discovery
  • Paymail Addresses
  • Paymail Host Discovery
  • Paymail Capability Discovery

Was this helpful?

Edit on GitHub
Export as PDF
  1. Payments

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:

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

Was this helpful?

is a server-side package that hosts a set of compatible endpoints.

is a JavaScript client for interacting with the Paymail protocol.

is the Paymail client created by Project Babbage [deprecated (no longer in active use)].

Money Button Express Paymail
Money Button Paymail Client
AtFinder