Polkadot Accounts
This document covers the basics of Polkadot 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 Polkadot accounts, please see the cryptography page.
Account Address
An address is the public part of a Polkadot account. The private part is the key used to access this address. The public and private parts together make up a Polkadot 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 Polkadot 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 Polkadot 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.
NOT ALL WALLETS USE THE SAME ALGORITHM TO CONVERT FROM MNEMONIC PHRASE TO PRIVATE KEY
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.
Its corresponding private/public keypair is also shown.
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
INFO
To learn more about generating accounts on Polkadot visit the Account Generation page.
Account Balance Types
In Polkadot 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 is an example that displays different balance types of a Kusama account in the Accounts tab of the Polkadot-JS UI (note that the balance types are the same for a Polkadot account).
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.
Query Account Data in Polkadot-JS
In the Polkadot-JS UI, you can also query account data under Developer > Chain state. Under selected state query choose the system pallet followed by account(AccountId32): FrameSystemAccountInfo, under Option choose an account, and then click on the "+" button on the right.
Account information include:
nonce, the number of transactions the account sent.consumers, the number of other modules that currently depend on this account's existence. The account cannot be reaped until this is zero.providers, the number of other modules that allow this account to exist. The account may not be reaped until this andsufficientsare both zero.sufficients, the number of modules that allow this account to exist for their own purposes. The account may not be reaped until this andprovidersare both zero.data, the additional data that belongs to this account. Used to store the balance(s) in a lot of chains.
More in-depth information about the above data can be found in the substrate code base.
The AccountData structure defines the balance types in Substrate. The three types of balances include free, reserved, and frozen. The usable balance of the account is the amount that is free minus any funds considered frozen, while the total balance of the account is the sum of free and reserved funds. The flags describe extra information about the account.
More in-depth information about the above data can be found in the balances pallet in the Substrate code base.
Unlocking Locks
LOCKS DO NOT STACK!
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
INFO
See this video tutorial or visit this support page for more information about existential deposit.
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 1 DOT.
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 Windows or .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.
Account Identity
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.
INFO
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.
Proxy Accounts
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.
INFO
See the proxies page for more information about proxies.
Multi-signature Accounts
Multi-signature accounts are accounts created from several standard accounts, pure proxies, and even other multi-sig accounts.
INFO
See the Multi-signature accounts page for a full explanation about multi-signature accounts, including their use-cases.
Resources
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.
Last updated