Skip to content

stakepass_prd_v2_full.md

Latest commit

 

History

History
347 lines (290 loc) · 16.2 KB

stakepass_prd_v2_full.md

File metadata and controls

347 lines (290 loc) · 16.2 KB
Raw

PRD: StakePass (v2 Reset, Full)

캐치프레이즈: Lock'n'Use — 스테이블을 잠그면, 구독을 바로 쓴다.

0. 용어/약어 정리 (Glossary)

  • StakePass: 본 서비스(구독 집금·운용 플랫폼)
  • YieldKey: 구독권 RWA(양도 불가 SBT NFT)
  • Subscription DeFi: 예치 자산을 운용하는 파이낸셜 레이어
  • Vault: 사용자 예치 자산을 수령/관리하는 온체인 금고(멀티-전략)
  • Provider: 구독 서비스를 제공하는 사업자(OTT, AI, 음악/웹툰 등)
  • KRWT/USDT: 스테이블 토큰(테스트넷 배포 토큰 포함). 문서 내 ‘KRWC’ 표기는 KRWT로 통일 제안
  • Term: 구독 의무 이용 기간(3/6/12개월)
  • LTV: (선지급 구독비/담보 예치금) 비율
  • Penalty: 의무기간 미준수 해지 시 차감 수수료

1. 배경과 컨셉

  • 문제: 대부분의 구독 서비스는 선불 과금이며, 사용자는 현금흐름 부담이 존재. 블록체인/DeFi 초보에게는 진입장벽이 큼.
  • 해결: 사용자는 KRWT/USDT를 StakePass의 Vault에 예치(Stake)하여 담보를 제공하고, StakePass는 해당 담보를 근거로 구독료를 선지급(소액 대출 성격)하여 사용자가 즉시 서비스를 이용하도록 함. 이후 예치금은 Subscription DeFi로 운용되어 수익을 창출.
  • 권리증명: Provider가 **YieldKey(SBT)**를 발행하여 이용권을 온체인 RWA로 증명(양도 불가, 검증 가능).

2. MVP 범위 (Kaia Testnet + LINE Mini App)

  • 체인: Kaia testnet 우선(지갑: Kaia 생태계 지갑 + MetaMask 호환), LINE Mini App 연계 UX 제공
  • 토큰: USDT, KRWT 테스트 토큰 자체 배포(ERC-20)
  • 컨트랙트: Vault(수령/인출), Aggregator(전략/정책), YieldKey(SBT), ProviderRegistry, Oracle, Hook, Test Tokens
  • 플랜: 3/6/12개월 Term만 지원, 자동 갱신(옵션)
  • 서비스 카탈로그: OTT(Netflix/Disney+/Tving/Wavve/Watcha), AI(Claude/Gemini/ChatGPT), LINE(만가/뮤직), Entertainment(웹툰/뮤직) — 데모용 카테고리

3. 핵심 도메인/엔터티

  • User: 담보 예치 및 구독 이용자
  • Provider: 구독 서비스 발행/정산 주체
  • ServicePlan: 서비스ID, 월 구독료, 통화(USDT/KRWT), 지원 Term, 최소 담보비율(LTV) 등
  • SubscriptionOrder: 사용자의 특정 서비스/Term 구독 신청 레코드
  • YieldKey(SBT): 서비스ID, Term, 만료일, 발행자(Provider), 소유자(User), 상태(유효/해지/만료)
  • VaultPosition: User별 예치 잔고, 잠금 상태, 인출가능액

4. 라이프사이클(요약)

  1. 신청: User가 Service+Term 선택 → 담보 예치(Stake)
  2. 선지급: StakePass가 Provider에 구독료 선지급(월별 혹은 일괄 지급/설정값)
  3. 발행: Provider가 User에게 YieldKey(SBT) 발행
  4. 이용: User는 SBT로 접근 권한 인증(Web2/3)
  5. 운용: Vault가 예치금으로 이자 농사(Subscription DeFi 전략)
  6. 갱신/해지: Term 종료 시 갱신 또는 해지. 조기해지 시 Penalty 차감 후 반환

