last change to this doc - 11 Nov 2021


If you want to give feedback then the author of these notes is @dumdave on the Iota Discord server. This document is only to be used as a quick reference - the Official Iota Wiki is all you should rely on.

The IOTA address scheme 2021 - BIP32 - Ed25519 - Bech32

IMPORTANT. For all official Iota information, go to the main Iota website www.iota.org This is an unofficial site TangleDust.com which contains information about Iota along with guides to installing Iota nodes etc.

On April 21st 2021, Iota launched its new Chrysalis network with a new addressing scheme. See the Iota Blog for the launch of Chrysalis here.

The new desktop wallet is called Firefly and its website is firefly.iota.org which is the only place you should refer to to find out about it.

Please read the explanation on the official Wiki about the wallet Firefly Wallet - Wiki Explanation

Everything starts with a SEED.

[1] BIP39 SEED and SEED WORDS

Each unique IOTA Seed has a corresponding mnemonic sentence of 24 words, created by reference to the BIP39 Standard which stands for Bitcoin Improvement Proposal: 39. There is a standard word list with considerably more than 24 words in it, so any particular combination of 24 words is vanishingly unlikely to ever be duplicated. It might look like this invented one:

banana, fish, giraffe, frog, lantern, fix, sad, slippy,
duck, cushion, lightbulb, terror, magic, antelope, grass, goldfish
arrive, government, fridge, hat, sock, cat, drive, bored

When you first use Firefly you are presented with a random list of 24 words which you memorise (just joking) - which you probably write down in more than one place. There are many other ways to secure your seed - but for that read the official Firefly docs. This document is just about the address scheme.

CAUTION. Never share your seed with anyone - it would be like handing them all of your money.


[2] WALLETS

A wallet is a tool to safely and easily manage your secrets for you. This way a wallet can manage multiple seeds and profiles, with their associated private keys and addresses derived from the respective seeds and tokens associated with the respective addresses.

The official wallet for Iota is called Firefly (see above for links etc)

[3] Ed25519 Signatures

IOTA now uses the Ed25519 scheme for the signatures for its addresses, based on the EdDSA (Edwards-curve Digital Signature Algorithm). Here is a formal document ed25519.cr.yp.to

To create an Iota address, an Ed25519 public key is derived from the BIP39 SEED. One seed can be used to create multiple Iota addresses within one wallet.

Each Iota address has an associated private key. When a wallet initiates a transaction it can use that private key to prove that it is an authorised transaction for that Iota address, for example, spending funds.

IOTA uses Ed25519 as it verifies both single signatures and does batch verification (taking care of the remaining tokens) very quickly.

Ed25519 public keys are fixed length 32 bytes.


[4] Wallet IOTA ADDRESSES

A wallet can contain a collection of Iota addresses. A typical address might be as below. This one is the 'tip' address for the TangleDust.com website, so if you are already feeling that this guide is helping do please send a few Mi - just to test the system!

iota1qp2fgd7nn00x09lnru7lzya3a72khuqrw25yafc3ehhuz2ucykpgk8m0hum

Note the following, as explained further below.

[1] an address starts with the word: 'iota' plus one more character.

[2] an IOTA Address contains 64 characters

[3] the final 6 digits are a checksum that stop simple errors from causing problems

[4] the central part of 53 characters uses Bech32 encoding to hold an ed25519 public key of fixed length 32 bytes


[5] The Bech32 address format

Bech32 is a segwit address format specified by BIP 0173 - (Bitcoin Improvement Proposal 0173). Segwit is short for Segregated Witness - which we don't need to discuss further here.

Bech32 has the clever characteristic of taking an array of 8-bit unsigned integers (base 2^8=256) and converting this to an array of 5-bit unsigned integers (base 2^5=32). To understand this, look at the table below where there are 32 possible characters to be selected by choosing a particular row or column.

Bech32 character table

If you add up all of the lower case letters in the alphabet (26) and all of the single digit numbers (10) you get 36. Remove 'b' and 'o' and 'i' and '1', then there are just 32 - the Bech32 character set. Its use is explained below.

BUT the Iota gratuity address has 'i', 'o' and '1' in it! True - but there is a reason foir that.

The 64 characters in an Iota address are made up as follows:

iota  1   qp2fgd7nn00x09lnru7lzya3a72khuqrw25yafc3ehhuz2ucykpgk    8m0hum

The parts are:

Human readable part (4 chars) => iota

Witness version (witver 1 char) => 1

