HomeGuidesAPI DocsUpdate Notes
Guides

SDK 연동

1. SDK 방식 개요

SDK 방식은 옥텟이 제공하는 MPC SDK를 엔드유저의 앱(iOS/Android) 또는 웹(Web) 환경에 직접 통합하는 통합 방식입니다. 고객사 서버를 거치지 않고 엔드유저 디바이스에서 직접 보안 연산이 수행되며, User Share는 디바이스 내 보안 저장소에 보관됩니다.


시스템 아키텍처

  1. 엔드유저(App/Web - SDK): 옥텟 MPC SDK가 탑재된 클라이언트입니다. 키 조각을 생성 및 보관하며, 서명 요청 시 디바이스 내에서 직접 MPC 연산에 참여합니다.
  2. 고객사 서버(Client): 엔드유저와 옥텟 사이에서 API 통신을 중계하며, 비즈니스 로직(출금 승인 등)을 관리합니다.
  3. 옥텟: MPC 키 생성 및 서명 요청에 필요한 인증 정보 및 데이터를 생성하며 SDK 키 관련 프로세스 시작 시 옥텟 측 MPC 연산을 시작합니다.

SDK 제공

해당 가이드를 진행하기 위해 필요한 SDK 제공 안내는 아래 연락처로 문의해 주세요.



2. MPC 키 생성 가이드

MPC 키는 고객사(Company) 단위로 생성되며, 생성된 키는 지갑의 자식 주소를 생성할 때 연결하여 사용할 수 있습니다.

키 생성 흐름

  1. MPC 키 생성 신청: 고객사는 옥텟 API를 호출하여 키 생성 작업을 요청하고 인증 토큰을 받습니다.
  2. SDK 키 생성 요청: 엔드유저 앱 내의 옥텟 SDK가 발급받은 토큰과 UUID를 사용하여 옥텟 서버와 직접 통신하며 실제 키 생성 연산을 시작합니다.
  3. User Share 보관: 연산 완료 후 생성된 User Share는 SDK를 통해 엔드유저의 로컬 보안 영역(Secure Enclave 등)에 안전하게 저장됩니다.
  4. 상세 단계 확인: 키 생성 연산의 진행 상황이나 최종 결과는 옥텟 API를 통해 확인할 수 있습니다.

상세 단계

1단계: 옥텟에 키 생성 신청

MPC 키 생성 신청 API를 호출합니다.

  • 응답값: uuid (작업 고유 ID), token (SDK 인증용 JWT), expiredDate (신청건 만료 일시)
  • 유효시간: 신청 시점부터 2분(120초, 정확한 시각은 응답의 expiredDate) 내에 키 생성이 완료되지 않으면 신청건이 만료(EXPIRED) 처리됩니다. 만료된 신청건은 재사용할 수 없으며, 키 생성을 새로 신청해야 합니다.

2단계: SDK 작업 요청

1단계에서 받은 정보를 엔드유저 앱의 SDK에 전달하여 작업을 시작합니다.

  • 작업: SDK와 옥텟간의 직접적인 통신을 통해 Key Share들이 분산 생성됩니다.

3단계: User Share 관리

  • 생성된 User Share는 SDK 내부 로직에 의해 기기 내 안전한 저장소에 보관됩니다.

4단계: 상태 확인

키 생성 연산의 진행 상황이나 최종 결과는 옥텟 API로 확인할 수 있습니다.

  • 생성 상태 조회: MPC 키 생성 신청 정보 조회
    • 상태는 AWAITING_CREATION에서 SUCCESS / FAILED / EXPIRED 중 하나로 종결됩니다. EXPIRED는 유효시간 내에 키 생성이 완료되지 않아 만료된 상태입니다.
  • 최종 키 정보 조회: MPC 키 조회 (공개키 정보 등 포함)

자식 주소 생성 시 MPC 키 연결

MPC 키 생성이 완료되면, 지갑 내에서 해당 키를 사용하는 주소를 만들 수 있습니다.

  • 방법: 자식 주소 생성 API 호출 시 mpcKeyUuid 필드에 위에서 생성한 키의 uuid를 입력합니다.
  • 이 주소로 발생하는 모든 출금은 해당 MPC 키의 서명이 필요하게 됩니다.


3. MPC 키 서명 가이드 (출금)

MPC 지갑에서의 출금은 엔드유저 디바이스가 보유한 User Share와 옥텟이 보유한 Octet Share가 결합하여 서명을 생성하는 과정을 거칩니다.

서명 및 출금 흐름

  1. 트랜잭션 생성: 고객사가 서명되지 않은 트랜잭션 데이터를 직접 생성합니다.
  2. 옥텟 출금 신청: 옥텟 API에 출금을 신청하고 서명 작업 정보를 받습니다.
  3. SDK 서명 실행: 엔드유저 앱의 SDK가 기기에 보관된 User Share와 옥텟의 작업 정보를 사용하여 서명 연산을 수행합니다.
  4. 트랜잭션 전파: 서명이 완료되면 옥텟이 자동으로 최종 트랜잭션을 구성하여 블록체인에 전파합니다.

상세 단계

1단계: 출금 신청 준비

MPC 주소로부터 출금할 때는 아래 두 가지 설정을 반드시 포함해야 합니다.

  • autoSigning: false (옥텟이 단독으로 서명할 수 없으므로 필수)
  • serializedUnsignedTransaction: 고객사가 직접 생성한 서명 전 트랜잭션 데이터 (Hex String)

2단계: 옥텟에 출금 신청

출금 신청 API를 호출합니다.

  • 응답값: 성공 시 응답 객체 내에 mpc 필드가 포함됩니다. 서명 대상은 mpcSigningTargets 배열로 내려오며, 단건 서명(EVM 등)은 원소 1개입니다.
{
  "uuid": "...",
  "mpc": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiredDate": "2026-07-29T00:02:00.000Z",
    "mpcSigningTargets": [
      {
        "signingIndex": 0,
        "message": "2c745b3cd5af47515df7bded000d1906147e27c275a3029cc6d4a585aa1c47b0"
      }
    ]
  }
}
  • 유효시간: 신청 시점부터 2분(120초, 정확한 시각은 mpc.expiredDate) 내에 MPC 서명이 완료되지 않으면 서명 요청이 만료(EXPIRED)되고, 해당 출금은 자동으로 실패(FAILED) 처리됩니다. 별도의 출금 취소 요청 없이 실패 처리되므로, 재시도가 필요하면 출금을 새로 신청합니다.

3단계: SDK 서명 요청

기기에 보관된 User Share와 2단계에서 받은 mpc 정보를 사용하여 SDK에 서명을 요청합니다.

  • 필수 입력: User Share, token, 서명 대상 메시지(mpc.mpcSigningTargets[0].message)
  • 동작: SDK가 옥텟과 연동하여 2-of-3 서명을 생성합니다. SDK 방식은 현재 단건 서명(서명 대상 1개, EVM 등)을 지원합니다.

4단계: 출금 완료

  • SDK에서 서명 연산이 성공적으로 완료되면, 옥텟 시스템은 이를 감지하여 미리 전달받았던 serializedUnsignedTransaction과 생성된 서명값을 결합합니다.
  • 최종적으로 서명된 트랜잭션(serializedSignedTransaction)이 만들어지며, 옥텟이 이를 블록체인 네트워크에 전파합니다.
  • 서명 진행 상태는 출금 신청 정보 조회 API 응답의 mpcSigning.status로 확인할 수 있으며, AWAITING_SIGNING에서 SUCCESS / FAILED / EXPIRED 중 하나로 종결됩니다.



Updated 10 days ago

Did this page help you?