5. 시퀀스 다이어그램 (MVP 구독 플로우)

sequenceDiagram
  participant U as User (Wallet)
  participant FE as Frontend (Web/MiniApp)
  participant API as StakePass API/Biz
  participant VA as Vault/Aggregator Contract
  participant PR as Provider (Off-chain + ProviderRegistry)
  participant YK as YieldKey (SBT)

  U->>FE: 서비스/Term 선택, 담보액 확인
  FE->>API: /quote(serviceId, term)
  API-->>FE: requiredDeposit, fee, expiry, LTV
  U->>VA: deposit(amount) (KRWT/USDT)
  VA-->>API: Deposit event(로그/웹훅)
  API->>PR: 선지급 요청(settlement schedule)
  PR-->>API: 수신 확인
  API->>YK: mintYieldKey(user, serviceId, term, expiry)
  YK-->>U: SBT 발행(지갑 수신)
  U->>Provider App: SBT 검증 후 사용 시작
Loading

6. 정책/수치(초안)

  • Collateral/LTV: LTV = 선지급총액 / 담보예치금 ≤ 0.8 (예: 3개월 선지급 시 담보 ≥ 1.25x)
  • Coverage Margin: coverage = fee*(months) * (1 + 10%)
  • Penalty(조기해지): penalty = remaining_fee * p + unwind_cost (p=20~50% 정책)
  • 정산 방식: Provider에게 월별 정산(기본) 또는 일괄 선지급(옵션)
  • 자동갱신: 만료 7일 전 알림, 담보/LTV 충족 시 자동 갱신

정책 수치는 MVP에서 환경변수/온체인 파라미터로 조정 가능하게 구현

7. 주요 유스케이스 (정의 + 입출력/시스템)

각 기능은 사전조건(Pre), 입력(Input), 출력(Output), 시스템(System) 순으로 기재.

UC-01 제공자 온보딩(Provider Onboarding)

  • Pre: 사업자 KYC/계약 완료
  • Input: providerName, payoutWallet, serviceList([]), attestPubKey
  • Output: providerId, onChain role/grant
  • System:
    1. Admin가 ProviderRegistry에 등록(Owner 권한 부여)
    2. Payout 지갑 검증 트랜잭션(소액 서명/콜백)
    3. 서비스 카탈로그 업로드(요금/통화/Term/환불 정책)

UC-02 서비스/플랜 생성(ServicePlan Create)

  • Pre: Provider 등록
  • Input: serviceId, currency(USDT/KRWT), monthlyFee, terms[3,6,12], minCollateral, policy
  • Output: planId
  • System: ProviderRegistry.setPlan(...) → 이벤트 인덱싱 → API 캐시 반영

UC-03 담보 견적 조회(Quote)

  • Pre: 활성 플랜 존재
  • Input: serviceId, term
  • Output: requiredDeposit, feeSchedule, expiry, LTV
  • System:
    1. monthlyFee*months 계산
    2. LTV/coverage 기준으로 requiredDeposit 산출
    3. 오라클(USD/KRW 환산) 및 슬리피지/수수료 고려

UC-04 담보 예치(Stake/Deposit)

  • Pre: User가 지갑 준비, 승인(approve)
  • Input: amount, token(USDT/KRWT), serviceId, term
  • Output: txHash, positionId
  • System: Vault.deposit → Aggregator 전략로 분배(부분 보유/부분 예치)

UC-05 정산 트리거(Settlement)

  • Pre: UC-04 완료 및 담보≥요구치
  • Input: orderId, schedule(monthly|upfront)
  • Output: payoutTxHash (on-chain/off-chain 기록)
  • System:
    1. (기본) 월별 정산: epoch마다 vault→provider payout
    2. (옵션) 일괄 선지급: 즉시 지급

