From b1037d1c9d8cb7aa6d1c1b49335d6d3810f314c9 Mon Sep 17 00:00:00 2001 From: Guillaume Thiolliere Date: Wed, 10 Sep 2025 13:47:41 +0900 Subject: [PATCH 1/6] Update spendable balance and ED spec --- docs/learn/learn-account-balances.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/learn/learn-account-balances.md b/docs/learn/learn-account-balances.md index c187d1fb76e..6191bf9a65b 100644 --- a/docs/learn/learn-account-balances.md +++ b/docs/learn/learn-account-balances.md @@ -32,7 +32,7 @@ There are four types of account balances: **Spendable Balance** is the portion of the free balance that can be transferred. It is also available for transaction fees and creating new reserves. -The spendable balance is calculated as follows: +In the usual case when ED is untouchable the spendable balance is calculated as follows: ``` spendable = free - max(frozen - reserved, ED) @@ -41,9 +41,15 @@ spendable = free - max(frozen - reserved, ED) Where `free`, `frozen`, and `reserved` are defined above. The `ED` is the [existential deposit](./learn-accounts.md#existential-deposit-and-reaping). +If an account has any other provider references then the spendable amount is: + +``` +spendable = free - max(frozen - reserved) +``` + ### Consumer and Provider References -In Polkadot and Substrate-based chains, each account must maintain a minimum free balance called the Existential Deposit (ED) to remain alive. An account cannot be reaped from the state while it has a reserved balance, or in general, +In Polkadot and Substrate-based chains, each account must maintain a minimum total balance called the Existential Deposit (ED) to remain alive. An account cannot be reaped from the state while it has a reserved 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 other pallets depend on the existence of such an account. For example, the existential deposit adds a provider reference simply @@ -52,8 +58,8 @@ depends on the proxied account; the proxy is the consumer). If an account’s free balance falls below this threshold and has no providers or consumers, it is reaped, meaning all its data is deleted to conserve state space. However, the ED rules are more nuanced than they may appear: -- Reserved balances do not count as spendable, but they do add a provider reference to the account. -- If an account has any provider references (e.g., via reserved balance or staking), it will not be reaped even if its free balance drops below the ED. In such cases, the ED is not untouchable: the free balance can be entirely spent, and the account will remain alive. In other words, the account is "dusted", which happens when its free balance drops below ED. Then the "dust" is deleted, but the account can still be alive, for example, because it has a provider reference. +- Reserved balances do not count as spendable, but they do add a provider reference to the account. (No they don't? otherwise ED would not be untouchable after having more than ED on hold. and ED is untouchable even when having more than ED on hold) +- If an account has any provider references (e.g., via staking), it will not be reaped even if its total balance drops below the ED. In such cases, the ED is not untouchable: the total balance can be entirely spent, and the account will remain alive. In other words, the account is "dusted", which happens when its total balance drops below ED. Then the "dust" is deleted, but the account can still be alive, for example, because it has a provider reference. - Conversely, if an account has consumers (such as active locks or dependencies) but only one or zero providers, then the ED must be preserved, or the account may be reaped once the last consumer or provider is removed. ## Example of Account Balance Types From 53f4fcff1f3a019f7e129d4faec1e289caa7e032 Mon Sep 17 00:00:00 2001 From: midegdugarova <59020389+midegdugarova@users.noreply.github.com> Date: Wed, 17 Sep 2025 13:49:59 +0200 Subject: [PATCH 2/6] Update docs/learn/learn-account-balances.md --- docs/learn/learn-account-balances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/learn-account-balances.md b/docs/learn/learn-account-balances.md index 6191bf9a65b..412f86bc60d 100644 --- a/docs/learn/learn-account-balances.md +++ b/docs/learn/learn-account-balances.md @@ -58,7 +58,7 @@ depends on the proxied account; the proxy is the consumer). If an account’s free balance falls below this threshold and has no providers or consumers, it is reaped, meaning all its data is deleted to conserve state space. However, the ED rules are more nuanced than they may appear: -- Reserved balances do not count as spendable, but they do add a provider reference to the account. (No they don't? otherwise ED would not be untouchable after having more than ED on hold. and ED is untouchable even when having more than ED on hold) +- Reserved balances do not count as spendable. - If an account has any provider references (e.g., via staking), it will not be reaped even if its total balance drops below the ED. In such cases, the ED is not untouchable: the total balance can be entirely spent, and the account will remain alive. In other words, the account is "dusted", which happens when its total balance drops below ED. Then the "dust" is deleted, but the account can still be alive, for example, because it has a provider reference. - Conversely, if an account has consumers (such as active locks or dependencies) but only one or zero providers, then the ED must be preserved, or the account may be reaped once the last consumer or provider is removed. From e706637ae537f5dbef8f73c5dbdc99c20e03475e Mon Sep 17 00:00:00 2001 From: Guillaume Thiolliere Date: Mon, 22 Sep 2025 09:54:02 +0900 Subject: [PATCH 3/6] Update docs/learn/learn-account-balances.md --- docs/learn/learn-account-balances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/learn-account-balances.md b/docs/learn/learn-account-balances.md index 412f86bc60d..5c872610b4b 100644 --- a/docs/learn/learn-account-balances.md +++ b/docs/learn/learn-account-balances.md @@ -49,7 +49,7 @@ spendable = free - max(frozen - reserved) ### Consumer and Provider References -In Polkadot and Substrate-based chains, each account must maintain a minimum total balance called the Existential Deposit (ED) to remain alive. An account cannot be reaped from the state while it has a reserved balance, or in general, +In Polkadot and Substrate-based chains, each account must maintain a minimum free balance called the Existential Deposit (ED) to remain alive (or have another provider see later). An account cannot be reaped from the state while it has a reserved 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 other pallets depend on the existence of such an account. For example, the existential deposit adds a provider reference simply From 4c99f2f9e43aa91e2d7b43720d068239efa7489e Mon Sep 17 00:00:00 2001 From: Guillaume Thiolliere Date: Mon, 22 Sep 2025 09:54:59 +0900 Subject: [PATCH 4/6] Update docs/learn/learn-account-balances.md --- docs/learn/learn-account-balances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/learn-account-balances.md b/docs/learn/learn-account-balances.md index 5c872610b4b..5dd309c42fd 100644 --- a/docs/learn/learn-account-balances.md +++ b/docs/learn/learn-account-balances.md @@ -59,7 +59,7 @@ depends on the proxied account; the proxy is the consumer). If an account’s free balance falls below this threshold and has no providers or consumers, it is reaped, meaning all its data is deleted to conserve state space. However, the ED rules are more nuanced than they may appear: - Reserved balances do not count as spendable. -- If an account has any provider references (e.g., via staking), it will not be reaped even if its total balance drops below the ED. In such cases, the ED is not untouchable: the total balance can be entirely spent, and the account will remain alive. In other words, the account is "dusted", which happens when its total balance drops below ED. Then the "dust" is deleted, but the account can still be alive, for example, because it has a provider reference. +- If an account has any provider references (e.g., via staking), it will not be reaped even if its free balance drops below the ED. In such cases, the ED is not untouchable: the total balance can be entirely spent, and the account will remain alive. In other words, the account may be "dusted", which happens ?sometimes? when its free balance drops below ED. Then the "dust" is deleted, but the account can still be alive, for example, because it has a provider reference. - Conversely, if an account has consumers (such as active locks or dependencies) but only one or zero providers, then the ED must be preserved, or the account may be reaped once the last consumer or provider is removed. ## Example of Account Balance Types From 09d3c8636a00bfdd1ffa60e9f2ab9b921f21ff8d Mon Sep 17 00:00:00 2001 From: Guillaume Thiolliere Date: Mon, 22 Sep 2025 09:55:24 +0900 Subject: [PATCH 5/6] Update docs/learn/learn-account-balances.md --- docs/learn/learn-account-balances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/learn-account-balances.md b/docs/learn/learn-account-balances.md index 5dd309c42fd..37df2c57769 100644 --- a/docs/learn/learn-account-balances.md +++ b/docs/learn/learn-account-balances.md @@ -49,7 +49,7 @@ spendable = free - max(frozen - reserved) ### Consumer and Provider References -In Polkadot and Substrate-based chains, each account must maintain a minimum free balance called the Existential Deposit (ED) to remain alive (or have another provider see later). An account cannot be reaped from the state while it has a reserved balance, or in general, +In Polkadot and Substrate-based chains, each account must maintain a minimum free balance called the Existential Deposit (ED) to remain alive (or have another provider). An account cannot be reaped from the state while it has a reserved 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 other pallets depend on the existence of such an account. For example, the existential deposit adds a provider reference simply From a4fc88b5d5e8d632da61eb366363aa87446e073b Mon Sep 17 00:00:00 2001 From: Guillaume Thiolliere Date: Mon, 22 Sep 2025 09:55:44 +0900 Subject: [PATCH 6/6] Update docs/learn/learn-account-balances.md --- docs/learn/learn-account-balances.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/learn/learn-account-balances.md b/docs/learn/learn-account-balances.md index 37df2c57769..0367aaf2918 100644 --- a/docs/learn/learn-account-balances.md +++ b/docs/learn/learn-account-balances.md @@ -59,7 +59,7 @@ depends on the proxied account; the proxy is the consumer). If an account’s free balance falls below this threshold and has no providers or consumers, it is reaped, meaning all its data is deleted to conserve state space. However, the ED rules are more nuanced than they may appear: - Reserved balances do not count as spendable. -- If an account has any provider references (e.g., via staking), it will not be reaped even if its free balance drops below the ED. In such cases, the ED is not untouchable: the total balance can be entirely spent, and the account will remain alive. In other words, the account may be "dusted", which happens ?sometimes? when its free balance drops below ED. Then the "dust" is deleted, but the account can still be alive, for example, because it has a provider reference. +- If an account has any provider references (e.g., via staking), it will not be reaped even if its free balance drops below the ED. In such cases, the ED is not untouchable: the free balance can be entirely spent, and the account will remain alive. In other words, the account may be "dusted", which happens ?sometimes? when its free balance drops below ED. Then the "dust" is deleted, but the account can still be alive, for example, because it has a provider reference. - Conversely, if an account has consumers (such as active locks or dependencies) but only one or zero providers, then the ED must be preserved, or the account may be reaped once the last consumer or provider is removed. ## Example of Account Balance Types