# Security Audit

## Contact Info

- Federico Kunze Küllmer - CEO & Co-Founder at Tharsis ([[e-mail]](mailto:[e-mail]))
- Security contact (Co-founders and core-engineering team): [[e-mail]](mailto:[e-mail])

## Proposed Scope of Work

### Keys and crypto

Ethermint implements the `secp256k1` key derivation from go-ethereum to comply with the required interfaces (PrivKey, PubKey, Keyring). All the relevant code can be found on the `crypto/` directory of the project as well as on the protobuf message definitions on the `proto/` library.

The scope on Ethermint should be that key derivation, signature verification and validation should work properly (no errors) and address should match ethereum's at using the different [`Signer`](https://pkg.go.dev/github.com/ethereum/go-ethereum/core/types#Signer) concrete types (according to each hard fork).

References:

- [https://pkg.go.dev/github.com/cosmos/cosmos-sdk@v0.43.0/crypto/keyring](https://pkg.go.dev/github.com/cosmos/cosmos-sdk@v0.43.0/crypto/keyring)
- [https://pkg.go.dev/github.com/cosmos/cosmos-sdk@v0.43.0/crypto/hd](https://pkg.go.dev/github.com/cosmos/cosmos-sdk@v0.43.0/crypto/hd)
- [https://pkg.go.dev/github.com/ethereum/go-ethereum/core/types#Signer](https://pkg.go.dev/github.com/ethereum/go-ethereum/core/types#Signer)

### JSON-RPC

Ethermint implements the JSON-RPC client for full Web3 compatibility with Ethereum tooling. In particular, several of the Ethereum [namespaces](https://ethermint.dev/api/json-rpc/namespaces.html) implementations have been adapted to be able to work with Tendermint and the EVM module.

In the `personal` API is the one manages private keys in the key store.

- https://ethermint.dev/api/json-rpc/namespaces.html
- https://ethermint.dev/api/JSON-RPC/endpoints.html

### AnteHandler

Implementation: `app/ante/`

### EVM module

This module is the most critical component of the Ethermint chain as it is the part of the codebase that supports the EVM state transition executions.

#### StateDB

The x/evm module is EVM compatible because it implements the [`StateDB`](https://pkg.go.dev/github.com/ethereum/go-ethereum/core/vm#StateDB) interface. This is done by leveraging other modules from the SDK that have access to accounts (AccountKeeper) and accounting (BankKeeper).

Important parts to take into consideration:

- Balance accounting: Add and subtract balance
- Account Updates (CRUD)
- Account Reset
- →**Reverting changes**← (`Snapshot` and `RevertToSnapshot`): Relevant for failed transaction execution.

#### EVM State Transition

Once the transaction is submitted by the JSON-RPC client. It's processed by the `AnteHandler` and then
processed by the evm module.

Implementation: `x/evm/keeper/state_transition.go`

References (go-ethereum):
- [https://pkg.go.dev/github.com/ethereum/go-ethereum/core#ApplyTransaction](https://pkg.go.dev/github.com/ethereum/go-ethereum/core#ApplyTransaction)
- [https://pkg.go.dev/github.com/ethereum/go-ethereum/core#ApplyMessage](https://pkg.go.dev/github.com/ethereum/go-ethereum/core#ApplyMessage)

## Codebase Architecture

- `proto/`: protobuf message definitions as well as query and msg services for gRPC
- `x/evm` module: This module is the most critical component of the Ethermint chain as it is the part of the codebase that supports the EVM state transition executions
- `keeper/`: Contains the StateDB reference implementation, state transition logic, tx and query functionality (gRPC services).
- `types/`: general types (including the auto generated ones from the protobuf definitions) and stateless functions used in the EVM module
- Parameters: module parameters that can be configured through on-chain governance.
- `TxData`: Interface that supports all the transactions types from go ethereum `LegacyTx`, `AccessListTx`, `DynamicFeeTx`.
- Messages: An EVM state transition can be achieved by using the `MsgEthereumTx`. This message encapsulates an Ethereum transaction as an SDK message and contains the necessary transaction data fields.
- `crypto/`: Implementation of the go-ethereum secp256k1 curve for compatibility with the SDK Keyring
- `hd/`: Key generation and derivation
- `ethsecp256k1/`: Implementation of the SDK crypto `PrivKey` and `PubKey` interfaces and signature verification
- `app/`: application constructor and [`AnteHandler`](https://docs.cosmos.network/v0.43/core/baseapp.html#antehandler)
- `ante/`:
-

- `ethereum/rpc` : The JSON-RPC server implementation and its corresponding APIs (i.e namespaces).

## References

- Docs: [ethermint.dev](http://ethermint.dev)
- Cosmos SDK docs: [https://docs.cosmos.network/](https://docs.cosmos.network/)
- Core Concepts: [https://docs.cosmos.network/v0.43/core/](https://docs.cosmos.network/v0.43/core/)
- Go-ethereum: [https://github.com/ethereum/go-ethereum/](https://github.com/ethereum/go-ethereum/)