@megatao/sdk 1.1.0

package/src/contracts/viem/AlphaViem.ts

@@ -0,0 +1,1615 @@
+/**
+ * Alpha contract wrapper using Viem
+ * Main implementation of ALPHA perpetual futures protocol
+ */
+
+import {
+  Address,
+  PublicClient,
+  WalletClient,
+  Hash,
+  TransactionReceipt,
+  parseEventLogs,
+  encodeFunctionData,
+} from 'viem';
+import { TransactionOptions } from '../../types';
+import * as AlphaTypes from '../../types/alpha';
+import AlphaABI from '../../abi/Alpha.json';
+
+export class AlphaViem {
+  private publicClient: PublicClient;
+  private walletClient?: WalletClient;
+  private contractAddress: Address;
+  private collateralTokenAddress?: Address;
+
+  constructor(
+    contractAddress: Address,
+    publicClient: PublicClient,
+    walletClient?: WalletClient,
+    collateralTokenAddress?: Address,
+  ) {
+    this.contractAddress = contractAddress;
+    this.publicClient = publicClient;
+    this.walletClient = walletClient;
+    this.collateralTokenAddress = collateralTokenAddress;
+  }
+
+  private get isNativeCollateral(): boolean {
+    return (
+      !this.collateralTokenAddress ||
+      this.collateralTokenAddress === '0x0000000000000000000000000000000000000000'
+    );
+  }
+
+  // ============ Utility Functions ============
+
+  /**
+   * Convert bytes32 (padded by ABI encoding) to bytes16
+   * Takes first 16 bytes from the 32 byte value
+   */
+  private bytes32ToBytes16(bytes32: string): `0x${string}` {
+    // Remove 0x prefix if present
+    const hex = bytes32.startsWith('0x') ? bytes32.slice(2) : bytes32;
+    // Take first 32 characters (16 bytes)
+    const bytes16Hex = hex.slice(0, 32);
+    return `0x${bytes16Hex}` as `0x${string}`;
+  }
+
+  /**
+   * Simulate a contract transaction before writing to catch errors early
+   * This prevents sending failed transactions to the wallet
+   */
+  private async simulateAndWriteContract<
+    T extends { functionName: string; args?: readonly unknown[] },
+  >(
+    writeParams: T & {
+      address: Address;
+      abi: typeof AlphaABI;
+      account: Address;
+      value?: bigint;
+    },
+  ): Promise<Hash> {
+    if (!this.walletClient) {
+      throw new Error('Wallet client required for write operations');
+    }
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    // Simulate the transaction first to catch errors early
+    try {
+      await this.publicClient.simulateContract({
+        address: writeParams.address,
+        abi: writeParams.abi,
+        functionName: writeParams.functionName,
+        args: writeParams.args,
+        account: this.walletClient.account.address,
+        value: writeParams.value,
+      });
+    } catch (simulationError: any) {
+      console.error('[simulateContract] Raw viem error:', simulationError);
+      let errorMessage = 'Transaction simulation failed';
+      let errorName: string | undefined;
+      let errorArgs: any[] | undefined;
+
+      // Walk the viem error chain to find decoded custom error data
+      for (let cur = simulationError; cur; cur = cur.cause) {
+        if (cur.data?.errorName) {
+          errorName = cur.data.errorName;
+          errorArgs = cur.data.args ? [...cur.data.args] : undefined;
+          errorMessage = errorName!;
+          if (errorArgs && errorArgs.length > 0) {
+            errorMessage += `: ${errorArgs
+              .map((arg: any) => (typeof arg === 'bigint' ? arg.toString() : String(arg)))
+              .join(', ')}`;
+          }
+          break;
+        }
+      }
+
+      // If no decoded error found, fall back to message extraction
+      if (!errorName) {
+        if (simulationError.cause?.shortMessage) {
+          errorMessage = simulationError.cause.shortMessage;
+        } else if (simulationError.shortMessage) {
+          errorMessage = simulationError.shortMessage;
+        } else if (simulationError.cause?.message) {
+          errorMessage = simulationError.cause.message;
+        } else if (simulationError.message) {
+          errorMessage = simulationError.message;
+        }
+      }
+
+      const error: any = new Error(errorMessage);
+      error.code = 'SIMULATION_FAILED';
+      error.cause = simulationError;
+      error.simulationError = true;
+      error.contractErrorName = errorName;
+      error.contractErrorArgs = errorArgs;
+      throw error;
+    }
+
+    // If simulation succeeds, proceed with the actual write
+    // Note: writeContract needs the full account object, not just the address
+    return await this.walletClient.writeContract({
+      ...writeParams,
+      account: this.walletClient.account,
+    } as any);
+  }
+
+  // ============ Admin Functions ============
+
+  async initializeMarket(
+    market: Address,
+    maxLeverage: bigint,
+    maintenanceMargin: bigint,
+    liquidationFee: bigint,
+    options?: TransactionOptions,
+  ): Promise<Hash> {
+    if (!this.walletClient) throw new Error('Wallet client required for write operations');
+
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.walletClient.writeContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'initializeMarket',
+      args: [market, maxLeverage, maintenanceMargin, liquidationFee],
+      account: this.walletClient.account,
+      ...txOptions,
+    } as any);
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  async addMarket(market: Address, symbol: string, options?: TransactionOptions): Promise<Hash> {
+    if (!this.walletClient) throw new Error('Wallet client required for write operations');
+
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.walletClient.writeContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'addMarket',
+      args: [market, symbol],
+      account: this.walletClient.account,
+      ...txOptions,
+    } as any);
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  async seedVault(amount: bigint, options?: TransactionOptions): Promise<Hash> {
+    if (!this.walletClient) throw new Error('Wallet client required for write operations');
+
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.walletClient.writeContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'seedVault',
+      args: [amount],
+      account: this.walletClient.account,
+      ...txOptions,
+    } as any);
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  // ============ Margin Management ============
+
+  async deposit(amount: bigint, options?: TransactionOptions): Promise<Hash> {
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient?.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.simulateAndWriteContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'deposit',
+      args: [amount],
+      account: this.walletClient.account.address,
+      ...(this.isNativeCollateral ? { value: amount } : {}),
+      ...txOptions,
+    });
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  async withdraw(amount: bigint, options?: TransactionOptions): Promise<Hash> {
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient?.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.simulateAndWriteContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'withdraw',
+      args: [amount],
+      account: this.walletClient.account.address,
+      ...txOptions,
+    });
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  // ============ Position Management ============
+
+  /**
+   * Opens a market position with specified margin, leverage, and slippage tolerance
+   * @param market - Market address
+   * @param isLong - True for long position, false for short
+   * @param margin - Collateral amount to risk (in wei)
+   * @param leverage - Leverage multiplier in 1e18 format (e.g., 3e18 for 3x)
+   * @param maxSlippage - Maximum allowed slippage in basis points
+   * @param options - Transaction options
+   * @returns Transaction hash
+   */
+  async openMarketPosition(
+    market: Address,
+    isLong: boolean,
+    margin: bigint,
+    leverage: bigint,
+    maxSlippage: bigint,
+    options?: TransactionOptions,
+  ): Promise<Hash> {
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient?.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    // Contract expects a single struct parameter: MarketPositionParams
+    const params = {
+      market,
+      isLong,
+      margin,
+      leverage,
+      maxSlippage,
+    };
+
+    const hash = await this.simulateAndWriteContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'openMarketPosition',
+      args: [params],
+      account: this.walletClient.account.address,
+      ...txOptions,
+    });
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  async openMarketPositionWithStruct(
+    params: AlphaTypes.MarketPositionParams,
+    options?: TransactionOptions,
+  ): Promise<Hash> {
+    if (!this.walletClient) throw new Error('Wallet client required for write operations');
+
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.walletClient.writeContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'openMarketPositionWithStruct',
+      args: [params],
+      account: this.walletClient.account,
+      ...txOptions,
+    } as any);
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  async closePosition(
+    positionId: AlphaTypes.Bytes16,
+    sizeToClose: bigint,
+    options?: TransactionOptions,
+  ): Promise<Hash> {
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient?.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.simulateAndWriteContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'closePosition',
+      args: [positionId, sizeToClose],
+      account: this.walletClient.account.address,
+      ...txOptions,
+    });
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  /**
+   * Batch multiple contract calls into a single transaction using multicall.
+   * Handles ABI encoding internally.
+   *
+   * @param calls - Array of { functionName, args } to batch
+   * @param options - Optional transaction options
+   * @returns Transaction hash
+   *
+   * @example
+   * // Close multiple positions in one tx
+   * await alpha.multicall([
+   *   { functionName: 'closePosition', args: [posId1, 0n] },
+   *   { functionName: 'closePosition', args: [posId2, 0n] },
+   * ]);
+   */
+  async multicall(
+    calls: { functionName: string; args?: readonly unknown[] }[],
+    options?: TransactionOptions,
+  ): Promise<Hash> {
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient?.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    if (calls.length === 0) {
+      throw new Error('No calls provided');
+    }
+
+    const calldata = calls.map((call) =>
+      encodeFunctionData({
+        abi: AlphaABI,
+        functionName: call.functionName,
+        args: call.args ?? [],
+      }),
+    );
+
+    const hash = await this.simulateAndWriteContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'multicall',
+      args: [calldata],
+      account: this.walletClient.account.address,
+      ...txOptions,
+    });
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+    }
+
+    return hash;
+  }
+
+  /**
+   * Close multiple positions in a single transaction using multicall
+   * @param positionIds - Array of position IDs to close (bytes16 format)
+   * @param options - Optional transaction options
+   * @returns Transaction hash
+   */
+  async closeAllPositions(
+    positionIds: AlphaTypes.Bytes16[],
+    options?: TransactionOptions,
+  ): Promise<Hash> {
+    if (positionIds.length === 0) {
+      throw new Error('No position IDs provided');
+    }
+
+    return this.multicall(
+      positionIds.map((positionId) => ({
+        functionName: 'closePosition',
+        args: [positionId, 0n],
+      })),
+      options,
+    );
+  }
+
+  // ============ Order Management ============
+
+  /**
+   * Places a limit order with specified margin and leverage
+   * @param market - Market address
+   * @param isBuy - True for buy order, false for sell
+   * @param margin - Collateral amount to risk
+   * @param leverage - Leverage multiplier in 1e18 format (e.g., 3e18 for 3x)
+   * @param price - Limit price in wei
+   * @param reduceOnlyType - 0=Normal, 1=TakeProfit (natural side), 2=StopLoss (opposite side)
+   * @param options - Transaction options
+   * @returns Transaction hash
+   */
+  async placeLimitOrder(
+    market: Address,
+    isBuy: boolean,
+    margin: bigint,
+    leverage: bigint,
+    price: bigint,
+    reduceOnlyType: number = 0,
+    options?: TransactionOptions,
+  ): Promise<Hash> {
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient?.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const params = {
+      market,
+      isBuy,
+      margin,
+      leverage,
+      price,
+      reduceOnlyType,
+    };
+
+    const hash = await this.simulateAndWriteContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'placeLimitOrder',
+      args: [params],
+      account: this.walletClient.account.address,
+      ...txOptions,
+    });
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  /**
+   * Places a limit order using a params struct
+   * @param params - LimitOrderParams struct containing all order parameters
+   * @param options - Transaction options
+   * @returns Transaction hash
+   */
+  async placeLimitOrderWithStruct(
+    params: AlphaTypes.LimitOrderParams,
+    options?: TransactionOptions,
+  ): Promise<Hash> {
+    return this.placeLimitOrder(
+      params.market,
+      params.isBuy,
+      params.margin,
+      params.leverage,
+      params.price,
+      params.reduceOnlyType,
+      options,
+    );
+  }
+
+  async cancelOrder(market: Address, orderId: AlphaTypes.Bytes16, options?: TransactionOptions): Promise<Hash> {
+    if (!this.walletClient) throw new Error('Wallet client required for write operations');
+
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.walletClient.writeContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'cancelOrder',
+      args: [market, orderId],
+      account: this.walletClient.account,
+      ...txOptions,
+    } as any);
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  async cancelAllOrders(market: Address, options?: TransactionOptions): Promise<Hash> {
+    if (!this.walletClient) throw new Error('Wallet client required for write operations');
+
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.walletClient.writeContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'cancelAllOrders',
+      args: [market],
+      account: this.walletClient.account,
+      ...txOptions,
+    } as any);
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  // ============ Liquidation Functions ============
+
+  async liquidatePosition(
+    positionId: AlphaTypes.Bytes16,
+    options?: TransactionOptions,
+  ): Promise<Hash> {
+    if (!this.walletClient) throw new Error('Wallet client required for write operations');
+
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.walletClient.writeContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'liquidatePosition',
+      args: [positionId],
+      account: this.walletClient.account,
+      ...txOptions,
+    } as any);
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  async claimKeeperRewards(options?: TransactionOptions): Promise<Hash> {
+    if (!this.walletClient) throw new Error('Wallet client required for write operations');
+
+    const { waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.walletClient.writeContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'claimKeeperRewards',
+      args: [],
+      account: this.walletClient.account,
+      ...txOptions,
+    } as any);
+
+    if (waitForConfirmation) {
+      await this.publicClient.waitForTransactionReceipt({ hash });
+      return hash;
+    }
+
+    return hash;
+  }
+
+  // ============ View Functions - Positions ============
+
+  async getPositionId(trader: Address, market: Address): Promise<AlphaTypes.Bytes16> {
+    const result = await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getPositionId',
+      args: [trader, market],
+    });
+    // Convert bytes32 (padded) to bytes16
+    return this.bytes32ToBytes16(result as string) as AlphaTypes.Bytes16;
+  }
+
+  async hasPosition(trader: Address, market: Address): Promise<boolean> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'hasPosition',
+      args: [trader, market],
+    })) as boolean;
+  }
+
+  async getPosition(positionId: AlphaTypes.Bytes16): Promise<AlphaTypes.MonolithPosition> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getPosition',
+      args: [positionId],
+    })) as any[];
+
+    // Ensure values are BigInt for calculations
+    const notionalValue = BigInt(result[3]);
+    const margin = BigInt(result[4]);
+
+    return {
+      // Based on ABI: [0] owner, [1] market, [2] isLong, [3] notionalValue, [4] margin, [5] entryPrice, [6] fundingIndex, [7] lastUpdateTime
+      notionalValue: result[3],
+      margin: result[4],
+      entryPrice: result[5],
+      isLong: result[2],
+      lastUpdated: result[7], // Maps from contract's lastUpdateTime
+      fundingIndex: result[6],
+      leverage: margin > 0n ? (notionalValue * 1000000000000000000n) / margin : 0n, // Calculate leverage in 1e18 format (notionalValue/margin * 1e18)
+      liquidationPrice: 0n, // Not returned by ABI - would need separate calculation
+    };
+  }
+
+  async getPositionDetails(positionId: AlphaTypes.Bytes16): Promise<AlphaTypes.PositionDetails> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getPositionDetails',
+      args: [positionId],
+    })) as AlphaTypes.PositionDetails;
+  }
+
+  async getUserPositions(trader: Address): Promise<AlphaTypes.Bytes16[]> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getUserPositions',
+      args: [trader],
+    })) as string[];
+    // Convert each bytes32 (padded) to bytes16
+    return result.map((id) => this.bytes32ToBytes16(id) as AlphaTypes.Bytes16);
+  }
+
+  async getUserPositionsSummary(trader: Address): Promise<AlphaTypes.PositionSummary> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getUserPositionsSummary',
+      args: [trader],
+    })) as any[];
+    return {
+      totalPositions: result[0],
+      totalMargin: result[1],
+      totalUnrealizedPnl: result[2],
+      totalSize: result[3],
+    };
+  }
+
+  async calculateUnrealizedPnl(positionId: AlphaTypes.Bytes16): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'calculateUnrealizedPnl',
+      args: [positionId],
+    })) as bigint;
+  }
+
+  async getMarginRatio(positionId: AlphaTypes.Bytes16): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getMarginRatio',
+      args: [positionId],
+    })) as bigint;
+  }
+
+  async isLiquidatable(positionId: AlphaTypes.Bytes16): Promise<boolean> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'isLiquidatable',
+      args: [positionId],
+    })) as boolean;
+  }
+
+  async getLiquidationStatus(
+    positionId: AlphaTypes.Bytes16,
+  ): Promise<AlphaTypes.LiquidationStatus> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getLiquidationStatus',
+      args: [positionId],
+    })) as any[];
+    return {
+      isLiquidatable: result[0],
+      marginRatio: result[1],
+      requiredMargin: result[2],
+      liquidationPrice: result[3],
+    };
+  }
+
+  /**
+   * Get account-level liquidation status (cross-margin)
+   * When account equity < total maintenance, ALL positions are liquidatable (Hyperliquid-style)
+   */
+  async getAccountLiquidationStatus(
+    trader: Address,
+  ): Promise<{
+    liquidatable: boolean;
+    worstPositionId: AlphaTypes.Bytes16;
+    accountEquity: bigint;
+    totalMaintenanceRequired: bigint;
+  }> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getAccountLiquidationStatus',
+      args: [trader],
+    })) as any[];
+    return {
+      liquidatable: result[0],
+      worstPositionId: result[1] as AlphaTypes.Bytes16,
+      accountEquity: result[2],
+      totalMaintenanceRequired: result[3],
+    };
+  }
+
+  /**
+   * Get cross-margin liquidation price for a position
+   * Uses Hyperliquid formula: accounts for all positions' PnL in the account
+   */
+  async getAccountLiquidationPrice(positionId: AlphaTypes.Bytes16): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getAccountLiquidationPrice',
+      args: [positionId],
+    })) as bigint;
+  }
+
+  // ============ View Functions - Margin ============
+
+  /**
+   * Get raw deposited margin balance (excludes unrealized PnL).
+   * For account equity (balance + PnL), use getAccountSummary().
+   */
+  async getMarginBalance(trader: Address): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getMarginBalance',
+      args: [trader],
+    })) as bigint;
+  }
+
+  /**
+   * Get comprehensive account summary in a single RPC call.
+   * Returns deposited balance, account equity, unrealized PnL, locked margin, and available margin.
+   */
+  async getAccountSummary(trader: Address): Promise<AlphaTypes.AccountSummary> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getAccountSummary',
+      args: [trader],
+    })) as any;
+    return {
+      depositedBalance: result.depositedBalance ?? result[0],
+      accountEquity: result.accountEquity ?? result[1],
+      unrealizedPnl: result.unrealizedPnl ?? result[2],
+      lockedMargin: result.lockedMargin ?? result[3],
+      availableMargin: result.availableMargin ?? result[4],
+    };
+  }
+
+  async getLockedMargin(trader: Address): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getLockedMargin',
+      args: [trader],
+    })) as bigint;
+  }
+
+  async getAvailableMargin(trader: Address): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getAvailableMargin',
+      args: [trader],
+    })) as bigint;
+  }
+
+  async getMaxUserDeposit(): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getMaxUserDeposit',
+      args: [],
+    })) as bigint;
+  }
+
+  async getMaxGlobalDeposits(): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getMaxGlobalDeposits',
+      args: [],
+    })) as bigint;
+  }
+
+  async getTotalDeposits(): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getTotalDeposits',
+      args: [],
+    })) as bigint;
+  }
+
+  // ============ View Functions - Markets ============
+
+  async getMarketInfo(market: Address): Promise<AlphaTypes.MarketInfo> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getMarketInfo',
+      args: [market],
+    })) as any[];
+
+    if (!result || !Array.isArray(result) || result.length < 8) {
+      throw new Error(
+        `Invalid market info response for market ${market}. ` +
+          `Expected array with 8 elements, got: ${JSON.stringify(result)}`,
+      );
+    }
+
+    return {
+      longOpenInterest: result[0],
+      shortOpenInterest: result[1],
+      fundingRate: result[2],
+      lastFundingUpdate: result[3],
+      isActive: result[4],
+      maxLeverage: result[5],
+      maintenanceMargin: result[6],
+      liquidationFee: result[7],
+    };
+  }
+
+  async getMarketOpenInterest(market: Address): Promise<{ longOI: bigint; shortOI: bigint }> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getMarketOpenInterest',
+      args: [market],
+    })) as any[];
+    return {
+      longOI: result[0],
+      shortOI: result[1],
+    };
+  }
+
+  async getFundingRate(market: Address): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getFundingRate',
+      args: [market],
+    })) as bigint;
+  }
+
+  async getFundingState(market: Address): Promise<AlphaTypes.FundingState> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getFundingState',
+      args: [market],
+    })) as any[];
+
+    // Based on ABI, getFundingState returns:
+    // [0] currentRate (int256), [1] cumulativeIndex (int256), [2] lastUpdate (uint256)
+    const lastUpdateTime = result[2] !== undefined ? BigInt(result[2]) : 0n;
+
+    return {
+      fundingRate: result[0] || 0n,
+      fundingIndex: result[1] || 0n,
+      lastUpdateTime: result[2] || 0n,
+      nextFundingTime: lastUpdateTime + 8n * 3600n, // Add 8 hours to lastUpdate
+    };
+  }
+
+  // ============ Funding Rate Updates (Keeper Function) ============
+
+  async updateFundingRates(
+    markets: Address[],
+    options?: TransactionOptions,
+  ): Promise<{
+    hash: Hash;
+    wait: () => Promise<TransactionReceipt>;
+  }> {
+    if (!this.walletClient) throw new Error('Wallet client required for write operations');
+
+    const { waitForConfirmation: _waitForConfirmation, ...txOptions } = options || {};
+
+    if (!this.walletClient.account) {
+      throw new Error('Wallet client must have an account for transactions');
+    }
+
+    const hash = await this.walletClient.writeContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'updateFundingRates',
+      args: [markets],
+      account: this.walletClient.account,
+      ...txOptions,
+    } as any);
+
+    return {
+      hash,
+      wait: async () => {
+        const receipt = await this.publicClient.waitForTransactionReceipt({ hash });
+        return receipt;
+      },
+    };
+  }
+
+  // ============ View Functions - Orders ============
+
+  async getBestBid(market: Address): Promise<AlphaTypes.Bytes16> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getBestBid',
+      args: [market],
+    })) as AlphaTypes.Bytes16;
+  }
+
+  async getBestAsk(market: Address): Promise<AlphaTypes.Bytes16> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getBestAsk',
+      args: [market],
+    })) as AlphaTypes.Bytes16;
+  }
+
+  /**
+   * Get all open order IDs for a trader in a specific market
+   * @param trader - Trader address
+   * @param market - Market address
+   * @returns Array of order IDs (bytes16)
+   */
+  async getUserOrders(trader: Address, market: Address): Promise<AlphaTypes.Bytes16[]> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getUserOrders',
+      args: [trader, market],
+    })) as string[];
+    // Convert each bytes32 (padded) to bytes16
+    return result.map((id) => this.bytes32ToBytes16(id) as AlphaTypes.Bytes16);
+  }
+
+  /**
+   * Get details of a specific order
+   * @param market - The market address
+   * @param orderId - The order ID (bytes16)
+   * @returns Order details including trader, direction, size, price, reduceOnly
+   */
+  async getOrderDetails(market: Address, orderId: AlphaTypes.Bytes16): Promise<AlphaTypes.OrderDetails> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getOrderDetails',
+      args: [market, orderId],
+    })) as any;
+
+    // Contract returns a struct with: trader, isLong, notionalValue, price, reduceOnly, next, prev
+    return {
+      trader: result.trader,
+      isLong: result.isLong,
+      notionalValue: result.notionalValue,
+      price: result.price,
+      reduceOnly: result.reduceOnly,
+      next: result.next,
+      prev: result.prev,
+    };
+  }
+
+  // ============ View Functions - Vault ============
+
+  async getVaultStats(): Promise<AlphaTypes.VaultStats> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getVaultStats',
+      args: [],
+    })) as any[];
+    return {
+      totalReserves: result[0],
+      availableReserves: result[1],
+      totalExposure: result[2],
+      unrealizedPnl: result[3],
+    };
+  }
+
+  async getVaultBalance(): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getVaultBalance',
+      args: [],
+    })) as bigint;
+  }
+
+  async getVaultState(): Promise<AlphaTypes.VaultState> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getVaultState',
+      args: [],
+    })) as AlphaTypes.VaultState;
+  }
+
+  async getVaultExposure(market: Address): Promise<AlphaTypes.VaultExposure> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getVaultExposure',
+      args: [market],
+    })) as any[];
+    return {
+      longExposure: result[0],
+      shortExposure: result[1],
+      netExposure: result[2],
+      utilizationRate: result[3],
+    };
+  }
+
+  // ============ View Functions - Protocol Limits ============
+
+  async getMaxPositionSize(market: Address): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getMaxPositionSize',
+      args: [market],
+    })) as bigint;
+  }
+
+  // ============ View Functions - Execution Analysis ============
+
+  async calculateVaultSlippage(market: Address, size: bigint, isBuy: boolean): Promise<bigint> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'calculateVaultSlippage',
+      args: [market, size, isBuy],
+    })) as bigint;
+  }
+
+  async getOptimalExecutionPlan(
+    market: Address,
+    size: bigint,
+    isLong: boolean,
+    maxSlippage: bigint,
+  ): Promise<AlphaTypes.ExecutionPlan> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getOptimalExecutionPlan',
+      args: [market, size, isLong, maxSlippage],
+    })) as AlphaTypes.ExecutionPlan;
+  }
+
+  async getExecutionStrategyAnalysis(
+    market: Address,
+    size: bigint,
+    isLong: boolean,
+    maxSlippage: bigint,
+  ): Promise<AlphaTypes.ExecutionStrategyAnalysis> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getExecutionStrategyAnalysisStruct',
+      args: [market, size, isLong, maxSlippage],
+    })) as AlphaTypes.ExecutionStrategyAnalysis;
+  }
+
+  // ============ View Functions - Market Depth ============
+
+  async getMarketDepth(
+    market: Address,
+    isBuy: boolean,
+    levels: bigint,
+  ): Promise<{ depth: AlphaTypes.DepthLevel[]; totalLiquidity: bigint }> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getMarketDepth',
+      args: [market, isBuy, levels],
+    })) as any[];
+    return {
+      depth: result[0],
+      totalLiquidity: result[1],
+    };
+  }
+
+  async getOrderbookDepth(
+    market: Address,
+    levels: number,
+  ): Promise<{ bidPrices: bigint[]; bidNotionals: bigint[]; askPrices: bigint[]; askNotionals: bigint[] }> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getOrderbookDepth',
+      args: [market, levels],
+    })) as [bigint[], bigint[], bigint[], bigint[]];
+    return {
+      bidPrices: result[0],
+      bidNotionals: result[1],
+      askPrices: result[2],
+      askNotionals: result[3],
+    };
+  }
+
+  async getVWAP(market: Address, size: bigint, isBuy: boolean): Promise<AlphaTypes.VWAPResult> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getVWAP',
+      args: [market, size, isBuy],
+    })) as AlphaTypes.VWAPResult;
+  }
+
+  async getBidAskSpread(market: Address): Promise<AlphaTypes.SpreadInfo> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getBidAskSpread',
+      args: [market],
+    })) as AlphaTypes.SpreadInfo;
+  }
+
+  async estimateMarketImpact(
+    market: Address,
+    size: bigint,
+    isBuy: boolean,
+  ): Promise<AlphaTypes.MarketImpactEstimate> {
+    const result = (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'estimateMarketImpact',
+      args: [market, size, isBuy],
+    })) as any[];
+    return {
+      averagePrice: result[0],
+      worstPrice: result[1],
+      priceImpact: result[2],
+      filledFromOrderbook: result[3],
+    };
+  }
+
+  async getMarketLiquidityAnalysis(market: Address): Promise<AlphaTypes.MarketLiquidityAnalysis> {
+    return (await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName: 'getMarketLiquidityAnalysisStruct',
+      args: [market],
+    })) as AlphaTypes.MarketLiquidityAnalysis;
+  }
+
+  // ============ Event Parsing ============
+
+  parsePositionOpenedEvent(
+    receipt: TransactionReceipt,
+  ): AlphaTypes.PositionOpenedEvent | undefined {
+    const logs = parseEventLogs({
+      abi: AlphaABI,
+      logs: receipt.logs,
+      eventName: 'PositionOpened',
+    });
+
+    if (logs.length > 0) {
+      const event = logs[0] as any;
+      // Convert bytes32 (padded) back to bytes16
+      const positionId = this.bytes32ToBytes16(event.args.positionId);
+      return {
+        positionId: positionId,
+        trader: event.args.trader,
+        market: event.args.market,
+        isLong: event.args.isLong,
+        notionalValue: event.args.notionalValue,
+        margin: event.args.margin,
+      };
+    }
+    return undefined;
+  }
+
+  parsePositionClosedEvent(
+    receipt: TransactionReceipt,
+  ): AlphaTypes.PositionClosedEvent | undefined {
+    const logs = parseEventLogs({
+      abi: AlphaABI,
+      logs: receipt.logs,
+      eventName: 'PositionClosed',
+    });
+
+    if (logs.length > 0) {
+      const event = logs[0] as any;
+      // Convert bytes32 (padded) back to bytes16
+      const positionId = this.bytes32ToBytes16(event.args.positionId);
+      return {
+        positionId: positionId,
+        trader: event.args.trader,
+        pnl: event.args.pnl,
+      };
+    }
+    return undefined;
+  }
+
+  parseOrderPlacedEvent(receipt: TransactionReceipt): AlphaTypes.OrderPlacedEvent | undefined {
+    const logs = parseEventLogs({
+      abi: AlphaABI,
+      logs: receipt.logs,
+      eventName: 'OrderPlaced',
+    });
+
+    if (logs.length > 0) {
+      const event = logs[0] as any;
+      return {
+        orderId: event.args.orderId,
+        trader: event.args.trader,
+        market: event.args.market,
+        isBuy: event.args.isBuy,
+        notionalValue: event.args.notionalValue,
+        price: event.args.price,
+      };
+    }
+    return undefined;
+  }
+
+  parseHybridOrderExecutedEvent(
+    receipt: TransactionReceipt,
+  ): AlphaTypes.HybridOrderExecutedEvent | undefined {
+    const logs = parseEventLogs({
+      abi: AlphaABI,
+      logs: receipt.logs,
+      eventName: 'HybridOrderExecuted',
+    });
+
+    if (logs.length > 0) {
+      const event = logs[0] as any;
+      return {
+        trader: event.args.trader,
+        market: event.args.market,
+        orderbookFilled: event.args.orderbookFilled,
+        vaultFilled: event.args.vaultFilled,
+        avgPrice: event.args.avgPrice,
+      };
+    }
+    return undefined;
+  }
+
+  // ============ Helper Functions ============
+
+  async waitForTransaction(hash: Hash): Promise<TransactionReceipt> {
+    return this.publicClient.waitForTransactionReceipt({ hash });
+  }
+
+  getContractAddress(): Address {
+    return this.contractAddress;
+  }
+
+  // Generic readContract method for custom function calls
+  async readContract({ functionName, args }: { functionName: string; args: any[] }): Promise<any> {
+    return await this.publicClient.readContract({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName,
+      args,
+    });
+  }
+
+  async getConstants(): Promise<AlphaTypes.MonolithConfig> {
+    const [
+      precision,
+      basisPoints,
+      maxLeverage,
+      defaultLeverage,
+      minPositionSize,
+      liquidationThreshold,
+      partialLiquidationThreshold,
+      liquidationFee,
+      fundingInterval,
+      maxFundingRate,
+      maxExposurePerAsset,
+      maxTotalUtilization,
+      criticalUtilizationBps,
+      maxLossRateBps,
+      maxLiquidationsPerBlock,
+    ] = await Promise.all([
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'PRECISION',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'BASIS_POINTS',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'MAX_LEVERAGE',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'DEFAULT_LEVERAGE',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'MIN_POSITION_SIZE',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'LIQUIDATION_THRESHOLD',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'PARTIAL_LIQUIDATION_THRESHOLD',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'LIQUIDATION_FEE',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'FUNDING_INTERVAL',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'MAX_FUNDING_RATE',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'MAX_EXPOSURE_PER_ASSET',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'MAX_TOTAL_UTILIZATION',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'CRITICAL_UTILIZATION_BPS',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'MAX_LOSS_RATE_BPS',
+        args: [],
+      }) as Promise<bigint>,
+      this.publicClient.readContract({
+        address: this.contractAddress,
+        abi: AlphaABI,
+        functionName: 'MAX_LIQUIDATIONS_PER_BLOCK',
+        args: [],
+      }) as Promise<bigint>,
+    ]);
+
+    return {
+      precision,
+      basisPoints,
+      maxLeverage,
+      defaultLeverage,
+      minPositionSize,
+      liquidationThreshold,
+      partialLiquidationThreshold,
+      liquidationFee,
+      fundingInterval,
+      maxFundingRate,
+      maxExposurePerAsset,
+      maxTotalUtilization,
+      criticalUtilizationBps,
+      maxLossRateBps,
+      maxLiquidationsPerBlock,
+    };
+  }
+
+  // Event watching methods
+
+  /**
+   * Watch for MarginDeposited events
+   */
+  watchMarginDepositedEvent(callback: (trader: Address, amount: bigint) => void) {
+    return this.publicClient.watchContractEvent({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      eventName: 'MarginDeposited',
+      onLogs: (logs) => {
+        for (const log of logs) {
+          const { trader, amount } = (log as any).args as { trader: Address; amount: bigint };
+          callback(trader, amount);
+        }
+      },
+    });
+  }
+
+  /**
+   * Watch for MarginWithdrawn events
+   */
+  watchMarginWithdrawnEvent(callback: (trader: Address, amount: bigint) => void) {
+    return this.publicClient.watchContractEvent({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      eventName: 'MarginWithdrawn',
+      onLogs: (logs) => {
+        for (const log of logs) {
+          const { trader, amount } = (log as any).args as { trader: Address; amount: bigint };
+          callback(trader, amount);
+        }
+      },
+    });
+  }
+
+  /**
+   * Watch for PositionOpened events
+   */
+  watchPositionOpenedEvent(
+    callback: (
+      positionId: `0x${string}`,
+      trader: Address,
+      market: Address,
+      isLong: boolean,
+      notionalValue: bigint,
+      entryPrice: bigint,
+      margin: bigint,
+    ) => void,
+  ) {
+    return this.publicClient.watchContractEvent({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      eventName: 'PositionOpened',
+      onLogs: (logs) => {
+        for (const log of logs) {
+          const { positionId, trader, market, isLong, notionalValue, entryPrice, margin } = (
+            log as any
+          ).args as any;
+          callback(positionId, trader, market, isLong, notionalValue, entryPrice, margin);
+        }
+      },
+    });
+  }
+
+  /**
+   * Get past MarginDeposited events
+   */
+  async getMarginDepositedEvents(fromBlock?: bigint, toBlock?: bigint, trader?: Address) {
+    return await this.publicClient.getContractEvents({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      eventName: 'MarginDeposited',
+      fromBlock: fromBlock || 'earliest',
+      toBlock: toBlock || 'latest',
+      args: trader ? { trader } : undefined,
+    });
+  }
+
+  /**
+   * Get past MarginWithdrawn events
+   */
+  async getMarginWithdrawnEvents(fromBlock?: bigint, toBlock?: bigint, trader?: Address) {
+    return await this.publicClient.getContractEvents({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      eventName: 'MarginWithdrawn',
+      fromBlock: fromBlock || 'earliest',
+      toBlock: toBlock || 'latest',
+      args: trader ? { trader } : undefined,
+    });
+  }
+
+  /**
+   * Get past PositionOpened events
+   */
+  async getPositionOpenedEvents(fromBlock?: bigint, toBlock?: bigint, trader?: Address) {
+    return await this.publicClient.getContractEvents({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      eventName: 'PositionOpened',
+      fromBlock: fromBlock || 'earliest',
+      toBlock: toBlock || 'latest',
+      args: trader ? { trader } : undefined,
+    });
+  }
+
+  /**
+   * Estimate gas for a transaction
+   */
+  async estimateGas(
+    functionName: string,
+    args: any[],
+    options?: TransactionOptions,
+  ): Promise<bigint> {
+    if (!this.walletClient) {
+      throw new Error('Wallet client is required for gas estimation');
+    }
+
+    const { gasPrice: _gasPrice, waitForConfirmation: _waitForConfirmation, ...estimateOptions } = options || {};
+
+    return await this.publicClient.estimateContractGas({
+      address: this.contractAddress,
+      abi: AlphaABI,
+      functionName,
+      args,
+      account: this.walletClient.account,
+      ...estimateOptions,
+    });
+  }
+}