IEUM SDK (@ieum/sdk)

@ieum/sdk는 파트너사(은행·기업)가 자사 서비스에 이음 스테이블코인 기능을 빠르게 통합할 수 있도록 제공하는 TypeScript 기반 npm 패키지입니다. Avalanche Subnet (Jelly Testnet) 기본 설정이 내장되어 있으며, KSC 토큰 프리셋을 포함합니다.

3.1 패키지 구성

구성 요소	포함 여부	설명
TypeScript SDK	✓ 포함	IeumClient, TransactionsApi 등 핵심 클라이언트
Type 정의	✓ 포함	TransactionCreateRequest, TransactionResponse 등 모든 타입
Example (node-cli)	✓ 포함	Node.js CLI 예제 코드 및 .env.example
Jelly Testnet preset	✓ 포함	chainId <CHAIN_ID>, RPC URL, Explorer 링크 헬퍼 (PoC 환경 기준)
KSC preset	✓ 포함	컨트랙트 주소 및 PaymentManager 주소 사전 설정
Error code mapping	✓ 포함	IeumError 클래스 및 에러 코드 매핑
core-ledger 내부 구현	✗ 미포함	오프체인 원장 로직은 서버 사이드에서만 운영
chain-adapter 내부 로직	✗ 미포함	체인 실행은 IEUM Runtime이 담당
멀티체인 확장 로직	✗ 미포함 (v1)	v2 이후 지원 예정

3.2 설치 및 빠른 시작

npm install @ieum/sdk
# 또는
pnpm add @ieum/sdk

import { IeumClient, NetworkType, TxPaymentType } from "@ieum/sdk";

const client = new IeumClient({
  baseUrl: process.env.IEUM_BASE_URL ?? "<API_BASE_URL>",
  apiKey:  process.env.IEUM_API_KEY!,
  orgCode: process.env.IEUM_ORG_CODE,      // 선택
});

// 트랜잭션 기록
const record = await client.transactions.create({
  fromNetworkType: NetworkType.AVAX,
  toNetworkType:   NetworkType.AVAX,
  paymentType:     TxPaymentType.INSTANT,
  fromAddress: "0xFROM...",
  toAddress:   "0xTO...",
  txHash:      "0xONCHAIN_TX_HASH",
  amount:      "1000000",   // 최소 단위 정수 문자열 (소수점 없음)
  fee:         "0",
  memo:        "결제 메모",
});

// 조회 / 목록
const tx   = await client.transactions.get(record.id);
const list = await client.transactions.list({ limit: 10, currentPage: 1 });

3.3 Transactions API

메서드	HTTP	설명
transactions.create(req)	POST /api/transaction	트랜잭션 생성 기록. INSTANT는 txHash 필수.
transactions.get(id)	GET /api/transaction/:id	단건 조회
transactions.list(query)	GET /api/transaction	목록 조회 (페이지네이션: limit, currentPage)
transactions.updateStatus(id, req)	PATCH /api/transaction/:id/status	상태 갱신 (PENDING → CONFIRMED / FAILED 등)
transactions.updateSchedule(id, req)	PATCH /api/transaction/:id/schedule	SCHEDULED 트랜잭션 예약 시각 변경
transactions.waitForStatus(id, fn)	내부 폴링	predicate가 true가 될 때까지 1.5초 간격으로 상태 확인 (기본 60초 타임아웃)

3.4 주요 타입 및 Conventions

• amount / fee: 소수점 없는 최소 단위 정수 문자열 (예: 6 decimals → 1.0 KRW = "1000000")

• INSTANT 타입: 중복 txHash 거부 (멱등성 보장)

• SCHEDULED 타입: scheduledAt 필수 (ISO 문자열, 미래), 동일 네트워크만 지원

• 기본 네트워크: Jelly Subnet Testnet (chainId <CHAIN_ID>) (PoC 환경 기준)