Reference

SDK — @hopae/sdk

읽기 전용 검증 클라이언트입니다. viem 기반 코어와 React 서브패키지로 구성되며, 발급·폐기는 포함되지 않습니다.

createHopae

import { createHopae } from '@hopae/sdk'

const hopae = createHopae({
  registry: '0x…',                        // HopaeRegistry 주소
  rpcUrl: 'https://sepolia-rpc.giwa.io',  // 또는 client: 기존 viem PublicClient 주입
})

rpcUrl 대신 이미 쓰고 있는 viem PublicClient를 client로 주입할 수 있습니다.

코어 API

메서드	반환	설명
`isVerified(addr, { kind?, minLevel? })`	`boolean`	활성 어테스테이션 보유 여부. 폐기·만료 자동 반영 (fail-closed). 기본값 kind=KYC, minLevel=1.
`isKycVerified(addr)`	`boolean`	KYC L1 이상 단축형. GatedKRW가 쓰는 호출.
`getStatus(addr, kind?)`	`HopaeStatus`	수명주기 상태 + 등급 + 발급/만료/폐기 시각 + 증적 해시 전체 조회.

HopaeStatus

interface HopaeStatus {
  state: 'active' | 'revoked' | 'lapsed' | 'none'
  subject: Address
  kind: number          // KIND.KYC(1) | KYB(2) | KYA(3)
  level: number         // 보증 등급 1–3 (none이면 0)
  uid: Hex | null       // EAS 어테스테이션 UID
  issuedAt: Date | null
  expiresAt: Date | null
  revokedAt: Date | null
  evidenceHash: Hex | null   // 오프체인 증적 레코드의 keccak256
  claimsRoot: Hex | null     // 스키마 v2 — Poseidon2 클레임 커밋 루트 (v1이면 null)
  auditRef: Hex | null       // 스키마 v2 — 감사 봉투 해시 (v1이면 null)
}

React API

export	설명
`<HopaeProvider config>`	컨텍스트 제공자 — 하위에서 훅·배지가 클라이언트를 공유.
`useHopae()`	Provider의 Hopae 클라이언트 인스턴스에 직접 접근.
`useHopaeStatus(addr, { kind?, refreshInterval? })`	라이브 상태 훅 — { status, isLoading, refetch }. refreshInterval(ms)로 폴링.
`<HopaeBadge address kind? locale? refreshInterval?>`	드롭인 인증마크 컴포넌트. dApp 테마와 무관하게 동일하게 보입니다.

상수 · ABI

export	설명
`KIND`	`{ KYC: 1, KYB: 2, KYA: 3 }`
`hopaeRegistryAbi / hopaeRegistryAbiV1`	viem·wagmi에서 직접 쓸 수 있는 레지스트리 ABI (v2 / v1 스키마).
`easAbi`	GIWA 프리디플로이 EAS ABI.
`SCHEMA_V1 / SCHEMA_V2 / computeSchemaUID`	스키마 문자열과 UID 계산 헬퍼 — 레지스트리가 어느 스키마로 배포됐는지 감지할 때 사용.

클레임 모듈 (스키마 v2 · ZK-ready)

스키마 v2 발급은 검증된 필드들을 Poseidon2 클레임 트리로 커밋하고 루트만 온체인에 올립니다. 값과 솔트는 사용자만 보관합니다. ZK 회로가 값을 공개하지 않고 “성인이다” 같은 술어를 증명하는 기반입니다.

export	설명
`buildClaims / claimsRootHex`	클레임 입력 → Poseidon2 트리 구성 → bytes32 루트.
`openClaim / verifyClaimOpening`	개별 클레임의 선택공개(머클 오프닝)와 검증.
`toCredential / fromCredential`	사용자 브라우저에 보관하는 크리덴셜 번들 직렬화.
`encodeDate / encodeCountry / encodeUnixTime`	클레임 값 인코딩 헬퍼 (BN254 필드 원소로).

SDK가 제공하는 것은 커밋먼트와 선택 공개까지입니다. 증명 생성을 포함한 ZK 경로는 ZK 검증 가이드를 참고하세요.

상태

알파. 데모 웹이 첫 소비자이며 npm 배포 전입니다. API 표면은 안정화 중입니다.