منطق کلی بازار (Market Logic)¶

مقدمه¶

این بخش منطق کلی سیستم بازار اسکناس همتا به همتا را توضیح می‌دهد. درک این منطق برای توسعه‌دهندگان ضروری است تا بتوانند به درستی از APIها استفاده کنند.

معماری کلی سیستم¶

نمودار کلی سیستم¶

flowchart TB
    subgraph "کاربران"
        A[بانک A]
        B[بانک B]
        C[کاربران خرد]
    end

    subgraph "API Gateway"
        D[Auth API]
        E[User API]
        F[Accounting API]
        G[Exchange API]
    end

    subgraph "موتور معاملاتی"
        H[Matching Engine]
        I[Order Book]
        J[Price Discovery]
    end

    subgraph "پایگاه داده"
        K[Users DB]
        L[Wallets DB]
        M[Orders DB]
        N[Trades DB]
    end

    A & B & C --> D
    D --> E & F & G
    E --> K
    F --> L
    G --> H
    H --> I & J
    H --> M & N

    style A fill:#e1f5ff
    style B fill:#e1f5ff
    style C fill:#e1f5ff
    style D fill:#fff2cc
    style E fill:#fff2cc
    style F fill:#fff2cc
    style G fill:#fff2cc
    style H fill:#d5e8d4
    style I fill:#d5e8d4
    style J fill:#d5e8d4

گردش کار معاملاتی (Transaction Flow)¶

نمودار گردش کار کامل¶

sequenceDiagram
    participant User
    participant Auth
    participant UserAPI
    participant WalletAPI
    participant ExchangeAPI
    participant MatchingEngine
    participant DB

    Note over User,Auth: مرحله 1: احراز هویت
    User->>Auth: POST /login (client_id, secret)
    Auth-->>User: access_token + refresh_token

    Note over User,UserAPI: مرحله 2: ایجاد کاربر
    User->>UserAPI: POST /users (اطلاعات کاربر)
    UserAPI->>DB: ذخیره کاربر
    UserAPI-->>User: user_id + wallet_id

    Note over User,WalletAPI: مرحله 3: واریز وجه
    User->>WalletAPI: POST /wallets/{id}/deposit
    WalletAPI->>DB: ثبت تراکنش واریز
    WalletAPI-->>User: transaction_id

    Note over User,ExchangeAPI: مرحله 4: مشاهده بازار
    User->>ExchangeAPI: GET /symbols
    ExchangeAPI-->>User: لیست نمادها

    User->>ExchangeAPI: GET /sessions
    ExchangeAPI-->>User: زمان‌های معاملاتی

    User->>ExchangeAPI: GET /tickers/BTC-IRR
    ExchangeAPI-->>User: قیمت فعلی

    Note over User,MatchingEngine: مرحله 5: ثبت سفارش
    User->>ExchangeAPI: POST /orders (سفارش خرید)
    ExchangeAPI->>MatchingEngine: ارسال سفارش
    MatchingEngine->>DB: ذخیره سفارش

    Note over MatchingEngine: مرحله 6: تطبیق سفارشات
    MatchingEngine->>MatchingEngine: جستجوی سفارش مطابق

    alt سفارش پیدا شد
        MatchingEngine->>DB: به‌روزرسانی سفارشات
        MatchingEngine->>DB: ایجاد معامله
        MatchingEngine-->>User: trade_id + status
    else سفارش پیدا نشد
        MatchingEngine-->>User: order_id + status: pending
    end

    Note over User,WalletAPI: مرحله 7: تسویه
    MatchingEngine->>WalletAPI: تسویه دارایی‌ها
    WalletAPI->>DB: به‌روزرسانی موجودی‌ها

    Note over User,ExchangeAPI: مرحله 8: مشاهده نتیجه
    User->>ExchangeAPI: GET /trades
    ExchangeAPI-->>User: لیست معاملات

موجودیت‌های اصلی (Entities)¶

1. User (کاربر)¶

User {
  uid: string
  username: string
  email: string
  role: string
  status: string
  created_at: datetime
  updated_at: datetime
}

ویژگی‌ها: - شناسه منحصر به فرد - اطلاعات هویتی - نقش (trader, admin, ...) - وضعیت (active, suspended, ...)

