1. 에이전트 방식 개요

에이전트 방식은 옥텟이 제공하는 MPC 에이전트(Agent) 프로그램을 고객사 서버에 설치하여 운용하는 통합 방식입니다. MPC 키 생성 및 서명 연산이 고객사 인프라 내 에이전트에서 수행되며, 엔드유저는 User Share를 직접 보관합니다.

시스템 아키텍처

엔드유저(App): 고객사에 키 생성 요청을 한 이후 받은 키를 저장하고 서명 요청 시에 저장하고 있는 키를 고객사에 전달합니다.
고객사 서버(Client): 엔드유저와 옥텟 사이에서 중계 역할을 하며, MPC 에이전트를 관리합니다.
MPC 에이전트: 고객사 서버 내에 설치되며, 엔드유저의 키 조각 생성 및 서명 연산을 수행합니다.
옥텟: 키 생성 및 서명 요청에 대해 옥텟 측 MPC 연산을 수행하며, 에러 핸들링 및 성공 시 후처리 합니다.

MPC 에이전트 제공

현재 옥텟의 MPC 솔루션 중 에이전트 방식은 고객사 서버에 설치하는 에이전트 형태로 제공됩니다. 해당 가이드를 진행하기 위해 필요한 에이전트 프로그램 및 설치 안내는 아래 연락처로 문의하시기 바랍니다.

이메일 문의: [email protected]

2. MPC 키 생성 가이드

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

키 생성 흐름

MPC 키 생성 신청: 고객사는 옥텟 API를 호출하여 키 생성 작업을 요청하고 인증 토큰을 받습니다.
MPC 에이전트 키 생성 요청: 발급받은 토큰과 UUID를 통해 고객사 인프라 내의 MPC 에이전트가 실제 키 생성 연산을 시작합니다.
User Share 추출 및 전달: 연산 완료 후, MPC 에이전트에서 생성된 User Share를 조회하여 엔드유저에게 안전하게 전달합니다.
에이전트 내 Share 삭제: 보안을 위해 에이전트에 일시 저장된 User Share를 삭제합니다.

상세 단계

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

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

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

2단계: MPC 에이전트 작업 요청

1단계에서 받은 정보를 사용하여 고객사 내 MPC 에이전트에 요청을 보냅니다.

작업: MPC 에이전트와 옥텟 간의 통신을 통해 Key Share들이 분산 생성됩니다.

3단계: User Share 전달 및 관리

키 조회: MPC 에이전트의 조회 API를 통해 생성된 User Share을 가져옵니다.
키 전달: 가져온 User Share을 엔드유저에게 전달합니다.
에이전트 내 삭제: 전달이 완료되면 에이전트의 삭제 API를 호출하여 고객사 서버에 남은 User Share을 지웁니다.

4단계: 상태 확인

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

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

자식 주소 생성 시 MPC 키 연결

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

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

3. MPC 키 서명 가이드

MPC 주소의 서명은 엔드유저가 보유한 키 조각과 옥텟이 보유한 키 조각이 결합하여 생성됩니다. 서명이 필요한 세 API — 출금 신청, 트랜잭션 서명 신청, 데이터 서명 신청 — 에서 모두 동일한 방식으로 동작하며, 아래는 출금 기준으로 설명합니다. 나머지 두 API와의 차이는 이 장 마지막의 "트랜잭션 서명·데이터 서명 API" 절에 정리되어 있습니다.

서명 및 출금 흐름

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

상세 단계

1단계: 출금 신청 준비

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

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

2단계: 옥텟에 출금 신청

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

응답값: 성공 시 응답 객체 내에 mpc 필드가 포함됩니다. 서명 대상은 mpcSigningTargets 배열로 내려오며, 단건 서명(EVM 등)도 원소 1개짜리 배열입니다. 비트코인처럼 트랜잭션 input마다 서명이 필요한 자산은 원소가 여러 개입니다.

