기와장터 (GIWA Village)
GIWA 체인 위의 한옥 저잣거리 — 지갑으로 접속해 아바타로 마을을 돌아다니고, 노점을 열어 장사하고, 다른 주민에게 실제 ETH를 선물하고, 길드를 맺어 던전을 오르는 "지갑을 공간으로" 만드는 실험. 고전 MMO 저잣거리(노점) 문화의 온체인 재해석이다.
지갑 전송을 선물로, P2P 거래를 노점으로, 신원 인증을 상인 뱃지로 — 지갑의 기능을 공간의 문화로 번역한다.
🌐 라이브 데모는 풀온체인 서버리스입니다 — 게임 서버 없이도 GIWA 체인만으로 동작합니다. 다른 방문자의 아바타(프레즌스 비컨)와 노점이 그대로 보이고, 테스트 ETH만 받으면 노점 개설 → 구매 → 길드 던전까지 전부 실동작합니다. 사람이 모이는 때에만 시연 서버가 떠서 걸음이 부드러워지고 동료와 함께 원정을 갈 수 있습니다 — 꺼져 있으면 조용히 체인만으로 돌아갑니다.
처음 오시면 촌장이 한 번 묻습니다 — "마을을 대신 걸어서 보여줄까?" 예를 고르면 자막과 함께 자동 시연이 돌고(ESC로 언제든 멈춤), 잔액이 없으면 가스가 들지 않는 구경 모드로 내려가 마을만 보여줍니다. 자세한 것은 놀아 보기.
시연 영상 (1.5배속)
▶ 원속도 mp4 — showcase.cmd 실행을 그대로 녹화한 영상입니다.
구매·에스크로 정산은 GIWA Sepolia 실제 온체인 트랜잭션입니다.
📓 개발일지 — 주장이 아니라 git 기록으로 되짚은 작업 기록. 🔍 AI Self-Audit — 개발한 AI가 감사자로 전환해 찾은 결함·수정·미해결 한계를 전부 공개한 기록.
마을에 무엇이 있나
"머무를 이유 · 만날 시간 · 자랑할 것 · 만들 거리 · 함께 싸울 상대" 다섯 축 — 자세한 것은 FEATURES.md.
| 🧺 장사와 거래 | 아무 곳에나 노점을 편다. 접속을 끊어도 노점은 남는다. 에스크로+ERC-1155 쿠폰, 온체인 흥정, 쿠폰 선물·소각 |
| 🏯 길드 + 백층 던전 | 비동기 코업. 주차 시드가 블록 해시로 고정돼 오른 층수를 누구나 재현·검증할 수 있다 |
| 🧿 도깨비 토벌 | 광장의 주간 보스를 함께 때려잡는다. 기여가 온체인에 쌓이고 전리품은 소울바운드 |
| 🔥 모닥불 + 장날 | 함께 앉아야 온기가 쌓인다. 토 21시(KST) 장날엔 2배 — 모두가 모일 시간 |
| 🎨 꾸미기 + 창작 | 칭호·복주머니 장신구·문양 공방(8×8 픽셀 UGC, 대금 창작자 직송) |
| 👥 주민과 놀기 + 오늘의 부탁 | 이모트 5종·근거리 합동 장단, KST마다 무료 부탁 하나를 골라 개인 도장 |
온체인 구성 (GIWA Sepolia)
설계 원칙은 "가치는 전부 온체인, 존재감은 비컨" — 거래·소유·기록은 컨트랙트가 들고, 실시간 위치만 저장 없는 이벤트로 흘린다. 그래서 게임 서버가 없어도 멀티플레이가 된다. 현행 주소와 소스 검증 상태는 contracts/README.md에 모아 둔다.
| 컨트랙트 | 역할 |
|---|---|
| GiwaMarketV3 | 노점 레지스트리·에스크로(분쟁/환불)·ERC-1155 쿠폰(선물·소각) |
| GiwaGuilds | 길드·백층 던전 v2 (문별 전략·블록해시 시드·settleRun 재계산 검증) |
| GiwaPresence | 저장 없는 위치+속도 비컨 → 클라 데드레커닝 |
| GiwaHonors | 소울바운드 칭호 5종 (v1 획득 상태 보존·온체인 자격 검증) |
| GiwaOffers | 흥정 에스크로 (MarketV3 조합 즉시 체결) |
| GiwaBoxes | 복주머니(무료·블록해시)·소울바운드 장신구 8종 |
| GiwaHearth | 모닥불 온기 (함께·장날 2배) |
| GiwaWorkshop | 문양 공방 UGC (등록·판매·착용, 대금 창작자 직송) |
| GiwaBoss | 주간 도깨비 토벌 (개인·길드 기여, v1 전리품 보존) |
| GiwaProfile | 소셜 프로필 애그리게이터 — v2 길드 묶음을 1콜로 집계 (SDK 진입점) |
여기에 GIWA 네이티브 읽기 연동 둘이 붙는다 — Dojang Verified Address(업비트가 신원을 보증한 상인 뱃지)와 UP.ID 이름표. 자세한 것은 FEATURES.md.
마을은 구현체가 아니라 프로토콜이다
입장 자격이 서명 하나뿐이라, 컨트랙트에는 그 서명이 사람에게서 왔는지 에이전트 루프에서 왔는지, 그 좌표가 웹에서 왔는지 언리얼에서 왔는지 구분할 자리가 없다. 그래서 둘 다 열어 뒀다.
- PROTOCOL.md — 공개 명세. 배치·충돌·소리 임계는
world.json으로 구워 누구나 읽는다.npm run smoke:protocol이 문서만 보고 짠 클라이언트로 실제 룸에 들어가 본다 (colyseus.js를 일부러 안 쓴다 — 쓰면 아무것도 증명 못 한다). - AGENTS.md — 사람과 AI가 같은 자격으로 사는 마을. MCP 서버와 LLM 상인 NPC로 실제로 돈다. 값은 LLM이 제안하고 하한선은 코드가 강제해서, 어떤 대답이 나와도 헐값 체결은 불가능하다.
빠른 시작
npm install
npm run showcase # 자동 시연 — 설명 없이 보기만 해도 전체 플로우가 지나간다
npm run playtest # 듀얼 테스트 창 (로컬 서버 + 클라이언트 2개)
npm test # 로직 69건 · 체인 없음 · 2초 미만
구조
PROTOCOL.md 공개 프로토콜 — 이것만 지키면 누구든 클라이언트를 만들 수 있다
guide/ 사람이 읽는 문서 (놀기·이어붙이기·검증·이어만들기)
client/ Vite + React + react-three-fiber 3D 클라이언트
src/chain/ 풀온체인 레이어 — 컨트랙트별 모듈 (stalls·guilds·boss·presence…)
public/world.json 마을 배치표(기계용) — npm run export-world 가 굽는다
core/ 던전 판정 순수 모듈 — 클라이언트와 검증기가 같은 코드를 임포트한다
contracts/ Solidity 10종 (카탈로그: contracts/README.md)
sdk/ @giwa-village/sdk — 외부 dApp·봇용 읽기 SDK
mcp/ 기와장터 MCP 서버 — LLM이 마을을 읽고 키가 있으면 직접 장사한다
server/ (선택) Colyseus 룸 서버 — 위치 릴레이 · 함께하는 원정. 없어도 마을은 돈다 (render.yaml · 0원 시연 서버)
scripts/ 배포·검증·봇·스모크
📚 문서
| 찾는 것 | 문서 |
|---|---|
| 어떻게 노나 (실행·조작·자동 시연) | guide/PLAY.md |
| 마을에 무엇이 있나 (다섯 축·주야·소리·Dojang) | guide/FEATURES.md |
| 테스트 ETH·지갑·포셋 | guide/WALLET.md |
| 어떻게 검증하나 (5겹 · 재현 가능성) | guide/TESTING.md |
| AI 에이전트로 마을 돌리기 | guide/AGENTS.md |
| 다른 엔진으로 클라이언트 만들기 | PROTOCOL.md |
| 컨트랙트 카탈로그 · 알려진 한계 | contracts/README.md |
| 외부 dApp에서 프로필 읽기 | sdk/README.md |
| 로드맵 · 규제 안전선 | guide/ROADMAP.md |
| 반입 에셋 원장 (출처·라이선스) | ASSETS.md |
| 시연 서버 0원 호스팅 (선택) | guide/DEPLOY.md |
| 계측 스키마 (모든 클라이언트 공용 · 기본 꺼짐) | guide/ANALYTICS.md |
| 개인정보 처리방침 · 이용약관 (v0 초안 · 법률 자문 아님) | guide/PRIVACY.md · guide/TERMS.md |
| 작업 규칙 (사람·AI 공용) | CLAUDE.md |
전체 색인은 guide/README.md.
네트워크
| 체인 | GIWA Sepolia (OP Stack L2) |
| Chain ID | 91342 |
| RPC | https://sepolia-rpc.giwa.io |
| 익스플로러 | https://sepolia-explorer.giwa.io |
설계 원칙 (규제 안전선)
게임 플레이의 결과로 양도 가능한 자산을 지급하지 않는다. 성장치는 소울바운드, 거래는 소셜 레이어의 지갑 기능(전송·선물·재화)으로만. 자세한 것은 guide/ROADMAP.md.
