readme and messages

x/evm/spec/04_messages.md

@@ -3,3 +3,44 @@ order: 4
 -->
 
 # Messages
+
+## MsgEthereumTx
+
+An EVM state transition can be achieved by using the `MsgEthereumTx`:
+
+```go
+// MsgEthereumTx encapsulates an Ethereum transaction as an SDK message.
+type MsgEthereumTx struct {
+  Data TxData
+
+  // caches
+  size atomic.Value
+  from atomic.Value
+}
+```
+
+```go
+// TxData implements the Ethereum transaction data structure. It is used
+// solely as intended in Ethereum abiding by the protocol.
+type TxData struct {
+  AccountNonce uint64          `json:"nonce"`
+  Price        *big.Int        `json:"gasPrice"`
+  GasLimit     uint64          `json:"gas"`
+  Recipient    *ethcmn.Address `json:"to" rlp:"nil"` // nil means contract creation
+  Amount       *big.Int        `json:"value"`
+  Payload      []byte          `json:"input"`
+
+  // signature values
+  V *big.Int `json:"v"`
+  R *big.Int `json:"r"`
+  S *big.Int `json:"s"`
+
+  // hash is only used when marshaling to JSON
+  Hash *ethcmn.Hash `json:"hash" rlp:"-"`
+}
+```
+
+This message is expected to fail if:
+
+- `Data.Price` (i.e gas price) is ≤ 0.
+- `Data.Amount` is negative

x/evm/spec/README.md

@@ -31,23 +31,30 @@ prerequisite reading.
 evm/
 ├── client
 │   └── cli
-│       ├── query.go
-│       └── tx.go
+│       ├── query.go      # CLI query commands for the module
+│       └── tx.go         # CLI transaction commands for the module
 ├── keeper
-│   ├── keeper.go
-│   └── querier.go
+│   ├── keeper.go         # Store keeper that handles the business logic of the module and has access to a specific subtree of the state tree.
+│   ├── params.go         # Parameter getter and setter
+│   ├── querier.go        # State query functions
+│   └── statedb.go        # Functions from types/statedb with a passed in sdk.Context
 ├── types
 │   ├── chain_config.go
 │   ├── codec.go          # Type registration for encoding
 │   ├── errors.go         # Module-specific errors
 │   ├── events.go         # Events exposed to the Tendermint PubSub/Websocket
 │   ├── genesis.go        # Genesis state for the module
 │   ├── journal.go        # Ethereum Journal of state transitions
+│   ├── keys.go           # Store keys and utility functions
+│   ├── logs.go           # Types for persisting Ethereum tx logs on state after chain upgrades
 │   ├── msg.go            # EVM module transaction messages
 │   ├── params.go         # Module parameters that can be customized with governance parameter change proposals
-│   ├── keys.go           # Store keys and utility functions
+│   ├── state_object.go   # EVM state object
+│   ├── statedb.go        # Implementation of the StateDb interface
+│   ├── storage.go        # Implementation of the Ethereum state storage map using arrays to prevent non-determinism
 │   └── tx_data.go        # Ethereum transaction data types
 ├── abci.go               # ABCI BeginBlock and EndBlock logic
+├── genesis.go            # ABCI InitGenesis and ExportGenesis functionality
 ├── handler.go            # Message routing
 └── module.go             # Module setup for the module manager
 ```