Problem: missing high-level docs for x/cronos

Closes: crypto-org-chain#64

Solution:
- write cronos module spec

x/cronos/spec/01_concepts.md

@@ -0,0 +1,47 @@
+<!--
+order: 1
+-->
+
+# Concepts
+
+## Cronos
+
+Cronos is the name of Crypto.org EVM Chain, also the module that glue multiple components together.
+
+## Gas Token
+
+Cronos use CRO as the gas token.
+
+The CROs on Cronos chain need to transfered from Crypto.org chain through IBC channel, they arrive in Cronos chain as IBC tokens first, then get converted to gas token automatically.
+
+### Decimal Places Conversion
+
+The CRO on Crypto.org chain has 8 decimals, while Cronos gas token has 18 decimals (to keep compatibility with Ethereum). So a convertion need to be done:
+
+- When transfer CRO to Cronos chain, the decimal places of the amount are expanded to 18.
+- When transfer CRO from Cronos chain, the amount are 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 gas fee.
+- staking token, used to do PoA consensus.
+- ibc token, tokens come from IBC channels.
+- gravity token, tokens come from gravity bridge.
+
+## CRC20 Token
+
+CRC20 token is Cronos's equavalence of ERC20 token on Ethereum with some extensions, they can be mapped with native tokens and support transfer to/from native tokens, and potential transfered to/from Ethereum and other cosmos chain through gravity bridge and IBC.
+
+## Auto-deployed Contract
+
+Contract whose byte code is embed 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.
+
+## Token Mapping
+
+To support transfer tokens between native tokens and EVM tokens, 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 govenance 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` stored the reversed map for both external and auto-deployed contracts.

x/cronos/spec/03_state_transitions.md

@@ -0,0 +1,7 @@
+<!--
+order: 3
+-->
+
+# State Transitions
+
+<!-- define state transitions for accounts and storage -->

x/cronos/spec/04_messages.md

@@ -0,0 +1,38 @@
+<!--
+order: 4
+-->
+
+# Messages
+
+## MsgConvertVouchers
+
+Convert native tokens to the mapped CRC20 tokens, if the mapping is not exists 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 is not exists and auto-deployment is not enabled.
+
+## MsgTransferTokens
+
+Transfer ibc tokens away from Cronos chain, will do decimals conversion automatically for CRO.
+
++++ 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 don't have enough balance.
+- the ibc transfer message fails.
+
+## 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.

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
+iterate 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,21 @@
+<!--
+order: 7
+-->
+
+# Parameters
+
+The Cronos module contains the following parameters:
+
+| Key | Type | Default Value |
+| ------------------------- | ------ | ------------------------------------------------------------ |
+| `IbcCroDenom` | string | `"ibc/6B5A664BF0AF4F71B2F0BAA33141E2F1321242FBD5D19762F541EC971ACB0865"` |
+| `KeyIbcTimeout` | uint64 | `86400000000000` |
+| `KeyCronosAdmin` | string | `""` |
+| `KeyEnableAutoDeployment` | bool | `false` |
+
+- `IbcCroDenom` Specifies the IBC token that should be converted to gas token upon arrival automatically.
+
+- `KeyIbcTimeout` The timeout value to use when Cronos module transfer tokens to IBC channels.
+
+- `KeyCronosAdmin` The account that is authorized to manage token mapping through message, empty means no admin, should be a valid bech32 cosmos address if specified.
+- `KeyEnableAutoDeployment` specifies if auto-deployment feature is enabled.

x/cronos/spec/README.md

@@ -0,0 +1,22 @@
+<!--
+order: 0
+title: EVM Overview
+parent:
+ title: "evm"
+-->
+
+# `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)**