Skip to main content

Summary

This document proposes an extendable address format for the IOTA protocol supporting various signature schemes and address types. It relies on the Bech32 format to provide a compact, human-readable encoding with strong error correction guarantees.

Motivation

With Chrysalis, IOTA started using Ed25519 to generate digital signatures, in which addresses correspond to a BLAKE2b-256 hash. It is necessary to define a universal and extendable address format capable of encoding different types of addresses (introduced also in TIP-18).

The legacy IOTA protocol (1.0, pre-Chrysalis) relies on Base27 addresses with a truncated Kerl checksum. However, both the character set and the checksum algorithm have limitations:

  • Base27 is designed for ternary and is ill-suited for binary data.
  • The Kerl hash function also requires ternary input. Further, it is slow and provides no error-detection guarantees.
  • It does not support the addition of version or type information to distinguish between different kinds of addresses with the same length.

All of these points are addressed in the Bech32 format introduced in BIP-0173: In addition to the usage of the human-friendly Base32 encoding with an optimized character set, it implements a BCH code that guarantees detection of any error affecting at most four characters and has less than a 1 in 109 chance of failing to detect more errors.

This TIP proposes a simple and extendable binary serialization for addresses of different types that is then Bech32 encoded to provide a unique appearance for human-facing applications such as wallets.

Detailed design

Binary serialization​

The address format uses a simple serialization scheme which consists of two parts:

  • The first byte describes the type of the address.
  • The remaining bytes contain the type-specific raw address bytes.

Currently, only three kind of addresses are supported:

  • Ed25519, where the address consists of the BLAKE2b-256 hash of the Ed25519 public key.
  • Alias, where the address consists of the BLAKE2b-256 hash of the Output ID (defined in TIP-0020) that created the alias.
  • NFT, where the address consists of the BLAKE2b-256 hash of the Output ID (defined in TIP-0020) that created the NFT.

They are serialized as follows:

TypeFirst byteAddress bytes
Ed255190x0032 bytes: The BLAKE2b-256 hash of the Ed25519 public key.
Alias0x0832 bytes: The BLAKE2b-256 hash of the Output ID that created the alias.
NFT0x1032 bytes: The BLAKE2b-256 hash of the Output ID that created the NFT.

Bech32 for human-readable encoding​

The human-readable encoding of the address is Bech32 (as described in BIP-0173). A Bech32 string is at most 90 characters long and consists of:

  • The human-readable part (HRP), which conveys the protocol and distinguishes between the different networks. HRPs are registered in SLIP-0173:
    • iota is the human-readable part for IOTA Mainnet addresses (IOTA tokens)
    • atoi is the human-readable part for IOTA Testnet/Devnet addresses
    • smr is the human-readable part for Shimmer network addresses (Shimmer tokens)
    • rms is the human-readable part for Shimmer Testnet/Devnet addresses
  • The separator, which is always 1.
  • The data part, which consists of the Base32 encoded serialized address and the 6-character checksum.

Examples​

  • Ed25519 Address
    • Ed25519 public key (32-byte): 6f1581709bb7b1ef030d210db18e3b0ba1c776fba65d8cdaad05415142d189f8
    • BLAKE2b-256 hash (32-byte): efdc112efe262b304bcf379b26c31bad029f616ee3ec4aa6345a366e4c9e43a3
    • serialized (33-byte): 00efdc112efe262b304bcf379b26c31bad029f616ee3ec4aa6345a366e4c9e43a3
    • Bech32 string:
      • IOTA (64-char):iota1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xqgyzyx
      • IOTA Testnet (64-char): atoi1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6x8x4r7t
      • Shimmer (63-char): smr1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xhcazjh
      • Shimmer Testnet: (63-char) rms1qrhacyfwlcnzkvzteumekfkrrwks98mpdm37cj4xx3drvmjvnep6xrlkcfw
  • Alias Address
    • Output ID (34-byte): 52fdfc072182654f163f5f0f9a621d729566c74d10037c4d7bbb0407d1e2c6490000
    • Alias ID, BLAKE2b-256 hash (32-byte): fe80c2eb7c736da2f7c98ecf135ee9e34e4e076afe6e1dfebc9ec578b8f56d2f
    • serialized (33-byte): 08fe80c2eb7c736da2f7c98ecf135ee9e34e4e076afe6e1dfebc9ec578b8f56d2f
    • Bech32 string:
      • IOTA (64-char): iota1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj76j6rev
      • IOTA Testnet (64-char): atoi1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj7autzrp
      • Shimmer (63-char): smr1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj7dzrr0a
      • Shimmer Testnet (63-char): rms1prlgpsht03ekmghhex8v7y67a835uns8dtlxu807hj0v279c74kj7e9ge5y
  • NFT Address
    • Output ID (34-byte): 97b9d84d33419199483daab1f81ddccdeff478b6ee9040cfe026c517f67757880000
    • NFT ID, BLAKE2b-256 hash (32-byte): 3159b115e27128b6db16db5e61f1aa4c70d84a99be753faa3ee70d9ad9c6a6b7
    • serialized (33-byte): 103159b115e27128b6db16db5e61f1aa4c70d84a99be753faa3ee70d9ad9c6a6b7
    • Bech32 string:
      • IOTA (64-char): iota1zqc4nvg4ufcj3dkmzmd4uc034fx8pkz2nxl820a28mnsmxkec6ntw0vklm7
      • IOTA Testnet (64-char): atoi1zqc4nvg4ufcj3dkmzmd4uc034fx8pkz2nxl820a28mnsmxkec6ntwgz87pn
      • Shimmer (63-char): smr1zqc4nvg4ufcj3dkmzmd4uc034fx8pkz2nxl820a28mnsmxkec6ntwcu0ld0
      • Shimmer Testnet (63-char): rms1zqc4nvg4ufcj3dkmzmd4uc034fx8pkz2nxl820a28mnsmxkec6ntwvmy9kk

Drawbacks

  • Addresses look fundamentally different from the established 81-tryte legacy IOTA addresses. However, since the switch from binary to ternary and Chrysalis in general was a substantial change, this is a very reasonable and desired consequence.
  • A four character HRP plus one type byte only leaves a maximum of 48 bytes for the actual address.

Rationale and alternatives

  • There are several ways to convert the binary serialization into a human-readable format, e.g. Base58 or hexadecimal. The Bech32 format, however, offers the best compromise between compactness and error correction guarantees. A more detailed motivation can be found in BIP-0173 Motivation.
  • The binary serialization itself must be as compact as possible while still allowing you to distinguish between different address types of the same byte length. As such, the introduction of a version byte offers support for up to 256 different kinds of addresses at only the cost of one single byte.

Reference implementation

Example Go implementation in wollac/iota-crypto-demo:

Example Go implementation in iotaledger/iota.go/v3:

Copyright

Copyright and related rights waived via CC0.