pacifica/specs/001-ts-pacifica-perp/data-model.md

Data Model: Pacifica Multi-Account BTC Wash Trading System

Date: 2024-12-29
Feature: Multi-account wash trading system for BTC pairs
Status: Complete

Core Entities

1. Account

Purpose: Represents a single trading account on Pacifica DEX

interface Account {
  id: string;                    // Unique account identifier
  name: string;                  // Human-readable account name
  apiKey: string;                // Pacifica API key (encrypted)
  privateKey: string;            // Private key for signing (encrypted)
  address: string;               // Wallet address
  balance: {
    total: number;               // Total account balance (USD)
    available: number;           // Available balance for trading
    used: number;                // Used balance (margin)
  };
  positions: Position[];         // Current positions
  riskLimits: RiskLimits;        // Account-specific risk limits
  isActive: boolean;             // Whether account is active for trading
  createdAt: Date;               // Account creation timestamp
  lastUpdated: Date;             // Last update timestamp
}

Validation Rules:

• id must be unique across all accounts
• apiKey and privateKey must be encrypted
• balance.total must be >= 0
• balance.available must be >= 0
• balance.used must be >= 0
• balance.total must equal balance.available + balance.used

State Transitions:

• inactive → active: Account enabled for trading
• active → inactive: Account disabled for trading
• active → suspended: Account suspended due to risk breach

2. WashTradingSession

Purpose: Represents a coordinated wash trading session across multiple accounts

interface WashTradingSession {
  id: string;                    // Unique session identifier
  name: string;                  // Human-readable session name
  strategy: TradingStrategy;     // Trading strategy configuration
  accounts: string[];            // Array of account IDs participating
  status: SessionStatus;         // Current session status
  targetVolume: number;          // Target volume to generate (BTC)
  currentVolume: number;         // Current volume generated (BTC)
  startTime: Date;               // Session start timestamp
  endTime?: Date;                // Session end timestamp (if completed)
  duration: number;              // Planned session duration (ms)
  orderPairs: OrderPair[];       // Generated order pairs
  riskMetrics: RiskMetrics;      // Current risk metrics
  auditLog: AuditEntry[];        // Audit trail
  createdAt: Date;               // Session creation timestamp
  updatedAt: Date;               // Last update timestamp
}

Validation Rules:

• id must be unique across all sessions
• accounts must contain at least 2 account IDs
• targetVolume must be > 0
• currentVolume must be >= 0
• duration must be > 0
• startTime must be <= endTime (if both present)

State Transitions:

• pending → active: Session started
• active → paused: Session paused
• paused → active: Session resumed
• active → completed: Session completed successfully
• active → failed: Session failed
• active → cancelled: Session cancelled

3. OrderPair

Purpose: Represents a matched buy and sell order across different accounts

interface OrderPair {
  id: string;                    // Unique order pair identifier
  sessionId: string;             // Parent session ID
  buyOrder: Order;               // Buy order details
  sellOrder: Order;              // Sell order details
  status: OrderPairStatus;       // Current order pair status
  volume: number;                // Order volume (BTC)
  price: number;                 // Order price (USD)
  expectedProfit: number;        // Expected profit from spread
  actualProfit: number;          // Actual profit realized
  fees: number;                  // Total fees paid
  slippage: number;              // Actual slippage experienced
  executionTime: number;         // Time to execute (ms)
  createdAt: Date;               // Order pair creation timestamp
  updatedAt: Date;               // Last update timestamp
}

Validation Rules:

• id must be unique across all order pairs
• buyOrder.accountId must differ from sellOrder.accountId
• volume must be > 0
• price must be > 0
• buyOrder.side must be 'buy'
• sellOrder.side must be 'sell'

State Transitions:

• pending → submitted: Orders submitted to exchange
• submitted → filled: Both orders filled successfully
• submitted → partial: One or both orders partially filled
• submitted → failed: One or both orders failed
• submitted → cancelled: Orders cancelled

4. Order

