Backend Services

The CloudBank backend is a monolithic Go service built with Go 1.23, the Gin HTTP framework, and GORM as the ORM layer. It handles authentication, wallet management, order matching, and administrative operations.

Technology Stack

Component	Technology
Language	Go 1.23
HTTP Framework	Gin
ORM	GORM
Cache / Rate Limiting	Redis
Database	MySQL (via GORM)
Authentication	JWT (HS256) + EIP-191

Custodial Wallet System

CloudBank provides custodial wallets for users who prefer a simplified experience without managing their own private keys.

Key Management

• Private keys are encrypted at rest using AES-256-GCM with a server-side master key.
• A key versioning system allows rotation of the encryption master key without re-encrypting all stored keys simultaneously. Each encrypted key record stores its encryption version, and decryption selects the correct master key based on version.
• Key material is never logged, never returned in API responses, and only decrypted in memory at the moment of transaction signing.

Authentication

User Auth (EIP-191)

Standard users authenticate by signing a challenge message with their Ethereum wallet:

1. Client requests a nonce from the server.
2. Client signs the nonce using their wallet (EIP-191 personal sign).
3. Server recovers the signer address from the signature and verifies it matches the claimed address.
4. Server issues a JWT (HS256) with the user's address and expiry.

Admin Auth

Admin endpoints use a layered authentication model:

• JWT + Basic Auth Bootstrap — Initial admin accounts are created via Basic Auth during platform setup, then transition to JWT-based auth.
• RBAC — Two roles: superadmin (full access including user management and system configuration) and admin (operational access for market management and monitoring).

Rate Limiting

The API uses a Redis-backed sliding window token bucket algorithm:

• Each client (identified by JWT subject or IP) has a token bucket in Redis.
• Tokens replenish at a fixed rate over a sliding window.
• When the bucket is empty, requests receive a 429 Too Many Requests response with a Retry-After header.
• Different rate limits apply to different endpoint groups (e.g., trading endpoints have higher limits than admin endpoints).

Contract Whitelist

To prevent custodial wallets from interacting with arbitrary contracts, the backend enforces a contract whitelist:

• Each entry specifies a contract address, allowed method selectors (4-byte function signatures), and the product the entry belongs to.
• Transactions are validated against the whitelist before signing and submission.
• This ensures custodial wallets can only call known, audited contract functions.

Withdrawal System

Withdrawals from custodial wallets are subject to safety controls:

• Daily limits per asset — Configurable caps for BNB and USDC withdrawals per user per day.
• Balance verification — The backend queries the on-chain balance before processing to prevent overdraft.
• Withdrawal requests exceeding the daily limit are queued for manual admin review.

Invite System

User acquisition is supported by an invite and referral system:

• Referral tracking — Each user receives a unique referral code. New signups can enter a referral code, linking the two accounts.
• Campaign management — Admins can create invite campaigns with configurable reward structures and expiration dates.
• CSV export — Referral data and campaign performance can be exported for analysis.

In-Memory Orderbook Engine

The backend includes a high-performance order matching engine:

• Orders are authenticated via EIP-712 typed structured data signatures.
• The matching engine maintains an in-memory order book with price-time priority — orders at the same price are filled in the order they were received.
• Matched trades are settled on-chain in batches to amortize gas costs.
• The engine supports GTC, GTD, FOK, and FAK order types (see Orderbook & AMM for details).

Audit Logging

All administrative actions are logged to the database with:

• Timestamp, admin user ID, and action type.
• Request parameters and affected resource IDs.
• IP address and user agent.

Audit logs are immutable (append-only) and retained for compliance review.

API Structure

The API follows RESTful conventions under versioned paths:

/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

All endpoints return JSON responses with consistent error structures including error codes, human-readable messages, and request trace IDs for debugging.