2. Wallet (کیف پول)¶

Wallet {
  uid: string
  user_id: string
  type: string
  currency: string
  balance: string
  hold: string
  available: string
  created_at: datetime
}

ویژگی‌ها: - موجودی کل: balance - موجودی در حال استفاده (hold): hold - موجودی قابل استفاده: available = balance - hold

3. Order (سفارش)¶

Order {
  uid: string
  user_id: string
  wallet_id: string
  symbol: string
  side: string
  type: string
  price: string
  quantity: string
  filled: string
  status: string
  created_at: datetime
}

ویژگی‌ها: - side: buy یا sell - type: limit, market, stop-limit, stop-market - filled: حجم پر شده - status: new, queued, active, partial, filled, cancelled, rejected, expired

4. Trade (معامله)¶

Trade {
  uid: string
  symbol: string
  price: string
  quantity: string
  maker_order_id: string
  taker_order_id: string
  maker_fee: string
  taker_fee: string
  status: string
  created_at: datetime
}

ویژگی‌ها: - نتیجه تطبیق دو سفارش - شامل کارمزد طرفین - وضعیت: pending, executed, failed

5. Symbol (نماد)¶

Symbol {
  uid: string
  symbol: string
  price_precision: integer
  quantity_precision: integer
  min_order_quantity: string
  tick_size: string
  daily_fluctuation_limit: string
  is_active: boolean
}

ویژگی‌ها: - تنظیمات دقت قیمت و حجم - محدودیت‌های معاملاتی - وضعیت فعال/غیرفعال

6. Session (جلسه معاملاتی)¶

Session {
  uid: string
  symbol: string
  open_at: datetime
  close_at: datetime
  opening_price: string
  price_tolerance_percentage: string
  broker_fee_percentage: string
  market_fee_percentage: string
}

ویژگی‌ها: - زمان‌های معاملاتی - تنظیمات کارمزد - محدودیت‌های نوسان

گردش کار سفارش (Order Flow)¶

نمودار چرخه عمر سفارش¶

stateDiagram-v2
    [*] --> New: کاربر ثبت می‌کند

    New --> Queued: در صف بررسی
    Queued --> Rejected: رد شد (مثلاً موجودی ناکافی)
    Queued --> Active: تایید شد

    Active --> Partial: بخشی پر شد
    Partial --> Partial: بخش دیگری پر شد
    Partial --> Filled: کامل پر شد

    Active --> Filled: کامل پر شد (سفارش مارکت)

    Active --> Cancelled: کاربر لغو کرد
    Partial --> Cancelled: کاربر لغو کرد

    Active --> Expired: منقضی شد
    Partial --> Expired: منقضی شد

    Rejected --> [*]
    Filled --> [*]
    Cancelled --> [*]
    Expired --> [*]

    note right of New: سفارش ایجاد شده
    note right of Queued: در انتظار بررسی
    note right of Active: در دفتر سفارشات
    note right of Partial: پر شده جزئی
    note right of Filled: پر شده کامل

مکانیزم تطبیق سفارشات (Matching Engine)¶

نمودار تطبیق¶

flowchart LR
    subgraph "دفتر سفارشات خرید (Bids)"
        B1[100M - 0.5 BTC]
        B2[99M - 0.3 BTC]
        B3[98M - 1.0 BTC]
    end

    subgraph "دفتر سفارشات فروش (Asks)"
        A1[101M - 0.4 BTC]
        A2[102M - 0.6 BTC]
        A3[103M - 0.8 BTC]
    end

    B1 -->|Match| A1
    B2 -->|No Match| A1

    style B1 fill:#d5e8d4
    style A1 fill:#d5e8d4
    style B2 fill:#fff2cc
    style A2 fill:#fff2cc

الگوریتم تطبیق¶

