# ADR 004: Split Denomination Keys
# Changelog
- 2020-01-08: Initial version
- 2020-01-09: Alterations to handle vesting accounts
- 2020-01-14: Updates from review feedback
- 2020-01-30: Updates from implementation
# Glossary
- denom / denomination key -- unique token identifier.
# Context
With permissionless IBC, anyone will be able to send arbitrary denominations to any other account. Currently, all non-zero balances are stored along with the account in an sdk.Coins
struct, which creates a potential denial-of-service concern, as too many denominations will become expensive to load & store each time the account is modified. See issues 5467 (opens new window) and 4982 (opens new window) for additional context.
Simply rejecting incoming deposits after a denomination count limit doesn't work, since it opens up a griefing vector: someone could send a user lots of nonsensical coins over IBC, and then prevent the user from receiving real denominations (such as staking rewards).
# Decision
Balances shall be stored per-account & per-denomination under a denomination- and account-unique key, thus enabling O(1) read & write access to the balance of a particular account in a particular denomination.
# Account interface (x/auth)
GetCoins()
and SetCoins()
will be removed from the account interface, since coin balances will
now be stored in & managed by the bank module.
The vesting account interface will replace SpendableCoins
in favor of LockedCoins
which does
not require the account balance anymore. In addition, TrackDelegation()
will now accept the
account balance of all tokens denominated in the vesting balance instead of loading the entire
account balance.
Vesting accounts will continue to store original vesting, delegated free, and delegated vesting coins (which is safe since these cannot contain arbitrary denominations).
# Bank keeper (x/bank)
The following APIs will be added to the x/bank
keeper:
GetAllBalances(ctx Context, addr AccAddress) Coins
GetBalance(ctx Context, addr AccAddress, denom string) Coin
SetBalance(ctx Context, addr AccAddress, coin Coin)
LockedCoins(ctx Context, addr AccAddress) Coins
SpendableCoins(ctx Context, addr AccAddress) Coins
Additional APIs may be added to facilitate iteration and auxiliary functionality not essential to core functionality or persistence.
Balances will be stored first by the address, then by the denomination (the reverse is also possible, but retrieval of all balances for a single account is presumed to be more frequent):
This will result in the balances being indexed by the byte representation of
balances/{address}/{denom}
.
DelegateCoins()
and UndelegateCoins()
will be altered to only load each individual
account balance by denomination found in the (un)delegation amount. As a result,
any mutations to the account balance by will made by denomination.
SubtractCoins()
and AddCoins()
will be altered to read & write the balances
directly instead of calling GetCoins()
/ SetCoins()
(which no longer exist).
trackDelegation()
and trackUndelegation()
will be altered to no longer update
account balances.
External APIs will need to scan all balances under an account to retain backwards-compatibility. It
is advised that these APIs use GetBalance
and SetBalance
instead of GetAllBalances
when
possible as to not load the entire account balance.
# Supply module
The supply module, in order to implement the total supply invariant, will now need
to scan all accounts & call GetAllBalances
using the x/bank
Keeper, then sum
the balances and check that they match the expected total supply.
# Status
Accepted.
# Consequences
# Positive
- O(1) reads & writes of balances (with respect to the number of denominations for which an account has non-zero balances). Note, this does not relate to the actual I/O cost, rather the total number of direct reads needed.
# Negative
- Slightly less efficient reads/writes when reading & writing all balances of a single account in a transaction.
# Neutral
None in particular.
# References
- Ref: https://github.com/cosmos/cosmos-sdk/issues/4982
- Ref: https://github.com/cosmos/cosmos-sdk/issues/5467
- Ref: https://github.com/cosmos/cosmos-sdk/issues/5492