Locker

PULSE에서 LOCKER 는 토큰을 안전하게 동결하고 거래 증거금을 관리할 수 있는 핵심 보안 시스템입니다.
이 가이드에서는 LOCKER의 역할과 주소 등록 방법을 안내합니다.

🤔 LOCKER란?

LOCKER는 토큰 거래 시 일시적으로 토큰을 동결(Lock) 하여 이중 지불을 방지하고 안전한 거래를 보장하는 시스템입니다.

💡 쉬운 이해를 위한 비유

은행에서 계좌 이체 시 잔액을 임시로 동결하는 것과 유사합니다. 송금 버튼을 누르는 순간 해당 금액이 일시적으로 사용 불가 상태가 되어 중복 송금을 방지하는 것처럼, LOCKER도 거래 진행 중인 토큰을 임시 동결하여 안전한 거래를 보장합니다.

🔧 LOCKER의 핵심 기능

LOCKER 시스템을 통해 다음과 같은 토큰 보안 관리가 가능합니다:

기능	설명	활용 사례
토큰 동결	특정 수량의 토큰을 일시적으로 사용 불가 상태로 전환	거래 주문 등록 시 증거금 동결
토큰 해제	동결된 토큰을 다시 사용 가능 상태로 복원	거래 완료 또는 취소 시 해제
이중 지불 방지	동일한 토큰의 중복 사용 차단	거래 진행 중 다른 거래 방지
거래 안전성	체결 전까지 토큰을 안전하게 보호	거래 실패 시 자동 원상복구

👥 LOCKER 권한별 관리 주체

PULSE는 다중 권한 구조로 LOCKER 시스템을 안전하게 관리합니다. LOCKER 권한 부여/회수는 ADMIN_ROLE이 처리하며, 회원사는 PULSE Web에서 권한 요청을 통해 신청합니다.

구분	담당자	주요 권한	사용 목적
관리자 (ADMIN)	토큰 관리자	LOCKER 부여/회수	시스템 전체 관리
SWAP 컨트랙트	자동화 시스템	자동 Lock/Unlock 실행	거래 체결 시 자동 처리
유통사	거래소/중개업체	실시간 Lock/Unlock 처리	주문 등록/취소 시 즉시 처리

🤝 협력 구조

🛡️ 관리자(ADMIN) 승인 → 📈 유통사 LOCKER 등록 → 🔄 SWAP 거래 시

❓ 토큰 발행 후 자동으로 등록되는 LOCKER 주소

SWAP 컨트랙트 자동 등록

토큰을 처음 발행하면 SWAP 컨트랙트 주소가 자동으로 LOCKER 주소로 등록됩니다.

🤔 왜 자동으로 등록될까요?

거래 시 토큰 동결 권한이 필요하기 때문입니다:

상황	설명
⚡ 즉시 동결	권한이 없으면 안전한 거래 진행 불가능
🔄 자동 해제	거래 완료/취소 시 SWAP 컨트랙트가 자동으로 동결 해제

📋 자동 등록되는 주소 정보

주소명: PULSE SWAP Contract

권한: LOCKER 권한 (토큰 Lock/Unlock)

관리: PULSE 시스템에서 자동 관리 (거래 시스템용 필수 주소이므로 임의 삭제 주의)

🔒 LOCKER 동작 원리

거래 과정에서의 LOCKER 활용

1️⃣ 매도 주문 등록
   투자자 A의 ST 1,000개 → 🔒 LOCK (거래 불가 상태)

2️⃣ 매수 주문 매칭  
   투자자 B의 DT 100,000원 → 🔒 LOCK (거래 불가 상태)

3️⃣ 거래 체결 실행
   🔓 SWAP 컨트랙트가 LOCK 해제 → 🔄 토큰 교환 처리

4️⃣ 거래 완료
   ✅ 토큰 이동 완료 (LOCK 해제된 상태로 교환)

ℹ️ 스왑 주문 생성 전에는 pre-swap Lock 으로 SWAP 타입 락을 먼저 설정해야 합니다. (Swap System 가이드 참고)

💰 투자자별 토큰 현황 예시

