@0xmonaco/core 0.0.0-develop-20260120180031

package/README.md

@@ -0,0 +1,693 @@
+# Monaco Core SDK
+
+⚠️ **EARLY DEVELOPMENT WARNING** ⚠️
+
+This package is currently in **early development**.
+
+**Breaking changes are expected** and may occur without notice. This version is intended for:
+- Early adopters and testing
+- Development and experimentation
+- Feedback collection
+
+---
+
+Core SDK implementation for interacting with Monaco Protocol. This SDK provides a comprehensive implementation with Authentication, Vault, Trading, Market, and Profile APIs, featuring JWT authentication and secure API Gateway integration.
+
+## Installation
+
+```bash
+npm install @0xmonaco/core
+```
+
+**Required Peer Dependencies:**
+```bash
+npm install viem@^2.31.7
+```
+
+### TypeScript Configuration
+
+For best results, use these TypeScript settings in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  }
+}
+```
+
+## Features
+
+### 🔐 **Authentication**
+- **JWT-based Authentication**: Secure token-based authentication
+- **Wallet Signature Verification**: EIP-712 signature-based login
+- **Token Refresh**: Automatic token refresh and management
+- **Session Management**: Secure session handling
+
+### 🏦 **Vault Operations**
+- **Token Approvals**: ERC20 token approvals for vault usage
+- **Deposits**: Secure token deposits with signature validation
+- **Withdrawals**: Token withdrawals with cryptographic validation
+- **Balance Queries**: Real-time vault balance tracking
+
+### 📈 **Trading Operations**
+- **Order Types**: Limit and Market orders
+- **Order Management**: Place, replace, and cancel orders
+- **Order Queries**: Paginated orders, order history, and individual order details
+- **Real-time Updates**: WebSocket support for live order updates
+
+### 📊 **Market Data**
+- **Trading Pairs**: Complete trading pair metadata
+- **Market Information**: Fees, tick sizes, order limits
+- **Pair Discovery**: Search and filter available markets
+
+### 👤 **Profile Management**
+- **User Profiles**: Account information and settings
+- **Sub-accounts**: Multi-account management
+- **Balance Tracking**: Cross-platform balance monitoring
+
+### 🔐 **Security Features**
+- **JWT Authentication**: Secure API access with token validation
+- **EIP-712 Signatures**: Type-safe, structured data signing for authentication
+- **API Gateway Integration**: Secure communication with Monaco backend
+- **TLS Encryption**: Secure API communications
+
+## Test Setup
+
+Before running tests, ensure you have:
+
+1. A running hardhat node with the Monaco Protocol contracts deployed:
+   ```bash
+   # In the contracts package
+   cd ../contracts
+   pnpm hardhat node  # Start a local hardhat node
+   pnpm hardhat deploy --network localhost  # Deploy contracts
+   ```
+
+2. Create a `.env.test` file in the tests directory:
+   ```bash
+   # Create the file
+   cd packages/core/tests
+   touch .env.test
+
+   # Add the following content to .env.test:
+   echo 'TEST_PRIVATE_KEY=0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef' > .env.test
+   ```
+
+3. Replace the example private key in `.env.test` with your actual test account private key:
+   - The private key must be a 0x-prefixed 64-character hex string
+   - The account must have enough ETH on the local hardhat network for transactions
+   - Never commit real private keys to version control
+
+4. Verify your setup:
+   ```bash
+   # Make sure you're in the core package directory
+   cd packages/core
+   
+   # Check if .env.test exists and has the correct format
+   cat tests/.env.test
+   # Should show: TEST_PRIVATE_KEY=0x...
+
+   # Run the tests
+   pnpm test
+   ```
+
+If you see an error about `TEST_PRIVATE_KEY` not being set:
+1. Double check that `.env.test` exists in `packages/core/tests` directory
+2. Make sure the private key format is correct (0x-prefixed, 64 characters)
+3. Try running the tests with the environment variable directly:
+   ```bash
+   TEST_PRIVATE_KEY=0x1234... pnpm test
+   ```
+
+## Network Support
+
+The SDK supports multiple preset networks and custom API URLs. Configure the network by providing the `network` and `seiRpcUrl` parameters:
+
+**Preset Networks:**
+- `"development"` - Development environment (https://develop.apimonaco.xyz)
+- `"staging"` - Staging environment (https://staging.apimonaco.xyz)
+- `"mainnet"` - Production environment (https://api.monaco.xyz)
+- `"local"` - Local development (http://localhost:8080)
+
+```typescript
+import { MonacoSDK } from "@0xmonaco/core";
+
+// Development configuration
+const devSdk = new MonacoSDK({
+  walletClient,
+  network: "development",
+  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com", // Atlantic-2 testnet
+  wsUrl: "wss://develop.apimonaco.xyz/ws"
+});
+
+// Staging configuration
+const stagingSdk = new MonacoSDK({
+  walletClient,
+  network: "staging",
+  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com", // Atlantic-2 testnet
+  wsUrl: "wss://staging.apimonaco.xyz/ws"
+});
+
+// Mainnet configuration
+const mainnetSdk = new MonacoSDK({
+  walletClient,
+  network: "mainnet",
+  seiRpcUrl: "https://evm-rpc.sei-apis.com", // Pacific-1 mainnet
+  wsUrl: "wss://api.monaco.xyz/ws"
+});
+
+// Custom API URL
+const customSdk = new MonacoSDK({
+  walletClient,
+  network: "https://my-custom-api.com",
+  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com",
+  wsUrl: "wss://my-custom-api.com/ws"
+});
+```
+
+## Quick Start
+
+```typescript
+import { MonacoSDK } from "@0xmonaco/core";
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Initialize the SDK with wallet client
+const account = privateKeyToAccount("0x...");
+const walletClient = createWalletClient({
+  account,
+  chain: sei, // or seiTestnet
+  transport: http("https://evm-rpc.sei-apis.com") // or https://evm-rpc-testnet.sei-apis.com for testnet
+});
+
+const monaco = new MonacoSDK({
+  walletClient,
+  network: "development", // or "staging", "mainnet"
+  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com", // or https://evm-rpc.sei-apis.com for mainnet
+  wsUrl: "wss://develop.apimonaco.xyz/ws" // or wss://staging.apimonaco.xyz/ws, wss://api.monaco.xyz/ws
+});
+
+// Authentication
+async function authExample() {
+  // Login with client ID and auto-connect authenticated WebSocket channels (Orders)
+  const authState = await monaco.login("your-client-id", { connectWebSocket: true });
+  console.log("Authenticated:", authState.user);
+  console.log("Tokens:", {
+    accessToken: authState.accessToken,
+    refreshToken: authState.refreshToken, // Use this for revokeToken()
+  });
+  
+  // Authenticated WebSocket channels are now connected - start receiving real-time updates
+  // Currently this includes: Orders (personal order updates)
+  monaco.websocket.orders.subscribeToOrderEvents("BTC/USDC", "SPOT", (event) => {
+    console.log("Order event:", event.eventType);
+  });
+  
+  // Check authentication status
+  console.log("Is authenticated:", monaco.isAuthenticated());
+  
+  // Logout (revokes the refresh token and disconnects authenticated WebSockets)
+  await monaco.logout();
+  
+  // Or manually revoke the token
+  // ✅ CORRECT: Use authState.refreshToken
+  await monaco.auth.revokeToken(authState.refreshToken);
+}
+
+// Market Data
+async function marketExample() {
+  // Get all trading pairs
+  const pairs = await monaco.market.getTradingPairs();
+  console.log("Available pairs:", pairs.length);
+  
+  // Get specific trading pair
+  const btcPair = await monaco.market.getTradingPairBySymbol("BTC/USDC");
+  console.log("BTC pair:", btcPair?.symbol, btcPair?.maker_fee_bps);
+}
+
+// Vault Operations
+async function vaultExample() {
+  // Get asset ID from trading pair
+  const pair = await monaco.market.getTradingPairBySymbol("USDC/USDT");
+  const assetId = pair.base_asset_id; // Asset ID (UUID)
+  
+  // Check vault balance
+  const balance = await monaco.vault.getBalance(assetId);
+  console.log("Vault balance:", balance.formatted, balance.symbol);
+
+  // Approve vault to spend tokens
+  const approval = await monaco.vault.approve(assetId, parseEther("1000"));
+  console.log("Approval transaction:", approval.hash);
+
+  // Deposit tokens
+  const result = await monaco.vault.deposit(assetId, parseEther("100"));
+  console.log("Deposit transaction:", result.hash);
+  
+  // Withdraw tokens
+  const withdrawal = await monaco.vault.withdraw(assetId, parseEther("50"));
+  console.log("Withdrawal transaction:", withdrawal.hash);
+}
+
+// Trading Operations
+async function tradingExample() {
+  // Place a limit order
+  const order = await monaco.trading.placeLimitOrder(
+    "BTC/USDC", // market
+    "BUY", // side
+    "0.001", // quantity
+    "50000" // price
+  );
+  console.log("Order placed:", order.order_id);
+
+  // Place a limit order with IOC (Immediate or Cancel)
+  const iocOrder = await monaco.trading.placeLimitOrder(
+    "BTC/USDC",
+    "BUY",
+    "0.001",
+    "50000",
+    { timeInForce: "IOC" } // Execute immediately or cancel
+  );
+  console.log("IOC order placed:", iocOrder.order_id);
+
+  // Place a market order
+  const marketOrder = await monaco.trading.placeMarketOrder(
+    "BTC/USDC",
+    "SELL",
+    "0.001"
+  );
+  console.log("Market order placed:", marketOrder.order_id);
+
+  // Place a market order with FOK (Fill or Kill)
+  const fokOrder = await monaco.trading.placeMarketOrder(
+    "BTC/USDC",
+    "BUY",
+    "0.001",
+    { timeInForce: "FOK" } // Must fill completely or cancel
+  );
+  console.log("FOK order placed:", fokOrder.order_id);
+
+  // Get paginated orders
+  const orders = await monaco.trading.getPaginatedOrders({
+    status: "PENDING",
+    trading_pair: "BTC/USDC",
+    page: 1,
+    page_size: 10
+  });
+  console.log("Orders:", orders.data.length);
+
+  // Replace an order
+  const replaceResult = await monaco.trading.replaceOrder("order-id", {
+    quantity: "0.002",
+    price: "51000"
+  });
+  console.log("Order replaced:", replaceResult.order_id);
+
+  // Cancel an order
+  const cancelResult = await monaco.trading.cancelOrder("order-id");
+  console.log("Order cancelled:", cancelResult.status);
+  
+  // Get specific order
+  const orderDetails = await monaco.trading.getOrder("order-id");
+  console.log("Order details:", orderDetails.order);
+}
+```
+
+## API Reference
+
+### MonacoSDK
+
+The main SDK class that provides access to all protocol features.
+
+```typescript
+class MonacoSDK {
+  readonly applications: ApplicationsAPI;
+  readonly auth: AuthAPI;
+  readonly vault: VaultAPI;
+  readonly trading: TradingAPI;
+  readonly market: MarketAPI;
+  readonly profile: ProfileAPI;
+  readonly websocket: {
+    orders: OrdersWebSocketClient;
+    ohlcv: OHLCVWebSocketClient;
+    orderbook: OrderbookWebSocketClient;
+  };
+  readonly walletClient: WalletClient;
+  readonly publicClient: PublicClient;
+
+  constructor(config: SDKConfig);
+  
+  // Authentication
+  login(clientId: string, options?: { connectWebSocket?: boolean }): Promise<AuthState>;
+  logout(): Promise<void>;
+  refreshAuth(): Promise<AuthState>;
+  getAuthState(): AuthState | undefined;
+  isAuthenticated(): boolean;
+  
+  // Network utilities
+  isConnected(): boolean;
+  getAccountAddress(): string;
+  getNetwork(): Network;
+  getChainId(): number;
+  waitForTransaction(hash: string, confirmations?: number, timeout?: number): Promise<TransactionReceipt>;
+}
+```
+
+### Configuration
+
+```typescript
+interface SDKConfig {
+  /** Wallet client for signing operations */
+  walletClient: WalletClient;
+  
+  /** Optional network override (defaults to 'mainnet') */
+  network?: Network;
+  
+  /** Optional transport for the public client */
+  transport?: Transport;
+}
+```
+
+### Authentication & Token Management
+
+The SDK uses JWT tokens for authentication. Understanding the token structure is important:
+
+```typescript
+// After login, you receive an AuthState object
+const authState = await sdk.login(clientId);
+
+// AuthState structure:
+interface AuthState {
+  accessToken: string;    // For making authenticated API requests
+  refreshToken: string;   // For refreshing tokens AND revoking (logout)
+  expiresAt: number;      // When the access token expires
+  user: User;             // User information
+}
+```
+
+**⚠️ Important:** The authentication response contains `refreshToken`, NOT `revokeToken`.
+
+```typescript
+// ✅ CORRECT: Revoke using refreshToken
+await sdk.auth.revokeToken(authState.refreshToken);
+
+// 💡 TIP: Use the built-in logout method
+await sdk.logout(); // Automatically calls revokeToken internally
+```
+
+**Token Management Methods:**
+- `login(clientId, options?)` - Authenticate and get tokens
+  - `clientId`: Your application's client ID
+  - `options.connectWebSocket`: (optional) Auto-connect WebSocket after login (default: `false`)
+  - Returns `AuthState` with access token, refresh token, expiration, and user info
+- `logout()` - Revoke token, disconnect WebSocket, and clear state
+  - Calls `auth.revokeToken()` internally
+  - Disconnects authenticated WebSocket channels
+  - Clears local auth state
+- `refreshAuth()` - Refresh the access token using the stored refresh token
+- `isAuthenticated()` - Check if user is authenticated
+- `getAuthState()` - Get current auth state with tokens
+- `setAuthState(authState)` - Set auth state directly (useful for sharing across SDK instances)
+
+### Vault API
+
+The vault API provides secure token management operations:
+
+```typescript
+interface VaultAPI extends BaseAPI {
+  // Vault address management
+  setVaultAddress(vaultAddress: Address): void;
+  getVaultAddress(): Address | undefined;
+  
+  // Token operations
+  approve(token: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
+  deposit(token: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
+  withdraw(token: string, amount: bigint, autoWait?: boolean): Promise<TransactionResult>;
+  
+  // Balance queries
+  getBalance(token: string): Promise<Balance>;
+}
+```
+
+### Trading API
+
+The trading API provides comprehensive order management:
+
+```typescript
+interface TradingAPI extends BaseAPI {
+  // Order placement
+  placeLimitOrder(
+    market: string, 
+    side: OrderSide, 
+    quantity: string, 
+    price: string, 
+    options?: {
+      tradingMode?: string;
+      useMasterBalance?: boolean;
+      expirationDate?: string;
+      timeInForce?: string; // "GTC", "IOC", or "FOK"
+    }
+  ): Promise<CreateOrderResponse>;
+  
+  placeMarketOrder(
+    market: string, 
+    side: OrderSide, 
+    quantity: string, 
+    options?: { 
+      tradingMode?: string;
+      slippageTolerance?: number;
+      timeInForce?: string; // "GTC", "IOC", or "FOK"
+    }
+  ): Promise<CreateOrderResponse>;
+  
+  // Order management
+  cancelOrder(orderId: string): Promise<CancelOrderResponse>;
+  replaceOrder(
+    orderId: string, 
+    newOrder: {
+      price?: string;
+      quantity: string;
+      useMasterBalance?: boolean;
+    }
+  ): Promise<ReplaceOrderResponse>;
+  
+  // Order queries
+  getPaginatedOrders(params?: GetPaginatedOrdersParams): Promise<GetPaginatedOrdersResponse>;
+  getOrder(orderId: string): Promise<GetOrderResponse>;
+}
+```
+
+### Market API
+
+The market API provides access to trading pair metadata:
+
+```typescript
+interface MarketAPI extends BaseAPI {
+  // Market data
+  getTradingPairs(): Promise<TradingPair[]>;
+  getTradingPairBySymbol(symbol: string): Promise<TradingPair | undefined>;
+}
+```
+
+### WebSocket Authentication
+
+The SDK provides three WebSocket clients with different authentication requirements:
+
+#### Public WebSockets (OHLCV and Orderbook)
+
+No authentication required. Provide public market data. You always connect manually:
+
+```typescript
+// Step 1: Establish WebSocket connection (no authentication needed)
+await monaco.websocket.ohlcv.connect();
+await monaco.websocket.orderbook.connect();
+
+// Step 2: Subscribe to public market data
+monaco.websocket.ohlcv.subscribeToOHLCV("BTC/USDC", "SPOT", "1m", (event) => {
+  console.log("OHLCV data:", event.candlestick);
+});
+
+monaco.websocket.orderbook.subscribeToOrderbookEvents("BTC/USDC", "SPOT", (event) => {
+  console.log("Orderbook update:", event.bids.length, "bids");
+});
+```
+
+#### Authenticated WebSockets (Orders)
+
+Requires JWT authentication for personal order updates. You can either auto-connect during login or connect manually:
+
+**Option 1: Auto-connect (recommended for authenticated channels)**
+```typescript
+// Login and auto-connect all authenticated WebSocket channels
+// Currently includes: Orders (personal order updates)
+await monaco.login(clientId, { connectWebSocket: true });
+
+// Subscribe to personal order events (already connected)
+monaco.websocket.orders.subscribeToOrderEvents("BTC/USDC", "SPOT", (event) => {
+  console.log("Personal order event:", event.eventType);
+});
+```
+
+**Option 2: Manual connection (required for public channels, optional for authenticated)**
+```typescript
+// Public channels like OHLCV always require manual connection (no auth needed)
+await monaco.websocket.ohlcv.connect();
+
+monaco.websocket.ohlcv.subscribeToOHLCV("BTC/USDC", "SPOT", "1m", (event) => {
+  console.log("OHLCV data:", event.candlestick);
+});
+
+// For authenticated channels, you can also connect manually for more control
+await monaco.login(clientId);
+await monaco.websocket.orders.connect();
+monaco.websocket.orders.subscribeToOrderEvents("BTC/USDC", "SPOT", (event) => {
+  console.log("Personal order event:", event.eventType);
+});
+```
+
+**Note:** 
+- The `connectWebSocket: true` option automatically connects all authenticated WebSocket channels (currently Orders).
+- Public WebSocket clients (OHLCV, Orderbook) always require calling `connect()` explicitly as they don't require authentication.
+
+### Error Handling
+
+The SDK uses structured error classes for comprehensive error handling:
+
+```typescript
+import { APIError, ContractError } from "@0xmonaco/core";
+
+try {
+  await sdk.vault.deposit(token, amount);
+} catch (error) {
+  if (error instanceof ContractError) {
+    console.error("Contract error:", error.message);
+    console.error("Error code:", error.code);
+  } else if (error instanceof APIError) {
+    console.error("API error:", error.message);
+    console.error("Status:", error.status);
+  }
+}
+```
+
+**Error Types:**
+- `MonacoCoreError`: Base error class for all SDK errors
+- `APIError`: API request failures and communication errors
+- `ContractError`: Smart contract operation errors
+- `InvalidConfigError`: Configuration validation errors
+- `InvalidStateError`: Invalid state or operation errors
+
+## Development
+
+### Project Structure
+
+```
+packages/core/
+├── src/                   # Source code
+│   ├── api/               # API implementations
+│   │   ├── applications/  # Applications API
+│   │   ├── auth/          # Authentication API
+│   │   ├── base.ts        # Base API class
+│   │   ├── market/        # Market data API
+│   │   ├── profile/       # Profile management API
+│   │   ├── trading/       # Trading operations API
+│   │   ├── vault/         # Vault operations API
+│   │   ├── websocket/     # WebSocket client
+│   │   └── index.ts       # API exports
+│   ├── constants/         # Constants and configurations
+│   ├── errors.ts          # Error classes and codes
+│   ├── networks.ts        # Network endpoint configurations
+│   ├── sdk.ts             # Main SDK implementation
+│   └── index.ts           # Public API exports
+├── tests/                 # Test suite
+├── dist/                  # Compiled output
+├── package.json           # Package configuration
+└── tsconfig.json          # TypeScript configuration
+```
+
+### Development Setup
+
+1. Clone the repository:
+```bash
+git clone https://github.com/monaco-protocol/monaco-monorepo.git
+cd monaco-monorepo
+```
+
+2. Install dependencies:
+```bash
+pnpm install
+```
+
+3. Build the package:
+```bash
+pnpm build --filter @0xmonaco/core
+```
+
+### Testing
+
+Run the test suite:
+```bash
+pnpm test --filter @0xmonaco/core
+```
+
+### Code Style
+
+The project uses ESLint and Prettier for code formatting. Run the linter:
+```bash
+pnpm lint --filter @0xmonaco/core
+```
+
+## Security Features
+
+### JWT Authentication
+- **Token-based security**: Secure JWT tokens for API access
+- **EIP-712 login**: Wallet signature-based authentication
+- **Automatic refresh**: Seamless token renewal
+- **Session management**: Secure session handling
+
+### API Gateway Integration
+- **Secure communication**: TLS encryption for all API calls
+- **Token validation**: Backend validates all JWT tokens
+- **Rate limiting**: Protection against abuse
+- **Audit logging**: Complete transaction history
+
+### On-chain Security
+- **Smart contract validation**: All operations validated on-chain
+- **Signature verification**: EIP-712 signatures for authentication
+- **Multi-signature support**: Advanced security for institutional users
+
+## Performance Considerations
+
+- **Batch operations**: Efficient handling of multiple operations
+- **Connection pooling**: Optimized API connections
+- **Caching**: Smart caching of frequently accessed data
+- **Async operations**: Non-blocking operations for better UX
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../../docs/contributing.mdx) for details.
+
+### Development Workflow
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details.
+
+## Support
+
+For support, please:
+
+- Open an issue on GitHub
+- Join our [Discord community](https://discord.gg/monaco)
+- Visit our [documentation site](https://docs.monaco.xyz)
+- Check our [API documentation](../../docs/api-reference.mdx)