update state & param specs

updates to the sections describing functionality will be updated once that functionality actually exists... :)
Kava-Labs · May 15, 2023 · 610b44c · 610b44c
1 parent d605fe7
commit 610b44c
Show file tree

Hide file tree

Showing 2 changed files with 40 additions and 4 deletions.
diff --git a/x/evmutil/spec/02_state.md b/x/evmutil/spec/02_state.md
@@ -6,14 +6,18 @@ order: 2
 
 ## Parameters and Genesis State
 
-`Parameters` define the list of conversion pairs allowed to be converted between Kava ERC20 tokens and sdk.Coins.
+`Parameters` define the list of conversion pairs allowed to be converted between Kava ERC20 tokens & sdk.Coins, and the list of native sdk.Coins that are allowed to be converted to ERC20s.
 
 ```protobuf
 // Params defines the evmutil module params
 message Params {
   // enabled_conversion_pairs defines the list of conversion pairs allowed to be
   // converted between Kava ERC20 and sdk.Coin
   repeated ConversionPair enabled_conversion_pairs = 4;
+
+  // allowed_native_denoms is a list of denom & erc20 token metadata pairs.
+  // if a denom is in the list, it is allowed to be converted to an erc20 in the evm.
+  repeated AllowedNativeCoinERC20Token allowed_native_denoms = 1;
 }
 
 // ConversionPair defines a Kava ERC20 address and corresponding denom that is
@@ -24,6 +28,24 @@ message ConversionPair {
   // Denom of the corresponding sdk.Coin
   string denom = 2;
 }
+
+// AllowedNativeCoinERC20Token defines allowed sdk denom & metadata
+// for evm token representations of sdk assets.
+// NOTE: once evm token contracts are deployed, changes to metadata for a given
+// sdk_denom will not change metadata of deployed contract.
+message AllowedNativeCoinERC20Token {
+  option (gogoproto.goproto_getters) = false;
+
+  // Denom of the sdk.Coin
+  string sdk_denom = 1;
+  // Name of ERC20 contract
+  string name = 2;
+  // Symbol of ERC20 contract
+  string symbol = 3;
+  // Number of decimals ERC20 contract is deployed with.
+  uint32 decimal = 4;
+}
+
 ```
 
 `GenesisState` defines the state that must be persisted when the blockchain stops/restarts in order for normal function of the evmutil module to resume.

diff --git a/x/evmutil/spec/05_params.md b/x/evmutil/spec/05_params.md
@@ -6,9 +6,10 @@ order: 5
 
 The evmutil module contains the following parameters:
 
-| Key                    | Type                   | Example       |
-| ---------------------- | ---------------------- | ------------- |
-| EnabledConversionPairs | array (ConversionPair) | [{see below}] |
+| Key                    | Type                                 | Example       |
+| ---------------------- | ------------------------------------ | ------------- |
+| EnabledConversionPairs | array (ConversionPair)               | [{see below}] |
+| AllowedNativeDenoms    | array (AllowedNativeCoinERC20Tokens) | [{see below}] |
 
 Example parameters for `ConversionPair`:
 
@@ -17,6 +18,19 @@ Example parameters for `ConversionPair`:
 | kava_erc20_Address | string | "0x43d8814fdfb9b8854422df13f1c66e34e4fa91fd" | ERC20 contract address             |
 | denom              | string | "erc20/chain/usdc"                           | sdk.Coin denom for the ERC20 token |
 
+Example parameters for `AllowedNativeCoinERC20Token`:
+
+| Key       | Type   | Example                                                                | Description                                        |
+| --------- | ------ | ---------------------------------------------------------------------- | -------------------------------------------------- |
+| sdk_denom | string | "ibc/27394FB092D2ECCD56123C74F36E4C1F926001CEADA9CA97EA622B25F41E5EB2" | denom of the sdk.Coin                              |
+| name      | string | "Kava-wrapped Atom"                                                    | name field of the erc20 token                      |
+| symbol    | string | "kATOM"                                                                | symbol field of the erc20 token                    |
+| decimal   | uint32 | 6                                                                      | decimal field of the erc20 token, for display only |
+
 ## EnabledConversionPairs
 
 The enabled conversion pairs parameter is an array of ConversionPair entries mapping an erc20 address to a sdk.Coin denom. Only erc20 contract addresses that are in this list can be converted to sdk.Coin and vice versa.
+
+## AllowedNativeDenoms
+
+The allowed native denoms parameter is an array of AllowedNativeCoinERC20Token entries. They include the sdk.Coin denom and metadata for the ERC20 representation of the asset in Kava's EVM. Coins may only be transferred to the EVM if they are included in this list. A token in this list will have an ERC20 token contract deployed on first conversion. The token will be deployed with the metadata included in the AllowedNativeCoinERC20Token. Once deployed, changes to the metadata will not affect or change the deployed contract.