UC-06 YieldKey 발행(Mint SBT RWA)

  • Pre: UC-05 성공
  • Input: user, serviceId, term, expiry, providerSig(EIP-712)
  • Output: tokenId
  • System: YieldKey.mint(to, metadata); Provider 서명/권한 확인; SBT 비양도 설정

UC-07 접근 인증(Access Verify: Web2/Web3)

  • Pre: User 로그인 또는 지갑 서명
  • Input: userId or wallet, tokenId
  • Output: valid(bool), expiry, serviceId
  • System:
    • Web3: 컨트랙트 직접 조회
    • Web2: SIWE(EIP-4361)/EIP-712 서명 → JWT 세션 발급 → 백엔드가 SBT 보유/만료 조회

UC-08 자동 갱신(Renewal)

  • Pre: 만료 7일 전, 담보/LTV 충족
  • Input: orderId
  • Output: renewed(bool), newExpiry
  • System: 배치서버가 조건 검증→ 정산 → 새로운 YieldKey 갱신(혹은 메타데이터 업데이트)

UC-09 조기 해지(Early Cancel)

  • Pre: User 요청, Term 미완료
  • Input: orderId, reason
  • Output: refundAmount, penalty
  • System: Penalty 계산→ Provider/플랫폼 수수료 분배→ Vault에서 잔액 환급→ YieldKey 소각

UC-10 만기 인출(Maturity Withdraw)

  • Pre: Term 완료 & 모든 정산 OK
  • Input: positionId
  • Output: withdrawTxHash
  • System: 전략 자산 언스테이킹→ Vault 출금→ 포지션 종료

UC-11 리스크/오버라이드(Admin)

  • Pre: 이상상황
  • Input: action(pause, limitLTV, blockProvider ...)
  • Output: policyApplied
  • System: 컨트랙트 pause, 파라미터 조정, 정산정지 등

8. 기능 목록(Features) — 상세 스펙 (Pre/Input/Output/System)

F0. 담보 견적(Quote)

  • Pre: 활성 ServicePlan 존재, 오라클 가용
  • Input: serviceId, term(3|6|12), (옵션)wallet
  • Output: quoteId, requiredDeposit, ltv, expiry(ts), feeSchedule{month:amount}, ttl(분)
  • System:
    1. ServicePlan 조회 → 월요금×term 계산
    2. LTV·커버리지 기준으로 requiredDeposit 산출, 환산(USD/KRW) 반영
    3. Quote를 캐시/DB 저장(TTL), 서명가능 페이로드 생성(EIP-712)

F1. Provider 관리

  • Pre: Admin 권한, Provider KYC 완료
  • Input: providerName, payoutWallet, attestPubKey, serviceList[]
  • Output: providerId, 온체인 role
  • System: Registry에 등록 tx → 이벤트 인덱싱 → 오프체인 KMS에 attestPubKey 보관

F2. ServicePlan 관리

  • Pre: Provider 등록
  • Input: serviceId, currency, monthlyFee, terms[], minCollateral, policy
  • Output: planId
  • System: on-chain setPlan → 이벤트 동기화 → 캐시 무효화

F3. 담보 예치(Stake/Deposit)

  • Pre: 토큰 approve, 유효 quoteId
  • Input: amount, token, serviceId, term, quoteId
  • Output: txHash, positionId
  • System:
    1. Quote 검증(TTL/LTV 일치)
    2. Vault.deposit → Aggregator 전략배분(유휴/예치 비율)
    3. Position 레코드 생성(락/만기/서비스ID)

F4. 선지급 정산(Settlement)

  • Pre: 담보≥요구치, position 유효
  • Input: orderId, schedule(monthly|upfront)
  • Output: payoutTxHash, settlementId
  • System:
    • 월별: 배치가 epoch마다 지급, 실패 시 재시도(backoff, idempotency key)
    • 일괄: 즉시 지급 후 스케줄 종료

F5. YieldKey(SBT) 발행/검증/소각

  • Pre: 정산 성공
  • Input: user, serviceId, term, expiry, providerSig
  • Output: tokenId, tokenURI, valid
  • System: Provider 서명 검증 → SBT mint(비양도) → 만료/해지 상태 전이 → 소각 시 access 차단

