Problem: missing high-level docs for x/cronos (crypto-org-chain#183)

* Problem: missing high-level docs for x/cronos

Closes: crypto-org-chain#64

Solution:
- write cronos module spec

fix wordings

add state transition

update title

highlight token mapping deletion

Apply suggestions from code review

Co-authored-by: aw126 <78806365+aw126@users.noreply.github.com>

apply suggestions

tmp

Apply suggestions from code review

Co-authored-by: Tomas Tauber <2410580+tomtau@users.noreply.github.com>

remove Key prefix

review suggstions

Revert "remove Key prefix"

This reverts commit 9fa8583a425f4cc7669fb2cb0c1ce29dcb484ea6.

remove Key prefix

review suggestions

* token withdraw won't be disabled

* contract remap is not allowed

x/cronos/spec/01_concepts.md

@@ -0,0 +1,51 @@
+ <!-- order: 1 -->
+
+# Concepts
+
+## Cronos
+
+Cronos is an EVM chain in Crypto.org ecosystem. It allows users to deploy and interact with smart contracts. Powered by Ethermint, it is built using cosmos SDK which allows to leverage to full capability of the cosmos ecosystem. It is also connected to the ethereum network with the gravity bridge integration (WIP).
+
+Bridging asset from cosmos or ethereum are automatically converted to a CRC20 asset when moved to Cronos which make it extremely easy to integrate with existing web3 tools.
+
+The Cronos module glues IBC, gravity bridge and ethermint together through hooks and token mapping.
+
+## Gas Token
+
+Cronos uses CRO as its gas token.
+
+The CRO assets on the Cronos Chain need to be transferred from the Crypto.org Chain through an IBC channel. The tokens arrive on the Cronos Chain as IBC tokens first, then are automatically converted to the gas token. 
+
+### Decimal Places Conversion
+
+The CRO on the Crypto.org chain has 8 decimals, while the Cronos gas token has 18 decimals (to keep compatibility with Ethereum). So a conversion is done automatically:
+
+- When transferring CRO to Cronos chain, the decimal places of the amount are expanded to 18.
+- When transferring CRO from Cronos chain, the amount is truncated to 8 decimals, the remaining part is left in Cronos, so the total value is preserved.
+
+## Native Token
+
+Native token is a token managed by cosmos native bank module, there are several kinds of native tokens in Cronos:
+
+- gas token. used to pay the gas fee.
+- staking token. used to do PoA consensus.
+- IBC token. tokens come from IBC channels.
+- gravity token. tokens come from the gravity bridge.
+
+## CRC20 Token
+
+CRC20 token is Cronos's equivalence of ERC20 token on Ethereum with some extensions, they can be mapped with native tokens and support transfer to/from native tokens, and potentially transfer to/from Ethereum and another cosmos chain through gravity bridge and IBC.
+
+## Auto-deployed Contract
+
+A contract whose byte code is embedded in Cronos module and deployed by it, and some operations in it are only authorized to Cronos module. These contracts can be trusted by Cronos module directly. Currently, Cronos module support auto-deploy a minimal CRC20 contract to support automatic wrapping native token in EVM.
+
++++ https://github.com/crypto-org-chain/cronos/blob/v0.6.0-testnet/contracts/src/ModuleCRC20.sol#L5-L52
+
+## Token Mapping
+
+To support transfer tokens between native tokens and EVM tokens, the Cronos module maintains two mappings between native denom to contract address, one for auto-deployed contracts, one for external contracts.
+
+When auto-deployment is enabled, incoming IBC and gravity native tokens are wrapped to an auto-deployed CRC20 contract automatically.
+
+One can also register an external contract mapping for the denom, either through the governance process or an authorized transaction.

x/cronos/spec/02_state.md

@@ -0,0 +1,17 @@
+<!--
+order: 2
+-->
+
+# State
+
+The `x/cronos` module keeps the following objects in state:
+
+| | Key | Value |
+| ----------------------- | -------------------------------------- | -------------------------- |
+| DenomToExternalContract | `[]byte{1} + []byte(denom)` | `[]byte(contract_address)` |
+| DenomToAutoContract | `[]byte{2} + []byte(denom)` | `[]byte(contract_address)` |
+| ContractToDenom | `[]byte{3} + []byte(contract_address)` | `[]byte(denom)` |
+
+- `DenomToExternalContract` stores a map from denom to external CRC20 contract.
+- `DenomToAutoContract` stores a map from denom to auto-deployed CRC20 contract.
+- `ContractToDenom` stores the reversed map for both external and auto-deployed contracts.

x/cronos/spec/03_state_transitions.md

@@ -0,0 +1,30 @@
+<!--
+order: 3
+-->
+
+# State Transitions
+
+<!-- define state transitions for accounts and storage -->
+
+This document describes the state transition operations of Cronos module, currently the only state is token mapping.
+
+## Token Mapping
+
+### Create/Update
+
+There are several scenarios when the token mapping is updated:
+
+- When auto-deployment is enabled and a new IBC or gravity token arrived.
+- When auto-deployment is enabled and `MsgConvertVouchers` message executed with a new token.
+- When a `TokenMappingChangeProposal` gov proposal is executed.
+- When the admin account execute a `MsgUpdateTokenMapping` message.
+
+When the mapping updated, the token migration between old and new contracts can be managed by contract developer, for example, the new contract could allow user to swap old token to new one.
+
+#### Contract Migration
+
+When token mapping get updated, the old contract still exists.
+
+### Delete
+
+There's no way to delete a token mapping currently.

x/cronos/spec/04_messages.md

@@ -0,0 +1,55 @@
+<!-- order: 4 -->
+
+# Messages
+
+## MsgConvertVouchers
+
+> Normally user should use Cronos smart contract to do this, no need to use this message directly.
+
+Convert native tokens to the mapped CRC20 tokens, if the mapping does not exist and auto-deployment is enabled, an embed CRC20 contract is deployed for it automatically, otherwise, the message fails.
+
++++ https://github.com/crypto-org-chain/cronos/blob/v0.6.0-testnet/proto/cronos/tx.proto#L26-L30
+
+This message is expected to fail if:
+
+- The coin denom is neither IBC nor gravity tokens.
+- The mapping does not exist and auto-deployment is not enabled.
+
+Fields:
+
+- `address`: Message signer, bech32 address on Cronos.
+- `coins`: The coins to convert.
+
+## MsgTransferTokens
+
+> Normally user should use Cronos smart contract to do this, no need to use this message directly.
+
+Transfer IBC tokens (including CRO) away from Cronos chain, decimals conversion is done automatically for CRO.
+
+It calls the ibc transfer module internally, the `timeoutHeight` parameter is hardcoded to zero, the `timeoutTimestamp` parameter is set according the `IbcTimeout` module parameter.
+
++++ https://github.com/crypto-org-chain/cronos/blob/v0.6.0-testnet/proto/cronos/tx.proto#L33-L38
+
+This message is expected to fail if:
+
+- The sender doesn't have enough balance.
+- The IBC transfer message fails.
+
+Fields:
+
+- `from`: Message signer, bech32 address on Cronos.
+- `to`: The destination address of IBC transfer.
+- `coins`: The coins to transfer.
+
+## MsgUpdateTokenMapping
+
+Update external token mapping, insert if not exists, can only be called by Cronos admin account, which is configured in module parameters.
+
++++ https://github.com/crypto-org-chain/cronos/blob/v0.6.0-testnet/proto/cronos/tx.proto#L47-L51
+
+This message is expected to fail if:
+
+- The sender is not authorized.
+- The contract address or denom is malformed.
+
+- The contract is already mapped to anther denom.

x/cronos/spec/05_abci.md

@@ -0,0 +1,15 @@
+<!--
+order: 5
+-->
+
+# ABCI
+
+## InitGenesis
+
+`InitGenesis` initializes the Cronos module genesis state by setting the `GenesisState` fields to the
+store. In particular it sets the parameters and token mapping state.
+
+## ExportGenesis
+
+The `ExportGenesis` ABCI function exports the genesis state of the Cronos module. In particular, it
+iterates all token mappings to genesis.

x/cronos/spec/06_events.md

@@ -0,0 +1,35 @@
+<!--
+order: 6
+-->
+
+# Events
+
+The Cronos module emits the Cosmos SDK [events](./../../../docs/quickstart/events.md#sdk-and-tendermint-events) after a state execution. It can be expected that the type `message`, with an
+attribute key of `action` will represent the first event for each message being processed as emitted
+by the Cosmos SDK's `Baseapp` (i.e the the basic application that implements Tendermint Core's ABCI
+interface).
+
+## MsgConvertVouchers
+
+| Type | Attribute Key | Attribute Value |
+| ---------------- | ------------- | ------------------ |
+| convert_vouchers | `"sender"` | `{bech32_address}` |
+| convert_vouchers | `"amount"` | `{amount}` |
+| message | module | cronos |
+| message | action | ConvertVouchers |
+
+## MsgTransferTokens
+
+| Type | Attribute Key | Attribute Value |
+| --------------- | ------------- | ------------------ |
+| transfer_tokens | `"sender"` | `{bech32_address}` |
+| transfer_tokens | `"recipient"` | `{bech32_address}` |
+| transfer_tokens | `"amount"` | `{amount}` |
+| message | module | cronos |
+| message | action | TransferTokens |
+
+## MsgUpdateTokenMapping
+
+| Type | Attribute Key | Attribute Value |
+| ------- | ------------- | ------------------ |
+| message | action | UpdateTokenMapping |

x/cronos/spec/07_params.md

@@ -0,0 +1,32 @@
+<!--
+order: 7
+-->
+
+# Parameters
+
+The Cronos module contains the following parameters:
+
+| Key | Type | Default Value |
+| ---------------------- | ------ | ------------------------------------------------------------ |
+| `IbcCroDenom` | string | `"ibc/6B5A664BF0AF4F71B2F0BAA33141E2F1321242FBD5D19762F541EC971ACB0865"` |
+| `IbcTimeout` | uint64 | `86400000000000` |
+| `CronosAdmin` | string | `""` |
+| `EnableAutoDeployment` | bool | `false` |
+
+- `IbcCroDenom` Specifies the IBC token that should be converted to gas token upon arrival automatically.
+
+ When update this parameter at runtime, the tokens are not migrated magically, might need to handle the token migration explicitly, e.g. some token swap mechanism.
+
+- `IbcTimeout` The timeout value to use when Cronos module transfer tokens to IBC channels.
+
+ Can be updated at runtime.
+
+- `CronosAdmin` The account that is authorized to manage token mapping through message, empty means no admin, should be a valid bech32 cosmos address if specified.
+
+ Can be updated at runtime.
+
+- `EnableAutoDeployment` Specifies if the auto-deployment feature is enabled. 
+
+ When disabled and there's no external contract mapped for the token, new coming tokens are kept as native tokens, user can transfer them back using cosmos native messages.
+
+ Can be updated at runtime, after disabled at runtime, the previous deposited tokens can still be withdrawn.

x/cronos/spec/README.md

@@ -0,0 +1,22 @@
+<!--
+order: 0
+title: Cronos Overview
+parent:
+ title: "cronos"
+-->
+
+# `cronos`
+
+## Abstract
+
+This document defines the specification of the Cronos module.
+
+## Contents
+
+1. **[Concepts](01_concepts.md)**
+2. **[State](02_state.md)**
+3. **[State Transitions](03_state_transitions.md)**
+4. **[Messages](04_messages.md)**
+5. **[ABCI](05_abci.md)**
+6. **[Events](06_events.md)**
+7. **[Parameters](07_params.md)**