QRL Primary Report, 2024

Read More

QRL Improvement Proposal (QIP-018)

Better format of wallet addresses

Overview & status

AuthorRobert Pösel (@robyer)
Statusdraft incomplete
Discussions tohttps://github.com/theQRL/qips/pull/44/


The QRL wallet addresses are currently represented as 79 characters strings. Such a long length has many disadvantages for the users. This QIP proposes use of more efficient encoding for address representation to make it shorter (64 characters) and user-friendly. It doesn’t require any changes to the internal wallet format, therefore it doesn’t affect internal APIs or security, and backwards compatibility is easily maintained.

There is currently new upgrade to QRL in the works (codename Zond), and since the format of wallet addresses is already changed there, it makes sense to apply this proposal only to Zond and keep the current version of QRL intact. That way the wallet addresses will be changed only once - with release of Zond (ideally with the first testnet release).

Note: Same encoding change should be applied to the Transaction IDs as well (separate QIP will be created for that).


There are many inconveniences associated with long addresses, for example:

  • Visual inspection of the address
    • Before user confirms an outgoing transaction, they should carefully check that the recipient’s address is correct. But the longer the address, the more annoying this activity is. As a result, user will probably check only the last few characters (which can be abused by bad actors generating addresses similar in this part), or just generally be less careful, increasing the probability of making a mistake.
  • Manual writing of the address
    • This has same problems as visual inspection, plus it’s more annoying to manually type the address somewhere. It is not always possible to rely on QR codes and their scanning, and sometimes it is simply necessary to write it down manually - whether on a computer/phone, or perhaps on a paper.
  • Bloated user interface in applications
    • Wherever a long address is used, a large amount of space must be reserved for it in the user interface. Either to show an input field for destination address, or to show user’s address to copy it, or having addresses in a list of transactions, in address book, in block explorer, etc.
    • It’s even worse on HW wallets, as they have small display sizes and user often needs to go through multiple screens to read the whole address.
  • Less friendly when compared to addresses of other cryptocurrencies
    • When people want to receive donations from others, they place their crypto addresses on the web, on their profiles, in a forum signatures or similar places. Not only do longer addresses take up more space (see the previous point), but in addition, when they are compared or placed next to (for example) a BTC address (34 or 42 or 62 characters) or an ETH address (42 characters), QRL addresses (79 characters) look more technical and less friendly.

It’s important to note that length is not the only aspect that must be considered here, but it is the main problem of current format. The addresses should be shorter AND user-friendly.


QRL currently uses wallet addresses starting with Q followed by 78 hexadecimal characters (0-9a-f - which is basically Base16 encoding).

Proposed format is keeping the q (but lower case) followed by 63 characters in z-base-32 encoding, which is more efficient and user-friendly (see the design considerations in the encoding specification).

For example current QRL addresses (79 characters):

  1. Q01070050d31c7f123995f097bc98209e9231d663dc26e06085df55dc2f6afe3c2cd62e8271a6bd
  2. Q0109003493192e08affe87d57e254df3e15be3b8709a40f07e0fc550de60696c2d0333f7070e1d

Would look like this (64 characters):

  1. qyrdoywgudt9trqci6nm53gbyu4jddiud5ouqyarf57k7am5k9a6n3itqoja4pxe
  2. qyrroyprudrzytm96o9kzhjkp6xoiza7aqnprbhd6b9nibzuypfsn4y3u6hdoh8e

Note that with QRL Zond it seems that addresses will be shorter - still having Q followed by 42 hexadecimal characters (in the docs is not yet reflected the Q prefix).

The planned Zond addresses (43 characters):

  1. Q1005003ea6ed78d597e7411a8ddbc2dffd8839e5
  2. Q20bf1acdae054f4194e0c132b489e8f9099caf8c

Would look like this (34 characters):

  1. qnynoyxig7ihpmf98erpe5s6n596aoqxf
  2. qrn9tiupqyi8wdf8yar3mjnxe9rr33mhc

To summary, change is only in the representation of the address (described in official docs for current version; for Zond they are not specified in the docs yet) to use (q + z-base-32 encoding) instead of (Q + base16 encoding).


The z-base-32 was created in 2002 as human-oriented base-32 encoding.

Citation from Wikipedia:

z-base-32 is a Base32 encoding designed by Zooko Wilcox-O’Hearn to be easier for human use and more compact. It includes 1, 8 and 9 but excludes l, v and 2. It also permutes the alphabet so that the easier characters are the ones that occur more frequently. It compactly encodes bitstrings whose length in bits is not a multiple of 8 and omits trailing padding characters. z-base-32 was used in the Mnet open source project, and is currently used in Phil Zimmermann’s ZRTP protocol, and in the Tahoe-LAFS open source project.

The full specification is here.

There are existing libraries for commonly used programming languages:

There are also online convertors, like here (you must switch the variant to z-base-32) or here.


Representing binary data to be human-readable is a common task and there are many different approaches which were created during the years. Wikipedia has a list of many of them. Creating new custom encoding format doesn’t make much sense, which leaves us to one of the existing ones.

For example original Bitcoin addresses used Base58 encoding (original reasoning), but there is a problem that it uses both lower and upper-case characters, which is not user-friendly. And Bitcoin later switched to a fully-lowercase format anyway.

Ethereum (and QRL currently) uses simply hexadecimal encoding, which is unnecessarily long and also less visually pleasant, as majority of the characters are numbers, which has full line height as capital letters and so they feel overwhelming and too technical. Additionally, QRL having first character (Q) uppercase while rest is lowercase is a bit inconvenient and inconsistent.

Other Base32 encodings has been considered for its nice balance between its length and user-friendliness, but the design decisions of the z-base-32 regarding human errors makes most sense, and because it’s fully lower-case, it makes it more visually pleasant (as opposite to fully upper-case Crockford’s Base32 encoding).

Backward compatibility

The addresses are parsed to a binary format at entry/exit points to the system, which is then used internally in communication between services, APIs, etc. This QIP proposes only visual change to the user-facing representation of wallet addresses, the internal format is unchanged, which keeps the addresses internally compatible. Only the part which handles parsing/formatting of wallet addresses must be changed in order to accept and produce the new format.

To provide the backward compatibility for user-facing forms, current apps/services should allow user to input addresses in both new and old formats. But the GUI should show only addresses in new format, everywhere. Additionally there could be created a simple conversion tool on the official website (and/or in official wallet apps) which would provide conversion from old to new format (and vice-versa) in case user needs to work with some old service or previously written address in old format.

Security Considerations

There are no security implications related to this change.