دریافت سفارش جدید
سفارش خرید: 100M، 0.5 BTC
سفارش فروش: 101M، 0.4 BTC
بررسی تطبیق
قیمت خرید (100M) < قیمت فروش (101M)
❌ تطبیق ندارد
افزودن به دفتر سفارشات
سفارش خرید به Bids اضافه می‌شود
سفارش فروش به Asks اضافه می‌شود
سفارش جدید
سفارش خرید: 102M، 0.3 BTC
تطبیق مجدد
قیمت خرید (102M) > قیمت فروش (101M)
✅ تطبیق دارد
انجام معامله
حجم معامله: min(0.3, 0.4) = 0.3 BTC
قیمت: 101M (قیمت سفارش فروش)
نتیجه: 0.3 BTC با قیمت 101M

انواع سفارشات¶

1. سفارش لیمیت (Limit Order)¶

User: می‌خواهم 0.5 BTC با قیمت 100M بخرم

رفتار: - در دفتر سفارشات قرار می‌گیرد - منتظر سفارش فروش با قیمت ≤ 100M - اگر پیدا نشود، باقی می‌ماند

استفاده: - کنترل قیمت - استراتژی‌های دقیق

2. سفارش مارکت (Market Order)¶

User: می‌خواهم 0.5 BTC با قیمت بازار بخرم

رفتار: - فوراً اجرا می‌شود - از بهترین قیمت موجود استفاده می‌کند - قیمت تضمین نمی‌شود

استفاده: - نیاز فوری - حجم کم

3. سفارش شرطی (Conditional Order)¶

User: اگر قیمت BTC به 105M رسید، 0.5 BTC بفروش

رفتار: - شرط نظارت می‌شود - فعال‌سازی خودکار - تبدیل به سفارش لیمیت/مارکت

استفاده: - استاپ لاس - بریک‌اوت

مدیریت ریسک¶

سیستم وثیقه (Escrow)¶

sequenceDiagram
    participant User
    participant System
    participant Wallet

    User->>System: ثبت سفارش (0.5 BTC)
    System->>Wallet: بررسی موجودی
    Wallet-->>System: موجودی کافی

    System->>Wallet: قفل 0.5 BTC (hold)
    Wallet-->>System: تایید قفل

    System->>User: سفارش فعال شد

    Note over System: اگر معامله انجام شد
    System->>Wallet: آزادسازی و تسویه

    Note over System: اگر لغو شد
    System->>Wallet: آزادسازی hold

محدودیت‌ها¶

1. حداقل حجم سفارش¶

min_order_quantity = 0.0001 BTC

- جلوگیری از سفارشات بی‌ارزش - کاهش بار سیستم

2. حداکثر حجم سفارش¶

max_order_quantity = 100 BTC

- مدیریت ریسک - جلوگیری از دستکاری

3. محدودیت نوسان قیمت¶

daily_fluctuation_limit = 5%

- جلوگیری از نوسان شدید - حفظ ثبات بازار

4. اندازه تیک (Tick Size)¶

tick_size = 1000 IRR

- قیمت‌ها مضربی از تیک - جلوگیری از اعشار ریز

کارمزدها (Fees)¶

ساختار کارمزد¶

Maker Fee: 0.1% (کسی که نقدینگی اضافه می‌کند)
Taker Fee: 0.2% (کسی که نقدینگی می‌گیرد)

محاسبه¶

# سفارش خرید: 0.5 BTC با قیمت 100M
quantity = 0.5
price = 100000000
maker_fee_rate = 0.001  # 0.1%
taker_fee_rate = 0.002  # 0.2%

# اگر سفارش در دفتر بود (Maker)
maker_fee = quantity * price * maker_fee_rate
# = 0.5 * 100M * 0.001 = 50,000 IRR

# اگر سفارش وارد شد و معامله کرد (Taker)
taker_fee = quantity * price * taker_fee_rate
# = 0.5 * 100M * 0.002 = 100,000 IRR

تفاوت Maker/Taker¶

Maker (سفارش در دفتر)¶

User: سفارش فروش 0.5 BTC با قیمت 100M
System: سفارش به دفتر اضافه شد
User: Maker است، کارمزد 0.1%

Taker (سفارش وارد شده)¶

User: سفارش خرید 0.5 BTC با قیمت بازار
System: سفارش با سفارش فروش موجود تطبیق داده شد
User: Taker است، کارمزد 0.2%

جریان تسویه (Settlement Flow)¶

نمودار تسویه¶

