마루 아키텍처
Cosmos SDK와 EVM을 결합한 하이브리드 체인입니다. 네 개의 네이티브 프리컴파일이 Solidity와 체인 레벨 기능을 연결합니다.
마루는 CometBFT 합의 위에 Cosmos SDK와 EVM을 결합한 하이브리드 체인입니다. Solidity 컨트랙트는 표준 도구(Hardhat, Foundry, ethers/viem)와 함께 그대로 동작하며, 고정된 EVM 주소에 위치한 네 개의 프리컴파일(OKRW, PCL, EAS, Agent)이 컨트랙트를 체인 고유 기능(스테이블코인, 컴플라이언스, 신원, AI 에이전트 레지스트리)에 연결합니다.
주요 기능
EVM 호환
Solidity, ABI, JSON-RPC 표준을 그대로 따릅니다. Hardhat, Foundry, ethers, viem 모두 마루 전용 패치 없이 동작합니다.
4개 네이티브 프리컴파일
OKRW(가스 겸 스테이블코인 운영), PCL(컴플라이언스), EAS(KYC/KYB attestation), Agent(ERC-8004 에이전트 신원) 네 가지로 구성됩니다.
합의 레벨 컴플라이언스
PCL이 AnteHandler 내부에서 정책을 평가하며, 비준수 트랜잭션은 실행 전에 거절되며 구조화된 ReasonCode를 반환합니다.
OKRW 기반 가스 (EIP-1559)
Base fee와 priority tip 모두 aokrw로 지불합니다. 수수료 시장이 EIP-1559와 호환되므로 표준 도구가 올바른 값을 자동으로 계산합니다.
아키텍처
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; 마루의 레이어드 스택을 보여줍니다. Solidity 컨트랙트가 고정 주소의 네이티브 프리컴파일을 호출하면, 프리컴파일이 정식 상태를 보유한 체인 모듈로 연결됩니다.
한 단락으로 보는 아키텍처
x/vm과 EIP-1559 수수료 시장)에 더해, 마루 고유 기능의 정식 상태를 보유하는 네이티브 모듈(x/okrw 스테이블코인, x/pcl 컴플라이언스, x/eas KYC/KYB attestation 인덱스, x/agent ERC-8004 에이전트 인덱스)과 표준 체인 모듈(auth, bank, staking, gov)을 함께 갖춥니다. CometBFT 합의가 즉각적이고 fork 없는 최종성을 제공합니다.dApp 빌더 입장에서는 Solidity로 작성하고 배포한 뒤 표준 도구로 호출하면 됩니다. 마루 고유 영역은 4개의 프리컴파일을 통해 제공됩니다.
프리컴파일이란
interface IFoo { ... } import, 같은 IFoo(address).bar() 문법. 차이는 프리컴파일이 체인 레벨 모듈 상태를 직접 읽고 쓸 수 있다는 점입니다. EVM 바이트코드로는 구현할 수 없는 기능(OKRW 발행, PCL 정책 평가, EAS attestation 조회 등)을 Solidity와 연결합니다.마루의 4개 프리컴파일은 제네시스 시점에 등록됩니다. 주소는 안정적이며, 직접 하드코딩하거나
@maroo-chain/contracts에서 import할 수 있습니다.트랜잭션 라이프사이클
1. AnteHandler 검증: 서명 → 논스 → 수수료 차감(
aokrw) → 가스 한도 검증 → 규제 경로의 경우 PCL 사전 검사를 수행합니다.2. 실행: EVM이 바이트코드를 실행합니다.
3. 상태 커밋: 변경사항이 영구화되고 이벤트가 발행됩니다.
PCL 사전 검사는 체인 레벨 컴플라이언스 게이트입니다. 활성 정책(denylist, attestation 요구, 금액 한도 등)을 위반하는 트랜잭션은 실행 전 여기서 거절되며, 구조화된
ReasonCode가 반환됩니다. 자세한 내용은 pcl-policy-enforcement와 pcl-reason-codes 페이지를 참고합니다.flowchart LR
Tx["Tx 진입"] --> AH["AnteHandler<br/>서명 · 논스 · 수수료 · 가스 · PCL 사전검사"]
AH -->|통과| Exec["EVM 실행"]
AH -->|거절| Rej["Revert + ReasonCode"]
Exec --> State["상태 업데이트, 이벤트 발행"]
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; 트랜잭션 흐름: 모든 tx는 실행 전 AnteHandler(PCL 사전검사 포함)를 거칩니다.
4개 핵심 프리컴파일
| 프리컴파일 | 주소 | 연결되는 모듈 | 상세 |
|---|---|---|---|
| OKRW | 0x...001 | x/okrw + x/bank | okrw-precompile-overview |
| PCL | 0x...005 | x/pcl | pcl-precompile-overview |
| EAS | 0x...009 | x/eas (Ethereum Attestation Service 브릿지) | eas-precompile-overview |
| Agent | 0x...00A | x/agent + ERC-8004 IdentityRegistry preinstall | agent-precompile-overview |
신원 프리미티브는 의도적으로 두 프리컴파일로 분리되어 있습니다 — EAS는 사람/법인 attestation (KYC/KYB), Agent는 ERC-8004 AI 에이전트 신원 (KYA). attestation 모델 차이가 커서, 통합 surface 하나보다 각각 별도 브릿지를 두는 편이 더 깔끔합니다.
각 프리컴파일 페이지에서 Solidity 인터페이스, 고정 주소, 호출 예제를 확인합니다.