Skip to main content

Announcement: a new PayNym directory

— Ashigaru Open Source Project

Overview

PayNyms are a Samourai Wallet implementation of BIP47, also known as “Reusable Payment Codes for Hierarchical Deterministic Wallets” which was a proposal by Justus Ranvier that enables users to create a unique and publicly shareable ID derived from a wallet seed. Unlike ordinary Bitcoin addresses, a BIP47 reusable payment code is used by a sender and receiver to generate a new address every time a payment is made by combining their codes. By eliminating address reuse, this avoids users revealing their balance and transaction history as they would if they posted a regular, static Bitcoin address publicly. It also removes the need for a sender to communicate out of band to the receiver when making repeat payments and allows a receiver to refund to a sender.

As Payment Codes are long and difficult to remember or recognise, the PayNym directory that Samourai have hosted since 2018 has provided a much needed UX improvement to these identifiers by using a hashing algorithm to create a short, Heroku-like name and robot avatar that is unique yet memorable for any payment code claimed by a user. In addition to being viewable on the paynym[dot]is site, an API has been available for other wallets and services to use, so those implementing BIP47 can leverage the user friendly PayNym representation of the IDs in their applications. PayNyms have been adopted by both Sparrow Wallet and Stack Wallet and can be used for pay outs for those directing hash to the Lincoin Mining pool.

However, the Ashigaru Open Source Project does not have access to Samourai’s infrastructure nor is it known for how long this server will remain operational. We have therefore decided to build our own directory hosted at paynym[dot]rs which has required research into the existing open source wallet codebases that use the current server so an optimal path for migration can be offered. It is not possible to replicate exactly the existing PayNym names and avatars that are derived from BIP47 reusable payment codes, as they are not deterministic and we believe the server plays a role in ensuring collisions are avoided. Although we could use the Haikunator and Robohash open source libraries to create a similar scheme, we believe this would cause a good deal of confusion.

We have, therefore, developed a new naming and avatar scheme which differentiates itself from the "old" scheme, retains some familiarity, provides some improvements and, we hope, pays homage to the team whose shoulders we stand on.

New PayNym name scheme

New PayNym names are constructed using:

    • Adjective
    • Noun
    • Two digit integer

For example: +bustlingmarket36

The new scheme uses a larger adjective and noun list than Samourai’s with no overlap of their word-list so it can be differentiated. This provides better scalability due to the greater number of combinations and allows us to not append the words with a hex character scheme which is case sensitive and less easy to recall than numbers only.

New PayNym avatar scheme

When claiming your wallet PayNym you are simultaneously assigned an avatar. We call our new scheme “Pepehash” and the Samurai Pepe takes inspiration from the early Bitcoin memes, Rare Pepes and other art published on the Counterparty marketplace that has been prevalent over the last few years.

Every Pepehash is made up of:

    • Background
    • Pepe head
    • Eyes or glasses
    • Mouth
    • Suit of armor

Each of these elements vary in color and pattern, and we believe are an improvement over Robohash bots due to their uniqueness and human-like expressiveness. Moreover Pepehash has over 15 times more possible combinations as compared to Robohash bot avatars.

BIP47 connections

Restoring from a samourai.txt file is the most reliable way to ensure all connection metadata is recovered in the Ashigaru mobile app as the file includes incoming and outgoing connections together with nicknames applied to PayNyms by the user in-app. For those that have already been using BIP47 to receive direct payments from an incoming connection, moving to the Ashigaru mobile application should be a smooth transition. Bitcoin received to a reusable payment code has no dependency on a PayNym server. If restoring from Samourai, Sparrow or Stack Wallet into Ashigaru, incoming bitcoin received will be recovered with no loss of funds.

Outgoing BIP47 connections, as not retrievable from a single notification address like incoming connections, require querying transaction history to restore. The PayNym server is utilised by the wallet to check for BIP47 codes that the user is following, retrieve notification addresses, then cross reference against addresses that have been spent to. During recovery, the new Ashigaru Wallet Syncing screen will show the progress of connection recovery. It is also possible to "Sync all payment codes" from the PayNym screen which will attempt again to fetch any outgoing BIP47 connections. In the case of outgoing connections not being restored, either due to the PayNym server not being available or not having all followed PayNyms present in our new server, there is no risk to loss of funds. At any time, a user can connect to a BIP47 reusable payment code by broadcasting a notification transaction, which will re-establish any previously lost outgoing BIP47 connection.

Data population in the new server

In order to make the transition to the PayNym wallet server straightforward for other wallets and services, the Ashigaru Open Source Project has replicated the same API endpoints as the old server together with creating a publicly accessible website. We utilised the capabilities of the API that provides existing PayNym "following" data to subscribing clients so we could migrate metadata from paynym[dot]is to our new one. Although it is not possible to guarantee that all data has been migrated, our methodology is likely to have captured all active wallets.

This was achieved by using the "+samouraiwallet" PayNym as an “anchor” with its 12,000+ followers. For each of these followers we were able to obtain their PayNym followers and those that they were following and replicate this logic for each of those PayNyms. This process was iterated through for all degrees of connection from the anchor PayNym. This has allowed us to populate our database with ~ 17,500 PayNyms and their respective followers. While this data is not essential for BIP47 to function correctly, it reduces the need for users to broadcast further transactions to re-establish connections again if they are missing any, and provides users with most, if not all, of the contacts they would communicate with using the Soroban protocol.

An invitation to developers

Our assessment is our new PayNym server uses the same API endpoints as the one hosted by Samourai, so there should be minimal impact on migration.

New clients/services can begin to use paynym[dot]rs immediately and existing wallet clients/services can move over at a time of their convenience until the old server is no longer available.

The PayNym site and API is accessible both via clearnet and via a Tor hidden service.

Should you have any development related queries, you may reach out via encrypted communications using the contact method here.