What is Paymail?

Paymail is a mechanism to replace the use of bitcoin addresses with simple to remember email addresses. It was developed collaboratively at the Bitcoin Association wallet workshop in March 2019 by a group of wallet developers representing a significant portion of the Bitcoin SV wallet ecosystem. It was subsequently developed into a specification and first implemented by moneybutton with other wallets already preparing their implementations.
A key feature of paymail is cross wallet compatibility. Handcash pioneered the simple naming concept with $handcash handles. Centbee explored another option with their pay-to-contacts system. This was a quantum leap in usability but with important an limitation. These systems are limited to other users of the same wallet.
Briefly, how paymail works is to provide a mechanism for a sending wallet to take an email like identifier e.g. alice@wallet.com and discover an authorised REST endpoint that can give your wallet an output script to pay to whenever you want to send funds to Alice. This is a replacement for obtaining an ugly Bitcoin address from Alice and doesn’t need to be visible to the user at all.

Problems Paymail attempts to solve

No solution makes sense without a problem. So let's look at some of the key drivers behind paymail.

Address transfer

Whether in Bitcoin world or in the traditional finance world a transfer of funds or property has one key requirement. The sender and receiver must agree somehow on where the funds should be delivered to. For the transfer to be effective the receiver must have confidence that, at completion, they have sufficient control over the funds. The sender also wants confidence that if they hand over funds the receiver will consider the payment made and provide whatever goods or services are being paid for.
In the real world this is accomplished in different ways depending on circumstances. In person it might simply be handing over some cash to the shopkeeper. The assurance for both parties is provided by proximity. We assume the person behind the counter is a legitimate representative of the shop owner and is authorised to hand over the cup of coffee after payment. When ordering goods over the phone we rely on the fact that we dialled the phone number to give credence that the identity on the other end is in fact from the shop we want to purchase from. For a friend-to-friend transfer we might send them a bank account number by phone, email or some messaging app. Some of the security assumptions we are making in these processes seem relatively weak, yet the fact they are in such universal use around the world would indicate that they are very effective in practise
In Bitcoin world we traditionally send a bitcoin address from receiver to sender. It might be by QR code, NFC, copy/paste into a messaging system, BIP70 payment protocol, or even (if you like pain) by reading it out over the phone.

Address replacement attack

If we are security conscious, when using these mechanisms we should (but often don’t) consider the possibility of an address replacement attack. These attacks are also possible in traditional finance. Imagine if Alice sent you an email saying to give cash to Bob (who she trusts) on her behalf and the message was intercepted by Charlie (who is a wicked evil thieving bastard) and modified to tell you to give it to him instead.
The most commonly talked about type of Bitcoin theft is the stolen private key attack. Most of us have our private keys very well secured, perhaps even on air gapped hardware wallets. But all of this is for naught if at the time Alice goes to send funds to Bob, Charlie is able to sneak in and replace Bob’s Bitcoin address with his own. If Alice doesn’t notice this somehow, Charlie is fraudulently enriched whilst Alice loses her funds and probably doesn’t get what she was buying from Bob.
This issue was starkly highlighted by a vulnerability in Ledger hardware wallets in 2017 that allowed the client application (the weakest link) to be relatively easily modified by an attacker with access to your system. The attack was to simply modify the public key before it was sent to the hardware wallet for signing. If you didn’t check the address (which wasn’t possible with the firmware at the time) you could easily approve sending you funds to a thief without realising it. Private keys remained secure but funds could be diverted nonetheless.

User experience

Let’s face it, bitcoin addresses are ugly. And mechanisms of transfer are not very nice. Because they are long, ugly and hard to remember it is barely an option to use any means of transfer that doesn’t rely on machines.
This can be mitigated to some extent in person with QR codes or NFC. But it requires to both sender and receiver to have an active device and use them in an interactive way. What if the receiver doesn’t have their phone with them? What if there are no NFC devices? What if I want to transfer from phone to laptop but my laptop wallet doesn’t have a camera or support QR codes?
But even worse, what if I’m on the phone to someone? The remote case presents additional challenges. On the phone, forget it. I am limited to reciting a bitcoin address or finding a secondary communications mechanism. So while I’m on the phone I have to switch to speaker phone, change app to my wallet, generate an address, copy it, choose a communications mechanism (email, IM etc), switch to that, then paste. I’m also making a big assumption that the communication medium is secure and not subject to MITM address replacement.
What if I could just tell you to send funds to alice@wallet.com? That is what paymail enables. I don’t have to read out an unintelligible string. I don’t have to open my wallet. I don’t have to use (and trust) another messaging system. I don’t even need to have my wallet device with me (it could be a cold wallet)... and most importantly I can REMEMBER it. So can the receiver.
Imagine your friend is buying some concert tickets for both of you. You want to pay them for your ticket. Alice likes to save money so she wants the money to go to her savings wallet.
Handcash solved this problem with spectacular effect using handcash handles… Almost… The conversation with either go like this:
Bob: “Hey Alice I’ll pay for mine tonight when I get home, are you on Handcash?”
Alice: “Yes my handle is $alicesavings”
Or this:
Bob: “Hey Alice I’ll pay for mine tonight when I get home, are you on Handcash?”
Alice: “Sorry I use a different wallet”
Bob: *sad face*
Paymail eliminates the need to care what wallet each party is using. If you’re on the universal paymail system you don’t even need to know.
Bob: “Hey Alice I’ll pay for mine tonight when I get home, what’s your paymail address?”
Alice: “Thanks Bob it’s alicesavings@wallet.com”
Later that night Bob has everything he needs to make the payment and he probably didn’t even need to write anything down.

Address reuse

Privacy is a big deal to many people and one of the best ways to compromise it is by reusing Bitcoin addresses. It happens usually because it’s just easier. The scenario is usually that you have to give someone an address for multiple payments.