{
  "uuid": "...",
  "mpc": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiredDate": "2026-07-29T00:02:00.000Z",
    "mpcSigningTargets": [
      {
        "signingIndex": 0,
        "message": "2c745b3cd5af47515df7bded000d1906147e27c275a3029cc6d4a585aa1c47b0"
      }
    ]
  }
}

유효시간: 신청 시점부터 2분(120초, 정확한 시각은 mpc.expiredDate) 내에 MPC 서명이 완료되지 않으면 서명 요청이 만료(EXPIRED)되고, 해당 출금은 자동으로 실패(FAILED) 처리됩니다. 별도의 출금 취소 요청 없이 실패 처리되므로, 재시도가 필요하면 출금을 새로 신청합니다.
Refresh 진행 중 출금 제한: 해당 MPC 키에 진행 중인 Refresh 신청이 있으면 출금 신청이 거절됩니다. Refresh가 종결(성공/실패/만료)된 후 다시 신청할 수 있습니다.

3단계: MPC 에이전트 서명 요청

엔드유저로부터 받은 User Share와 2단계에서 받은 mpc 정보를 사용하여 에이전트에 서명을 요청합니다.

필수 입력: User Share, token, mpcSigningTargets
- mpcSigningTargets는 2단계 응답의 배열을 순서·값 그대로 전달하되, 필드명만 snake_case로 변환합니다(signingIndex → signing_index, message는 동일). 값을 가공하면 옥텟에 기록된 서명 대상과의 교차검증에서 작업이 거절됩니다.
동작: 에이전트가 옥텟과 연동하여 2-of-3 서명을 생성합니다. 서명 대상이 여러 개인 트랜잭션도 한 번의 호출로 접수되며, 한 세션 안에서 순차 처리됩니다.

4단계: 출금 완료

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

트랜잭션 서명·데이터 서명 API

위 서명 흐름은 출금 외에 트랜잭션 서명 신청, 데이터 서명 신청 API에도 동일하게 적용됩니다. 신청 API와 서명 완료 후 처리만 다르며, 응답의 mpc 형식과 3단계(MPC 에이전트 서명 요청)는 완전히 동일합니다.

	출금 신청	트랜잭션 서명 신청	데이터 서명 신청
신청 입력	`serializedUnsignedTransaction` + `autoSigning: false`	`serializedUnsignedTransaction`	서명할 데이터와 타입 (`EIP191` / `EIP712` / `KIP97`)
서명 대상 `message`	트랜잭션 서명 해시	트랜잭션 서명 해시	옥텟이 계산한 데이터 해시
서명 완료 후	옥텟이 서명본을 구성해 블록체인에 전파까지 수행	옥텟이 서명본(`serializedSignedTransaction`)을 구성해 보관하며, 전파는 고객사가 서명된 트랜잭션 전송 API로 수행	옥텟이 서명 결과(`serializedSignedData`)를 보관
결과 확인	출금 신청 정보 조회 API	트랜잭션 서명 신청 정보 조회 API	데이터 서명 신청 정보 조회 API

유효시간(2분)과 만료 시 EXPIRED → 신청 실패(FAILED) 처리, Refresh 진행 중 신청 제한은 세 API 모두 동일하게 적용됩니다.
데이터 서명의 서명 대상 해시는 옥텟이 계산하여 응답의 mpcSigningTargets의 message로 반환하므로, 고객사는 원본 데이터만 제출하면 됩니다. 서명 결과 serializedSignedData는 65바이트 서명(r ‖ s ‖ v, v = 27 + recovery id)을 RLP 인코딩한 값입니다.

4. MPC 키 Refresh 가이드 (재발급)

Refresh는 엔드유저가 User Share를 분실했을 때, 모든 파티의 키 조각을 새 버전으로 재발급하는 기능입니다. 옥텟이 보관 중인 키 조각 2개만으로 재발급 연산이 수행되므로, 신청 시 기존 User Share를 제출할 필요가 없습니다.