F6. 접근 인증(Web2/Web3)

  • Pre: 로그인 또는 지갑서명(SIWE/EIP-712)
  • Input: userId or wallet, tokenId
  • Output: JWT 또는 valid(bool)
  • System:
    • Web2: 지갑연결→JWT 발급→백엔드가 컨트랙트 조회 캐시
    • Web3: 컨트랙트 직접 조회(Revert-safe), 세션키 관리

F7. 조기해지(Early Cancel)

  • Pre: Term 미완료
  • Input: orderId, reason
  • Output: refundAmount, penalty, txHash
  • System: Penalty 공식 적용→ 언스테이킹→ 환급→ SBT burn

F8. 만기 인출(Maturity Withdraw)

  • Pre: Term 완료, 미연체
  • Input: positionId
  • Output: withdrawTxHash
  • System: 포지션 해제→ 전략 언스테이킹→ Vault 출금

F9. 운용전략 엔진(Subscription DeFi)

  • Pre: Vault 잔고 존재
  • Input: strategyId, alloc%, params{}
  • Output: rebalanceTx, APR, PnL
  • System: 허용목록(allowlist) 프로토콜만 사용, 슬리피지/가스/리스크 한도 체크, 주기적 리밸런싱

F10. MEV/플래시론 방어

  • Pre: 대규모 정산·스왑 예정
  • Input: batchId, ops[]
  • Output: privateBundleTxHash
  • System: MEV-protect RPC 또는 Private Tx, 4337 Bundler/Paymaster(가스 후원), 시세 급변 시 중단/롤백

F11. 오라클/리스크

  • Pre: 가격/디페그 모니터링 필요
  • Input: feeds[], thresholds
  • Output: riskEvent, pause/limit
  • System: 멀티소스 오라클, 하트비트/탈선 감지, 자동 pause/담보율 상향

F12. 갱신/알림

  • Pre: 만료 임박
  • Input: orderId
  • Output: renewed, newExpiry 또는 알림발송 결과
  • System: 배치가 조건 확인→ 자동 갱신 트리거 또는 푸시/메일 알림

F13. Admin/Analytics

  • Pre: Admin 권한
  • Input: 기간/서비스/프로바이더 필터
  • Output: TVL, 활성구독, 체납, 수익, 리스크 지표
  • System: 온체인 이벤트 + 오프체인 메타 집계, 대시보드 제공

F14. 컴플라이언스/감사로그

  • Pre: 민감 이벤트 발생
  • Input: 액션/주체/서명/정책ID
  • Output: 불변 로그(append-only)
  • System: WORM 스토리지/해시체인, 접근통제, 보존정책

18. Contract PRD (요약)

  • 모듈: Vault, Aggregator, YieldKey(SBT), ProviderRegistry, Oracle, Hook (업그레이더블 UUPS 권장)
  • 주요 스토리지:
    • Vault: mapping(user=>position), totalDeposited, lockedUntil
    • Aggregator: strategies[], allocations, ltvParams, settlementPolicy
    • YieldKey: ownerOf(tokenId), serviceId, term, expiry, status
    • Registry: providers, plans, roles
  • 핵심 함수: deposit/withdraw, rebalance/stake/unStake, mint/burn/verifySBT, setPlan/updatePlan, setOracle, pause
  • 이벤트: Deposited, Settled, YieldKeyMinted, Cancelled, Withdrawn, Paused 등
  • 접근제어: AccessControl(ADMIN/PROVIDER/OPERATOR), Pausable, ReentrancyGuard
  • 정책파라미터: LTV, coverage, penalty, settlement schedule, allowlist
  • 보안: 체크리스트(재진입, 인플레이션, 승인·토큰 취급, 오라클 조작, 업그레이드 롤 소유권)
  • 테스트: 단위/프로퍼티/시뮬(test) + 포크 테스트, 가스리포트
  • MVP 경계: 실제 DeFi 연동은 mock/샌드박스 전략으로 시작, 이후 실제 프로토콜 어댑터 추가

