백엔드 서비스

CloudBank 백엔드는 Go 1.23, Gin HTTP 프레임워크, GORM을 ORM 레이어로 사용하여 구축된 모놀리식 Go 서비스입니다. 인증, 지갑 관리, 주문 매칭, 관리 업무를 처리합니다.

기술 스택

Component	Technology
Language	1.23 가세요
HTTP 프레임워크	Gin
ORM	GORM
캐시/속도 제한	Redis
Database	MySQL(GORM을 통해)
Authentication	JWT (HS256) + EIP-191

보관형 지갑 시스템

CloudBank은(는) 자신의 개인 키를 관리하지 않고 단순화된 경험을 선호하는 사용자를 위해 관리형 지갑을 제공합니다.

키 관리

• 개인 키는 서버 측 마스터 키와 함께 AES-256-GCM를 사용하여 저장 시 암호화됩니다.
• 키 버전 관리 시스템을 사용하면 저장된 모든 키를 동시에 다시 암호화하지 않고도 암호화 마스터 키를 순환할 수 있습니다. 각 암호화된 키 레코드는 암호화 버전을 저장하고, 암호 해독에서는 버전에 따라 올바른 마스터 키를 선택합니다.
• 키 자료는 기록되지 않으며 API 응답으로 반환되지 않으며 트랜잭션 서명 시점에만 메모리에서 해독됩니다.

Authentication

사용자 인증(EIP-191)

표준 사용자는 Ethereum 지갑으로 챌린지 메시지에 서명하여 인증합니다.

1. 클라이언트는 서버에 nonce를 요청합니다.
2. 클라이언트는 지갑(EIP-191 개인 서명)을 사용하여 nonce에 서명합니다.
3. 서버는 서명에서 서명자 주소를 복구하고 그것이 청구된 주소와 일치하는지 확인합니다.
4. 서버는 사용자의 주소와 만료일이 포함된 **JWT(HS256)**을 발행합니다.

관리자 인증

관리 엔드포인트는 계층화된 인증 모델을 사용합니다.

• JWT + 기본 인증 부트스트랩 — 플랫폼 설정 중에 기본 인증을 통해 초기 관리자 계정이 생성된 후 JWT 기반 인증으로 전환됩니다.
• RBAC — 두 가지 역할: RBAC(사용자 관리 및 시스템 구성을 포함한 전체 액세스) 및 superadmin(시장 관리 및 모니터링을 위한 운영 액세스).

속도 제한

API은 Redis 지원 슬라이딩 윈도우 토큰 버킷 알고리즘을 사용합니다.

• 각 클라이언트(JWT 주제 또는 IP로 식별됨)에는 Redis에 토큰 버킷이 있습니다.
• 토큰은 슬라이딩 윈도우를 통해 고정된 비율로 보충됩니다.
• 버킷이 비어 있으면 요청은 Retry-After 헤더가 포함된 429 Too Many Requests 응답을 받습니다.
• 다양한 엔드포인트 그룹에는 다양한 비율 제한이 적용됩니다(예: 거래 엔드포인트는 관리 엔드포인트보다 한도가 더 높습니다).

계약 화이트리스트

관리 지갑이 임의 계약과 상호 작용하는 것을 방지하기 위해 백엔드는 계약 화이트리스트를 시행합니다.

• 각 항목은 계약 주소, 허용된 메서드 선택기(4바이트 함수 서명) 및 항목이 속한 제품을 지정합니다.
• 거래는 서명 및 제출 전에 화이트리스트에 따라 검증됩니다.
• 이를 통해 관리 지갑은 알려진 감사된 계약 기능만 호출할 수 있습니다.

출금 시스템

관리 지갑에서 인출하는 경우 안전 통제가 적용됩니다.

• 자산당 일일 한도 — 사용자당 일일 BNB 및 USDC 인출 한도를 구성할 수 있습니다.
• 잔액 확인 — 백엔드는 초과 인출을 방지하기 위해 처리하기 전에 온체인 잔액을 쿼리합니다.
• 일일 한도를 초과하는 출금 요청은 수동 관리자 검토를 위해 대기됩니다.

초대 시스템

사용자 확보는 초대 및 추천 시스템을 통해 지원됩니다.

• 추천 추적 — 각 사용자는 고유한 추천 코드를 받습니다. 신규 가입 시 추천 코드를 입력하여 두 계정을 연결할 수 있습니다.
• 캠페인 관리 — 관리자는 구성 가능한 보상 구조와 만료 날짜를 사용하여 초대 캠페인을 만들 수 있습니다.
• CSV 내보내기 — 분석을 위해 추천 데이터 및 캠페인 성과를 내보낼 수 있습니다.

인메모리 주문장 엔진

백엔드에는 고성능 주문 일치 엔진이 포함되어 있습니다.

• 주문은 EIP-712 유형의 구조화된 데이터 서명을 통해 인증됩니다.
• 매칭 엔진은 가격-시간 우선으로 인메모리 주문서를 유지합니다. 즉, 동일한 가격의 주문은 접수된 순서대로 체결됩니다.
• 일치하는 거래는 가스 비용을 상각하기 위해 일괄적으로 온체인으로 정산됩니다.
• 엔진은 GTC, GTD, FOK 및 FAK 주문 유형을 지원합니다(자세한 내용은 주문서 및 AMM 참조).

감사 로깅

모든 관리 작업은 다음과 같이 데이터베이스에 기록됩니다.

• 타임스탬프, 관리자 사용자 ID 및 작업 유형.
• 요청 매개변수 및 영향을 받는 리소스 ID입니다.
• IP 주소 및 사용자 에이전트.

감사 로그는 변경할 수 없으며(추가만 가능) 규정 준수 검토를 위해 보관됩니다.

API 구조

API은 버전이 지정된 경로에서 RESTful 규칙을 따릅니다.

/api/v1/auth/*        — Authentication endpoints
/api/v1/markets/*     — Market CRUD and trading
/api/v1/orderbook/*   — Order placement and routing
/api/v1/admin/*       — Administrative operations
/api/v1/wallet/*      — Custodial wallet management
/api/v1/users/*       — User profiles and referrals

모든 엔드포인트는 오류 코드, 사람이 읽을 수 있는 메시지, 디버깅을 위한 요청 추적 ID를 포함한 일관된 오류 구조와 함께 JSON 응답을 반환합니다.