What are PayNyms?

‘PayNym’ is the Samourai Wallet implementation of BIP47 defined ‘Reusable Payment Codes’ by Justus Ranvier. A reusable payment code is essentially a publicly shareable ID, derived from your wallet seed and completely unique to you. With this payment code, anyone else using a BIP47 compatible wallet can combine their own unique code with yours to generate bitcoin addresses for the two of you to transact.

Currently, anyone wanting to receive Bitcoin donations or payments has three main choices…

  1. Post a static address on their profile or website (which is terrible for privacy)
  2. Manually generate a new address for each transaction (not scalable)
  3. Run a BTCPay server or something similar (the best option of the 3 but comes with a much higher barrier to entry)

PayNyms fix this problem.

Anyone using a Paynym can post their payment code anywhere they like and receive private payments, to a new address every time. No address reuse, no server requiring 24/7 up time and zero requirement to manually serve a fresh address to each new individual wanting to pay them.

Payment code or PayNym. What’s the difference?

The payment code is the BIP47 defined specification. The ‘PayNym’ ID you see within Samourai Wallet is simply a visual layer built on top to improve user experience and not integral to the underlying operation of the BIP.

Here is my payment code :-

PM8TJVfAKEmGWqDvikN8EYwTo8jnZze1fpCtHuhZzXFeq9bhf4KeV1te4fa7T9YyLvQuiVnNAhrXpvjnwFDuQ88Sdo4Q265YC4dGo6ArAWY5dHrj2tq4

Here is that same payment code represented in a QR code:-

Here is the PayNym bot that goes with it :-

How do PayNym’s work?

The cryptography underlying BIP47 Payment Codes is very technical and out of the scope of this introductory article. At a very high level, for Alice to donate to Bob via his payment code, the simplified flow works as follows :-

  1. Bob posts his PayNym on his website or social media account. He also shares the QR code version to make it easy for people to connect with him
  2. Alice opens her Samourai Wallet and scans Bob’s QR code
  3. Alice ‘follows’ Bob
  4. Alice also ‘connects’ with Bob (currently a 15,000 sats + miner fees)
  5. Alice waits for the connection transaction to receive 1 confirmation
  6. Alice can now construct a transaction with Bob and her wallet will generate an address that only Bob can spend from
  7. Alice can now continually send Bob as many payments as she likes, each one being delivered to a new address that only Bob controls

Here is what step 6 looks like under the hood.

Follow or Connect?

When interacting with any new PayNym in Samourai Wallet, you will initially be met with the option to ‘Follow’. This option is completely free and takes place over the Tor based ‘Soroban’ communication layer built by the Samourai Developer team. This step allows you and any other PayNym you follow to collaborate using the suite of Cahoots transactions the wallet offers.

After you have followed a PayNym, you will see an option to ‘Connect’ to them for a 15,000 sat (+ miner) fee. This connection (also referred to as the notification transaction) is what facilitates the information sharing between the two wallets to enable them to generate their unique Bitcoin addresses. This step can put some people off, however, in the recently proposed update to BIP47, plans are in place to remove this on chain footprint requirement and subsequently remove the need for any connection fee.

Why the robot?

As alluded to earlier, the robots you see plastered all over people’s Twitter are merely a visual representation of the underlying payment code generated by their Samourai Wallet. The bot is created by running a hashing algorithm on your unique payment code. This process ensures that every nym gets a unique name and bot. Besides looking cool, the idea behind the image and short name is to make your payment code memorable and much easier to share. For example, +billiwingsnow2B3 is far easier to share than

PM8TJSuwWRextp2hcwymFwKWzAuRkCqA25mKFQreV6NSHsnsfFHE1dkAFsEzc2a8Tibs6jsLrotfdr4Pu46pa3E69UY5Wjox2AMAwhgwmQW78g1SQXj.

The Samourai team maintain the website paynym.is which is a public directory of every nym claimed from a Samourai Wallet. This directory provides another easy way to share your ID. Simply append the paynym.is URL with your PayNym to find your Nym’s own web page like this paynym.is/+BQA.

What can my PayNym do?

Aside from private, repeat payments, Paynyms and the infrastructure being built around them provide multiple different use cases. They include :-

  • Paying/receiving wages in bitcoin
  • Private donations
  • A publicly shareable ID
  • Collaborate in Cahoots transactions over Soroban

PayNym Considerations

The current implementation of PayNyms do have a couple of minor drawbacks that you should be aware of.

The Connection Transaction

This is the 15,000 sat (+ miner fee) ‘initial’ transaction that connects you with your desired recipient. This is not required for participating in cahoots transactions, only for traditional Person A > Person B spends. The new proposal of the BIP removes the need for this connection transaction completely so keep your eyes peeled for that going live.

Here is a technical view of the connection transaction :-

No ‘Watch Only’

The structure of BIP47 dictates that a wallet requires your private keys to successfully derive the addresses between you and any other connected PayNyms. As such, you cannot have a ‘watch only’ version of any PayNym generated transactions.

How do I get a PayNym?

Any time you set up a new Samourai Wallet, you will be asked if you want to Claim your PayNym. If you already have a Samourai Wallet and haven’t yet used your PayNym, simply tap the blue + on the home screen and then hit PayNyms. From here you can see a list of the Nyms you currently follow and the Nyms that follow you. You can also open your QR code scanner to follow a new PayNym contact. (This can also be done by pasting in the raw payment code).

How do I get a custom PayNym?

You may have seen some PayNym’s with names or bot images that do not follow the standard format that Samourai Wallet typically generates. This is simply a manual change that the dev team kindly offer to make on the PayNym.is servers. Due to the manual nature of this change, the team does not make a habit of offering this as a request service and it has absolutlely zero to do with the underlying payment code.

Where can I learn more?

If you want to learn more about PayNyms or ask any BIP47 related questions, stop by the Samourai Wallet Telegram chat. If you already have a PayNym and want to put it to good use, stop by the Matrix or Telegram channels to find a cahoots partner.