added content

w3f · May 6, 2024 · db83415 · db83415
1 parent 5b829db
commit db83415
Show file tree

Hide file tree

Showing 16 changed files with 216 additions and 73 deletions.
diff --git a/docs/assets/balance-example-1.png b/docs/assets/balance-example-1.png
diff --git a/docs/assets/balance-example-2.png b/docs/assets/balance-example-2.png
diff --git a/docs/assets/balance-example-3.png b/docs/assets/balance-example-3.png
diff --git a/docs/assets/balance-example-4.png b/docs/assets/balance-example-4.png
diff --git a/docs/assets/locks-example-1.png b/docs/assets/locks-example-1.png
diff --git a/docs/assets/locks-example-2.png b/docs/assets/locks-example-2.png
diff --git 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
@@ -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
@@ -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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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",