fix: Account Balances page

[Imod7]

Description

Related to this issue #6787

Review

Review from @Ank4n would be very helpful! Thank you very much in advance!

[Ank4n]

This is complex to explain, but here is how I would explain it. I would still like to get more eyes on this to verify @filippoweb3 @DrW3RK

• Free Balance: Balance that can be used for any on-chain activity (staking, governance, deposits) as long as your total balance (free + reserved) remains above the maximum of frozen balance and existential deposit.

• Frozen Balance (also called locks): This is a balance that overlaps across pallets . Example: If governance freezes 100 DOT and vesting freezes 120 DOT, total frozen = 120 DOT (not 220 DOT).

• Reserved Balance (also called holds): Balance removed from free and doesn't overlap. Used by Nomination Pools, Staking, etc. Can still be used for governance voting but not for transfers or fees.

• Spendable Balance: Portion of free balance available for transaction fees and creating new holds.

[filippoweb3]

I am on it, I need to verify a couple of things but there is already PR in place to update the balances page.

[Imod7]

@filippoweb3 Let me know if you would like to incorporate the changes reviewed by Ankan into your PR, and I can close mine. Otherwise, I am happy to add them to this PR.

[Imod7]

Just pushed the changes suggested from @Ank4n in this commit

[joepetrowski]

4

[Imod7]

Updated in this commit

[joepetrowski]

This needs to be updated as part of this PR. E.g. on_hold is no longer defined. Does the formula need an update? @Ank4n

[Imod7]

I updated the formula in this commit. If there are any objections from Ankan I will edit again.

[Ank4n]

Formula looks good.

Also aligns with https://github.com/w3f/polkadot-wiki/pull/6793/files#r2231235271

[ggwpez]

I think this is sadly not correct, since a reserved balance creates a provider ref which makes the ED spendable. I will check again how it is exactly, but more complicated than the formula currently.

[ggwpez]

IMO it should be something like this. It is also not 100% correct though, see the NOTE. So not sure how to easily explain this. In practice its not easy.

untouchable = frozen - on_hold.min(frozen);

// NOTE: The `(on_hold > 0 || frozen > 0)` is an *approximation* for
// `(consumers != 0 && providers <= 1)`, which is the condition that actually matters.
if free > 0 && (on_hold > 0 || frozen > 0) {
	untouchable = untouchable.max(ed);
}

spendable = free - untouchable.min(free);

[Ank4n]

We have a test case here demonstrating that when a hold exists, the ED is not spendable.

Here’s the AccountInfo for 11 from that test (not printed in the test output, but retrieved by running it locally):

AccountInfo {
    nonce: 0,
    consumers: 1,
    providers: 1,
    sufficients: 0,
    data: AccountData {
        free: 1,
        reserved: 1000,
        frozen: 0,
        flags: ...
    }
}

[joepetrowski]

There are still changes below (spendable calculation, examples) that need to be made.

[Imod7]

There are still changes below (spendable calculation, examples) that need to be made.

• I updated the examples but the changes need to be double checked.
• Once the example changes are confirmed, the photos will need to be aligned. I am not sure what tool to use to edit them, but I assume @filippoweb3 will know how to handle this.
• Also, this section Query Account Data in Polkadot-JS was updated.
• Untouchable should either be added again in the balance types or be removed from the examples to maintain consistency.

[filippoweb3]

@Imod7 I will have a look by EoW, will update the figures as well. I will push my edits, ask for review by @michalisFr and merge. Thank you so much for starting this PR!

[michalisFr]

A vested transfer increases the total balance as well. At the end of the day when all locks and reserves are removed you should have 150 DOT transferable. Also, in this example you suddenly have more frozen than free, so you lose access to the 20 DOT you had before.

What would happen here is this:
Free: 70
Frozen: 50
Reserved: 80
Spendable: 69
Untouchable: 1

However, since Frozen overlaps with Reserved, as you can see you have that 50 extra DOT as spendable from day 1. But at the end of the day that's not a problem since if you remove all reserves and the governance lock, you'll still have 50 DOT frozen that will become spendable according to the vesting schedule.

But again I'd like @joepetrowski or @Ank4n to confirm.

[filippoweb3]

added an example for a second gov lock as vesting can be a further example.

[ggwpez]

I did not read through the context here, but i had this in my notes. Will compare against it:

|__total__________________________________|
|__on_hold__|_____________free____________|
|__________frozen___________|
|__on_hold__|__ed__|        
            |__untouchable__|__spendable__|

untouchable = max(ed, frozen - on_hold)

from here.

[Ank4n]

I added a few suggestions, but overall, great job.

[Ank4n]

...but only after all the free balance has been slashed

Not sure what this means - shouldn’t only the reserved funds be subject to slashing? Why would the free balance be slashed?

[michalisFr]

This is taken from here @Ank4n
https://paritytech.github.io/polkadot-sdk/master/frame_support/traits/tokens/fungible/index.html#terminology

[Ank4n]

Thanks for pointing out. This is not correct anymore. I think the original text was correct when staking was using locks, and it was part of free balance.

(I will make a fix in the fungible rustdoc)

[Ank4n]

(pending review) fix

[Ank4n]

@filippoweb3 This text should be fixed too. Totally misleading as it is now. You can refer the text here.

[Ank4n]

A subtle nuance to explain is that the spendable balance is 99 DOT if you intend to keep the account alive. However, if you’re fine with the account being reaped, you can transfer up to the full 100 DOT (minus transaction fees).

[Ank4n]

I had a question today about voting locks, and it wasn’t clear to the person asking — and probably not to many others either — that governance votes use the total balance, including non-staking holds (like proxy deposits).

Might be worth calling this out explicitly in the docs as well:
https://github.com/paritytech/polkadot-sdk/blob/master/substrate/frame/conviction-voting/src/lib.rs#L425

Also, I think we should go ahead and merge this (post handing current open comments). It’s not perfect, but already a clear improvement over what’s currently in the docs. We can continue to iterate on it from here.
Approving this PR for that reason.

[Ank4n]

@filippoweb3 Regarding the balance examples, how are they currently being cross-verified? Should we add dedicated unit tests in the SDK to match each example one-to-one? Or any other idea?

[filippoweb3]

@Ank4n we validate with Polkadot JS and the support team :) I would wait to build unit tests until those figures and examples are final, as the Wiki content is subject to changes, and this would add additional work to update test dependencies. Thanks!