Initial implementation of payback loan

[Kailai-Wang]

Context

As topic - it follows the action of:

• cancelling the order or closing the position
• transfer to spot
• spot by the collateral

It fixes the price calculation too (using meta-and-asset-ctxs instead of mid price)

I detected some small issues in tests - still investigating them, but want to make changes after this PR is reviewed/merged to make it more clear

Edit:
I had a few more commits trying to fix the bugs that I found:

• I add the position_size into the loanRecord, which will be used when closing the position - we can't fully rely on the position_size from the clearingHouseState as it could be the sum of multiple positions (of the same ticker)
• it seems that the markPx in the metadata could denote either the highest buy order or lowest sell order, to figure that out, we'll need to compare it with midPx
• the price should be re-fetched when doing action 3
• recalculate the spot-buy-size: how much can we buy with available USDC?

Note:
occasionally, I still see position opening order gets silently ignored (I get unknownOid if I query it) - the encoding of price and size looked ok. I don't know the reason yet..

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
heima-aa-demo-app	Ready	Preview	Comment	Oct 28, 2025 9:05pm

[claude]

Claude finished @Kailai-Wang's task —— View job

---

PR Review: Initial implementation of payback loan

Todo List:

• Read repository setup guidelines (CLAUDE.md)
• Analyze main implementation files
• Review test coverage and test data
• Check for security concerns
• Assess performance considerations
• Provide comprehensive feedback

---

Summary

This PR implements a comprehensive payback loan feature for the Heima omni-executor system. The implementation includes order cancellation, position closing, fund transfers, and spot trading operations. The code quality is generally good with proper error handling and detailed logging.

Code Quality Assessment

Strengths ✅

1. Comprehensive Error Handling: Excellent error propagation throughout the codebase with detailed error messages
2. Thorough Logging: Good use of info!, debug!, and error! logging for monitoring execution flow
3. Input Validation: Proper validation of parameters including account value thresholds and balance checks
4. State Management: Well-structured account state tracking with debug printing methods
5. Test Data: Includes realistic test data for both perp and spot markets
6. Modular Design: Clean separation of concerns between API client, core writer, and business logic

Areas for Improvement ⚠️

Security Concerns

1. Price Manipulation Risk (hypercore_api.rs:406-473, payback_loan_test.rs:489-510)

   • Uses external market prices without additional validation
   • Recommendation: Consider implementing price bounds checking or oracle validation

2. Integer Overflow/Underflow (corewriter.rs:84-97)

   let size = notional / market_price;
   (size * 100_000_000.0) as u64  // Potential overflow

   • Recommendation: Add overflow checks before casting to u64

3. Floating Point Precision (payback_loan_test.rs:744-746)

   let calculated_amount = initial_margin + unrealized_pnl - cum_funding_all_time - close_position_fee - buffer;

   • Financial calculations using f64 can lead to precision errors
   • Recommendation: Use decimal types for financial calculations

Performance Considerations

1. Sequential API Calls (payback_loan_test.rs:489-510)

   • Multiple sequential calls to HyperCore API could be parallelized
   • Recommendation: Batch related API calls where possible

2. Polling with Fixed Intervals (hypercore_api.rs:694-736)

   tokio::time::sleep(Duration::from_secs(2)).await;

   • Fixed 2-second polling intervals may be inefficient
   • Recommendation: Implement exponential backoff or event-based notifications

3. Large Test Data Files

   • 44KB+ JSON files included in binary
   • Recommendation: Consider loading test data dynamically or using smaller representative datasets

Bugs and Code Issues

1. Potential Race Condition (payback_loan_test.rs:587-599)

   • Order cancellation wait uses OrderWaitCondition::Filled which seems incorrect for cancel operations
   • Recommendation: Use appropriate wait condition or implement cancel-specific validation

2. Hardcoded Magic Numbers (hyperliquid/src/lib.rs)

   pub const SPOT_SELL_PRICE_RATIO: f64 = 0.98;
   pub const PERP_CLOSE_PRICE_RATIO: f64 = 0.98;

   • Recommendation: Make these configurable or document the rationale

3. Inconsistent Error Types (payback_loan_test.rs:216-222)

   • Mix of parsing errors and internal errors for similar validation failures
   • Recommendation: Standardize error classifications

Test Coverage Issues

1. Missing Edge Case Tests

   • No tests for market price edge cases (zero, negative, extremely large values)
   • No tests for network timeout scenarios
   • Limited error path testing

2. Test Data Dependency

   • Tests depend on static JSON files which may become outdated
   • Recommendation: Add tests with mock data or data generation

Architecture Concerns

1. Function Complexity (payback_loan_test.rs:201-934)

   • Single function with 700+ lines handling multiple responsibilities
   • Recommendation: Break into smaller, focused functions

2. Type Safety (hypercore_api.rs:55-59)

   pub struct MetaAndAssetCtxsResponse(pub Vec<serde_json::Value>);

   • Using serde_json::Value reduces type safety
   • Recommendation: Define proper structs for better compile-time checks

Specific Line Comments

• hypercore_api.rs:634-638: CLOID conversion logic is complex - consider extracting to helper function
• payback_loan_test.rs:378-391: Account value validation logic should be extracted to reusable function
• corewriter.rs:5-7: Random CLOID generation using timestamp could create collisions - consider adding entropy

