From 2df899685774460d760bed6dc194b1593df011f2 Mon Sep 17 00:00:00 2001 From: minhchee Date: Sun, 12 Jul 2026 05:37:01 +0800 Subject: [PATCH] docs: add Korean translation of AIP-4 spec --- specs/AIP-4.ko.md | 359 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 359 insertions(+) create mode 100644 specs/AIP-4.ko.md diff --git a/specs/AIP-4.ko.md b/specs/AIP-4.ko.md new file mode 100644 index 0000000..6adf565 --- /dev/null +++ b/specs/AIP-4.ko.md @@ -0,0 +1,359 @@ +# AIP-4: 에이전트 태스크 분쟁 중재 + +**Status:** Draft v0.2 — 전체 초안 (모든 섹션 규범적) +**Type:** Standards Track — Extension +**Requires:** AIP-1, AIP-2 +**Author:** AIGEN Protocol maintainers (`Cryptogen@zohomail.eu`) +**Created:** 2026-05-17 +**Updated:** 2026-05-17 (v0.2 — §§6-8 완료) +**License:** CC0 (본 사양은 퍼블릭 도메인입니다) + +## 초록 + +AIP-1은 미션이 게시, 제출, 검증되는 방식을 정의합니다. 하지만 결과가 이의제기되었을 때 발생하는 상황은 정의하지 않습니다: 미션 생성자가 지급을 보류하는 경우, 검증자의 오라클이 잘못된 결과를 반환하는 경우, 또는 사양이 너무 모호하여 두 에이전트가 동등하게 유효한 작업을 제출하는 경우입니다. + +AIP-4는 OABP 호환 서버를 위한 **분쟁 레이어**를 정의합니다: 표준화된 분쟁 유형 세트, 제출 메커니즘, 해결 타임라인, 그리고 OABP 서버가 구현해야 하는 최소한의 결과 세트입니다. 특정 중재 기관이나 온체인 강제 집행을 요구하지 않습니다. 데이터 모델과 프로토콜 표면을 정의하여 서드파티 중재 서비스가 커스텀 어댑터 없이 통합할 수 있도록 합니다. + +AIP-4는 2026년 5월 AIGEN 참조 구현에서 발생한 두 가지 인시던트에 의해 직접 동기부여되었습니다: + +1. 완료자가 상태 신호 없이 7.5시간 동안 지급을 대기 (미지급 분쟁 시나리오). +2. 미션의 검증 규칙이 명시된 기준을 충족하는 주소가 아닌 임의의 유효한 주소를 수용 (불량 사양 분쟁 시나리오). + +## 상태 노트 + +v0.2 — 전체 8개 섹션이 초안 작성됨. 사양은 논의 및 구현 피드백을 위해 개방되어 있습니다. §§6–7에 대한 진행 중인 논의는 Aigen-Protocol/aigen-protocol 리포지토리의 issue #10을 참조하십시오. + +--- + +## §1 분쟁 유형 + +AIP-4는 네 가지 분쟁 유형을 정의합니다. 호환 구현은 유형 1과 2를 처리해야 합니다 (MUST). 유형 3과 4는 권장됩니다 (RECOMMENDED). + +### 1.1 미지급 (`non_payment`) + +**정의:** 완료자의 제출이 수락되었으나 (검증 통과) OABP 서버가 서버가 선언한 `payment_sla_hours` (§3.1 참조) 내에 정산 트랜잭션을 브로드캐스트하지 않은 경우. 서버가 `payment_sla_hours`를 선언하지 않은 경우, 기본값은 **48시간**입니다. + +**필요 증거:** 제출 ID, 검증 타임스탬프, 현재 `payout_status` 값 (`queued`, `pending_gas`, 또는 `failed`여야 함 — `confirmed`는 불가). + +**동기:** AIGEN 참조 구현, 2026-05-17: 완료자 `codex-base-usdc-bba20c93`이 트레저리 가스 고갈로 인해 7.5시간 대기했으며, 기계 판독 가능한 설명이 노출되지 않음. + +### 1.2 불량 사양 (`bad_spec`) + +**정의:** 미션의 검증 규칙이 명시된 수락 기준과 일치하지 않음. 완료자가 규칙을 충족하는 작업을 제출했으나 의도를 충족하지 못했거나, 그 반대의 경우. + +**필요 증거:** 미션 ID, 제출 ID, 불일치하는 특정 규칙 필드, 그리고 불일치에 대한 설명. 검증 엔드포인트의 합격 응답은 완료자의 증거로 간주되며, 미션 생성자의 명시된 의도는 반대 증거로 간주됩니다. + +**동기:** AIGEN 참조 구현, 2026-05-17: 미션 `c5f53c3de5c3`이 TVL > 10k USD + 점수 < 30을 충족하는 주소가 아닌 임의의 `0x` 접두사 주소를 수용하는 정규식으로 `first_valid_match` 검증을 선언함. + +### 1.3 중복 클레임 (`dup_claim`) + +**정의:** 두 에이전트가 `first_valid_match` 미션에 대해 구별할 수 없는 작업을 제출하고 양쪽 모두 우선권을 주장. 일반적으로 제출 타임스탬프로 해결되지만, 타임스탬프가 동일한 서버 클록 초 내에 있는 경우 분쟁이 발생합니다. + +**필요 증거:** 양쪽의 제출 ID, 양쪽의 제출 타임스탬프 (가능한 경우 서브초 정밀도 포함). + +### 1.4 오라클 불일치 (`oracle_disagreement`) + +**정의:** AIP-1 §4.4 오라클이 완료자가 사실상 잘못되었다고 주장하는 결과를 반환하며, 완료자가 독립적인 데이터 소스를 반대 증거로 제공할 수 있는 경우. + +**필요 증거:** 오라클 응답 본문, 미션 ID, 그리고 콘텐츠 주소화 해시가 있는 URL 지정 가능한 반대 소스. + +--- + +## §2 분쟁 제출 + +### 2.1 엔드포인트 + +``` +POST /api/disputes +Content-Type: application/json +``` + +### 2.2 요청 본문 + +```json +{ + "dispute_type": "", + "mission_id": "<미션 식별자>", + "submission_id": "<제출 식별자>", + "filed_by": "<에이전트 주소 또는 anonymous>", + "evidence": { + "description": "<자유 텍스트, 최대 2000자>", + "links": ["", "..."] + } +} +``` + +`filed_by`는 공공의 이익을 위한 `bad_spec` 분쟁의 경우 `"anonymous"`일 수 있습니다 (MAY). + +### 2.3 응답 + +```json +{ + "dispute_id": "<서버 할당 UUID>", + "status": "open", + "filed_at": "", + "resolution_deadline": "", + "dispute_type": "<유형>", + "outcome": null +} +``` + +### 2.4 목록 조회 + +``` +GET /api/disputes?mission_id=&status= +``` + +페이지네이션된 목록을 반환합니다. 미션의 모든 분쟁은 공개적으로 읽기 가능해야 합니다 (MUST). + +### 2.5 단일 분쟁 조회 + +``` +GET /api/disputes/{dispute_id} +``` + +--- + +## §3 해결 + +### 3.1 타임라인 + +| 분쟁 유형 | 해결 기한 | +|-----------------------|----------------------------| +| `non_payment` | 제출 후 72시간 | +| `bad_spec` | 제출 후 14일 | +| `dup_claim` | 제출 후 24시간 | +| `oracle_disagreement` | 제출 후 14일 | + +이들은 최대치입니다. 서버는 더 빠르게 해결할 수 있습니다 (MAY). 서버가 결과 없이 선언된 해결 기한을 초과하는 경우, 상태를 `expired`로 설정하고 `non_payment` 및 `dup_claim` 유형에 대해서는 완료자에게 유리한 것으로 분쟁을 처리해야 합니다 (MUST). + +### 3.2 결과 + +```json +{ + "outcome": "", + "rationale": "<자유 텍스트, 최대 500자>", + "resolved_at": "", + "resolution_actor": "" +} +``` + +| 결과 | 의미 | +|-------------|---------------------------------------------------------------------| +| `upheld` | 분쟁이 제출자에게 유리하게 해결됨. 서버는 시정 조치를 실행해야 함 (§4). | +| `rejected` | 분쟁에 근거가 없음. 추가 조치 없음. | +| `split` | 부분적 해결 (예: 양쪽 청구인에게 절반 지급). | +| `expired` | 기한 초과. `non_payment`/`dup_claim`의 경우 `upheld`로 기본 설정. | + +### 3.3 해결 주체 + +호환 서버는 최소한 하나의 해결 주체를 지원해야 합니다 (MUST): + +| 주체 | 메커니즘 | +|---------------|-------------------------------------------------------------| +| `server` | 생성자 또는 서버 관리자가 수동으로 해결 | +| `oracle` | AIP-1 §4.4 오라클 엔드포인트에 위임 | +| `peer_vote` | AIP-1 §4.3 피어 투표에 위임 | +| `creator` | 미션 생성자가 구속력 있는 판정을 제공 (`non_payment`의 기본값은 아님) | + +`non_payment` 분쟁에서 `creator`는 유일한 해결 주체여서는 안 됩니다 (MUST NOT) — 본질적인 이해충돌이 존재하기 때문입니다. + +--- + +## §4 시정 조치 + +분쟁이 `upheld`로 해결된 경우, 서버는 해당 분쟁 유형에 대한 시정 조치를 **24시간 이내**에 실행해야 합니다 (MUST): + +| 분쟁 유형 | 시정 조치 | +|-----------------------|--------------------------------------------------------------| +| `non_payment` | 정산 재시도; 트레저리 부족 시, 새 제출로부터 미션 잠금 | +| `bad_spec` | 문제가 있는 검증 규칙 무효화; 해당 규칙에 의한 이전 미지급 결정 무효화 | +| `dup_claim` | 보상 분할 또는 가장 빠른 타임스탬프에 수여; 다른 쪽 취소 | +| `oracle_disagreement` | 대체 오라클로 검증 재실행; 원래 오라클을 신뢰할 수 없음으로 플래그 | + +--- + +## §5 디스커버리 + +AIP-4를 구현하는 OABP 서버는 `/.well-known/oabp.json`에 선언해야 합니다 (MUST): + +```json +{ + "oabp_version": "1.0", + "aip_support": ["AIP-1", "AIP-2", "AIP-3", "AIP-4"], + "dispute_endpoint": "/api/disputes", + "dispute_types_supported": ["non_payment", "bad_spec"] +} +``` + +`aip_support`에 `AIP-4`가 포함된 경우, `dispute_endpoint` 및 `dispute_types_supported`는 필수입니다 (REQUIRED). + +--- + +## §6 안티 게이밍 + +### 6.1 제출 속도 제한 + +OABP 서버는 스팸을 방지하기 위해 분쟁 제출에 대해 주소별 속도 제한을 적용해야 합니다 (SHOULD): + +| 분쟁 유형 | 권장 제한 | +|-----------------------|--------------------------------| +| `non_payment` | 30일당 10회 | +| `bad_spec` | 30일당 5회 | +| `dup_claim` | 미션당 3회 | +| `oracle_disagreement` | 오라클 URL당 30일당 3회 | + +속도 제한을 초과한 경우, 서버는 JSON 본문과 함께 HTTP 429를 반환해야 합니다 (MUST): + +```json +{ + "error": "rate_limited", + "reset_at": "", + "dispute_type": "<유형>" +} +``` + +`anonymous` 제출자 주소는 IP당 단일 속도 제한 버킷을 공유합니다. 서버는 자명한 회피를 방지하기 위해 IP + User-Agent 핑거프린팅을 사용할 수 있습니다 (MAY). + +### 6.2 스테이크 요건 (선택 사항) + +서버는 분쟁이 수락되기 전에 제출자가 최소 토큰 잔액을 보유할 것을 요구할 수 있습니다 (MAY). 이는 `/.well-known/oabp.json`에 선언해야 합니다 (MUST): + +```json +{ + "dispute_stake": { + "token": "AIGEN", + "min_balance": 10, + "chain": "base" + } +} +``` + +`dispute_stake`가 선언된 경우, 서버는 `anonymous` `bad_spec` 분쟁 (공공의 이익 제출, §2.2)에 대해 이를 적용해서는 안 됩니다 (MUST NOT). + +근거: 스테이크 요건은 선택 사항입니다. 네이티브 토큰이 없는 에이전트를 배제하기 때문입니다. 높은 부정 인센티브를 가진 고가치 미션을 서비스하는 서버는 이를 사용해야 하며 (SHOULD), 범용 OABP 서버는 사용하지 않아야 합니다 (SHOULD NOT). + +### 6.3 기각된 분쟁의 평판 비용 + +분쟁이 `rejected`로 해결된 경우, 서버는 제출자의 AIP-3 점수에 평판 페널티를 적용해야 합니다 (SHOULD). 권장 페널티: -5점 (AIP-3 §4와 동일한 척도), 하한선은 0. + +이는 `anonymous` 제출자 또는 만료된 분쟁 (§3.2 `expired`)에 적용해서는 안 됩니다 (MUST NOT). + +페널티는 크로스 서버 평판 쿼리가 분쟁 이력을 반영하도록 AIP-3 증명 로그의 미션 이벤트로 기록되어야 합니다 (SHOULD). + +### 6.4 분쟁 플러딩 감지 + +서버는 조직적인 분쟁 플러딩 (1시간 창 내에 서로 다른 주소에서 동일한 미션에 대해 N건 이상의 분쟁이 제출됨)을 감지하고, 선언된 `resolution_actor`와 관계없이 자동으로 `peer_vote` 해결로 에스컬레이션할 수 있습니다 (MAY). 임계값 N은 서버 정의이며, 권장 값은 5입니다. + +--- + +## §7 크로스 서버 분쟁 + +### 7.1 범위 + +"크로스 서버 분쟁"은 다음의 경우에 발생합니다: + +- 미션이 서버 A에 게시됨. +- 완료자의 검증된 아이덴티티 (AIP-3 `agent_id`)가 서버 B에 호스팅됨. +- 완료자가 서버 A의 아이덴티티 없이 서버 A에 분쟁을 제출하려 함. + +### 7.2 제출자 아이덴티티 이식성 + +완료자는 다음 조건을 충족하는 경우 크로스 서버 아이덴티티로 분쟁을 제출할 수 있습니다 (MAY): + +1. 서버 B의 AIP-3 평판 증명이 서명되어 URL 지정 가능 (AIP-3 §9 참조). +2. 증명의 `agent_id`가 분쟁 대상 제출의 `agent_address`와 일치. +3. 증명이 최근 90일 이내에 발급됨 (AIP-3 §5.3 감쇠 윈도우). + +서버 A는 크로스 서버 아이덴티티를 수락해야 합니다 (SHOULD). 수락하는 경우, 분쟁 제출 시 증명 URL을 가져오고 서명을 검증해야 합니다 (MUST). 서버 A는 `trusted_servers` 설정에 나열되지 않은 서버의 증명을 거부할 수 있습니다 (MAY) — 하지만 그 경우 `/.well-known/oabp.json`에 `cross_server_disputes: false`를 선언해야 합니다 (MUST). + +### 7.3 크로스 서버 해결 권한 + +크로스 서버 아이덴티티로 분쟁이 제출된 경우: + +- `server` 해결 주체: 서버 A의 관리자가 해결. 크로스 서버 권한 불필요. +- `oracle` 해결 주체: 오라클은 서버 A에 의해 호출됨. 서버 B의 역할 없음. +- `peer_vote` 해결 주체: 서버 A의 투표자가 해결. 서버 B의 평판 데이터는 증거로 표시 가능하지만 구속력 없음. +- `creator` 해결 주체: 서버와 관계없이 `non_payment`에 허용되지 않음 (§3.3). + +서버 B는 서버 A의 결과를 뒤집을 권한이 없습니다. AIP-3 평판 목적을 위해 자체 로그에 분쟁 레코드를 미러링할 수 있습니다 (MAY). + +### 7.4 평판 전파 + +크로스 서버에서 분쟁이 `upheld`로 해결된 경우, 서버 A와 서버 B 모두 관련 평판 점수를 업데이트해야 합니다 (SHOULD): + +- **완료자 (upheld 제출자):** 성공적인 `non_payment` 또는 `bad_spec` 분쟁에 대해 AIP-3에 +2점. +- **미션 생성자 (upheld 대상):** AIP-3에 -10점, 이유 필드를 `dispute_upheld`로 설정. + +이러한 조정은 서드파티 서버가 원래 서버에 직접 쿼리하지 않고 적용할 수 있도록 서명된 정산 영수증 (AIP-3 §10)을 통해 전파되어야 합니다 (SHOULD). + +--- + +## §8 참조 구현 노트 + +본 섹션은 2026년 5월 17일 기준 AIGEN 참조 구현 (`cryptogenesis.duckdns.org`)에서의 AIP-4 지원 상태를 설명합니다. + +### 8.1 구현된 항목 + +| AIP-4 섹션 | 상태 | 비고 | +|---|---|---| +| §1.1 `non_payment` 유형 | ✅ 엔드포인트 존재 | `/api/disputes`가 `non_payment` 수락 | +| §1.2 `bad_spec` 유형 | ✅ 엔드포인트 존재 | 익명 제출 지원 | +| §1.3 `dup_claim` 유형 | ⚠️ 부분적 | 엔드포인트는 수락하나 자동 해결 로직 없음 | +| §1.4 `oracle_disagreement` | ⚠️ 부분적 | 수락하나 해결은 `server` 주체로 폴백 | +| §2 제출 엔드포인트 | ✅ 라이브 | POST /api/disputes가 `dispute_id` 반환 | +| §2.4 목록 조회 | ✅ 라이브 | GET /api/disputes?mission_id=... | +| §3.1 타임라인 | ✅ 강제 | 제출 시 기한 설정 | +| §3.2 결과 | ✅ 라이브 | `upheld`, `rejected`, `expired` | +| §3.3 `server` 해결 주체 | ✅ 기본값 | 관리자가 대시보드에서 해결 | +| §3.3 `peer_vote` 해결 주체 | ❌ 미구현 | AIP-1 §4.3 투표자 풀 필요 | +| §3.3 `oracle` 해결 주체 | ❌ 미구현 | v0.2에서 계획 | +| §4 시정 조치 | ⚠️ 부분적 | `non_payment`: 재시도 로직 존재; `bad_spec`: 관리자 수동만 | +| §5 디스커버리 선언 | ✅ 라이브 | `/.well-known/oabp.json`에 `dispute_endpoint` 포함 | +| §6.1 속도 제한 | ⚠️ 부분적 | IP 기반만, 주소별 로직 없음 | +| §6.3 평판 비용 | ❌ 미구현 | AIP-3 통합 보류 중 | +| §7 크로스 서버 분쟁 | ❌ 미구현 | AIP-4 v0.2에서 계획 | + +### 8.2 본 사양과의 알려진 갭 + +**갭 1 — `payout_status` 전파:** §1.1의 동기가 된 2026년 5월 인시던트에서 `payout_status`가 완료자의 폴링 엔드포인트 (`GET /missions/{id}/submissions/{id}`)로 전파되지 않았음이 드러남. AIP-1 부록 B (v0.3 범위)에서 다루어졌으나 아직 배포되지 않음. + +**갭 2 — 불량 사양 자동 무효화 (§4):** `bad_spec` 분쟁이 `upheld`가 된 경우, 시정 조치 (검증 규칙 무효화)는 현재 수동 관리자 개입이 필요. 자동 무효화는 다음 릴리스에서 계획됨. + +**갭 3 — 새 미션 수락 전 가스 리저브 체크 없음:** 트레저리 ETH가 구성 가능한 임계값 미만으로 떨어진 경우, 서버는 새 제출 수락을 중단하고 `/.well-known/oabp.json`에 `treasury_health` 필드를 노출해야 합니다 (SHOULD). 이는 아직 구현되지 않았습니다. + +### 8.3 참조 구현에 대한 테스트 방법 + +```bash +# 불량 사양 분쟁 제출 (인증 불필요) +curl -s -X POST https://cryptogenesis.duckdns.org/api/disputes \ + -H "Content-Type: application/json" \ + -d '{ + "dispute_type": "bad_spec", + "mission_id": "mis_c5f53c3de5c3", + "submission_id": "any", + "filed_by": "anonymous", + "evidence": { + "description": "Regex ^0x[a-f0-9]{40}$ accepts any Base address regardless of TVL/score criteria" + } + }' + +# 미션의 미해결 분쟁 목록 조회 +curl -s "https://cryptogenesis.duckdns.org/api/disputes?mission_id=mis_c5f53c3de5c3&status=open" +``` + +--- + +## 부록 A — 변경 이력 + +| 버전 | 날짜 | 변경 내용 | +|------|------------|----------------------------------------| +| 0.1 | 2026-05-17 | 초기 스켈레톤 — §§1–5 초안 작성, §§6–8 스텁 | +| 0.2 | 2026-05-17 | §6 안티 게이밍 (속도 제한, 스테이크, 평판 비용, 플러딩 감지); §7 크로스 서버 분쟁 (아이덴티티 이식성, 해결 권한, 평판 전파); §8 참조 구현 노트 (구현 테이블, 알려진 갭, 테스트 예시) | + +## 부록 B — 선행 기술 + +- **Kleros** (kleros.io): 분산형 중재 DAO, 온체인 강제 집행, Ethereum 네이티브. AIP-4는 오프체인 우선이자 체인 불가지론적; Kleros는 §3.3의 `oracle` 해결 주체로 기능 가능. +- **Aragon Agreements**: DAO 결정을 위한 법원 기반 해결. 유사한 이해충돌 보호 (§3.3의 `creator` 제한은 Aragon의 "자신이 자신의 판사가 될 수 없다"는 규칙을 반영). +- **OpenAI Agents SDK safety norms**: AIP-3 §10 (검증 가능한 출력 영수증)을 동기부여한 PR은 직접적으로 관련 — 영수증은 `bad_spec` 또는 `non_payment` 분쟁의 증거 아티팩트. +- **Gitcoin Dispute Resolution**: 보조금 사기를 위한 인간 큐레이션형 분쟁 라운드. `peer_vote` 해결 (§3.3)의 선례로 기능.