Purpose: Represents a single order on Pacifica DEX

interface Order {
  id: string;                    // Unique order identifier
  accountId: string;             // Account that placed the order
  pairId: string;                // Parent order pair ID
  symbol: string;                // Trading pair (e.g., 'BTC/USD')
  side: 'buy' | 'sell';         // Order side
  type: 'market' | 'limit';     // Order type
  size: number;                  // Order size (BTC)
  price?: number;                // Order price (for limit orders)
  status: OrderStatus;           // Current order status
  filledSize: number;            // Amount filled (BTC)
  averagePrice?: number;         // Average fill price
  fees: number;                  // Fees paid
  slippage: number;              // Slippage experienced
  pacificaOrderId?: string;      // Pacifica exchange order ID
  createdAt: Date;               // Order creation timestamp
  updatedAt: Date;               // Last update timestamp
}

Validation Rules:

• id must be unique across all orders
• size must be > 0
• price must be > 0 (for limit orders)
• filledSize must be >= 0 and <= size
• side must be either 'buy' or 'sell'
• type must be either 'market' or 'limit'

State Transitions:

• pending → submitted: Order submitted to exchange
• submitted → filled: Order completely filled
• submitted → partial: Order partially filled
• submitted → cancelled: Order cancelled
• submitted → failed: Order failed

5. TradingStrategy

Purpose: Defines how wash trading orders are generated and executed

interface TradingStrategy {
  id: string;                    // Unique strategy identifier
  name: string;                  // Human-readable strategy name
  type: StrategyType;            // Strategy type
  symbol: string;                // Trading pair (e.g., 'BTC/USD')
  parameters: {
    volumeDistribution: 'equal' | 'weighted' | 'random';
    priceRange: {
      min: number;               // Minimum price offset (%)
      max: number;               // Maximum price offset (%)
    };
    timing: {
      minInterval: number;       // Minimum interval between orders (ms)
      maxInterval: number;       // Maximum interval between orders (ms)
      orderSize: {
        min: number;             // Minimum order size (BTC)
        max: number;             // Maximum order size (BTC)
      };
    };
    riskLimits: {
      maxPositionSize: number;   // Maximum position size (% of balance)
      stopLossThreshold: number; // Stop loss threshold (%)
      maxSlippage: number;       // Maximum acceptable slippage (%)
    };
  };
  isActive: boolean;             // Whether strategy is active
  createdAt: Date;               // Strategy creation timestamp
  updatedAt: Date;               // Last update timestamp
}

Validation Rules:

• id must be unique across all strategies
• symbol must be a valid trading pair
• priceRange.min must be < priceRange.max
• timing.minInterval must be < timing.maxInterval
• timing.orderSize.min must be < timing.orderSize.max
• All percentage values must be between 0 and 100

6. RiskMetrics

Purpose: Tracks risk metrics for a trading session

interface RiskMetrics {
  sessionId: string;             // Parent session ID
  totalExposure: number;         // Total exposure across all accounts
  maxDrawdown: number;           // Maximum drawdown experienced
  currentDrawdown: number;       // Current drawdown
  sharpeRatio: number;           // Risk-adjusted return ratio
  volatility: number;            // Price volatility
  correlation: number;           // Correlation between accounts
  riskScore: number;             // Overall risk score (0-100)
  alerts: RiskAlert[];           // Active risk alerts
  lastUpdated: Date;             // Last update timestamp
}

Validation Rules:

• totalExposure must be >= 0
• maxDrawdown must be >= 0
• currentDrawdown must be >= 0
• riskScore must be between 0 and 100
• correlation must be between -1 and 1

7. RiskAlert

Purpose: Represents a risk management alert

interface RiskAlert {
  id: string;                    // Unique alert identifier
  sessionId: string;             // Parent session ID
  type: RiskAlertType;           // Alert type
  severity: 'low' | 'medium' | 'high' | 'critical';
  message: string;               // Alert message
  threshold: number;             // Threshold that was breached
  currentValue: number;          // Current value
  accountId?: string;            // Account ID (if account-specific)
  isAcknowledged: boolean;       // Whether alert was acknowledged
  createdAt: Date;               // Alert creation timestamp
  acknowledgedAt?: Date;         // Acknowledgment timestamp
}