Overall Assessment

The implementation demonstrates good understanding of the domain and includes necessary safety checks. The main concerns are around financial calculation precision, error handling consistency, and function complexity. The security model appears sound but would benefit from additional price validation mechanisms.

Priority Recommendations:

1. Address floating-point precision in financial calculations
2. Add overflow protection for integer conversions
3. Break down the main payback function into smaller components
4. Improve test coverage for edge cases
5. Consider making price ratios configurable

The code is production-ready with the above improvements addressed.

---

[claude]

Claude finished @Kailai-Wang's task —— View job

---

PR Review: Initial implementation of payback loan

Todo List:

• Read repository setup guidelines (CLAUDE.md)
• Analyze main implementation files
• Review test coverage and test data
• Check for security concerns
• Assess performance considerations
• Provide comprehensive feedback

---

Summary

This PR implements a comprehensive payback loan feature for the Heima omni-executor system. The implementation includes order cancellation, position closing, fund transfers, and spot trading operations. The code quality is generally good with proper error handling and detailed logging.

Code Quality Assessment

Strengths ✅

1. Comprehensive Error Handling: Excellent error propagation throughout the codebase with detailed error messages
2. Thorough Logging: Good use of info!, debug!, and error! logging for monitoring execution flow
3. Input Validation: Proper validation of parameters including account value thresholds and balance checks
4. State Management: Well-structured account state tracking with debug printing methods
5. Test Data: Includes realistic test data for both perp and spot markets
6. Modular Design: Clean separation of concerns between API client, core writer, and business logic

Areas for Improvement ⚠️

Security Concerns

1. Price Manipulation Risk (hypercore_api.rs:406-473, payback_loan_test.rs:489-510)

   • Uses external market prices without additional validation
   • Recommendation: Consider implementing price bounds checking or oracle validation

2. Integer Overflow/Underflow (corewriter.rs:84-97)

   let size = notional / market_price;
   (size * 100_000_000.0) as u64  // Potential overflow

   • Recommendation: Add overflow checks before casting to u64

3. Floating Point Precision (payback_loan_test.rs:744-746)

   let calculated_amount = initial_margin + unrealized_pnl - cum_funding_all_time - close_position_fee - buffer;

   • Financial calculations using f64 can lead to precision errors
   • Recommendation: Use decimal types for financial calculations

Performance Considerations

1. Sequential API Calls (payback_loan_test.rs:489-510)

   • Multiple sequential calls to HyperCore API could be parallelized
   • Recommendation: Batch related API calls where possible

2. Polling with Fixed Intervals (hypercore_api.rs:694-736)

   tokio::time::sleep(Duration::from_secs(2)).await;

   • Fixed 2-second polling intervals may be inefficient
   • Recommendation: Implement exponential backoff or event-based notifications

3. Large Test Data Files

   • 44KB+ JSON files included in binary
   • Recommendation: Consider loading test data dynamically or using smaller representative datasets

Bugs and Code Issues

1. Potential Race Condition (payback_loan_test.rs:587-599)

   • Order cancellation wait uses OrderWaitCondition::Filled which seems incorrect for cancel operations
   • Recommendation: Use appropriate wait condition or implement cancel-specific validation

2. Hardcoded Magic Numbers (hyperliquid/src/lib.rs)

   pub const SPOT_SELL_PRICE_RATIO: f64 = 0.98;
   pub const PERP_CLOSE_PRICE_RATIO: f64 = 0.98;

   • Recommendation: Make these configurable or document the rationale

3. Inconsistent Error Types (payback_loan_test.rs:216-222)

   • Mix of parsing errors and internal errors for similar validation failures
   • Recommendation: Standardize error classifications

Test Coverage Issues

1. Missing Edge Case Tests

   • No tests for market price edge cases (zero, negative, extremely large values)
   • No tests for network timeout scenarios
   • Limited error path testing

2. Test Data Dependency

   • Tests depend on static JSON files which may become outdated
   • Recommendation: Add tests with mock data or data generation

Architecture Concerns

1. Function Complexity (payback_loan_test.rs:201-934)

   • Single function with 700+ lines handling multiple responsibilities
   • Recommendation: Break into smaller, focused functions

2. Type Safety (hypercore_api.rs:55-59)

   pub struct MetaAndAssetCtxsResponse(pub Vec<serde_json::Value>);

   • Using serde_json::Value reduces type safety
   • Recommendation: Define proper structs for better compile-time checks

Specific Line Comments

• hypercore_api.rs:634-638: CLOID conversion logic is complex - consider extracting to helper function
• payback_loan_test.rs:378-391: Account value validation logic should be extracted to reusable function
• corewriter.rs:5-7: Random CLOID generation using timestamp could create collisions - consider adding entropy

Overall Assessment

The implementation demonstrates good understanding of the domain and includes necessary safety checks. The main concerns are around financial calculation precision, error handling consistency, and function complexity. The security model appears sound but would benefit from additional price validation mechanisms.

Priority Recommendations:

1. Address floating-point precision in financial calculations
2. Add overflow protection for integer conversions
3. Break down the main payback function into smaller components
4. Improve test coverage for edge cases
5. Consider making price ratios configurable

The code is production-ready with the above improvements addressed.

---

[Kailai-Wang]

As agreed with @kziemianek - we'll merge this PR first and address problems in separate PRs.