Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(x/evmutil): Remove akava and evmbankkeeper from x/evmutil spec #1968

Merged
merged 1 commit into from
Jul 26, 2024
Merged

docs(x/evmutil): Remove akava and evmbankkeeper from x/evmutil spec #1968

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 0 additions & 32 deletions x/evmutil/spec/01_concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,34 +4,6 @@ order: 1

# 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.

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 excess `akava` balance is stored in the `x/evmutil` store, while its `ukava` balance remains in the cosmos-sdk `x/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.

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

### `x/evm` Parameter Requirements

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`.

### Balance Calculation of `akava`

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 via the module `Keeper`.

### `akava` <> `ukava` Conversion

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 `x/evmutil` module account, then adding the equivalent `akava` amount to the sender's balance in the module state.

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 in the module store, then transferring the equivalent `ukava` coins from the `x/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.

## ERC20 token <> sdk.Coin Conversion

`x/evmutil` facilitates moving assets between Kava's EVM and Cosmos co-chains. This must be handled differently depending on which co-chain to which the asset it native. The messages controlling these flows involve two accounts:
Expand Down Expand Up @@ -65,7 +37,3 @@ EVM-native asset conversion is done through the use of the `MsgConvertERC20ToCoi
Only ERC20 contract address that are in the `EnabledConversionPairs` param (see **[Params](05_params.md)**) can be converted via these messages.

`EnabledConversionPairs` can be altered through governance.

## Module Keeper

The module Keeper provides access to an account's excess `akava` balance and the ability to update the balance.
16 changes: 2 additions & 14 deletions x/evmutil/spec/02_state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,24 +51,12 @@ message AllowedCosmosCoinERC20Token {

```protobuf
message GenesisState {
repeated Account accounts = 1 [(gogoproto.nullable) = false];
// previously stored accounts containing fractional balances.
reserved 1;
Params params = 2 [(gogoproto.nullable) = false];
}
```

## Account

An `Account` is a struct representing the excess `akava` balance of an address.

Since an address's total `akava` balance is derived from its `ukava` balance and the excess `akava` balance stored by the `Account` struct, the `akava` balance here should never exceed 1 `ukava` (10^12 `akava`).

```protobuf
message Account {
bytes address = 1;
string balance = 2;
}
```

## Deployed Cosmos Coin Contract Addresses

Addresses for the ERC20 contracts representing cosmos-sdk `Coin`s are kept in the module store. They are stored as bytes by the cosmos-sdk denom they represent.
Expand Down
7 changes: 0 additions & 7 deletions x/evmutil/spec/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,6 @@ parent:

The evmutil module provides additional functionalities on top of the evm module.

### EVM `akava` Usage

evmutil stores additional state data for evm accounts and exposes an `EvmBankKeeper` that should be used by the `x/evm` keeper for bank operations.
The purpose of the `EvmBankKeeper` is to allow the usage of the `akava` balance on the EVM via an account's existing `ukava` balance. This is needed because the EVM gas token use 18 decimals, and since `ukava` has 6 decimals, it cannot be used as the EVM gas denom directly.

For additional details on how balance conversions work, see **[Concepts](01_concepts.md)**.

### ERC20 Token <> sdk.Coin Conversion

evmutil exposes messages to allow for the conversion of Kava ERC20 tokens and sdk.Coins via a whitelist.
Expand Down
Loading