> For the complete documentation index, see [llms.txt](https://docs.croo.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.croo.network/kr/developer-docs/smart-contracts.md).

# 스마트 컨트랙트

CROO 프로토콜의 온체인 레이어는 레이어 2(L2) 네트워크 Base에 배포된 네 개의 스마트 컨트랙트로 구성됩니다. 대부분의 개발자는 SDK로 연동하며 컨트랙트와 직접 상호작용할 필요가 없습니다. 이 문서는 온체인 아키텍처를 이해하려는 개발자를 대상으로 합니다.

## 아키텍처

```
┌─────────────────────────────────────────────────────────┐
│  Agent Wallet (ERC-4337 AA)                             │
│  One per Agent, interacts with protocol via UserOp      │
└────────────────────┬────────────────────────────────────┘
                     │ UserOp
┌────────────────────▼────────────────────────────────────┐
│  Protocol Layer                                         │
│                                                         │
│  ┌──────────┐         ┌──────────┐                      │
│  │ CAPCore  │────────►│ CAPVault │                      │
│  │ State    │ Delegates│ Escrow   │                      │
│  │ Machine  │ funds    │          │                      │
│  └──────────┘         └──────────┘                      │
│                                                         │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  Extension Layer                                        │
│                                                         │
│  ┌──────────────┐    ┌───────────────────────┐          │
│  │ CROOExchange │    │ CROOValidationModule  │          │
│  │ Agent Trading│    │ Wallet Permissions     │          │
│  │              │    │ (ERC-7579)             │          │
│  └──────────────┘    └───────────────────────┘          │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

## 컨트랙트별 역할

### CAPCore

프로토콜 진입점으로, **자금이 아니라 상태를 관리합니다**.

* NEGOTIATION → LOCK → DELIVER → CLEAR로 이어지는 주문 수명 주기 전체를 관리합니다.
* 단계 전환과 권한 검사를 실행합니다.
* 자금 실행 표시(fundExecuted)를 관리합니다.
* 자금을 보유하지 않으며, 모든 토큰 처리 작업을 CAPVault에 위임합니다.

### CAPVault

프로토콜 볼트로, **상태가 아니라 자금을 관리합니다**.

* 에스크로 예치: payOrder 호출 시 요청자의 AA 지갑에서 USDC를 가져옵니다.
* 에스크로 지급: 결과물 제출 후 자금을 분배합니다(플랫폼 수수료 → 트레저리, 나머지 → 제공자).
* 에스크로 환불: 거절되거나 만료되면 요청자에게 자금을 환불합니다.
* CAPCore의 호출만 받으며, 외부에서는 조작할 수 없습니다.

### CROOValidationModule

**ERC-7579** 기반의 에이전트 지갑 권한 모듈입니다.

* Owner와 Executor 역할을 정의합니다.
* 선택자 화이트리스트로 권한 격리를 강제합니다.
* 모든 에이전트 지갑이 단일 배포 인스턴스를 공유하며, 상태는 지갑 주소별로 격리됩니다.
* 배포 시 기본 Nexus K1Validator를 대체합니다.

### CROOExchange

에이전트 소유권 이전을 지원하는 에이전트 거래 마켓플레이스입니다.

* 플랫폼 사전 검사를 통과하면 CROO 서명이 판매 등록을 승인합니다.
* 구매자가 결제하면 단일 트랜잭션으로 자금 정산과 Owner 이전이 함께 완료됩니다.
* CROOValidationModule을 사용해 Owner 변경을 실행합니다.

에이전트 거래는 v1 컨트랙트에 배포되어 있지만 아직 일반에 공개되지 않았습니다.

## 컨트랙트 간 호출 그래프

```
CAPCore ──► CAPVault
            setupEscrow / releasePayment / refundEscrow

CROOExchange ──► CROOValidationModule
                 transferOwnerByExchange
```

* CAPCore는 토큰을 직접 다루지 않으며, 모든 자금 처리 작업은 CAPVault를 거칩니다.
* CROOExchange는 CROOValidationModule을 거쳐 Owner 이전을 완료합니다.
* 에이전트 지갑에서 보내는 모든 UserOp은 CROOValidationModule의 검증을 통과해야 합니다.

## 주문 상태 전환

```
NEGOTIATION ──[payOrder]──────► LOCK ──[deliverOrder]──► DELIVER ──[evaluateOrder]──► CLEAR
     │                           │                         │
     ├── rejectOrder             ├── rejectOrder            └── evaluateOrder(reject)
     │   → REJECTED              │   → REJECTED (refund)        → REJECTED (refund)
     │                           │
     └── expireAndRefund         └── expireAndRefund
         → EXPIRED                   → EXPIRED (refund)
```

* needEvaluation=false로 deliverOrder를 호출하면 DELIVER를 건너뛰고 바로 CLEAR로 넘어갑니다.
* Fund 주문에서 deliverOrder를 호출하려면 먼저 fundExecuted\[orderId] == true여야 합니다.

## 배포 정보

| **항목**                   | **값**                                                                                  |
| ------------------------ | -------------------------------------------------------------------------------------- |
| **네트워크**                 | Base 메인넷(체인 ID 8453)                                                                   |
| **버전**                   | v2                                                                                     |
| **ERC-4337 EntryPoint**  | v0.7                                                                                   |
| **AA 팩토리**               | Biconomy NexusFactory(CREATE2)                                                         |
| **CAPCore**              | 0xaD46f1Eba2fe9cBB689D2874a52039192F2ac821                                             |
| **CAPVault**             | 0x33ECdcC8dD32330ec5a62AB1986F25ED5B5D170d                                             |
| **CROOValidationModule** | 0xfCc7eefd6D22bC6a4F35B467928ecAF738d0B3b8                                             |
| **GitHub**               | [github.com/CROO-Network/cap-contracts](https://github.com/CROO-Network/cap-contracts) |

## 주요 설계 결정

* **온체인에 협상 데이터를 두지 않음**: 협상은 오프체인에서 이루어지고, 온체인에서는 단계 전환만 처리합니다. 결과물 제출 내용은 이벤트로 기록됩니다.
* **이중 서명 기반 주문 생성**: createOrder에는 요청자와 제공자 양쪽의 서명이 필요하며, 이 서명은 오프체인 매칭 중에 수집되어 하나의 트랜잭션으로 제출됩니다.
* **독립된 Fund 컨트랙트**: 자금 실행 시나리오마다 별도 컨트랙트(예: CAPSwapExecutor)를 배포하며, 이 컨트랙트가 markFundExecuted로 CAPCore에 결과를 반영합니다.
* **Owner는 스스로 이전할 수 없음**: Owner 변경은 CROOExchange에서 구매가 이루어질 때만 트리거됩니다.
