This document covers the basics of Kusama accounts. See the Advanced Account page for more information about accounts such as account derivation and indices. For a more in-depth explanation of the cryptography behind Kusama accounts, please see the cryptography page.
An address is the public part of a Kusama account. The private part is the key used to access this address. The public and private parts together make up a Kusama account. You can think of the public address of your account like your mailbox and the private key like the key to open that mailbox. Anybody can send mail to your mailbox, but only you can access them as only you have access to its key. In the context of Kusama accounts, anybody can send tokens to your public address but only you can transact with them using your private key. That is why you should keep your private key secret.
Mnemonic and Address Generation
A valid account requires a private key that can sign on to one of the supported curves and signature schemes. Without a private key an account cannot sign anything. In Kusama there are some exceptions of accounts that do not have private keys (i.e. key-less accounts). Such accounts are multi-signature accounts and anonymous proxies that are not discussed here and are meant for an advanced audience.
Most wallets generate a mnemonic phrase for users to back up their wallets and generate a private key from the mnemonic. Not all wallets use the same algorithm to convert from mnemonic phrase to private key, which affects the ability to use the same mnemonic phrase in multiple wallets. Wallets that use different measures will arrive at a different set of addresses from the exact mnemonic phrase.
Subkey and Polkadot-JS based wallets use the BIP39 dictionary for mnemonic generation, but use the entropy byte array to generate the private key, while full BIP39 wallets (like Ledger) use 2048 rounds of PBKDF2 on the mnemonic. The same mnemonic may generate different private keys on other wallets due to the various cryptographic algorithms used. See Substrate BIP39 Repo for more information.
A typical mnemonic phrase generated by the Subkey tool is shown below.
'caution juice atom organ advance problem want pledge someone senior holiday very'
Its corresponding private/public keypair is also shown.
Secret seed (Private key): 0x056a6a4e203766ffbea3146967ef25e9daf677b14dc6f6ed8919b1983c9bebbc
Public key (SS58): 5F3sa2TJAWMqDhXG6jhV4N8ko9SxwGy8TpaNS1repo5EYjQX
Polkadot default address format is the
MultiAddress type. This means that the same mnemonic phrase
will generate public keys for different parachains. For more information see the
Address Format section on the
Advanced Account page.
Obtaining and Managing an Address
To learn more about generating accounts on Kusama visit the Account Generation page.
Account Balance Types
In Kusama there are different types of balance depending on the account activity. Different balance types indicate whether your balance can be used for transfers, to pay fees, or must remain frozen and unused due to an on-chain requirement. Below we give an example of different balance types on Kusama
- The total balance indicates the total number of tokens in the account. Note that this number does not necessarily correspond to the tokens you are allowed to transfer. In the example the total number of tokens in 0.6274 KSM. The transferrable balance indicates the number of tokens that are free to be transferred. This is calculated by subtracting the number of locked and reserved tokens from the total number of tokens. Locked funds correspond to tokens used in staking, governance, and vested transfers (see below). In the example, the transferrable balance is 0.0106 KSM.
- The vested balance indicates tokens that were sent to the account and that are released with a specific time schedule. The tokens are owned by the account but are locked and become available for transfer after a specific number of blocks. In the example, the vested balance is 0.25 KSM.
- The bonded balance indicates the number of tokens that are locked for on-chain participation to staking. In the example the bonded balance is 0.4 KSM.
- The democracy balance indicates the number of tokens that are locked for on-chain participation to democracy (i.e. voting for referenda and council). In the example, the democracy balance is 0.4 KSM.
- The redeemable balance indicates the number of tokens that are ready to be unlocked to become transferrable again. Those tokens already went through the unbonding period. In this case, the redeemable balance is 0.1 KSM.
- The locked balance indicates the number of tokens that are frozen for on-chain participation to staking and democracy, or for vested transfers. Locks do not stack, which means that if you have different locks the total locked balance is not the addition of all single locks. Instead, the biggest lock decides the total locked balance. In the example, the locked balance is 0.55 KSM because the biggest lock is on democracy (0.55 KSM).
- The reserved balance indicates the number of tokens that are frozen for on-chain activity other than staking, governance, and vested transfers. Such activity can be setting an identity or a proxy. Reserved funds are held due to on-chain requirements and can usually be freed by taking some on-chain action. For example, the "Identity" pallet reserves funds while an on-chain identity is registered, but by clearing the identity, you can unreserve the funds and make them free again. The same applies to proxies. The idea is that those actions require some network memory usage that is not given for free. In the example we created a governance proxy and the reserved funds for this are 0.0668 KSM.
The biggest lock decides the total amount of locked funds. See this walk-through video tutorial that will guide you in the process of unlocking funds in the example above.
In the example, we mentioned that the locked balance is 0.55 KSM because the biggest lock is on democracy and is 0.55 KSM. As soon as the democracy lock is removed the next biggest lock is on staking 0.5 KSM (bonded 0.4 KSM + redeemable 0.1 KSM). This means that the locked balance will be 0.5 KSM, and 0.05 KSM will be added to the transferrable balance. After redeeming the unbonded 0.1 KSM, the locked balance will be 0.4 KSM, and an additional 0.1 KSM will be added to the transferrable balance. Now the biggest lock is still the bonded one. This means that even if we remove the vested lock, the locked balance will still be 0.4 KSM and no tokens will be added to the transferrable balance. To free those bonded tokens we will need to unbond them and wait for the unbonding period to make them redeemable. If we remove the proxy the reserved funds will be automatically added to the transferrable balance.
Existential Deposit and Reaping
When you generate an account (address), you only generate a key that lets you access it. The account does not exist yet on-chain. For that, it needs the existential deposit of .
Having an account go below the existential deposit causes that account to be reaped. The account will be wiped from the blockchain's state to conserve space, along with any funds in that address. You do not lose access to the reaped address - as long as you have your private key or recovery phrase, you can still use the address - but it needs a top-up of another existential deposit to be able to interact with the chain.
Transaction fees cannot cause an account to be reaped. Since fees are deducted from the account before any other transaction logic, accounts with balances equal to the existential deposit cannot construct a valid transaction. Additional funds will need to be added to cover the transaction fees.
Here's another way to think about existential deposits. Ever notice those
Thumbs.db files on
.DS_Store files on Mac? Those are junk; they serve no specific purpose other than
making previews a bit faster. If a folder is empty saved for such a file, you can remove the folder
to clear the junk off your hard drive. That does not mean you lose access to this folder forever -
you can always recreate it. You have the key, after all - you're the computer's owner. It just
means you want to keep your computer clean until you maybe end up needing this folder again and then
recreate it. Your address is like this folder - it gets removed from the chain when nothing is in it
but gets put back when it has the existential deposit.
The Identities pallet built into Polkadot allows users to attach on-chain metadata to their accounts. Independent registrars can verify this metadata to provide trustworthiness.
To learn more about how to set or release an identity, how to define sub-accounts, or how to become a registrar, please read this guide.
Polkadot comes with a generalized proxy account system that allows users to keep keys in cold storage while proxies act on their behalf with restricted (or unrestricted) functionality.
See the proxies page for more information about proxies.
Multi-signature accounts are accounts created from several standard accounts, pure proxies, and even other multi-sig accounts.
See the Multi-signature accounts page for a full explanation about multi-signature accounts, including their use-cases.
- Understanding Accounts and Keys in Polkadot - An explanation of what the different kinds of accounts and keys are used for in Polkadot, with Bill Laboon and Chinmay Patel of BlockX Labs.