Skip to content

CashAddr: Add support for token-aware cash addresses

This MR is the preferred alternative to !1595 (closed). Either this MR or !1595 (closed) are required before we can roll out CashTokens !1580 (closed). However, it can be merged after !1580 (closed).


This adds two new "address types" - TOKEN_PUBKEY (token-aware p2pkh, type=2) and TOKEN_SCRIPT (token-aware p2sh, type=3) to the cashaddress code. In cashaddress, the "address type" is encoded into the cashaddress string thus wallets wishing to signal token awareness will be required to advertise their addresses using these two new "address types", which affects how the final cashaddr string looks. For more details see the CashTokens v2.1 spec.

For example the following p2pkh:

  • bitcoincash:qr6m7j9njldwwzlg9v7v53unlr4jkmx6eylep8ekg2

Could also be encoded as signaling token-awareness and it would look like so:

  • bitcoincash:zr6m7j9njldwwzlg9v7v53unlr4jkmx6eycnjehshe

(Both of these addresses are identical destinations and would end up mapping to the same locking script on sends).

This MR contains all relevant changes such that the node can accept and parse the two new address types (beginning with z for p2pkh and r for p2sh), allowing the node wallet to send to these two new addresses. Unit tests were also updated to test the new functionality.

Additionally, the validateaddress RPC was slightly modified to add an extra key: istokenaware which may be useful.


  • The bitcoin-qt wallet (and the RPC wallet) store addresses internally in the wallet.dat as "legacy" strings thus the "token awareness" of an address you sent to is "lost" in the UI or in RPC wallet history. So if one were to send to a z address, when reading back the history one would be told it was a regular q address (same destination). This limitation will be fixed in subsequent work.
  • The node wallet itself doesn't advertise these new "token aware" addresses when you ask it for a new receiving address, since at the present time the wallet cannot actually manage and send tokens. The CashTokens spec says only wallets that can send tokens may advertise these new type=2 and type=3 addresses. In future work we may add support for managing and sending CashTokens, at which time we can update the wallet UI and RPC to always advertise "token aware" addresses (type=2 and type=3).

Test Plan

  • ninja all check-all
  • Run the GUI wallet and paste a "token aware" cash address into the send dialog and verify it is accepted.
    • This may require you to write code or to use the enclosed modified test/functional/test_framework/ to create a "token aware" cash address.
Edited by Calin Culianu

Merge request reports