diff --git a/docs/assets/balance-example-1.png b/docs/assets/balance-example-1.png new file mode 100644 index 000000000000..90efa5b8a8e6 Binary files /dev/null and b/docs/assets/balance-example-1.png differ diff --git a/docs/assets/balance-example-2.png b/docs/assets/balance-example-2.png new file mode 100644 index 000000000000..248344f5093a Binary files /dev/null and b/docs/assets/balance-example-2.png differ diff --git a/docs/assets/balance-example-3.png b/docs/assets/balance-example-3.png new file mode 100644 index 000000000000..9adcc111695b Binary files /dev/null and b/docs/assets/balance-example-3.png differ diff --git a/docs/assets/balance-example-4.png b/docs/assets/balance-example-4.png new file mode 100644 index 000000000000..cffd7b17b8fe Binary files /dev/null and b/docs/assets/balance-example-4.png differ diff --git a/docs/assets/locks-example-1.png b/docs/assets/locks-example-1.png new file mode 100644 index 000000000000..141dfc92175a Binary files /dev/null and b/docs/assets/locks-example-1.png differ diff --git a/docs/assets/locks-example-2.png b/docs/assets/locks-example-2.png new file mode 100644 index 000000000000..ee8c19307a13 Binary files /dev/null and b/docs/assets/locks-example-2.png differ diff --git a/docs/general/polkadotjs-ui.md b/docs/general/polkadotjs-ui.md index b8df9e44c456..0060fe1d36ca 100644 --- a/docs/general/polkadotjs-ui.md +++ b/docs/general/polkadotjs-ui.md @@ -33,7 +33,8 @@ In this section of the UI, you can see accounts injected from a browser extensio [**Polkadot-JS Extension**](./polkadotjs.md#polkadot-js-extension) or [**other in-browser wallets**](./wallets-and-extensions.md#browser-extensions). It is also possible to expand balance details and see different -[**account balance types**](../learn/learn-accounts.md#account-balance-types). You can also: +[**account balance types**](../learn/learn-account-balances.md#balance-types-on-polkadot-js). You +can also: - Add an account (this option must be enabled under [Settings](#settings)). Note that if you clear the cache of your browser, you will lose it, and you will need to recover it through seed phrase diff --git a/docs/learn/learn-account-balances.md b/docs/learn/learn-account-balances.md new file mode 100644 index 000000000000..0342ed4f8153 --- /dev/null +++ b/docs/learn/learn-account-balances.md @@ -0,0 +1,202 @@ +--- +id: learn-account-balances +title: Polkadot's Account Balances +sidebar_label: Account Balances +description: Polkadot's Account Balance Types. +keywords: [Polkadot, locks, balance, account] +slug: ../learn-account-balances +--- + +In {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :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. + +:::info A more efficient use of wallet balances + +Soon Polkadot SDK pallets will implement the _fungible_ trait (see +[Rust Book](https://doc.rust-lang.org/book/ch10-02-traits.html) for more info about traits). This +new logic will allow for more efficient use of your wallet balance. Specifically, the +[fungible trait](https://github.com/paritytech/polkadot-sdk/issues/1833#issuecomment-1805764506) +will allow to use of the `free` balance for on-chain activity like setting proxies and identities. + +::: + +There are 5 types of balances + +- **Free** is the balance is the balance that can be used for on-chain activity but is not + necessarily spendable (or transferrable) +- **Frozen** is the free balance locked for [staking](./learn-staking.md), + [governance](./learn-polkadot-opengov.md), and [vesting](./learn-transactions.md#vested-transfers) + (also called locked balance) +- **On hold** is used for [identities](./learn-identity.md), [proxies](./learn-proxies.md), + [OpenGov preimages and deposits](./learn-guides-polkadot-opengov.md#claiming-opengov-deposits), + and it is no longer free (also called reserved balance) +- **Spendable** is the free balance that can be spent +- **Untouchable** is the portion of the free balance that cannot be moved (i.e. not spendable), but + can still be used for on-chain activity + +The spendable balance is calculated as follows: + +``` +spendable = free - max(frozen - on_hold, ED) +``` + +where `free`, `frozen` and `on_hold` are defined above. The `ED` is the the +[existential deposit](./learn-accounts.md#existential-deposit-and-reaping). + +**Wallet providers might just show you the spendable, locked and reserved balance.** + +## Example of Wallet Balance + +Here below there is an example of how a wallet balance composition changes depending user actions. +Let’s take for example a wallet with 100 DOT. + +``` +Free: 100 DOT +Frozen: 0 DOT +On hold: 0 DOT +Spendable: 99 DOT +Untouchable: 1 DOT (ED) +``` + +![balance-example-1](../assets/balance-example-1.png) + +In this case, the existential deposit of 1 DOT is untouchable (meaning you can’t touch it if the +account can’t or shouldn’t get reaped). We stake 80 DOT, and we get the following balance structure: + +``` +Free: 100 DOT +Frozen : 80 DOT +Onhold: 0 DOT +Spendable: 20 DOT +Untouchable: 80 DOT +``` + +![balance-example-2](../assets/balance-example-2.png) + +The spendable balance would be 20 DOT (- transaction fees). + +Note how the account cannot be reaped from the state while it has a frozen balance, or in general +any [consumer and provider reference](./learn-guides-accounts.md#query-account-data-in-polkadot-js). +Those references determine if an account can be reaped, usually because there are other accounts +depending on the existence of such an account). For example, the existential deposit adds a provider +reference simply because the account exists, while a proxy account adds a consumer reference (the +proxy existence depends on the existence of the proxied account, the proxy is the consumer). + +If the account creates a proxy, it will use the `free` balance as shown below. + +``` +Free: 80 DOT +Frozen : 80 DOT +Onhold: 20 DOT +Spendable: 20 DOT +Untouchable: 60 DOT +``` + +![balance-example-3](../assets/balance-example-3.png) + +**Note how (through the fungible trait) the system uses the `balance` that is frozen, instead of the +`free` balance that is spendable (present situation).** In other words, holds are subtracted from +free, but they overlap with the frozen balance. The free portion shrinks from 100 to 80 DOT, and the +`on_hold` portion increases from 0 to 20 DOT. The creation of an identity will grow the `on_hold` +portion to 40 DOT, and shrink further the `free` from 80 to 60 DOT. Note how in the process, the +spendable balance stays the same. + +``` +Free: 60 DOT +Frozen: 80 DOT +Onhold: 40 DOT +Spendable: 20 DOT +Untouchable: 40 DOT +``` + +![balance-example-4](../assets/balance-example-4.png) + +This update using the fungible trait allows the use of the frozen balance for on-chain activity like +setting up proxies and identities. Note that +[holds are slashable](https://github.com/paritytech/substrate/pull/12951), and the pallet +[migrations](https://github.com/paritytech/polkadot-sdk/issues/226) need to take that into account. +This means that freezes should account for hold being slashed (for example your stash getting +reduced because your governance deposit for a proposal was slashed). + +## Locks + +Locks account for the `frozen` balance of your wallet. This is the balance that can be `free` but +not transferrable, and locked on staking, governance and vesting. + +Locks overlap (in both, size and time), and the general rule is that: + +- If you have multiple locks of different sizes, the biggest lock decides the total amount of locked + tokens +- If you have multiple locks of the same size, the longest lock decides when all the tokens can be + unlocked + +Let's take for example 80 DOT as `frozen` balance. These 80 DOT are currently used in staking and +governance as follows: + +- 80 DOT Staking (just unbonded) -> lock 28 days +- 24 DOT OpenGov 1x conviction (Ref just ended, winning side) -> lock 7 days +- 4 DOT OpenGov 6x conviction (Ref just ended, winning side) -> lock 224 days + +![locks-example-1](../assets/locks-example-1.png) + +The 1 DOT ED is the existential deposit. The locked amount is 80 DOT (not 108 DOT!). But those 80 +DOT will be available for unlock at different times. You will need first to remove the governance +lock on the 24 DOT after 7 days, then remove the staking lock for the 80 DOT after 28 days, and +finally after 224 days, you will be able to remove the second governance lock. + +![locks-example-2](../assets/locks-example-2.png) + +### Edge Cases for Overlocking + +If you used different convictions, the longest period and the largest amount are taken into account. +This is an (edge) case of overlocking. + +Following the previous example, if you + +- undelegate a 1x conviction delegation of 24 DOT -> 7 days lock 24 DOT +- delegate 4 DOT with 6x conviction +- undelegate again before the 1x conviction lock is removed + +You will get a 6x conviction for 24 DOT! See +[here](https://substrate.stackexchange.com/questions/5067/delegating-and-undelegating-during-the-lock-period-extends-it-for-the-initial-am) +for more information. + +## Balance Types on Polkadot-JS + +Below is an example that displays different balance types on the +[Polkadot-JS UI (wallet)](../general/polkadotjs-ui.md) of a Kusama account (note that the balance +types are the same for a Polkadot account). + +![account_balance_types](../assets/account-balance-types.png) + +- The **total** balance indicates the total number of tokens in the account. Note that this number + does not necessarily correspond to the tokens you can transfer. In the example, the total number + of tokens is 0.6274 KSM. The **transferrable** balance indicates the number of free tokens 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 sent to the account and released with a specific time + schedule. The account owns the tokens, but they 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 in 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 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 frozen tokens 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. diff --git a/docs/learn/learn-accounts.md b/docs/learn/learn-accounts.md index 478380b90039..4540739d37ad 100644 --- a/docs/learn/learn-accounts.md +++ b/docs/learn/learn-accounts.md @@ -145,48 +145,6 @@ It just means you want to keep your computer clean until you maybe need this fol 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 Balance Types - -In {{ polkadot: Polkadot :polkadot }}{{ kusama: Kusama :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 is an example that displays different balance types on the -[Polkadot-JS UI (wallet)](../general/polkadotjs-ui.md) of a Kusama account (note that the balance -types are the same for a Polkadot account). - -![account_balance_types](../assets/account-balance-types.png) - -- The **total** balance indicates the total number of tokens in the account. Note that this number - does not necessarily correspond to the tokens you can transfer. In the example, the total number - of tokens is 0.6274 KSM. The **transferrable** balance indicates the number of free tokens 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 sent to the account and released with a specific time - schedule. The account owns the tokens, but they 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 in 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 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 frozen tokens 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. - --- :::info Polkadot-JS Guides diff --git a/docs/learn/learn-locks.md b/docs/learn/learn-locks.md deleted file mode 100644 index 37edc7df3ee7..000000000000 --- a/docs/learn/learn-locks.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -id: learn-locks -title: Polkadot's Locks -sidebar_label: Locks -description: Polkadot's Balance Locks. -keywords: [Polkadot, locks, OpenGov] -slug: ../learn-locks ---- diff --git a/docs/learn/learn-polkadot-opengov.md b/docs/learn/learn-polkadot-opengov.md index e5e0fad531c0..471ba5924d0b 100644 --- a/docs/learn/learn-polkadot-opengov.md +++ b/docs/learn/learn-polkadot-opengov.md @@ -576,7 +576,8 @@ different scenarios: **Before delegating a specific track, you must remove any [vote](#voting-on-a-referendum) on that track.** -For more information about locks, see [this page](./learn-accounts.md#account-balance-types). +For more information about locks, see +[this page](./learn-account-balances.md#balance-types-on-polkadot-js). ::: diff --git a/docs/learn/learn-transactions.md b/docs/learn/learn-transactions.md index a432388b1d55..d22304df3bea 100644 --- a/docs/learn/learn-transactions.md +++ b/docs/learn/learn-transactions.md @@ -99,8 +99,9 @@ of transfer. ### Vested Transfers {{ polkadot: DOT :polkadot }}{{ kusama: KSM :kusama }} may have a lock placed on them to account for -vesting funds. Like other types of locks, these funds cannot be transferred but can be used in other -parts of the protocol such as voting in governance or being staked as a validator or nominator. +vesting funds. Like other types of [locks](./learn-account-balances.md#locks), these funds cannot be +transferred but can be used in other parts of the protocol such as voting in governance or being +staked as a validator or nominator. Vesting funds are on a release schedule and unlock a constant number of tokens at each block (**linear vesting**) or can unlock the full amount after a specific block number (**cliff diff --git a/docs/maintain/archive/maintain-guides-democracy.md b/docs/maintain/archive/maintain-guides-democracy.md index 2ddbf26addae..4ac1f3ae4d5d 100644 --- a/docs/maintain/archive/maintain-guides-democracy.md +++ b/docs/maintain/archive/maintain-guides-democracy.md @@ -160,17 +160,11 @@ Once successful, you will see your endorsement appear in the dropdown in the pro At the end of each launch period, the most endorsed proposal will move to a referendum. During this time you can cast a vote for or against the proposal. You may also lock up your tokens for a greater -length of time to weigh your vote more strongly. During the time your tokens are locked, you are -unable to transfer them, however they can still be used for further votes. Locks are layered on top -of each other, so an eight-week lock does not become a 15-week lock if you vote again a week later, -rather another eight-week lock is placed to extend the lock just one extra week. - -:::info Voting and staking locks can overlap - -- A user can use staked funds to vote on referenda (and/or to vote for Councillors). -- A user is only prohibited from transferring these funds to another account. - -::: +length of time to weigh your vote more strongly. During the time your tokens are +[locked](../../learn/learn-account-balances.md#locks), you are unable to transfer them, however they +can still be used for further votes. Locks are layered on top of each other, so an eight-week lock +does not become a 15-week lock if you vote again a week later, rather another eight-week lock is +placed to extend the lock just one extra week. To vote on a referendum, navigate to the ["Democracy" tab of Polkadot Apps](https://polkadot.js.org/apps/#/democracy/). Any active referendum diff --git a/docs/maintain/archive/maintain-guides-how-to-vote-councillor.md b/docs/maintain/archive/maintain-guides-how-to-vote-councillor.md index 67e55f63948a..fa39a660fd6e 100644 --- a/docs/maintain/archive/maintain-guides-how-to-vote-councillor.md +++ b/docs/maintain/archive/maintain-guides-how-to-vote-councillor.md @@ -27,13 +27,6 @@ of {{ polkadot: 0.032 DOT :polkadot }}{{ kusama: 0.0001 KSM :kusama }} per vote. whatever amount you wish to put behind your vote. See the [democracy guide](./maintain-guides-democracy.md) for more information. -:::info Voting and staking locks can overlap - -- A user can use staked funds to vote for Councillors (and/or use those funds in referenda). -- A user is only prohibited from transferring these funds to another account. - -::: - :::warning If your balance is vesting, you cannot use unvested tokens for this lock. You will have to wait diff --git a/kusama-guide/sidebars.js b/kusama-guide/sidebars.js index 56219908ce4d..b1daf626066b 100644 --- a/kusama-guide/sidebars.js +++ b/kusama-guide/sidebars.js @@ -198,6 +198,7 @@ module.exports = { id: "learn/learn-accounts" }, items: [ + "learn/learn-account-balances", "learn/learn-account-abstraction", "learn/learn-identity", "learn/learn-account-multisig", diff --git a/polkadot-wiki/sidebars.js b/polkadot-wiki/sidebars.js index c7b412c75c82..ea279b26e2f4 100644 --- a/polkadot-wiki/sidebars.js +++ b/polkadot-wiki/sidebars.js @@ -198,6 +198,7 @@ module.exports = { id: "learn/learn-accounts" }, items: [ + "learn/learn-account-balances", "learn/learn-account-abstraction", "learn/learn-identity", "learn/learn-account-multisig", @@ -232,7 +233,6 @@ module.exports = { "learn/learn-nomination-pools", ], }, - "learn/learn-locks", { type: "category", label: "Polkadot OpenGov",