Resolve "Create a runtime API UniversalDividendApi_account_balances to retrieve total and transferable account balances"

The “balance” of an account is more complex than it first appears.

In Duniter, for example, there may be unclaimed UDs that aren’t included in the “free” balance but are spendable if wrapped in a batched call [claim_uds, transfer]. Substrate itself adds further complexity with concepts like the “existential deposit” and “reserved” balance.

All of this makes it difficult for wallets and other applications to display a single, clear balance to the user.

I propose adding a new runtime API, UniversalDividendApi_account_balances, which returns an object containing:

{
  /// The total amount of funds for which the user is the ultimate beneficial owner. 
  /// Includes funds that may not be transferable (e.g., reserved balance, existential deposit).
  total: number,

  /// The maximum amount of funds that can be successfully withdrawn or transferred 
  /// (includes unclaimed UDs).
  transferable: number,

  /// The total amount of unclaimed UDs (accounts for any re-evaluations of UDs).
  unclaim_amount: number
}

---

This PR add runtime API UniversalDividendApi_account_balances.

Runtime API can be called via RPC with RPC method state_call.

here is an example with curl:

curl -X POST http://127.0.0.1:9933 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "state_call",
    "params": [
      "UniversalDividendApi_account_balances",
      "0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    ]
  }'

The account ID is the hexadecimal representation of the 32‐byte public key.

Closes #303 (closed)

changed milestone to %runtime-1000

changed the description

added 1 commit

• 98e2912d - add runtime API: UniversalDividendApi_account_total_balance

Compare with previous version

added 1 commit

• f71e33d8 - add runtime API: UniversalDividendApi_account_total_balance

Compare with previous version

added RN-runtime label

changed the description

added 1 commit

• ba8c24ef - add runtime API: UniversalDividendApi_account_total_balance

Compare with previous version

added 1 commit

• 99e317b6 - add runtime API: UniversalDividendApi_account_total_balance

Compare with previous version

added 1 commit

• dfe3dae6 - update metadata

Compare with previous version

requested review from @tuxmain

assigned to @HugoTrentesaux

unassigned @HugoTrentesaux

approved this merge request

@HugoTrentesaux @bgallois do you have some time to review this MR?

marked this merge request as ready

mentioned in issue clients/python/silkaj#429

Will merge now to move forward as it doesn't change the protocol logic

merged

mentioned in commit 6c9b611d