TCPDashboard/docs/modules/transformation.md

Transformation Module

Purpose

The transformation module provides safe and standardized data transformation utilities for crypto trading operations, with built-in safety limits and validations to prevent errors and protect against edge cases.

Architecture

The module is organized into several submodules:

safety.py

Provides safety limits and validations for trading operations:

• Trade size limits (min/max)
• Price deviation checks
• Symbol format validation
• Stablecoin-specific rules

trade.py

Handles trade data transformation with comprehensive safety checks:

• Trade side normalization
• Size and price validation
• Symbol validation
• Market price deviation checks

Safety Limits

Default Limits

DEFAULT_LIMITS = TradeLimits(
    min_size=Decimal('0.00000001'),  # 1 satoshi
    max_size=Decimal('10000.0'),     # 10K units
    min_notional=Decimal('1.0'),     # Min $1
    max_notional=Decimal('10000000.0'),  # Max $10M
    price_precision=8,
    size_precision=8,
    max_price_deviation=Decimal('30.0')  # 30%
)

Stablecoin Pairs

STABLECOIN_LIMITS = DEFAULT_LIMITS._replace(
    max_size=Decimal('1000000.0'),      # 1M units
    max_notional=Decimal('50000000.0'),  # $50M
    max_price_deviation=Decimal('5.0')   # 5%
)

Volatile Pairs

VOLATILE_LIMITS = DEFAULT_LIMITS._replace(
    max_size=Decimal('1000.0'),         # 1K units
    max_notional=Decimal('1000000.0'),  # $1M
    max_price_deviation=Decimal('50.0')  # 50%
)

Usage Examples

Basic Trade Transformation

from data.common.transformation.trade import TradeTransformer

# Initialize transformer
transformer = TradeTransformer()

# Transform trade data
trade_data = {
    'symbol': 'BTC-USDT',
    'side': 'buy',
    'size': '1.5',
    'price': '50000'
}

try:
    transformed = transformer.transform_trade(trade_data)
    print(f"Transformed trade: {transformed}")
except ValueError as e:
    print(f"Validation error: {e}")

With Market Price Validation

from data.common.transformation.trade import TradeTransformer
from your_market_data_provider import MarketDataProvider

# Initialize with market data for price deviation checks
transformer = TradeTransformer(
    market_data_provider=MarketDataProvider()
)

# Transform with price validation
try:
    transformed = transformer.transform_trade({
        'symbol': 'ETH-USDT',
        'side': 'sell',
        'size': '10',
        'price': '2000'
    })
    print(f"Transformed trade: {transformed}")
except ValueError as e:
    print(f"Validation error: {e}")

Error Handling

The module uses explicit error handling with descriptive messages:

try:
    transformed = transformer.transform_trade(trade_data)
except ValueError as e:
    if "below minimum" in str(e):
        # Handle size too small
        pass
    elif "exceeds maximum" in str(e):
        # Handle size too large
        pass
    elif "deviation" in str(e):
        # Handle price deviation too large
        pass
    else:
        # Handle other validation errors
        pass

Logging

The module integrates with Python's logging system for monitoring and debugging:

import logging

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# Transformer will log warnings when approaching limits
transformer = TradeTransformer()

Testing

Run the test suite:

uv run pytest tests/common/transformation/test_safety.py -v

Key test areas:

• Trade size validation
• Price deviation checks
• Symbol format validation
• Stablecoin detection
• Edge case handling

Dependencies

• Internal:
  • data.common.types
  • data.common.validation
• External:
  • Python's decimal module
  • Python's logging module

Known Limitations

• Market price validation requires a market data provider
• Stablecoin detection is based on a predefined list
• Price deviation checks are percentage-based only