Bank
Abstract
This document specifies the internal x/bank
module of the HAQQ Network.
The x/bank
module is a custom wrapper around the native Cosmos SDK x/bank
module.
If you're not familiar with the core functionality of original module, please check this
document as prerequisite reading.
Initially, this wrapper was made to comply with the tokenomics requirements described in the Islamic Coin
Whitepaper. HAQQ bank keeper has a custom coins burn
policy, that funds
Evergreen DAO account instead of complete coins destruction in certain cases.
The latest improvements of HAQQ bank make it an EVM-first module. It supports a trustless, on-chain bidirectional
internal conversion of tokens between HAQQ EVM and Cosmos runtimes. Bank utilizes the x/erc20
features
to instantaneously convert users' native Cosmos sdk.Coins
(in this document referred to as "Coin(s)")
to ERC-20 (aka "Token(s)") during the transfers. That allows users' to see the same information about
balances and make transfers without additional conversions using the preferred wallet apps (e.g. Keplr, MetaMask, etc).
Module Architecture
If you're not familiar with the overall module structure from the SDK modules, please check this document as prerequisite reading.
bank/
├── keeper
│ ├── grpc_query.go # gRPC state query handlers
│ ├── keeper.go # Store keeper with the custom Burn() function
│ └── msg_server.go # Tx handlers (overrides functions Send, GetBalance, etc.)
│ └── querier.go # Legacy state query handlers
│ └── wrapped_keeper.go # Store keeper wrapper
└── module.go # Module setup for the module manager & ABCI InitGenesis and ExportGenesis functionality
Concept
Send ERC-20 Tokens
Once a token pair proposal passes, users of native Cosmos wallets (e.g., Keplr) can see their accurate Tokens
balance as if they were native Coins.
Holders of native Cosmos coins and IBC vouchers on the HAQQ Network can transfer their Tokens on HAQQ EVM
by creating a MsgSend
or MsgTransfer
Tx.
Learn more about x/erc20
module and token pair registration here.
Internal Burn of Coins
There are a few cases when Coins are subject to be burnt but are transferred to Evergreen DAO instead:
- Staking:
- slash validator for an infraction
- slash redelegation
- slash an unbonding delegation
- Governance:
- burn proposal deposits, if more than 1/3 of voters veto
Improvements
Get Balance(s)
The Balance
endpoint allows users to query account balance by address for a given denomination.
The AllBalances
endpoint allows users to query account balance by address for all denominations.
Internal requests being executed to retrieve balance(s):
- retrieve balance(s) of native coins on HAQQ Cosmos runtime
- retrieve balance(s) of registered ERC-20 tokens on HAQQ EVM runtime
MsgSend
Send coins from one address to another.
Internal state transitions during execution:
- check if ERC-20 is enabled
- check if the coins have registered token pairs
- convert coins into tokens
- execute ERC-20 transfer on HAQQ EVM runtime
- send native coins on HAQQ Cosmos runtime
MsgTransfer
Send coins from one address to another via IBC.
Internal state transitions during execution:
- check if ERC-20 is enabled
- check if the coins have registered token pairs
- convert tokens into coins
- execute IBC transfer on HAQQ Cosmos runtime