Add Hyperliquid perpetual futures trading support

[brann-dev]

Summary

• Complete Hyperliquid perpetual futures trading integration with REST API and gRPC wallet service
• Market and limit order execution with stop loss functionality
• Real-time position and account management
• Asset universe support for all Hyperliquid perpetuals

Implementation Details

• hyperliquid-common: Shared SDK wrapper, types, and gRPC protocol definitions
• hyperliquid-api: REST API server (port 3100) for trading operations
• hyperliquid-wallet: Secure gRPC wallet service (port 50052) for transaction signing
• Full order management: market orders, limit orders, stop losses, cancellations
• Position monitoring and account information endpoints
• Comprehensive error handling and validation

Test Plan

• Build workspace successfully: cargo build --workspace
• Start Hyperliquid wallet service: cargo run --bin hyperliquid-wallet
• Start Hyperliquid API server: cargo run --bin hyperliquid-api
• Test API endpoints using hyperliquid-rest-client.http
• Verify gRPC communication between API and wallet services
• Test market and limit order placement
• Verify position and account data retrieval

🤖 Generated with Claude Code

[claude]

Claude finished @BrandonFlorian's task —— View job

---

PR Review: Hyperliquid Trading Integration

• Read and understand the codebase structure
• Analyze code quality and best practices
• Check for potential bugs or issues
• Review performance considerations
• Evaluate security concerns
• Assess test coverage and recommendations

✅ Strengths

Architecture & Design

• Excellent separation of concerns with clear microservice boundaries
• Well-structured Rust workspace with proper dependency management
• Good use of type system with custom error types and comprehensive data structures
• Clean API design with consistent response formats using ApiResponse<T>

Code Quality

• Proper async/await usage throughout the codebase
• Good error propagation using Result<T> patterns and thiserror for custom errors
• Consistent naming conventions and module organization
• Well-defined gRPC protocol with comprehensive service definitions

⚠️ Areas of Concern

Security Issues (High Priority)

1. Private Key Exposure hyperliquid-api/src/main.rs:26-27

   let private_key = std::env::var("HYPERLIQUID_PRIVATE_KEY")
       .expect("HYPERLIQUID_PRIVATE_KEY must be set");

   • Consider using secure key management solutions
   • Add key rotation capabilities
   • Implement encrypted storage for private keys

2. No Authentication/Authorization

   • API endpoints are completely open (financial trading system!)
   • Recommend implementing API keys, JWT tokens, or similar auth mechanisms
   • Add rate limiting to prevent abuse

3. Overly Permissive CORS hyperliquid-api/src/main.rs:55-59

   .allow_origin(Any)
   .allow_methods(Any)
   .allow_headers(Any)

   • Should restrict to specific origins in production
   • Consider implementing proper CORS policies

4. Input Validation Gaps

   • No decimal precision validation for financial amounts
   • Missing validation for asset names and order IDs
   • No bounds checking on order sizes

Potential Bugs

1. Panic-prone Error Handling hyperliquid-common/src/client.rs:233-240

   let oid: u64 = order_id.parse()
       .map_err(|_| crate::HyperliquidError::InvalidOrder("Invalid order ID format".to_string()))?;

   • Should validate UUID vs numeric order ID formats more robustly

2. Hardcoded Asset Indices hyperliquid-common/src/assets.rs:6-36

   • Static asset mapping may become stale
   • Should fetch universe dynamically or implement refresh mechanism

3. Float Precision Issues hyperliquid-wallet/src/service.rs:88-92

   size: Decimal::from_f64_retain(req.size).unwrap_or(Decimal::ZERO),
   price: req.price.map(|p| Decimal::from_f64_retain(p).unwrap_or(Decimal::ZERO)),

   • Using unwrap_or(Decimal::ZERO) could mask precision errors
   • Should return proper validation errors instead

Performance Considerations

1. Missing Connection Pooling

   • Each request creates new SDK client connections
   • Consider implementing connection reuse for better performance

2. Synchronous Asset Validation hyperliquid-common/src/client.rs:51-55

   • Asset universe validation on every order could be cached
   • Implement universe caching with TTL

3. Blocking Operations

   • Some operations like get_positions make multiple API calls
   • Consider batching or optimizing these operations

Code Quality Issues

1. Missing Input Validation Middleware

   • Should validate request payloads before processing
   • Implement consistent validation across all endpoints

2. Error Context Loss

   • Some errors convert to generic strings, losing valuable debugging context
   • Consider preserving error chains for better debugging

3. Incomplete Error Handling hyperliquid-api/src/handlers.rs:85-87

   match client.place_order(order_request).await {
       Ok(response) => Ok(Json(ApiResponse::success(response))),
       Err(e) => Ok(Json(ApiResponse::error(e.to_string()))),
   }

   • Should map different error types to appropriate HTTP status codes

🚨 Critical Test Coverage Gap

No automated tests found - This is a significant concern for a financial trading system:

Recommendations:

1. Unit Tests: Test core business logic, especially order validation and conversion
2. Integration Tests: Test API endpoints with mock Hyperliquid SDK
3. Property-Based Tests: Validate decimal calculations and order transformations
4. Error Handling Tests: Ensure proper error propagation and handling

Suggested Test Structure:

// hyperliquid-common/src/client.rs tests
#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_order_validation() { /* ... */ }
    
    #[test]
    fn test_decimal_precision() { /* ... */ }
}

📝 Recommendations

High Priority

1. Add comprehensive test suite (unit + integration tests)
2. Implement authentication/authorization for API endpoints
3. Add input validation middleware with proper error responses
4. Secure private key management using external key stores
5. Add rate limiting to prevent API abuse

Medium Priority

1. Implement dynamic asset universe fetching with caching
2. Add connection pooling for SDK clients
3. Improve error handling with proper HTTP status codes
4. Add API documentation (OpenAPI/Swagger)
5. Implement monitoring and observability (metrics, tracing)

Low Priority

1. Add configuration validation on startup
2. Implement graceful shutdown handling
3. Add health check endpoints with dependency status
4. Consider implementing circuit breakers for external API calls

🎯 Overall Assessment

This is a solid foundation for Hyperliquid integration with good architectural decisions and clean code structure. However, the lack of tests and security measures makes it unsuitable for production use with real funds.

Recommendation: Address security and testing concerns before merging, especially for a financial trading system where bugs can result in monetary losses.

---