Validation Rules:

• id must be unique across all alerts
• severity must be one of the defined levels
• message must not be empty
• threshold must be > 0
• currentValue must be >= 0

8. AuditEntry

Purpose: Represents an audit log entry for compliance and debugging

interface AuditEntry {
  id: string;                    // Unique audit entry identifier
  sessionId: string;             // Parent session ID
  action: string;                // Action performed
  details: any;                  // Action details
  accountId?: string;            // Account ID (if applicable)
  orderId?: string;              // Order ID (if applicable)
  timestamp: Date;               // Action timestamp
  userId?: string;               // User ID (if applicable)
}

Validation Rules:

• id must be unique across all audit entries
• action must not be empty
• timestamp must be valid date
• details must be serializable

Enums and Types

SessionStatus

type SessionStatus = 'pending' | 'active' | 'paused' | 'completed' | 'failed' | 'cancelled';

OrderPairStatus

type OrderPairStatus = 'pending' | 'submitted' | 'filled' | 'partial' | 'failed' | 'cancelled';

OrderStatus

type OrderStatus = 'pending' | 'submitted' | 'filled' | 'partial' | 'cancelled' | 'failed';

StrategyType

type StrategyType = 'equal_volume' | 'time_based' | 'market_making' | 'custom';

RiskAlertType

type RiskAlertType = 'position_size' | 'drawdown' | 'slippage' | 'margin' | 'correlation' | 'volatility';

Entity Relationships

Primary Relationships

• WashTradingSession → Account (many-to-many via accounts array)
• WashTradingSession → OrderPair (one-to-many)
• OrderPair → Order (one-to-many, exactly 2)
• Order → Account (many-to-one)
• WashTradingSession → TradingStrategy (many-to-one)
• WashTradingSession → RiskMetrics (one-to-one)
• RiskMetrics → RiskAlert (one-to-many)
• WashTradingSession → AuditEntry (one-to-many)

Data Flow

1. Session Creation: WashTradingSession created with strategy and accounts
2. Order Generation: Strategy generates OrderPair instances
3. Order Execution: Orders submitted to Pacifica DEX
4. Status Updates: Order and OrderPair statuses updated via WebSocket
5. Risk Monitoring: RiskMetrics updated continuously
6. Audit Logging: All actions logged in AuditEntry instances

Data Validation Rules

Cross-Entity Validation

• Account balance must be sufficient for order size
• Order pair must maintain position neutrality across accounts
• Session target volume must be achievable with available account balances
• Risk limits must be respected across all active sessions

Business Logic Validation

• Maximum 20 accounts per session
• Minimum 2 accounts per session
• Order pairs must be executed atomically
• Risk alerts must be acknowledged before session can continue
• All trading activities must be audited

Data Persistence Strategy

In-Memory Storage

• Active sessions and order pairs
• Real-time risk metrics
• WebSocket connection states
• Account balances and positions

Persistent Storage

• Account configurations (encrypted)
• Trading strategies
• Audit logs
• Session history
• Risk alert history

Data Cleanup

• In-memory data cleaned up when sessions end
• Audit logs retained for compliance (configurable retention period)
• Old sessions archived after completion
• Risk alerts archived after acknowledgment

Performance Considerations

Data Structure Optimization

• Use Maps for O(1) lookups by ID
• Use Sets for account membership checks
• Use arrays for ordered collections (order pairs, audit entries)
• Implement efficient filtering and sorting

Memory Management

• Limit in-memory session count
• Implement data pagination for large collections
• Use weak references where appropriate
• Monitor memory usage and implement cleanup

Query Optimization

• Index frequently queried fields
• Implement efficient filtering algorithms
• Use batch operations for bulk updates
• Cache frequently accessed data