@0xmonaco/core 0.1.0

package/README.md

@@ -0,0 +1,421 @@
+# Monaco Core SDK
+
+⚠️ **EARLY DEVELOPMENT WARNING** ⚠️
+
+This package is currently in **early development** (v0.1.0). 
+
+**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 Vault and Trading APIs, featuring EIP-712 intent signatures and secure API Gateway integration.
+
+## Installation
+
+```bash
+npm install @0xmonaco/core
+```
+
+## Features
+
+### 🏦 **Vault Operations**
+- **Token Approvals**: ERC20 token approvals for vault usage
+- **Deposits**: Secure token deposits with EIP-712 signatures
+- **Withdrawals**: Token withdrawals with cryptographic validation
+- **Balance Queries**: Real-time vault balance tracking
+- **Allowance Management**: Efficient approval checking and management
+
+### 📈 **Trading Operations**
+- **Order Types**: Limit (with timeInForce: GTC/IOC/FOK), Market, Post-Only orders
+- **Order Management**: Place, replace (cancel + new), and cancel orders
+- **Position Management**: Close positions with slippage control
+- **Order Queries**: Open orders, order history, and individual order details
+- **Real-time Updates**: Live order status and execution tracking
+
+### 🔐 **Security Features**
+- **EIP-712 Signatures**: Type-safe, structured data signing
+- **Intent-Based Authorization**: Every action explicitly authorized
+- **API Gateway Integration**: Secure communication with Monaco backend
+- **Nonce Protection**: Replay attack prevention
+- **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/src/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 src/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/src/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 both Sei mainnet (pacific-1) and testnet (atlantic-2) networks. Network configurations are automatically handled through the `NETWORK_ENDPOINTS` constant:
+
+```typescript
+import { NETWORK_ENDPOINTS } from "@0xmonaco/core";
+
+// Access network configurations by network name
+const mainnetConfig = NETWORK_ENDPOINTS.mainnet; // Pacific-1 mainnet
+const testnetConfig = NETWORK_ENDPOINTS.testnet; // Atlantic-2 testnet
+
+// Each network config includes:
+// - rpcUrl: RPC endpoint for the network
+// - apiUrl: API gateway endpoint for the network
+```
+
+## Quick Start
+
+```typescript
+import { MonacoSDK } from "@0xmonaco/core";
+
+// Initialize the SDK with private key
+const monaco = new MonacoSDK({
+  privateKey: "0x...", // Your private key
+  network: "mainnet", // or "testnet"
+});
+
+// Vault Operations
+async function vaultExample() {
+  // Check vault balance
+  const balance = await monaco.vault.getBalance("0x..."); // token address
+  console.log("Vault balance:", balance.formatted, balance.symbol);
+
+  // Check if approval is needed
+  const needsApproval = await monaco.vault.needsApproval("0x...", parseEther("100"));
+  if (needsApproval) {
+    // Approve vault to spend tokens
+    const approval = await monaco.vault.approve("0x...", parseEther("1000"));
+    console.log("Approval transaction:", approval.hash);
+  }
+
+  // Deposit tokens
+  const result = await monaco.vault.deposit("0x...", parseEther("100"));
+  console.log("Deposit transaction:", result.hash);
+}
+
+// Trading Operations
+async function tradingExample() {
+  // Place a limit order
+  const order = await monaco.trading.placeLimitOrder(
+    "ETH-USDC", // market
+    "buy", // side
+    parseEther("1.0"), // size (1 ETH)
+    parseUnits("2000", 6) // price (2000 USDC)
+  );
+  console.log("Order placed:", order.orderId);
+
+  // Place a market order with slippage protection
+  const marketOrder = await monaco.trading.placeMarketOrder(
+    "ETH-USDC",
+    "sell",
+    parseEther("0.5"),
+    { slippageToleranceBps: 50 } // 0.5% max slippage (50 basis points)
+  );
+  console.log("Market order placed:", marketOrder.orderId);
+
+  // Place a limit order with IOC time in force
+  const iocOrder = await monaco.trading.placeLimitOrder(
+    "ETH-USDC",
+    "buy",
+    parseEther("1.0"),
+    parseUnits("2000", 6),
+    { timeInForce: "IOC" } // Immediate-or-Cancel
+  );
+  console.log("IOC order placed:", iocOrder.orderId);
+
+  // Get open orders
+  const openOrders = await monaco.trading.getOpenOrders({ market: "ETH-USDC" });
+  console.log("Open orders:", openOrders.length);
+
+  // Replace an order (cancel + new)
+  const replaceResult = await monaco.trading.replaceOrder("order-id", {
+    market: "ETH-USDC",
+    side: "buy",
+    size: parseEther("2.0"),
+    price: parseUnits("2100", 6),
+    type: "limit",
+    timeInForce: "FOK" // Fill-or-Kill
+  });
+  console.log("Order replaced:", replaceResult.orderId);
+
+  // Cancel an order
+  const cancelResult = await monaco.trading.cancelOrder("order-id");
+  console.log("Order cancelled:", cancelResult.status);
+}
+```
+
+## API Reference
+
+### MonacoSDK
+
+The main SDK class that provides access to all protocol features.
+
+```typescript
+class MonacoSDK {
+  readonly vault: VaultAPI;
+  readonly trading: TradingAPI;
+  readonly walletClient: WalletClient;
+  readonly publicClient: PublicClient;
+
+  constructor(config: SDKConfig);
+}
+```
+
+### Configuration
+
+```typescript
+interface SDKConfig {
+  /** Private key as hex string (0x-prefixed) */
+  privateKey?: Hex;
+  
+  /** Viem Account for advanced account management */
+  signer?: PrivateKeyAccount;
+  
+  /** Custom Account implementation (overrides privateKey/signer) */
+  account?: Account;
+  
+  /** Optional network override (defaults to 'mainnet') */
+  network?: Network;
+}
+```
+
+### Vault API
+
+The vault API provides secure token management operations:
+
+```typescript
+interface VaultAPI {
+  // Token approvals
+  approve(token: string, amount: bigint): Promise<TransactionResult>;
+  
+  // Deposit and withdrawal
+  deposit(token: string, amount: bigint): Promise<TransactionResult>;
+  withdraw(token: string, amount: bigint): Promise<TransactionResult>;
+  
+  // Balance and allowance queries
+  getBalance(token: string): Promise<Balance>;
+  getAllowance(token: string): Promise<bigint>;
+  needsApproval(token: string, amount: bigint): Promise<boolean>;
+}
+```
+
+### Trading API
+
+The trading API provides comprehensive order management with support for different execution policies:
+
+#### Order Types and Execution Policies
+
+- **Limit Orders**: Standard limit orders with optional `timeInForce` parameter
+  - `GTC` (Good Till Cancelled): Default behavior, order stays active until filled or cancelled
+  - `IOC` (Immediate or Cancel): Order fills what it can immediately, then cancels the rest
+  - `FOK` (Fill or Kill): Order must fill completely or not at all
+
+- **Market Orders**: Immediate execution with optional slippage protection
+- **Post-Only Orders**: Limit orders that never execute immediately, only add liquidity
+
+#### Order Management
+
+- **Replace Orders**: Cancel existing order and place a new one (atomic operation)
+- **Cancel Orders**: Cancel any open order by ID
+
+```typescript
+interface TradingAPI {
+  // Order placement
+  placeLimitOrder(market: string, side: OrderSide, size: bigint, price: bigint, options?: { timeInForce?: TimeInForce }): Promise<OrderResponse>;
+  placeMarketOrder(market: string, side: OrderSide, size: bigint, options?: { slippageToleranceBps?: number }): Promise<OrderResponse>;
+  placePostOnlyOrder(market: string, side: OrderSide, size: bigint, price: bigint): Promise<OrderResponse>;
+  
+  // Order management
+  replaceOrder(originalOrderId: string, newOrder: { market: string; side: OrderSide; size: bigint; price?: bigint; type: OrderType; timeInForce?: TimeInForce }): Promise<OrderResponse>;
+  cancelOrder(orderId: string): Promise<CancelOrderResponse>;
+  
+  // Position management
+  closePosition(market: string, options?: { maxSlippage?: number }): Promise<ClosePositionResponse>;
+  
+  // Order queries
+  getOrder(orderId: string): Promise<Order>;
+  getOpenOrders(params?: GetOpenOrdersParams): Promise<Order[]>;
+  getOrderHistory(params: OrderHistoryParams): Promise<PaginatedOrders>;
+}
+```
+
+### Error Handling
+
+The SDK uses structured error classes for comprehensive error handling:
+
+```typescript
+import { APIError, ContractError, TransactionError, OrderError } 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);
+  } else if (error instanceof TransactionError) {
+    console.error("Transaction error:", error.message);
+  } else if (error instanceof OrderError) {
+    console.error("Order error:", error.message);
+    console.error("Market:", error.market);
+  }
+}
+```
+
+**Error Types:**
+- `APIError`: API request failures and communication errors
+- `ContractError`: Smart contract operation errors
+- `TransactionError`: Blockchain transaction errors
+- `OrderError`: Trading order specific errors
+- `InvalidConfigError`: Configuration validation errors
+
+## Development
+
+### Project Structure
+
+```
+packages/core/
+├── src/                   # Source code
+│   ├── api/               # API implementations
+│   │   ├── vault/         # Vault operations API
+│   │   │   └── api.ts     # Vault API implementation with comprehensive docs
+│   │   └── trading/       # Trading operations API
+│   │       └── api.ts     # Trading API implementation with comprehensive docs
+│   ├── chains.ts          # Chain definitions (Sei mainnet/testnet)
+│   ├── 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
+
+### EIP-712 Intent Signatures
+- **Type-safe signing**: Structured data with domain separation
+- **Intent-based authorization**: Every action explicitly authorized
+- **Nonce protection**: Prevents replay attacks
+- **Domain validation**: Ensures signatures are valid for specific contracts
+
+### API Gateway Integration
+- **Secure communication**: TLS encryption for all API calls
+- **Signature validation**: Backend validates all signed intents
+- **Rate limiting**: Protection against abuse
+- **Audit logging**: Complete transaction history
+
+### On-chain Security
+- **Smart contract validation**: All operations validated on-chain
+- **Multi-signature support**: Advanced security for institutional users
+- **Emergency stops**: Circuit breakers for critical situations
+
+## 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)

package/dist/api/auth/api.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Auth API Implementation
+ *
+ * Handles authentication operations including challenge creation, signature verification,
+ * and backend authentication. All operations go through the API Gateway.
+ *
+ * This class provides a complete interface for authentication on the Monaco protocol,
+ * including frontend wallet authentication and backend service authentication.
+ *
+ * @example
+ * ```typescript
+ * const authAPI = new AuthAPIImpl(walletClient, apiUrl, chain);
+ *
+ * // Complete authentication flow
+ * const authResult = await authAPI.authenticate(clientId);
+ *
+ * // Or step-by-step flow
+ * const challenge = await authAPI.createChallenge(userAddress, clientId);
+ * const signature = await authAPI.signChallenge(challenge.message);
+ * const authResult = await authAPI.verifySignature(
+ *   userAddress,
+ *   signature,
+ *   challenge.nonce,
+ *   clientId
+ * );
+ *
+ * // Authenticate backend service
+ * const backendAuth = await authAPI.authenticateBackend(secretKey);
+ * ```
+ */
+import { type WalletClient, type Chain } from "viem";
+import { type AuthAPI, type ChallengeResponse, type VerifyResponse, type BackendAuthResponse, type TokenRefreshResponse } from "@0xmonaco/types";
+export declare class AuthAPIImpl implements AuthAPI {
+    private readonly walletClient;
+    private readonly apiUrl;
+    private readonly chain;
+    /**
+     * Creates a new AuthAPI instance.
+     *
+     * @param walletClient - The viem wallet client for signing operations
+     * @param apiUrl - The base URL for the Monaco API Gateway
+     * @param chain - The blockchain network configuration
+     */
+    constructor(walletClient: WalletClient, apiUrl: string, chain: Chain);
+    /**
+     * Complete authentication flow for frontend applications.
+     *
+     * This method handles the entire authentication process:
+     * 1. Creates a challenge
+     * 2. Signs the challenge message
+     * 3. Verifies the signature and returns JWT tokens
+     *
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the verification response with JWT tokens
+     * @throws {APIError} When authentication fails
+     * @throws {InvalidConfigError} When wallet account is not available
+     *
+     * @example
+     * ```typescript
+     * // Complete authentication in one call
+     * const authResult = await authAPI.authenticate("my-app-client-id");
+     * console.log(`Access token: ${authResult.access_token}`);
+     * console.log(`User ID: ${authResult.user.id}`);
+     * ```
+     */
+    authenticate(clientId: string): Promise<VerifyResponse>;
+    /**
+     * Signs a challenge message using the wallet client.
+     *
+     * Signs the provided message using the wallet's private key.
+     * This is used in the authentication flow to prove ownership of the wallet.
+     *
+     * @param message - The message to sign
+     * @returns Promise resolving to the signature
+     * @throws {InvalidConfigError} When wallet account is not available
+     * @throws {APIError} When signing fails
+     *
+     * @example
+     * ```typescript
+     * const challenge = await authAPI.createChallenge(address, clientId);
+     * const signature = await authAPI.signChallenge(challenge.message);
+     * console.log(`Signature: ${signature}`);
+     * ```
+     */
+    signChallenge(message: string): Promise<string>;
+    /**
+     * Creates a challenge for frontend authentication.
+     *
+     * Generates a unique nonce and message that the user must sign with their wallet.
+     * This is the first step in the authentication flow for frontend applications.
+     *
+     * @param address - Wallet address of the user
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the challenge response
+     * @throws {APIError} When challenge creation fails
+     *
+     * @example
+     * ```typescript
+     * const challenge = await authAPI.createChallenge(
+     *   "0x1234...",
+     *   "my-app-client-id"
+     * );
+     * console.log(`Challenge message: ${challenge.message}`);
+     * console.log(`Nonce: ${challenge.nonce}`);
+     * ```
+     */
+    createChallenge(address: string, clientId: string): Promise<ChallengeResponse>;
+    /**
+     * Verifies a signature for frontend authentication.
+     *
+     * Validates the signature against the challenge and returns JWT tokens for
+     * authenticated API access. This is the second step in the authentication flow.
+     *
+     * @param address - Wallet address of the user
+     * @param signature - Signature of the challenge message
+     * @param nonce - Nonce from the challenge response
+     * @param clientId - Client ID of the application
+     * @returns Promise resolving to the verification response with JWT tokens
+     * @throws {APIError} When signature verification fails
+     *
+     * @example
+     * ```typescript
+     * // First create a challenge
+     * const challenge = await authAPI.createChallenge(address, clientId);
+     *
+     * // User signs the challenge message with their wallet
+     * const signature = await wallet.signMessage(challenge.message);
+     *
+     * // Verify the signature and get tokens
+     * const authResult = await authAPI.verifySignature(
+     *   address,
+     *   signature,
+     *   challenge.nonce,
+     *   clientId
+     * );
+     *
+     * console.log(`Access token: ${authResult.accessToken}`);
+     * console.log(`User ID: ${authResult.user.id}`);
+     * ```
+     */
+    verifySignature(address: string, signature: string, nonce: string, clientId: string): Promise<VerifyResponse>;
+    /**
+     * Authenticates a backend service using a secret key.
+     *
+     * Returns JWT tokens for API access. This method is used for backend services
+     * that need to authenticate with the Monaco API Gateway.
+     *
+     * @param secretKey - Secret key of the application
+     * @returns Promise resolving to the backend auth response with JWT tokens
+     * @throws {APIError} When backend authentication fails
+     *
+     * @example
+     * ```typescript
+     * const backendAuth = await authAPI.authenticateBackend("my-secret-key");
+     * console.log(`Backend access token: ${backendAuth.accessToken}`);
+     * console.log(`Application: ${backendAuth.application.name}`);
+     * ```
+     */
+    authenticateBackend(secretKey: string): Promise<BackendAuthResponse>;
+    /**
+     * Refreshes an access token using a refresh token.
+     *
+     * Obtains a new access token using a valid refresh token. This is useful for
+     * maintaining long-term authentication without requiring the user to sign
+     * a new challenge.
+     *
+     * @param refreshToken - The refresh token to use
+     * @returns Promise resolving to new access and refresh tokens
+     * @throws {APIError} When token refresh fails
+     *
+     * @example
+     * ```typescript
+     * const newTokens = await authAPI.refreshToken(refreshToken);
+     * console.log(`New access token: ${newTokens.accessToken}`);
+     * console.log(`Expires at: ${new Date(newTokens.expiresAt * 1000)}`);
+     * ```
+     */
+    refreshToken(refreshToken: string): Promise<TokenRefreshResponse>;
+    /**
+     * Revokes a refresh token.
+     *
+     * Invalidates a refresh token, preventing it from being used to obtain
+     * new access tokens. This is useful for logout functionality or when
+     * a token has been compromised.
+     *
+     * @param refreshToken - The refresh token to revoke
+     * @returns Promise resolving when the token is revoked
+     * @throws {APIError} When token revocation fails
+     *
+     * @example
+     * ```typescript
+     * await authAPI.revokeToken(refreshToken);
+     * console.log("Token revoked successfully");
+     * ```
+     */
+    revokeToken(refreshToken: string): Promise<void>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/api/auth/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/api/auth/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,KAAK,EAAE,MAAM,MAAM,CAAC;AACrD,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAC1B,MAAM,iBAAiB,CAAC;AAGzB,qBAAa,WAAY,YAAW,OAAO;IASvC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAVxB;;;;;;OAMG;gBAEgB,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK;IAG/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAgC7D;;;;;;;;;;;;;;;;;OAiBG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BrD;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAqCpF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,CAAC;IA4C1B;;;;;;;;;;;;;;;;OAgBG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAwC1E;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAkCvE;;;;;;;;;;;;;;;;OAgBG;IACG,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA2BvD"}