공개키·주소·키 UUID 보존: 키의 version만 1 증가하며, 기존에 생성한 주소와 자산은 영향을 받지 않습니다.
이전 키 조각 무효화: Refresh가 성공하면 이전 버전의 키 조각 조합으로는 더 이상 서명이 성립하지 않습니다. 반드시 새 User Share를 엔드유저에게 전달해야 합니다.

Refresh 흐름

Refresh 신청: 고객사는 옥텟 API를 호출하여 Refresh 작업을 요청하고 인증 토큰을 받습니다.
MPC 에이전트 Refresh 요청: 발급받은 토큰과 UUID를 통해 고객사 인프라 내의 MPC 에이전트가 재발급 연산을 시작합니다.
상태 확인: 옥텟 API를 호출하여 신청 상태가 SUCCESS가 되었는지 확인합니다.
User Share 추출 및 전달: 새로 발급된 User Share를 MPC 에이전트에서 조회하여 엔드유저에게 안전하게 전달하고, 에이전트에 일시 저장된 User Share를 삭제합니다.

상세 단계

1단계: 옥텟에 Refresh 신청

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

요청값: mpcKeyUuid (재발급할 MPC 키의 UUID)
응답값: uuid (Refresh 신청건 고유 ID), token (MPC 에이전트 인증용 JWT), expiredDate (신청건 만료 일시)
- 응답의 uuid는 Refresh 신청건의 UUID로, MPC 키의 UUID와 다릅니다. 신청 상태 조회에 사용하며, 에이전트에서의 키 조각 조회에는 사용하지 않습니다.
유효시간: 신청 시점부터 2분(120초, 정확한 시각은 응답의 expiredDate) 내에 Refresh가 완료되지 않으면 신청건이 만료(EXPIRED) 처리됩니다. 이 경우 키 버전은 그대로 유지되며, Refresh를 새로 신청해야 합니다.

2단계: MPC 에이전트 작업 요청

1단계에서 받은 정보를 사용하여 고객사 내 MPC 에이전트에 요청을 보냅니다.

작업: MPC 에이전트와 옥텟 간의 통신을 통해 모든 파티의 Key Share가 새 버전으로 재생성됩니다. 기존 User Share는 필요하지 않습니다.

3단계: 상태 확인

신청 상태 조회: MPC 키 Refresh 신청 정보 조회
- 상태는 AWAITING_REFRESH에서 SUCCESS / FAILED / EXPIRED 중 하나로 종결됩니다.
- SUCCESS: 재발급 완료. 키가 신청 시 확정된 toVersion 버전으로 교체됩니다.
- FAILED: 재발급 실패. errorCode / errorMessage를 확인한 후 새로 신청할 수 있습니다.
- EXPIRED: 유효시간 내에 완료되지 않아 만료된 상태입니다.
신청 이력 조회: MPC 키 Refresh 신청 목록 조회 (mpcKeyUuid 필터 지원)

4단계: User Share 전달 및 관리

키 조회: 반드시 상태가 SUCCESS인 것을 확인한 후, MPC 에이전트의 조회 API를 통해 키 UUID로 새로 발급된 User Share를 가져옵니다. 키 생성 때와 동일한 방식입니다.
키 전달: 가져온 User Share를 엔드유저에게 전달합니다. 이전 User Share는 더 이상 사용할 수 없습니다.
에이전트 내 삭제: 전달이 완료되면 에이전트의 삭제 API를 호출하여 고객사 서버에 남은 User Share를 삭제하는걸 권장합니다.

주의 사항

사전 조건: 대상 MPC 키가 ACTIVATED 상태여야 하며, 해당 키에 진행 중인 서명(출금, 트랜잭션 서명, 데이터 서명)이나 다른 Refresh 신청이 없어야 합니다. 진행 중인 세션은 만료 시각이 지나면 자동으로 만료됩니다.