DEX Parsers

Tested against 4,468 real transactions with 1,319 swaps extracted.

Base chain (EVM) support using viem for transaction parsing.

Hyperliquid perpetual futures parsing via REST API.

Parser Interface

All chain parsers implement the IChainParser interface:

interface IChainParser<TTransaction, TTrade> {
  readonly chain: ChainId;
  readonly marketType: 'spot' | 'perpetual';

  // Fetch transactions for an address
  fetchTransactions(address: string, options?: FetchOptions): Promise<TTransaction[]>;

  // Parse raw transaction to trade(s)
  parseTransaction(tx: TTransaction, address: string): TTrade[];

  // Get address balance
  getBalance(address: string, token?: string): Promise<bigint>;

  // Validate address format
  isValidAddress(address: string): boolean;

  // Normalize address to canonical form
  normalizeAddress(address: string): string;
}

Normalized Swap Output

interface NormalizedSwap {
  signature: string;
  timestamp: number;
  chain: 'solana' | 'base' | 'hyperliquid';
  venue: string;

  tokenIn: {
    mint: string;
    amount: bigint;
    decimals: number;
  };

  tokenOut: {
    mint: string;
    amount: bigint;
    decimals: number;
  };

  fee?: {
    amount: bigint;
    mint: string;
    recipient?: string;
  };

  bot?: {
    name: string;
    fee: bigint;
  };

  // MEV/Slippage detection
  mevLossUsd?: number;
  realisedSlippageBps?: number;
}

Bot Detection

Bot transactions are identified by fee recipients and source patterns:

Known Bot Patterns

const BOT_SOURCE_PATTERNS = {
  'BONKBOT': 'bonkbot',
  'TROJAN': 'trojan',
  'PHOTON': 'photon',
  'MAESTRO': 'maestro',
  'BULLX': 'bullx',
  'AXIOM': 'axiom',
  'BANANA': 'banana',
  'SOL_TRADING_BOT': 'sol_trading_bot',
};

MEV/Slippage Detection

The parser detects MEV attacks and calculates realized slippage:

• Sandwich detection - Identifies front-run + back-run patterns
• MEV loss calculation - USD value lost to MEV
• Slippage calculation - Actual vs expected execution price
• Severity classification - Low, Medium, High, Critical

Adding a New DEX

1. Create a new file in packages/parser/src/chains/{chain}/normalizers/
2. Implement the normalizer interface for that chain
3. Add to the normalizer registry in index.ts
4. Add tests for common transaction patterns
5. Update the venue enum in the database schema

File Structure

packages/parser/src/
├── chains/
│   ├── types.ts          # IChainParser interface
│   ├── factory.ts        # Parser factory
│   ├── solana/
│   │   ├── parser.ts
│   │   └── normalizers/
│   │       ├── jupiter.ts
│   │       ├── raydium.ts
│   │       ├── pumpfun.ts
│   │       ├── orca.ts
│   │       └── meteora.ts
│   ├── base/
│   │   ├── parser.ts
│   │   └── normalizers/
│   │       ├── uniswap-v2.ts
│   │       ├── uniswap-v3.ts
│   │       └── aerodrome.ts
│   └── hyperliquid/
│       ├── parser.ts
│       ├── client.ts
│       └── types.ts
├── cost-basis.ts
├── mev.ts
└── slippage.ts