운영 가이드

6.1 Worker 실행 방법

# 1. 의존성 설치
npm install

# 2. 환경 변수 설정 (.env)
cp .env.example .env
# 필요한 환경 변수는 온보딩 문서를 참조하세요.

# 3. API 서버 실행
npm run start:api

# 4. Commit Worker 실행 (별도 프로세스)
npm run start:worker

6.2 Key 관리 방법 (환경 변수)

키 관리 정책은 온보딩 문서를 참조하세요.

• [비공개: 내부 보안 절차 — 온보딩 시 별도 안내]

6.3 Vault 권한 설정

역할	주소 설정 대상	권한 범위
DEFAULT_ADMIN_ROLE / TRUSTEE_ROLE	신탁사 지갑 (Gnosis Safe 권장)	maxSupply 조정, 컨트랙트 업그레이드 승인
ISSUER_ROLE	은행 운영 지갑	Mint/Burn 실행, Vault 충전 실행
Dual Control	Bank + Trust 양측 동의 필수	단일 키 탈취만으로 임의 발행 불가

6.4 장애 대응 Runbook

에러 상황	원인	대응 절차
insufficient_funds	잔액 부족	사용자 충전 유도 또는 정책 엔진 한도 조정 워크플로우 실행
nonce_sync_error	트랜잭션 순서 불일치	[비공개: 내부 운영 절차 — 온보딩 시 별도 안내]
idempotency_conflict	중복 요청 감지	기존 receiptId 기반 상태 트레이싱 후 결과값 재전달
RPC timeout	Subnet 일시 지연	Developer RPC로 전환. 공식 복구 후 Public RPC 원복.
Contract upgrade risk	TRUSTEE 키 탈취 위험	Gnosis Safe 멀티시그 사용. 단일 키로 업그레이드 불가 구조 유지.

6.5 문서 및 리소스

접속 URL은 온보딩 시 별도 전달됩니다.

리소스	설명
개발자 문서 (Gitbook)	Quickstart, API Reference, 연동 가이드
플랫폼 (Admin)	메타마스크 연결 후 역할별 대시보드 접근
은행 업무 화면	Mint/Burn 요청 및 담보 관리
신탁사 화면	신탁사 감사·승인 기능
Explorer (Jelly)	온체인 트랜잭션 조회
Postman Collection	전체 API 테스트 컬렉션
SDK npm 패키지	TypeScript SDK. 예제: packages/sdk/README.md

지원 문의 기술 문의 및 API Key 발급은 이음 팀 담당자에게 연락해주세요. 이슈 발생 시 requestId와 receiptId를 함께 전달하시면 빠른 트레이싱이 가능합니다.