# @0xmonaco/types

Core type definitions for the Monaco protocol. This package provides TypeScript types and interfaces used throughout the Monaco ecosystem, focusing on SDK configuration, vault operations, trading operations, market data, and contract management.

## Installation

```bash
npm install @0xmonaco/types
```

**Note:** This package is typically installed as a dependency of `@0xmonaco/core` or `@0xmonaco/react`, but you can install it directly for type definitions in your TypeScript project.

## Type Categories

### SDK Types

Core SDK configuration and main interface types:

```typescript
import { MonacoSDK, SDKConfig } from "@0xmonaco/types";

// SDK configuration
interface SDKConfig {
  walletClient?: WalletClient; // Wallet client for signing operations
  network: Network; // Network preset: "local", "development", "staging", or "mainnet"
  seiRpcUrl: string; // RPC URL for Sei blockchain interactions
}

// Main SDK interface
interface MonacoSDK {
  applications: ApplicationsAPI; // Applications operations API
  auth: AuthAPI; // Auth operations API
  vault: VaultAPI; // Vault operations API
  trading: TradingAPI; // Trading operations API
  market: MarketAPI; // Market metadata API
  profile: ProfileAPI; // Profile operations API
  websocket: {
    orders: OrdersWebSocketClient; // WebSocket client for real-time order events
    ohlcv: OHLCVWebSocketClient; // WebSocket client for real-time OHLCV data
    orderbook: OrderbookWebSocketClient; // WebSocket client for real-time orderbook updates
  };
  walletClient: WalletClient; // Wallet client for blockchain operations
  publicClient: PublicClient; // Public client for read-only operations

  // Authentication
  login(clientId: string, options?: { connectWebSocket?: boolean }): Promise<AuthState>;
  logout(): Promise<void>;
  refreshAuth(): Promise<AuthState>;
  getAuthState(): AuthState | undefined;

  // Account management
  isAuthenticated(): boolean;
  isConnected(): boolean;
  getAccountAddress(): string;
  getNetwork(): Network;
  getChainId(): number;
  waitForTransaction(
    hash: string,
    confirmations?: number,
    timeout?: number
  ): Promise<TransactionReceipt>;
}
```

### Vault Types

Types for vault operations including deposits, withdrawals, and balance management:

```typescript
import { VaultAPI, Balance, TransactionResult } from "@0xmonaco/types";

// Vault operations
interface VaultAPI extends BaseAPI {
  approve(
    assetId: string,
    amount: bigint,
    autoWait?: boolean
  ): Promise<TransactionResult>;
  deposit(
    assetId: string,
    amount: bigint,
    autoWait?: boolean
  ): Promise<TransactionResult>;
  withdraw(
    assetId: string,
    amount: bigint,
    autoWait?: boolean
  ): Promise<TransactionResult>;
  getAllowance(assetId: string): Promise<bigint>;
  needsApproval(assetId: string, amount: bigint): Promise<boolean>;
  getVaultAddress(): Promise<string>;
}

// Vault response types
interface Balance {
  token: string;
  amount: bigint;
  formatted: string;
  symbol: string;
  decimals: number;
}

interface TransactionResult {
  hash: string;
  status: "pending" | "confirmed" | "failed";
  nonce: bigint;
  receipt?: TransactionReceipt;
}
```

### Trading Types

Types for trading operations including order placement and management:

```typescript
import {
  TradingAPI,
  OrderSide,
  OrderType,
  CreateOrderResponse,
  CancelOrderResponse,
  ReplaceOrderResponse,
  GetPaginatedOrdersResponse,
  GetOrderResponse,
} from "@0xmonaco/types";

// Trading operations
interface TradingAPI extends BaseAPI {
  placeLimitOrder(
    tradingPairId: string,
    side: OrderSide,
    quantity: string,
    price: string,
    options?: {
      tradingMode?: TradingMode;
      useMasterBalance?: boolean;
      expirationDate?: string;
      timeInForce?: TimeInForce;
    }
  ): Promise<CreateOrderResponse>;

  placeMarketOrder(
    tradingPairId: string,
    side: OrderSide,
    quantity: string,
    options?: {
      tradingMode?: TradingMode;
      slippageTolerance?: number;
    }
  ): Promise<CreateOrderResponse>;

  cancelOrder(orderId: string): Promise<CancelOrderResponse>;

  replaceOrder(
    orderId: string,
    newOrder: {
      price?: string;
      quantity: string;
      useMasterBalance?: boolean;
    }
  ): Promise<ReplaceOrderResponse>;

  getPaginatedOrders(
    params?: GetPaginatedOrdersParams
  ): Promise<GetPaginatedOrdersResponse>;
  getOrder(orderId: string): Promise<GetOrderResponse>;
}

// Trading types
type OrderSide = "BUY" | "SELL";
type OrderType = "LIMIT" | "MARKET";
type OrderStatus = "SUBMITTED" | "PARTIALLY_FILLED" | "FILLED" | "SETTLED_ON_CHAIN" | "SETTLED" | "CANCELLED" | "REJECTED" | "EXPIRED";
type TradingMode = "SPOT";
type TimeInForce = "GTC" | "IOC" | "FOK"; // GTC: Good Till Cancel, IOC: Immediate or Cancel, FOK: Fill or Kill

// Trading response types
interface CreateOrderResponse {
  order_id: string;
  status: "SUCCESS" | "FAILED";
  match_result?: {
    remaining_quantity: string;
    status: string;
  };
}

interface CancelOrderResponse {
  order_id: string;
  status: "SUCCESS" | "FAILED";
}

interface ReplaceOrderResponse {
  order_id: string;
  status: "SUCCESS" | "FAILED";
}
```

