Maroo Architecture

core external-dapp

Cosmos SDK + EVM hybrid with four native precompiles bridging Solidity to chain-level functionality.

Maroo is a Cosmos SDK + EVM hybrid chain with CometBFT consensus. Solidity contracts work as-is with standard tooling (Hardhat, Foundry, ethers/viem), and four precompiles — OKRW, PCL, EAS, Agent — live at fixed EVM addresses and bridge those contracts to chain-specific functionality (stablecoin, compliance, identity, AI-agent registry).

Key Features

EVM-Compatible

Standard Solidity, ABI, JSON-RPC. Hardhat / Foundry / ethers / viem work without Maroo-specific patches.

Four Native Precompiles

OKRW (gas + stablecoin ops), PCL (compliance), EAS (KYC/KYB attestation), Agent (ERC-8004 agent identity).

Compliance at Consensus Level

PCL evaluates policies inside the AnteHandler — non-compliant transactions are rejected before execution, with a structured ReasonCode.

OKRW-Denominated Gas (EIP-1559)

Base fee + priority tip both paid in aokrw. Fee market is EIP-1559–compatible, so standard tooling computes correct values.

Architecture

graph TB
    subgraph EVM["EVM Execution Environment"]
        SC["Solidity Smart Contract"]
    end

    subgraph PC["Native Precompiles (fixed addresses)"]
        OKRW["OKRW<br/>0x..001"]
        PCL["PCL<br/>0x..005"]
        EAS["EAS<br/>0x..009"]
        AGT["Agent<br/>0x..00A"]
    end

    subgraph COSMOS["Cosmos SDK Modules"]
        XOK["x/okrw"]
        XPC["x/pcl"]
        XEA["x/eas"]
        XAG["x/agent"]
        XBK["x/bank"]
        XGV["x/gov"]
        XST["x/staking"]
        XFM["x/feemarket"]
    end

    SC -->|call| OKRW
    SC -->|call| PCL
    SC -->|call| EAS
    SC -->|call| AGT

    OKRW --> XOK
    OKRW --> XBK
    PCL --> XPC
    EAS --> XEA
    AGT --> XAG

    classDef evm fill:#0096AA,stroke:#0096AA,color:#fff;
    classDef precompile fill:#FF8C50,stroke:#FF8C50,color:#fff;
    classDef module fill:#8CC3C3,stroke:#8CC3C3,color:#fff;
    class SC evm;
    class OKRW,PCL,EAS,AGT precompile;
    class XOK,XPC,XEA,XAG,XBK,XGV,XST,XFM module;

Maroo's layered stack. Solidity contracts call native precompiles at fixed addresses; precompiles bridge to chain modules that hold the canonical state.

Architecture in one paragraph

Maroo combines an EVM execution environment (provided by x/vm plus an EIP-1559 fee market) with native modules that hold the canonical state for Maroo-specific functionality — x/okrw (stablecoin), x/pcl (compliance), x/eas (KYC/KYB attestation index), x/agent (ERC-8004 agent index) — alongside standard chain modules (auth, bank, staking, gov). CometBFT consensus gives instant, fork-free finality.

For an app developer the practical effect is: write Solidity, deploy it, call standard tooling. The Maroo-specific surface appears via the four precompiles.

What is a precompile

A precompile is a smart contract whose logic is implemented in the chain client's native language (Go) instead of EVM bytecode, deployed at a fixed reserved address. From a Solidity caller's perspective it looks and is called exactly like a regular contract — the same interface IFoo { ... } import, the same IFoo(address).bar() syntax. The difference is that the precompile can read and write chain-level module state directly, bridging Solidity to functionality that wouldn't fit in EVM bytecode (e.g., minting OKRW, evaluating a PCL policy, looking up an EAS attestation).

Maroo's four precompiles are registered at genesis. Their addresses are stable; you can hard-code them or import from @maroo-chain/contracts.

Transaction lifecycle

Every transaction flows through the same gate before execution.

1. AnteHandler validation: signature → nonce → fee deduction (in aokrw) → gas-limit check → PCL preflight for the regulated path.
2. Execution: EVM runs the bytecode.
3. State commit: changes are persisted; events emitted.

The PCL preflight is the chain-level compliance gate. If a transaction would violate any active policy (denylist, attestation requirement, volume limit, etc.) it's rejected here, before execution, with a structured ReasonCode. See pcl-policy-enforcement and pcl-reason-codes.

flowchart LR
    Tx["Tx enters"] --> AH["AnteHandler<br/>signature · nonce · fee · gas · PCL preflight"]
    AH -->|pass| Exec["EVM execution"]
    AH -->|reject| Rej["Revert + ReasonCode"]
    Exec --> State["State updated, events emitted"]

    classDef ok fill:#0096AA,stroke:#0096AA,color:#fff;
    classDef gate fill:#FF8C50,stroke:#FF8C50,color:#fff;
    classDef bad fill:#AA0019,stroke:#AA0019,color:#fff;
    class AH gate;
    class Exec,State ok;
    class Rej bad;

Transaction flow: every tx goes through AnteHandler (including PCL preflight) before execution.

The four core precompiles

Precompile	Address	What it bridges to	Detail
OKRW	`0x...001`	`x/okrw` + `x/bank`	`okrw-precompile-overview`
PCL	`0x...005`	`x/pcl`	`pcl-precompile-overview`
EAS	`0x...009`	`x/eas` (bridge to Ethereum Attestation Service)	`eas-precompile-overview`
Agent	`0x...00A`	`x/agent` + ERC-8004 IdentityRegistry preinstall	`agent-precompile-overview`

Identity primitives are split into two precompiles intentionally: EAS is for human/corporate attestations (KYC/KYB), Agent is for ERC-8004 AI agent identity (KYA) — the attestation models differ enough that one bridge each is cleaner than a single combined surface.

Click through to each precompile page for the Solidity interface, fixed address, and call examples.

Next Steps

OKRW Precompile reference → PCL Precompile reference → EAS Precompile reference → Agent Precompile reference →