flowchart TD
    A[معامله انجام شد] --> B[محاسبه کارمزد]

    B --> C[کسر از خریدار]
    B --> D[کسر از فروشنده]

    C --> E[انتقال به فروشنده]
    D --> F[انتقال به صندوق کارمزد]

    E --> G[به‌روزرسانی کیف پول‌ها]
    F --> G

    G --> H[ثبت در تراکنش‌ها]
    H --> I[پایان]

    style A fill:#d5e8d4
    style I fill:#d5e8d4

مثال عددی¶

معامله: - 0.5 BTC با قیمت 100M IRR - کارمزد Maker: 0.1% - کارمزد Taker: 0.2%

تسویه:

خریدار (Taker):
- کیف پول IRR: -50,000,000 (قیمت)
- کیف پول IRR: -100,000 (کارمزد)
- کیف پول BTC: +0.5

فروشنده (Maker):
- کیف پول BTC: -0.5
- کیف پول IRR: +49,950,000 (قیمت - کارمزد)

مدیریت نقدینگی¶

منابع نقدینگی¶

کاربران عادی
سفارشات خرید/فروش
بازارسازان خودکار
بانک‌ها
ارائه نقدینگی عمده
بازارساز رسمی
سیستم خودکار
بازارساز الگوریتمی
تنظیم خودکار قیمت

تشویق نقدینگی¶

Maker Fee < Taker Fee
0.1% < 0.2%

این باعث می‌شود کاربران تشویق شوند سفارشات خود را در دفتر قرار دهند.

امنیت و نظارت¶

سیستم‌های نظارتی¶

flowchart TB
    A[معاملات] --> B[تشخیص الگو]
    B --> C{مشکوک؟}

    C -->|بله| D[هشدار]
    C -->|خیر| E[ادامه عادی]

    D --> F[بررسی دستی]
    F --> G{تخلف؟}

    G -->|بله| H[مسدودسازی]
    G -->|خیر| I[آزادسازی]

    style D fill:#ffcccc
    style H fill:#ff9999

موارد نظارتی¶

دستکاری قیمت
سفارشات پشت سر هم
حجم‌های غیرعادی
پولشویی
معاملات چرخشی
الگوهای مشکوک
دسترسی غیرمجاز
تلاش‌های متعدد
IPهای مشکوک

چرخه کامل یک معامله¶

سناریوی کامل¶

مرحله 1: کاربر A (فروشنده)
- ثبت سفارش فروش: 1 BTC @ 100M
- وضعیت: Queued → Active
- موجودی: 1 BTC قفل شد

مرحله 2: کاربر B (خریدار)
- ثبت سفارش خرید: 1 BTC @ 100M
- وضعیت: Queued → Active → Filled
- موجودی: 100M کسر شد

مرحله 3: Matching Engine
- تطبیق سفارشات
- ایجاد معامله: trade_123
- قیمت: 100M
- حجم: 1 BTC

مرحله 4: تسویه
- کارمزد Maker: 100,000 IRR (0.1%)
- کارمزد Taker: 200,000 IRR (0.2%)

مرحله 5: نتیجه
- کاربر A: 99,900,000 IRR (100M - 100k)
- کاربر B: 1 BTC
- صندوق کارمزد: 300,000 IRR

بهترین روش‌ها برای توسعه‌دهندگان¶

1. درک کامل گردش کار¶

قبل از کدنویسی، گردش کار را بفهمید
نمودارها را دنبال کنید

2. تست در محیط توسعه¶

سفارشات کوچک تست کنید
تمامی وضعیت‌ها را بررسی کنید

3. مدیریت خطاها¶

خطاهای احتمالی را پیش‌بینی کنید
retry logic اضافه کنید

4. امنیت¶

توکن‌ها را امن نگه دارید
درخواست‌ها را اعتبارسنجی کنید

5. لاگ‌گیری¶

تمامی درخواست‌ها و پاسخ‌ها را لاگ کنید
برای خطایابی

خلاصه¶

سیستم P2P: مستقیم بین کاربران
Matching Engine: تطبیق خودکار سفارشات
Escrow: تضمین امنیت معاملات
Maker/Taker: کارمزد متفاوت برای تشویق نقدینگی
تسویه: خودکار و شفاف

بعدی: مطالعه چرخه عمر سفارش