### Market Types

Types for market data operations including trading pair metadata:

```typescript
import {
  MarketAPI,
  TradingPair,
  GetTradingPairsResponse,
  GetTradingPairResponse,
} from "@0xmonaco/types";

// Market operations
interface MarketAPI extends BaseAPI {
  getTradingPairs(): Promise<TradingPair[]>;
  getTradingPairBySymbol(symbol: string): Promise<TradingPair | undefined>;
}

// Market data types
interface TradingPair {
  id: string;
  symbol: string;
  base_token: string;
  quote_token: string;
  base_token_contract: string;
  quote_token_contract: string;
  base_decimals: number;
  quote_decimals: number;
  market_type: string;
  is_active: boolean;
  maker_fee_bps: number;
  taker_fee_bps: number;
  min_order_size: string;
  max_order_size: string;
  tick_size: string;
}

// Market response types
interface GetTradingPairsResponse {
  data: {
    data: TradingPair[];
    limit: number;
    page: number;
    total: number;
    total_pages: number;
  };
  success: boolean;
}

interface GetTradingPairResponse {
  data: TradingPair;
  success: boolean;
}
```

### Contract Types

Types for contract addresses, instances, and contract-related operations:

```typescript
import {
  ContractAddresses,
  ContractInstances,
  Token,
  UserBalance,
} from "@0xmonaco/types";

// Contract addresses
interface ContractAddresses {
  VAULT: string; // Vault contract address for managing user balances
}

// Contract instances
type ContractInstances = {
  vault: GetContractReturnType<typeof CONTRACT_ABIS.vault>;
};

// Contract-related types
interface Token {
  address: string;
  decimals: number;
  symbol: string;
  name: string;
}

interface UserBalance {
  token: Token;
  amount: bigint;
  formatted: string;
}
```

### Network Types

Types for network configuration:

```typescript
import { Network, NetworkEndpoints } from "@0xmonaco/types";

type Network = "mainnet" | "development" | "staging" | "local";

interface NetworkEndpoints {
  rpcUrl: string;
  apiUrl: string;
}
```

## Type Reference

### SDK Types

- `MonacoSDK`: Main SDK interface with all API modules
- `SDKConfig`: Configuration options for the Monaco SDK
- `Network`: Network type ("mainnet" | "development" | "staging" | "local")
- `AuthState`: Authentication state information

### Vault Types

- `VaultAPI`: Interface for vault operations (deposits, withdrawals, balances)
- `Balance`: Token balance information
- `TransactionResult`: Result of blockchain transactions

### Trading Types

- `TradingAPI`: Interface for trading operations (orders, positions)
- `OrderSide`: Order side type ("BUY" | "SELL")
- `OrderType`: Order type ("LIMIT" | "MARKET")
- `TimeInForce`: Time in force type ("GTC" | "IOC" | "FOK")
- `CreateOrderResponse`: Response from order placement
- `CancelOrderResponse`: Response from order cancellation
- `ReplaceOrderResponse`: Response from order replacement

### Market Types

- `MarketAPI`: Interface for market data operations
- `TradingPair`: Trading pair metadata with all market information
- `GetTradingPairsResponse`: Response wrapper for trading pairs list
- `GetTradingPairResponse`: Response wrapper for single trading pair

### Contract Types

- `ContractAddresses`: Contract address mappings
- `ContractInstances`: Typed contract instances
- `Token`: Token interface with metadata
- `UserBalance`: User's token balance information

## Project Structure

The types package is organized into domain-specific modules:

```
src/
├── api/            # Base API types
│   └── index.ts   # Common API interfaces
├── applications/   # Applications types
├── auth/           # Authentication types
├── contracts/      # Contract types
│   ├── index.ts   # Contract interfaces
│   └── balances.ts # Balance-related types
├── market/         # Market data types
│   └── index.ts   # Market API interface and types
├── profile/        # Profile types
├── sdk/            # SDK types
│   ├── index.ts   # Main SDK interfaces and configuration
│   └── network.ts # Network-related types
├── trading/        # Trading types
│   ├── index.ts   # Trading API interface
│   ├── orders.ts  # Order-related types
│   └── responses.ts # Trading response types
├── vault/          # Vault types
│   ├── index.ts   # Vault API interface
│   └── responses.ts # Vault response types
├── websocket/      # WebSocket types
└── index.ts        # Package exports
```

## Dependencies

This package uses `viem` for blockchain-related types:

- `Address`, `Hex`, `Account`, `WalletClient`, `PublicClient` from `viem`
- `GetContractReturnType` for contract instance typing

## Best Practices

- Keep types focused and single-purpose
- Use descriptive names that reflect the domain
- Document complex types with JSDoc comments
- Use TypeScript's strict mode
- Maintain backward compatibility
- Follow the established naming conventions
- Group related types in the same file
- Leverage `viem` types for blockchain operations rather than defining custom ones