Common cases:

  • publishing a donation address on a website
  • entering a payout address for a mining pool
  • giving an address to a friend who reuses it because it’s easier than getting another one off you or simply not wanting to bother implementing a system that constantly generates new ones.
Paymail solves those problems by providing that system. As well as avoiding actually giving someone a Bitcoin address in the first place.
Imagine your donation address being payto:alice@wallet.com. Wallets that are aware of paymail will use the protocol to obtain an address for each payment. You’ve replaced a static address with a pointer to a dynamically changing one. You mining pool recognises paymail and gets a new address for each payment. Your friend can safely reuse your paymail address because their wallet knows to go fetch a new address whenever you use it.
Address reuse is a problem because it is easier to do than getting a new one. Paymail not only makes it easier to get a new address than to reuse and old one but also makes the overall system easier to use.

Address paradigm

Lastly, paymail doesn’t actually use addresses at all. It uses output scripts. Bitcoin addresses are actually an encoded form of an output script. But they are very limited to specific types of output scripts. In Bitcoin SV we want to get away from that. Bitcoin was designed to use an unlimited variety of output scripts and the fact that so much software is reliant on and limited to the Bitcoin address paradigm makes interoperability for application layer software with non-standard scripts hard if not impossible.
By making all wallets agnostic to output script type we eliminate a huge standards barrier for the exploration of the potential of unique payment types that make use of the flexibility of bitcoin script.

How does Paymail solve these problems?

We've got a problem, now for the solution. Solutions are rarely one size fits all so we have some minor variations.

Two key cases

For the purposes of this article we will consider two key cases that we think cover most of the ways paymail is likely to be deployed

Case 1: Domain owner hosting (“Self-hosted”)

This where the paymail service service itself for alice@wallet.com is hosted by the owner of the wallet.com domain. This is most likely to be a managed service where users delegate the hosting to a third party but may also be used by a hobbyist that wants to host their own paymail service. This might be desirable if your privacy requirements extend so far as to not want to let a paymail service provider see your public keys.

Case 2: Delegated hosting (“Delegated”)

This is where the owner of a domain does not wish to deal with the hassle of hosting the paymail service themself but wishes to use their own domain. For example I might want to use the address steve@shadderspaymail.com (that’s NOT a real paymail address BTW so no presents please) but I want to make use of moneybutton’s infrastructure to host my paymail service. This is somewhat analogous to Google’s GSuite where I can use Gmail infrastructure with my own domain.


Before we describe the process we will establish two key security assumptions that we are making in analysing this model.
  1. HTTPS (and by extension TLS) is a secure enough method to establish that you are in fact talking to the owner of the domain you’re making requests to and not a MITM
  2. DNSSEC provides assurance that the client’s DNS lookup has pointed to a server that the domain owner intended
All security is a probabilistic and where trust is concerned an assumption at the source of trust is always required. But we will examine the limits of this trust and whether it practically matters for our purposes later in this post.

The two keys steps

The full paymail spec is published at https://bsvalias.org/
I don’t propose to go into fine grained detail of the spec here but to describe the phases. When Bob’s wallet wants to make a payment to alice@wallet.com it begins first with:

Service discovery

This is achieved by using DNS to lookup an SRV record for _bsvalias._tcp.wallet.com
In the Self-hosted case the domain SHOULD be DNSSEC enabled (the protections involved are somewhat replicated by another mechanism which is why this is not a MUST).
In the Delegated case the domain MUST be DNSSEC enabled
This lookup returns nothing more than a host and port where the paymail discovery process should begin from. We now check that returned ‘wallet.com’ is the same as the paymail address domain ‘wallet.com’. In this case it is and we CAN rely on TLS for identity confirmation*. If it is not we cannot rely on TLS and MUST rely on DNSSEC*. In this case if the client doesn’t confirm DNSSEC is enabled and valid for the domain, the paymail client (sender) MUST fail the process* as we have no assurance that we have been directed to the correct server and may be vulnerable to address replacement attacks.
The next step is to use HTTPS (HTTP is NOT allowed) to request a predetermined URL in the form:
In our case the URL will be:
Without going into too much detail (it’s described here: https://bsvalias.org/04-01-basic-address-resolution.html), the information returned from this URL will be enough to determine how to make a paymail call to get an output script to pay alice@wallet.com. This will almost certainly be on the same domain (wallet.com) that the host discovery lead us to. If not additional security measures will be required. At this point the paymail spec doesn’t address or support this case.

Address resolution

The final step is to get the output script for Alice which requires a REST call to the URL determined from the above service discovery process. We have already determined whether we have chosen to trust the host by this point. So all that remains is validation of the public key on the server side which is an internal implementation detail rather than one that belongs in the paymail spec.

The final step

Is very simple. The sender constructs a transaction using the given output script and adds their own change output. Of course there is also the step where they send it but that’s a story for another day…
Here endeth part 1 where we have explored the drivers behind the development of the paymail standard and elaborated on the basics of the address resolution process. In part 2 we will examine the security assumptions of this model in more detail and answer some FAQs like:
  • But DNSSEC is horrible and no one uses it?
  • What happens when CA’s are compromised?
  • What if my paymail service provider goes rogue?

We’ll consider both the security model and these questions. Not just from a cryptographic perspective but also taking into account real world factors like behaviour, incentives and of course the great litmus test of risk assessment: “What’s the worst that could happen?”.
* note this is not explicitly called out in the spec although it is was always assumed by the paymail working party and is implicit in the first implementation as well as the release presentation. This will be resolved in a forthcoming update to the spec.


5 of 6 reviewers say it's worth paying for

1 of 6 reviewers say it's not worth paying for