Swap System

PULSE에서 SWAP System은 ST(Security Token)와 DT(Deposit Token) 간의 안전한 교환을 처리하는 핵심 거래 시스템입니다.
이 가이드에서는 SWAP의 동작 원리와 구현 과정에 대해 상세히 안내합니다.

🤔 SWAP System이란?

SWAP System은 유통사와 발행사가 순차적으로 트랜잭션을 처리하여 ST와 DT를 안전하게 교환하는 자동화된 거래 시스템입니다.

💡 쉬운 이해를 위한 비유

증권 거래소에서 주식과 현금이 동시에 교환되는 것과 같습니다. 매수자의 현금(DT)과 매도자의 주식(ST)이 안전하게 맞교환되면서, 수수료와 세금까지 자동으로 처리되는 시스템입니다.

🎯 SWAP이 필요한 이유

이유	설명
거래 안전성	Lock 해제와 토큰 이동이 하나의 트랜잭션에서 원자적으로 처리
즉시 결제	T+0 당일 결제로 빠른 거래 체결
이중 지불 방지	사전 토큰 동결로 안전한 거래 보장
권한 분리	유통사와 발행사의 역할 분리로 이해상충 방지

⚡ PULSE SWAP 특징

특징	상세 내용
이중 서명 구조	DT Order + ST Order 매칭 처리
원자적 실행	두 Order 매칭 시 SWAP 컨트랙트 자동 실행
자동 수수료 처리	구매자/판매자 수수료 및 세금 자동 계산
스마트 Lock 관리	Lock 해제와 토큰 이동 동시 처리

🏗️ SWAP 시스템 구조

👥 참여자별 역할

참여자	역할	주요 권한
유통사	주문 매칭 및 DT Order 처리	DT Operator, ST/DT Locker
발행사	ST Order 검증 및 처리	ST Operator, Locker 권한 부여
SWAP 컨트랙트	자동 토큰 교환 실행	ST/DT Operator, ST/DT Locker
수수료 수집자	거래 수수료 및 세금 수취	feeTaxCollector 주소

🔑 권한 설정 요구사항

SWAP 시스템이 동작하기 위해서는 유통사가 ST/DT 모두 Lock/Unlock 할 수 있는 LOCKER 권한을 가져야 합니다:

유통사 주소를 LOCKER로 등록 (권한 요청 → PULSE 승인)

주문 생성 전 pre-swap Lock 으로 대상 토큰을 SWAP 타입으로 동결

📋 SWAP Order 데이터 구조

🔍 필수 Order 정보

SWAP 실행을 위해 다음 정보들이 포함되어야 합니다:

필드	설명	예시
executeId	체결 ID (DT는 숫자로 전달 시 서버가 `회원사코드-번호`로 조합, ST는 완성된 문자열)	"WE7M6D5XMZ-1"
stockCd	ST 토큰 심볼	"BCG"
tokenDTSymbol	DT 심볼 (ST Order에만 포함, `'DT'` 사용 가능)	"DT"
holderDT	DT 보유자 주소 (매수자)	"0xCa127f076c..."
holderST	ST 보유자 주소 (매도자)	"0x0cC4fEE4FDB..."
amountDT	거래할 DT 수량	10000
amountST	거래할 ST 수량	1
partitionName	파티션 이름	"유통"

💰 수수료 및 세금 정보

필드	설명	부담자
amountBuyerFee	구매자 수수료	매수자
amountBuyerTax	구매자 세금	매수자
amountSellerFee	판매자 수수료	매도자
amountSellerTax	판매자 세금	매도자
feeTaxCollector	수수료 수집 주소	유통사 지정

🚀 SWAP 실행 프로세스

📋 전체 프로세스 개요

pre-swap Lock → 유통사 DT Order → 발행사 ST Order → SWAP 자동 실행

1️⃣ 주문 등록 및 토큰 동결

매도자: ST 매도 주문 등록 → 유통사가 해당 ST를 pre-swap Lock

매수자: DT 매수 주문 등록 → 유통사가 해당 DT를 pre-swap Lock

유통사 매칭 시스템에서 주문 매칭 완료

2️⃣ 유통사 DT Order 처리

DT Order API로 트랜잭션 데이터 생성

유통사 DT Operator Key로 서명

블록체인에 트랜잭션 전송

발행사에게 거래 내역 및 executeId 전달

3️⃣ 발행사 ST Order 처리

거래 내역 검증 후 승인

ST Order API로 트랜잭션 데이터 생성

발행사 ST Operator Key로 서명

블록체인에 트랜잭션 전송

4️⃣ SWAP 컨트랙트 자동 실행

두 Order가 같은 orderID로 매칭되면 두 번째 트랜잭션 안에서 SWAP 컨트랙트가 하나의 트랜잭션에서 다음을 순차 처리:

Lock 해제 (ST + DT 동시) -> 수수료 자동 처리 -> 토큰 교환 실행 -> 거래 완료 이벤트 발생

🔌 SWAP API

기능	메서드 · 경로
pre-swap Lock 생성	`POST /main/v1/locker/lock/pre-swap`
DT Order 생성	`POST /main/v1/swap/dt/create/tx/data`
ST Order 생성	`POST /main/v1/swap/st/create/tx/data`

SWAP 실행은 별도 API가 없습니다. 두 Order가 매칭되는 순간 온체인에서 자동 실행됩니다.
요청·응답 필드와 상세 스펙은 API Reference → Swap 을 참고하세요. 인증 방식은 API Key 가이드를 참고하세요.