Payload (53 characters) => qp2fgd7nn00x09lnru7lzya3a72khuqrw25yafc3ehhuz2ucykpgk

Error check (6 chars) performed on the hrp+witver+payload => 8m0hum

So the payload has no banned characters. The 'human readable part' can have those characters as it is to make it easier humans to recognise an Iota address.

This is a really nice article on some of the maths involved: Article on Bech32 math. It says that "the 6 character checksum gives a chance of less than 1 in a billion that an invalid address is deemed correct, even if more than 4 errors are made".

[6] Converting 32 byte Ed25519 public key to 53 character Bech32 payload

This is not intended to be an overly technical description! Start with a 32 byte Ed25519 key and add some brief header info to indicate that an Ed25519 key is expected. => 33 bytes approx. Write the bits out in a row.

00000000   01010100  10010100  00110111 11010011  ...

Rewrite the digits into groups of 5.

00000  00001  01010  01001  01000  01101 11110 10011 ...

Turn this into a number between 0 and 31 (inclusive)

  0      1      10      9      8     13    30    19  ...

using the Bech32 character table above, find the Bech character:

  q      p       2      f      g      d     7     n   ...

actual payload = "qp2fgd7nn00x09lnru7lzya3a72khuqrw25yafc3ehhuz2ucykpgk"

The start point was 33 bytes approx. 33 x 8 = 264.

The end point is 53 chars, each 5 bits. 53 x 5 = 265.

Summary: Leaving aside fine detail, this explains how the Ed25519 32 byte public key turns into a 53 character Bech32 payload.




_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

End note - SSH Key Generation and Ed25519

Note. This is not relevant to Iota but answers a question raised of why a common Terminal action to create SSH keys does not appear to generate a 32 Byte public key.

Generating an ED25519 Key in your Terminal

Enter the following at the command prompt:

ssh-keygen -o -a 100 -t ed25519 -f ~/.ssh/id_ed25519 -C "john@example.com"

This is typical terminal output.


Generating public/private ed25519 key pair.

Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 

Your identification has been saved in /Users/xxxxxx/.ssh/id_ed25519.
Your public key has been saved in /Users/xxxxxx/.ssh/id_ed25519.pub.

The key fingerprint is:
SHA256:qVYtulEs3qcxTHnPX++GzukollllVoPgN6urmgwcUfI john@example.com

Looking in the given folder we get the private key:

-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEFFAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABA/6zuCHN
NwXozhez+Y7zstAAAAZAAAAAEAAAAzAAAAC3NzaC1lZDI1NTE5AAAAIPdwcvbYdYj5wubG
DBfFm/wGEn0kdX+Qd0AWRtE6bEW3AAAAoO/6OAHtB4w5MMQ7uChGNDN+bUU7mkpt0ZbW/t
vDXsPs/3hfjrw0ohodLlPklSy54uDSRgTrOJxQnlFlyBzRExGyN9dw5Yzy7V8DKHSDq/R2
3ZUdcGMiY1wrRXsL0/ZRw2y5k7l5ltPfc3340LJ8NJWoS29mMSka2eq2VIubmhrn+iCtES
GXnGXQk3L1/fxk2knRCOtSpmeLVpdhS1SOTOA=
-----END OPENSSH PRIVATE KEY-----

and the public key:

ssh-ed25519 AAAAC3NzaC1lSDI1NTE5AAAAIPdwcvbYdXj5wrrbGWBfFc/wGEn0kdX+Qd0AWRtE6bEW3 john@example.com

Stack Exchange answer on public key length

The link above provides some useful information: OpenSSH stores public keys as a line containing two or three space-separated fields: a type or algorithm name, a base64 encoded 'blob' which itself can contain multiple subfields, and an optional comment string. In the example above:

type or algorithm name: ssh-ed25519

optional comment string: john@example.com

blob: AAAAC3NzaC1lZDI1NTE5AAAAIPdwcvbYdXj5wubGWBfFm/wGEn0kdX+Qd0AWRtE6bEW3 => 68 characters in base 64 (which can be rewritten as 51 bytes - see below)

This is made up of a 15-byte string containing the algorithm name 'ssh-ed255219' (again), another 4-byte length, then a 32-byte value which is the actual public key value. 51 bytes is base64-encoded.

So there is an Ed25519 32-byte public key value here - it is just hidden a little.

Note. 68 chars in base 64 (which is 2 to the power 6) => 68 x 6 = 408 bits

51 bytes (which is 2 to the power 8) => 408 bits