WalletKit 개요
WalletKit은 지갑 제공사가 자체 지갑 앱에서 SCOPE Connect 세션을 수립하고 dApp 요청에 응답하도록 지원하는 Kotlin Multiplatform 라이브러리입니다. Android·JVM 라이브러리와 iOS용 네이티브 라이브러리를 제공하며, 현재 제품 상태는 파트너 프리뷰입니다.
현재 버전은 0.0.1입니다. iOS 패키지는 공개 Swift Package로 배포됩니다. Android·JVM 패키지는 아직 Maven Central에 게시하지 않았으며, 파트너 프리뷰 기간에는 SCOPE Connect 담당자를 통해 아티팩트를 전달합니다. 접근 권한과 엔드포인트, 지원 범위도 담당자와 협의합니다.
도입 대상
WalletKit은 아래 조건을 모두 갖춘 지갑 제공사에 적합합니다.
- 자체 계정·서명 키 관리 체계와 사용자 승인 화면을 이미 갖추고 있습니다.
- dApp이 만든 페어링 URI를 QR 코드나 딥링크로 전달받습니다.
- 릴레이 채널의 암호문을 직접 구독하고 세션 응답을 발행합니다.
dApp에서 지갑 연결 기능을 구현하는 경우에는 WalletKit이 아니라 AppKit 개요를 사용합니다.
지원 플랫폼
| 플랫폼 | 배포 형태 | 최소 요구 사항 |
|---|---|---|
| Android | KMP Android AAR (파트너 전달) | API 28, compile SDK 35 |
| iOS | 공개 Swift Package (XCFramework) | iOS 16 |
| JVM | KMP JVM JAR (파트너 전달) | JDK 21 |
iOS는 공개 저장소 Lambda256/scope-connect-walletkit-swift의 0.0.1 태그를 Swift Package Manager로 설치합니다. Android·JVM 패키지는 Maven Central 게시가 끝난 뒤 저장소에서 직접 설치할 수 있습니다.
세션 연결 흐름
WalletKit을 사용하는 지갑의 최소 흐름은 다음과 같습니다.
- 페어링 URI에서 토픽과 채널 정보를 읽습니다.
- 지갑 측 릴레이 연결을 열고 페어링 토픽을 구독합니다.
- 연결 요청을 복호화하고 요청한 체인과 dApp 정보를 사용자에게 표시한 뒤 승인을 받습니다.
- 사용자가 승인한 계정만 세션 응답에 포함합니다.
- 세션 토픽에서 서명 요청을 수신하고 메서드와 거래 정보를 표시한 뒤 별도 승인을 받습니다.
- 응답을 암호화해 릴레이에 발행하고, 흐름이 끝나면 전송 리소스를 닫습니다.
현재 connect() 호출 한 번은 서명 요청 한 건을 처리하고 종료됩니다. 추가 요청은 dApp이 새 페어링 URI를 발급해 이 흐름을 다시 시작합니다.
연결 승인과 서명 요청 승인은 서로 독립된 단계입니다. 연결 승인은 이후 서명이나 트랜잭션 승인을 포함하지 않습니다.
역할 범위
WalletKit은 페어링 URI 파싱, 릴레이 전송, 채널 암호화, 세션 연결과 응답 발행을 처리합니다. 지갑 제공사는 다음 영역을 직접 구현하고 운영합니다.
- 개인키 생성·보관·복구
- 계정 선택과 사용자 인증
- 요청에 담긴 체인·도메인·수취인·금액이 올바른지 검증
- 사용자 동의 화면과 피싱 방지
- 세션 철회와 장기 보관 정책
현재 WalletKit의 EIP-3009 흐름은 지갑의 승인과 서명까지만 처리합니다. 구조화 데이터 생성, 반환된 서명의 검증, 온체인 제출과 확정 추적은 dApp 또는 결제 백엔드가 담당합니다.
샘플·테스트 모듈에 들어 있는 키 값과 지갑 구현은 동작 확인용입니다. 실제 지갑에서는 자체 보안 구조와 개인키 생성·보관·백업·복구 정책을 적용하고, 개인키 바이트를 직접 받는 서명 함수를 쓸 때는 서명 직전에 필요한 값만 메모리에 불러오세요.
릴레이와 개인정보
메시지 본문은 지갑과 dApp 사이에서 암호화되지만 릴레이 메타데이터까지 모두 암호화되지는 않습니다. 플랫폼 값은 릴레이 발행 요청에 항상 포함됩니다. userHash를 설정하면 설치 단위 식별값도 함께 전송되고 방문 이벤트가 활성화됩니다. 운영 도입 전 보안 검토에서 수집 목적과 보존 기간, 동의 방식, 비활성화 방법을 확정합니다.
페어링 URI, 채널 키, 서명 요청 원문, 개인키는 로그에 남기지 않습니다.
가이드 구성
| 영역 | 주요 구성 요소 | 다음 문서 |
|---|---|---|
| 설치·구성 | WalletKit, WalletKitConfig, 플랫폼 아티팩트 | 설치 |
| 첫 세션 연결 | JVM 명령줄 예제, connect() 왕복 | 빠른 시작 |
| 세션 연결 | 페어링 URI, connect(), 연결 과정 | 세션 연결 |
| 사용자 승인 | setApprovalHandler(), 연결·서명 승인 | 승인 단계 |
| 서명·개인키 처리 | Signer | 서명과 개인키 처리 |
| 릴레이 전송 | RelayTransport, KtorRelayTransport | 릴레이 전송 |
가이드는 지갑 제공사의 통합 흐름과 순서에 집중합니다. 공개 API의 정확한 함수·타입 정의와 기본값은 WalletKit API에서 확인합니다. 오류 코드와 복구 기준은 WalletKit 오류 처리에서 확인합니다.