⚠️ API 사용 시 주의사항

중요: SWAP 관련 API 호출 시 정확한 Order 정보를 전달해야 합니다.
특히 executeId와 수수료 정보는 유통사와 발행사 Order 간에 완전히 일치해야 합니다. (필드 해시가 다르면 매칭 실패)

💡 SWAP 스마트 컨트랙트 동작 원리

🔄 내부 처리 로직

SWAP 컨트랙트는 다음 순서로 하나의 트랜잭션에서 모든 작업을 처리합니다:

🛡️ 안전성 보장

원자성: 모든 작업이 성공하거나 모두 실패 (중간 상태 없음)

일관성: Lock 해제와 Transfer가 동시에 처리되어 토큰 손실 방지

격리성: 다른 트랜잭션의 간섭 없이 독립적으로 실행

⚠️ SWAP 실패 사례

🚨 주요 실패 원인

실패 원인	설명	해결 방법
Lock 미설정	ST 또는 DT가 사전에 Lock되지 않음	주문 전 pre-swap Lock 실행
잔액 부족	토큰 잔액이 거래 수량보다 적음	잔액 확인 후 주문 등록
권한 없음	Operator 또는 Locker 권한 부족	권한 설정 확인 및 재등록
Order 불일치	유통사와 발행사 Order 정보 상이	executeId 및 거래 정보 재확인
KYC 미등록	토큰 수신자가 KYC 미등록 상태	KYC 등록 후 거래 재시도

🎯 실제 거래 시나리오

📈 구체적인 SWAP 거래 예시

🏪 상황: 투자자 A가 BCG 토큰 1개를 10,000원에 판매, 투자자 B가 구매
       (구매자 수수료 50원, 판매자 수수료 50원)

💰 거래 전 잔액:
   - 투자자 A: BCG 토큰 5개 보유
   - 투자자 B: DT 50,000개 보유

📋 Order 정보:
   - executeId: "WE7M6D5XMZ-1"
   - amountST: 1, amountDT: 10,000
   - amountBuyerFee: 50, amountSellerFee: 50
   - feeTaxCollector: 유통사 수수료 수집 주소

🔄 처리 과정:
   1. 유통사: BCG 1개 Lock + DT 10,050개 Lock (수수료 포함)
   2. 유통사: DT Order 생성 및 전송
   3. 발행사: 거래 검증 후 ST Order 생성 및 전송
   4. SWAP 컨트랙트: 자동 실행
      - Lock 해제: BCG 1개 + DT 10,050개
      - 수수료 처리: 구매자 50원 + 판매자 50원 → feeTaxCollector
      - 토큰 교환: BCG 1개 → 투자자 B, DT 9,950원 → 투자자 A

✅ 거래 완료 후 잔액:
   - 투자자 A: BCG 4개 + DT 9,950개
   - 투자자 B: BCG 1개 + DT 39,950개  
   - 수수료 수집자: DT 100개 (수수료)

🤔 자주 묻는 질문

Q: SWAP이 실행되는 정확한 조건은 무엇인가요?

A: 유통사의 DT Order와 발행사의 ST Order가 같은 orderID로 매칭되면, 두 번째 Order 트랜잭션 안에서 SWAP 컨트랙트가 자동으로 실행됩니다.

Q: SWAP 실행 중 오류가 발생하면 어떻게 되나요?

A: SWAP은 원자적 트랜잭션이므로 오류 발생 시 모든 작업이 롤백되어 원래 상태로 돌아갑니다. Lock된 토큰들은 그대로 유지됩니다.

Q: 수수료는 누가 설정하나요?

A: 유통사가 feeTaxCollector 주소를 지정하고, 각 거래별로 구매자/판매자 수수료 및 세금을 설정할 수 있습니다.

Q: 한 번에 여러 건의 SWAP을 처리할 수 있나요?

A: 각 SWAP은 독립적인 트랜잭션으로 처리되므로, 동시에 여러 건을 처리할 수 있습니다.

Ready for trading? 👉 DT System 알아보기 | Locker System 알아보기

🤔 SWAP System이란?#

💡 쉬운 이해를 위한 비유#

🎯 SWAP이 필요한 이유#

⚡ PULSE SWAP 특징#

🏗️ SWAP 시스템 구조#

👥 참여자별 역할#

🔑 권한 설정 요구사항#

📋 SWAP Order 데이터 구조#

🔍 필수 Order 정보#

💰 수수료 및 세금 정보#

🚀 SWAP 실행 프로세스#

📋 전체 프로세스 개요#

1️⃣ 주문 등록 및 토큰 동결#

2️⃣ 유통사 DT Order 처리#

3️⃣ 발행사 ST Order 처리#

4️⃣ SWAP 컨트랙트 자동 실행#

🔌 SWAP API#

⚠️ API 사용 시 주의사항#

💡 SWAP 스마트 컨트랙트 동작 원리#

🔄 내부 처리 로직#

🛡️ 안전성 보장#

⚠️ SWAP 실패 사례#

🚨 주요 실패 원인#

🎯 실제 거래 시나리오#

📈 구체적인 SWAP 거래 예시#

🤔 자주 묻는 질문#

Q: SWAP이 실행되는 정확한 조건은 무엇인가요?#

Q: SWAP 실행 중 오류가 발생하면 어떻게 되나요?#

Q: 수수료는 누가 설정하나요?#

Q: 한 번에 여러 건의 SWAP을 처리할 수 있나요?#