0g-chain/x/evmutil/spec/01_concepts.md
Draco Li c511c56560
Add EVM Support (#1215)
* ibc v3 upgrade

* ibc no longer uses confio

* add proofs proto for ibc/v3

* wip add ethermint module

* update cosmos to 0.45.0

* add ethermint proto & bug fixes

* remove todo

* update docs

* fix a number of bugs

* minor comments update

* fix breaking tests

* Wrap bank keeper for EVM to convert decimals (#1154)

* Add bankkeeper wrapper for evm

* Remove agas from init-new-chain.sh, use ukava for evm_denom

* Fix sdk.Coins conversion, require min 1 coin amount

* Remove gas from init script

idk how this happened lol

* Remove debug logging stmt

* Restore original init ukava amounts

* Fix inplace coins conversion

* Use evmtypes.BankKeeper interface insteadof banktypes

* Add TestGetBalance

* Add doc comments, remove temp actualAmt vars

actualAmt vars replaced with inline calls to make it more clear that the
converted value is being used, as opposed to accidentally reusing the
raw EVM amt.

* Add TestSetBalance

* Add TestIdempotentConversion

* Panic if converted coin from EVM is 0

This happens if a value is less than 1ukava

* Deep copy coins instead of in place modification

* Update test coins amount

* Add panic tests for small EVM amounts

* Use evmtypes.BankKeeper as NewEVMBankKeeper param

* Tidy test setup

* ensure sdk config is set when creating new apps

* Respond EVM bank keeper GetBalance with SpendableCoins

Co-authored-by: Nick DeLuca <nickdeluca08@gmail.com>

* further speed up docker builds

* feat: restore previous keys add defaults, add eth flag (#1172)

* feat: restore previous keys add defaults, add eth flag

* remove outdated comment

* fix: remove redundant flag default

* evm bank keeper with akava handling

* fix issues

* add remaining tests

* add emv module to app

* add missing imports

* clean up comments

* wip akava keeper

* evm keeper

* fix genesis import

* reduce module permissions

* add bank keeper tests

* cleanup tests

* genesis tests

* change defaults

* add eth faucet key & fix issues

* switch to kava ethermint

* add a lot of tests

* add balances invariant

* add evm tests

* Remove panic if Swagger disabled in config (#1155) (#1183)

Co-authored-by: Derrick Lee <derrick@dlee.dev>

* add invariant to catch any akava balance > 1 ukava

* clarify name of balances invariant

* connect invariants to app

* fix evmbankkeeper akava issues

* add spec for evmutil

* remove zero balance accounts from state

* minor adustments

* update to ethermint 0.10.0

* fix eth ante

* add missing godoc comment

* Update x/evmutil/spec/01_concepts.md

Co-authored-by: Kevin Davis <karzak@users.noreply.github.com>

* Update x/evmutil/spec/01_concepts.md

Co-authored-by: Kevin Davis <karzak@users.noreply.github.com>

* Update ethermint to v0.12 (#1203)

* update to ethermint v0.12.2

* use app.Options for new evm options

* fix missed references to app.Options

* use ethermint branch while waiting on upstream fix

* evm migrations for tesnet alpha 2 (#1206)

* update to ethermint v0.12.2

* use app.Options for new evm options

* fix missed references to app.Options

* use ethermint branch while waiting on upstream fix

* add upgrade handler for evm-alpha testnet 2

* v17 migration setup + evm modules

* refactor migrate states

* x/feemarket migration

* v17 migrations setup + evm modules migration (#1210)

* v17 migration setup + evm modules

* refactor migrate states

* update gen time

* fix: update genesis time in test output

Co-authored-by: karzak <kjydavis3@gmail.com>

* add savings module to app blockers

Co-authored-by: Derrick Lee <derrick@dlee.dev>
Co-authored-by: Nick DeLuca <nickdeluca08@gmail.com>
Co-authored-by: rhuairahrighairigh <ruaridh.odonnell@gmail.com>
Co-authored-by: Kevin Davis <karzak@users.noreply.github.com>
Co-authored-by: Ruaridh <rhuairahrighairidh@users.noreply.github.com>
Co-authored-by: karzak <kjydavis3@gmail.com>
2022-04-21 16:16:28 -04:00

2.5 KiB

Concepts

EVM Gas Denom

In order to use the EVM and be compatible with existing clients, the gas denom used by the EVM must be in 18 decimals. Since ukava has 6 decimals of precision, it cannot be used as the EVM gas denom directly.

In order to use the Kava token on the EVM, the evmutil module provides an EvmBankKeeper that is responsible for the conversion of ukava and akava. A user's akava balance is stored in the evmutil store, while it's ukava balance remains stored in the cosmos-sdk bank module.

EvmBankKeeper Overview

The EvmBankKeeper provides access to an account's total akava balance and the ability to transfer, mint, and burn akava. If anything other than the akava denom is requested, the EvmBankKeeper will panic.

type BankKeeper interface {
	evmtypes.BankKeeper
	SpendableCoins(ctx sdk.Context, addr sdk.AccAddress) sdk.Coins
	SendCoins(ctx sdk.Context, fromAddr sdk.AccAddress, toAddr sdk.AccAddress, amt sdk.Coins) error
}

The keeper implements the x/evm module's BankKeeper interface to enable the usage of akava denom on the EVM.

x/evm Parameter

Since the EVM denom akava is required to use the EvmBankKeeper, it is necessary to set the EVMDenom param of the x/evm module to akava.

akava Balance Calculation

The akava balance of an account is derived from an account's spendable ukava balance times 10^12 (to derive its akava equivalent), plus the account's excess akava balance that can be accessed by the module Keeper.

Conversions Between akava & ukava

When an account does not have sufficient akava to cover a transfer or burn, the EvmBankKeeper will try to swap 1 ukava to its equivalent akava amount. It does this by transferring 1 ukava from the sender to the evmutil module account, then adding the equivalent akava amount to the sender's balance via the keeper's AddBalance.

In reverse, if an account has enough akava balance for one or more ukava, the excess akava balance will be converted to ukava. This is done by removing the excess akava balance tracked by evmutil module store, then transferring the equivalent ukava coins from the evmutil module account to the target account.

The swap logic ensures that all akava is backed by the equivalent ukava balance stored in the module account.

Module Keeper

The module Keeper provides access to an account's excess akava balance and the ability to update the balance.