마루 아키텍처
Cosmos SDK와 EVM을 결합한 하이브리드 체인입니다. 네이티브 프리컴파일이 Solidity와 체인 레벨 기능을 연결합니다.
마루는 CometBFT 합의 위에 Cosmos SDK와 EVM을 결합한 하이브리드 체인입니다. Solidity 컨트랙트는 표준 도구(Hardhat, Foundry, ethers/viem)와 함께 그대로 동작하며, 고정된 EVM 주소에 위치한 프리컴파일(OKRW, PCL, EAS, Agent, Privacy)이 컨트랙트를 체인 고유 기능(스테이블코인, 컴플라이언스, 신원, AI 에이전트 레지스트리, 은닉 전송)에 연결합니다.
주요 기능
EVM 호환
Solidity, ABI, JSON-RPC 표준을 그대로 따릅니다. Hardhat, Foundry, ethers, viem 모두 마루 전용 패치 없이 동작합니다.
네이티브 프리컴파일
OKRW(가스 겸 스테이블코인 운영), PCL(컴플라이언스), EAS(KYC/KYB attestation), Agent(ERC-8004 에이전트 신원), Privacy(은닉 OKRW)로 구성됩니다.
합의 레벨 컴플라이언스
PCL은 각 트랜잭션의 호출 자체를 제출 시점과 체인의 실행 전 검사에서 전역 정책에 대해 검사하며, 여기서 위반이 확인된 트랜잭션은 실행 전에 거절되고 구조화된 ReasonCode를 반환합니다. PCL 래핑 컨트랙트의 정책은 실행 중 프록시 훅에서 실행되고, 전역 정책은 실행 후 다시 실행됩니다. 이 단계에서 위반이 발견되면 트랜잭션은 실패하지만 블록에 포함되며 가스비도 부과됩니다.
OKRW 기반 가스 (EIP-1559)
Base fee와 priority tip 모두 atokrw로 지불합니다. 수수료 시장이 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"]
PRV["Privacy<br/>0x..00b"]
end
STATE["Maroo chain state<br/>balances · policies · agents · shielded pool"]
EASC["EAS contracts<br/>SchemaRegistry 0x…006 · EAS 0x…007 · Indexer 0x…008"]
SC -->|call| OKRW
SC -->|call| PCL
SC -->|call| PRV
SC -->|call| EAS
SC -->|call| AGT
OKRW -->|reads · writes| STATE
PCL -->|reads · writes| STATE
PRV -->|reads · writes| STATE
EAS -.->|returns the EAS contract addresses| EASC
AGT -->|reads| STATE
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,EASC evm;
class OKRW,PCL,EAS,AGT,PRV precompile;
class STATE module; 마루의 레이어드 스택을 보여줍니다. Solidity 컨트랙트는 고정 주소의 네이티브 프리컴파일을 호출합니다. OKRW, PCL, Privacy 프리컴파일은 체인의 네이티브 상태(잔액, 정책, 은닉 풀)를 읽고 씁니다. Agent 프리컴파일은 읽기만 하며, 에이전트 인덱스와 매개변수를 반환합니다. EAS 프리컴파일은 EAS 컨트랙트(SchemaRegistry, EAS, Indexer)의 주소만 반환하며, attestation은 EAS 컨트랙트에 있습니다.
한 단락으로 보는 아키텍처
x/vm과 EIP-1559 수수료 시장)에 더해, 마루 고유 기능을 위한 네이티브 모듈(x/okrw 스테이블코인 발행, x/pcl 컴플라이언스, x/agent ERC-8004 에이전트 인덱스, x/privacy 은닉 OKRW)과 표준 체인 모듈(auth, bank, staking, gov)을 함께 갖춥니다. OKRW 잔액은 bank 모듈에 있습니다. x/eas는 매개변수(세 EAS 컨트랙트의 주소)만 저장하고, PCL을 대신해 EAS_POLICY가 지정한 EAS 컨트랙트와 Indexer를 읽습니다(보통 정식 preinstall이며, 테스트넷의 전역 정책도 그렇습니다). CometBFT 합의가 즉각적이고 fork 없는 최종성을 제공합니다.dApp 빌더 입장에서는 Solidity로 작성하고 배포한 뒤 표준 도구로 호출하면 됩니다. 마루 고유 영역은 프리컴파일을 통해 제공됩니다.
프리컴파일이란
interface IFoo { ... } import와 같은 IFoo(address).bar() 문법을 씁니다. 다만 한 가지 차이에 주의해야 합니다. 프리컴파일에는 EVM 바이트코드가 없습니다(eth_getCode가 0x를 반환합니다). Solidity는 반환값이 없는 함수를 일반 문법으로 호출하기 전에 대상의 코드 크기를 확인하므로, 이런 호출은 프리컴파일에 닿기 전에 빈 데이터로 revert됩니다. 이런 함수는 address(…).call(abi.encodeCall(IFoo.bar, (…))) 같은 저수준 호출로 부르고 revert 데이터를 그대로 전달합니다. 값을 반환하는 함수는 일반 문법으로 호출해도 됩니다. 차이는 프리컴파일이 체인 레벨 모듈 상태를 직접 읽고 쓸 수 있다는 점입니다. EVM 바이트코드로는 구현할 수 없는 기능(OKRW 발행, PCL 정책 평가 등)을 Solidity와 연결합니다. EAS는 여기에 해당하지 않습니다. attestation은 일반 EVM 바이트코드인 0x1000000000000000000000000000000000000007의 EAS 컨트랙트 preinstall에 있으며, EAS 프리컴파일은 schemaRegistry, eas, indexer 주소만 반환합니다(getParams).마루 프리컴파일의 주소는 안정적이며, 직접 하드코딩하거나
@maroo-chain/contracts에서 import할 수 있습니다. 다만 마루 테스트넷에서 처음부터 있었던 것은 OKRW와 PCL뿐입니다. EAS와 Agent는 v0.4.0 업그레이드(블록 6,372,905)로, Privacy는 v0.8(블록 14,882,540)로 추가되었으므로, 그 이전 높이에서 이들을 호출하거나 로그를 조회하면 아무것도 나오지 않습니다.트랜잭션 라이프사이클
1. 실행 전 검사: 직접 호출과 규제 경로 모두에 대해 전역 정책으로 PCL 사전 검사를 먼저 수행한 뒤, 서명 → 수수료 차감(
atokrw) → 논스 → 가스 한도 검증을 진행합니다.2. 실행: EVM이 바이트코드를 실행합니다.
3. 상태 커밋: 변경사항이 영구화되고 이벤트가 발행됩니다.
노드의 JSON-RPC는 트랜잭션이 제출될 때 이와 같은 검사를 실행하므로,
eth_sendRawTransaction은 위반 트랜잭션을 거절하고 전파하지 않습니다. 체인 내부에서는 PCL 사전 검사가 첫 번째 컴플라이언스 게이트입니다. 트랜잭션의 호출 자체가 이미 활성 전역 정책(denylist, attestation 요구, 금액 한도 등)을 위반하면 실행 전 여기서 거절되며, 구조화된 ReasonCode가 반환됩니다. 검사는 여기서 끝나지 않습니다. PCL 래핑 컨트랙트의 자체 정책은 실행 중 프록시의 preCall / postCall 훅에서 실행되고, 전역 정책은 실행 후 그 트랜잭션이 만든 전송들에 대해 다시 실행됩니다. 이 단계에서 위반이 발견되면 트랜잭션은 실패하지만 블록에는 포함되며 가스비도 부과됩니다. 자세한 내용은 pcl-policy-enforcement와 pcl-reason-codes 페이지를 참고합니다.flowchart LR
Tx["Tx 진입"] --> AH["실행 전 검사<br/>PCL 사전 검사 · 서명 · 수수료 · 논스 · 가스"]
AH -->|통과| Exec["EVM 실행"]
AH -->|거절| Rej["실행 전 거절<br/>(PCL ReasonCode 또는 SDK 오류)"]
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는 실행에 앞서 체인의 실행 전 검사(PCL 사전 검사 포함)를 거칩니다.
핵심 프리컴파일
| 프리컴파일 | 주소 | 연결되는 모듈 | 상세 |
|---|---|---|---|
| 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 |
| Privacy | 0x...00b | x/privacy — 은닉 OKRW | privacy-precompile-overview |
신원 프리미티브는 의도적으로 두 프리컴파일로 분리되어 있습니다 — EAS는 사람/법인 attestation (KYC/KYB), Agent는 ERC-8004 AI 에이전트 신원 (KYA). attestation 모델 차이가 커서, 통합 surface 하나보다 각각 별도 브릿지를 두는 편이 더 깔끔합니다.
각 프리컴파일 페이지에서 Solidity 인터페이스, 고정 주소, 호출 예제를 확인합니다.