투자자 A의 ST 토큰 보유 현황:
📊 총 보유량: 1,000개
💚 사용 가능: 700개  
🔒 동결된 수량: 300개 (거래 진행 중)

🔄 LOCKER 활용 시나리오

📈 거래소 주문 관리

매도 주문 등록 → 토큰 LOCK → 체결 대기 → 체결 완료 → 자동 UNLOCK

🏭 관리적 목적

규제 조치 → 관련 토큰 LOCK → 조사 진행 → 문제 해결 → 수동 UNLOCK

🔒 담보 관리

대출 신청 → 담보 토큰 LOCK → 대출 실행 → 상환 완료 → 담보 UNLOCK

🚀 추가 LOCKER 주소 등록하기

기본 SWAP 컨트랙트 외에 발행사나 유통사의 자체 LOCKER 주소를 추가로 등록할 수 있습니다. 토큰 상세 → Locker 탭에서 권한 요청으로 등록합니다.

ℹ️ 알림: 토큰 발행 직후에는 SWAP 컨트랙트 주소가 이미 하나 등록되어 있습니다. 이는 거래 시스템 운영을 위해 자동으로 추가된 필수 주소입니다.

📝 입력 시 주의사항

✅ 올바른 형식: 0x로 시작하는 40자리 16진수 주소

✅ EOA 주소: 개인키로 제어 가능한 외부 소유 계정

✅ 신뢰할 수 있는 주소: 검증된 발행사/유통사 주소만 등록

주소 형식 예시:

0x742d35Cc6634C0532925a3b8d78dE30BEd85a7E0

🔌 LOCKER API

단일 관리자(ADMIN)로 운영하는 토큰은 파트너 API로 직접 등록/해제할 수 있습니다.

기능	메서드 · 경로
Locker 등록 / 해제	`POST` · `DELETE /main/v1/administration/locker`
Lock / Unlock	`POST` · `DELETE /main/v1/locker/lock`
pre-swap Lock	`POST /main/v1/locker/lock/pre-swap`
동결 잔액 조회	`GET /main/v1/holders/...`

요청·응답 필드와 상세 스펙은 API Reference → Token Lock 을 참고하세요. 인증 방식은 API Key 가이드를 참고하세요.

🛡️ LOCKER 보안 관리

권장사항

✅ 안전한 키 관리: LOCKER 주소의 개인키를 안전하게 보관

✅ 최소 권한 원칙: 필요한 LOCKER 권한만 부여

✅ 정기적 감사: 동결된 토큰 현황을 주기적으로 점검

✅ 자동화 활용: 가능한 한 자동 시스템(SWAP) 활용 권장

주의사항

⚠️ 무분별한 동결 금지: 과도한 토큰 동결은 유동성 저하 초래

⚠️ 해제 누락 방지: 동결된 토큰의 적시 해제 필수

⚠️ 권한 남용 금지: LOCKER 권한의 부적절한 사용 금지

🚀 다음 단계

단계	설명
⚙️ Operator 관리	토큰 전송 권한과 LOCKER 권한 연계 관리
📦 Partition 관리	파티션별 LOCKER 정책 설정
💱 거래 시스템	LOCKER와 연동된 안전한 거래 실행

🤔 LOCKER란?#

💡 쉬운 이해를 위한 비유#

🔧 LOCKER의 핵심 기능#

👥 LOCKER 권한별 관리 주체#

🤝 협력 구조#

❓ 토큰 발행 후 자동으로 등록되는 LOCKER 주소#

SWAP 컨트랙트 자동 등록#

🤔 왜 자동으로 등록될까요?#

📋 자동 등록되는 주소 정보#

🔒 LOCKER 동작 원리#

거래 과정에서의 LOCKER 활용#

💰 투자자별 토큰 현황 예시#

🔄 LOCKER 활용 시나리오#

📈 거래소 주문 관리#

🏭 관리적 목적#

🔒 담보 관리#

🚀 추가 LOCKER 주소 등록하기#

📝 입력 시 주의사항#

🔌 LOCKER API#

🛡️ LOCKER 보안 관리#

권장사항#

주의사항#

🚀 다음 단계#