19. Frontend PRD (요약)

  • 플랫폼: Web + LINE Mini App(모바일 우선)
  • 주요 화면:
    1. 온보딩/로그인(지갑연결·SIWE)
    2. 서비스 카탈로그(카테고리/요금/필요예치금 표시)
    3. 견적(Quote) → 예치(Deposit) 플로우
    4. 구독 현황(활성 YieldKey, 만료일, 갱신/해지)
    5. 알림센터(만료 안내)
    6. 설정/지갑/보안
  • 지갑/연동: Kaia 지갑 + MetaMask, WalletConnect; SIWE/EIP-712 서명; JWT 세션
  • 상태관리: React Query/Zustand, 캐시 정합성(Event 기반 리프레시)
  • 에러/예외: 잔액/승인 부족, Quote 만료, 체인 mismatch, 트랜잭션 실패
  • 접근성: 다국어(i18n), 키보드·스크린리더 고려

20. Backend PRD (요약)

  • 서비스: Auth, API, Biz, Batch, Finance, Scanner, Admin
  • 주요 기능:
    • Auth: Nonce, SIWE, JWT, wallet-user 매핑
    • API: REST/gRPC 게이트웨이, OpenAPI 준수
    • Biz: UC 플로우 오케스트레이션(정산/갱신/해지)
    • Batch: 월정산/만기모니터/알림
    • Finance: 전략엔진/MEV 보호/리밸런싱
    • Scanner: 온체인 이벤트 인덱싱
    • Admin: 정책/대시보드/감사로그
  • 데이터 모델(요약): Users, Providers, Plans, Orders, Positions, YieldKeys(meta), Settlements, Quotes, RiskEvents, AuditLogs
  • 통신: 내부 gRPC + 메시지 큐(Kafka/RabbitMQ)로 비동기 이벤트 처리
  • 보안/운영: RBAC, Rate-limit, WAF, observability(OpenTelemetry), 백업/DR

21. 개발 계획(Plan)

  • Phase 0 (아키/부트스트랩, 1주): 레포 구성, CI/CD, 코드규약, 시크릿·환경설정
  • Phase 1 (컨트랙트 스켈레톤, 2주): Vault/Agg/YieldKey/Registry mock 배포, 이벤트 스키마 고정
  • Phase 2 (백엔드 코어, 2주): Auth/API/Biz/Scanner 기본 플로우(/quote,/subscribe)
  • Phase 3 (프론트 MVP, 2주): 카탈로그→견적→예치→발행 플로우, MiniApp 베타
  • Phase 4 (정산/갱신/해지, 2주): Batch/Settlement/Renew/Cancel, Admin 최소기능
  • Phase 5 (전략엔진 v0 & 리스크, 2주): mock 전략, 오라클·리스크 가드, MEV protect 시범
  • QA/보안 검토 (1주): E2E/성능/침투·스마트컨트랙트 정적분석
  • 릴리즈: Kaia testnet 데모 공개

Acceptance Criteria (핵심)

  • /quote→deposit→settlement→SBT mint 시나리오 95% 이상 성공
  • 조기해지/만기인출 정상 처리, 재진입·중복정산 없음
  • Web2/Web3 인증 후 Provider 데모앱에서 SBT 검증 통과
  • 장애/리스크 조건에서 자동 pause 동작

리스크/완화

  • 가격 급변/디페그 → Oracle 2중화·LTV 상향 자동화
  • MEV/슬리피지 → Private Tx·쿨다운·한도
  • 규제이슈 → 선지급/에스크로 법무 자문 및 지역 제한 플래그

22. API/스펙 연동

  • REST/gRPC, OpenAPI, 인증 스펙은 본 PRD v2 기준으로 재사용/보완.
  • 추가 엔드포인트: /quote, /renew, /cancel-early, /provider/* 등은 다음 단계에서 OpenAPI에 반영.