Maroo Application Architecture
A deep dive into the modular structure of the Maroo blockchain application, combining the Cosmos SDK, EVM, and custom Maroo modules.
The Maroo application (MarooApp) is the core software that runs a Maroo node. It's built using the Cosmos SDK framework, providing a robust, modular foundation for features like staking, governance, and interoperability via IBC. At its heart, it integrates a fully EVM-compatible execution environment, allowing developers to deploy and interact with Solidity smart contracts. Maroo extends this base with specialized modules for compliance (PCL), identity, and its native stablecoin (OKRW).
Key Features
Modular Composition
Built on the Cosmos SDK, the application is composed of interoperable modules, making it extensible and maintainable.
Full EVM Compatibility
Integrates the `x/vm` (EVM) module, enabling seamless execution of Ethereum transactions and smart contracts.
Custom Business Logic
Features unique Maroo modules like PCL, Identity, and OKRW, exposed as precompiles for easy smart contract access.
Integrated Mempool
Utilizes a specialized EVM mempool for sophisticated transaction ordering and prioritization, compatible with both Cosmos and Ethereum transaction types.
Architecture
graph TD
subgraph Maroo Node
A[JSON-RPC / gRPC / Tendermint RPC] --> B[MarooApp];
B --> C{Module Manager};
C --> D[x/auth];
C --> E[x/bank];
C --> F[x/staking];
C --> G[x/vm - EVM];
C --> H[x/feemarket];
C --> I[x/pcl];
C --> J[x/okrw];
C --> K[x/identity];
B --> L[AnteHandler Chain];
B --> M[EVM Mempool];
B --> N[CometBFT];
N --> O[State DB];
end High-level architecture of the Maroo application, showing the flow of requests through the module manager to core Cosmos, EVM, and custom Maroo modules.
Application Initialization
NewMarooApp function in app/app.go is the entry point for constructing a new application instance. This extensive function performs several critical setup tasks:1. Module Registration: It registers all necessary Cosmos SDK modules (
auth, bank, staking, gov), EVM modules (vm, feemarket, erc20), and Maroo's custom modules (pcl, okrw, identity). This registration process informs the application about each module's message handlers, queriers, and genesis logic.2. Keeper Instantiation: It creates instances of each module's 'keeper', which is responsible for managing that module's dedicated portion of the blockchain state.
3. Store Key Allocation: It allocates unique keys for each module to access its own isolated state within the underlying database.
4. Wiring Dependencies: It connects the modules by passing keeper instances to other modules that depend on them. For example, the
EVMKeeper requires access to the BankKeeper to handle token transfers and the AccountKeeper to manage account nonces.Transaction Processing Flow
AnteHandler and the mempool.The
AnteHandler is a chain of decorators, each performing a specific validation check. For Maroo, this includes standard checks like signature verification, fee deduction, and nonce validation, as well as EVM-specific checks for gas limits and chain ID. The NewAppAnteHandler function in ante/ante.go constructs this chain, ensuring all transactions, whether Cosmos or Ethereum-native, are properly vetted.Once validated by the AnteHandler, transactions enter the EVM-aware mempool, configured in
app/mempool.go. This component is responsible for prioritizing transactions, typically by gas price (or tip), to determine their order of inclusion in the next block proposed by a validator. It manages both Cosmos SDK sdk.Tx and Ethereum ethtx.MsgEthereumTx types, creating a unified queue for consensus.State Export and Genesis
ExportAppStateAndValidators function in app/export.go handles this process. It queries the state of each registered module at a given block height and serializes it into a genesis.json format.Conversely, the
app/genesis.go file defines the default initial state for a brand new Maroo chain. It contains constructor functions like NewEVMGenesisState and NewOkrwGenesisState that specify default parameters, such as enabling all EVM precompiles, setting the native gas token to aokrw, and initializing the parameters for the PCL and OKRW modules. This ensures that a new Maroo network starts with a consistent and correct configuration.