feat(vaults/v2): Core Logic - Operations, Accounting, and Inflight Management

[zmanian]

PR B: Core Business Logic

This PR implements all core business logic for Vaults V2, including multi-position operations, cursor-based accounting, and comprehensive inflight funds management.

Note: Reviews should focus on the logic files only. Proto and state files are reviewed in PR A.

Summary

Implements the heart of the Vaults V2 system with:

• Multi-position deposit/withdrawal operations
• Cursor-based accounting with atomic snapshots
• Complete inflight funds lifecycle management
• Cross-chain operations and remote position management
• Oracle integration for NAV updates

Key Changes

Core Vault Operations (keeper/msg_server_vaults_v2.go)

• ✅ Deposit: Creates new position with auto-increment ID per user
• ✅ RequestWithdrawal: Position-specific withdrawals with queue management
• ✅ SetYieldPreference: Per-position yield preferences
• ✅ ProcessWithdrawalQueue: Batch processing with position tracking
• ✅ Deposit velocity tracking and limits enforcement

Accounting System (keeper/accounting.go)

• ✅ Cursor-based pagination: Handles large user sets efficiently
• ✅ Atomic snapshots: All-or-nothing accounting updates
• ✅ Residual tracking: Fair distribution of fractional amounts
• ✅ Message-triggered: Via UpdateVaultAccounting (no BeginBlock)
• ✅ Support for both shares and position-based accounting

Inflight Funds Management

• ✅ keeper/inflight_lifecycle.go: Complete lifecycle management
• ✅ InitiateRemotePositionRedemption: Strategist-triggered redemptions
• ✅ ProcessIncomingWarpFunds: Marks funds as arrived via warp route
• ✅ Stale inflight detection and cleanup
• ✅ Route capacity enforcement
• ✅ Amount mismatch handling (fees/slippage)

Cross-Chain Operations

• ✅ RemoteDeposit/RemoteWithdraw: Cross-chain fund movements
• ✅ Rebalance: Multi-position rebalancing
• ✅ ProcessInFlightPosition: Update inflight status
• ✅ Route and position management

Oracle System (keeper/hyperlane*.go)

• ✅ hyperlane.go: Hyperlane integration utilities
• ✅ hyperlane_nav.go: NAV message processing
• ✅ Oracle registration and management
• ✅ Position value updates via cross-chain messages
• ✅ NAV recalculation with accounting protection

Files to Review

Critical Business Logic (Deep Review Required)

• keeper/msg_server_vaults_v2.go (~2755 lines) - All message handlers
• keeper/accounting.go (~384 lines) - Accounting math and distribution
• keeper/inflight_lifecycle.go (~294 lines) - Inflight funds state machine

Supporting Logic

• keeper/hyperlane_nav.go (~221 lines) - Oracle NAV updates
• keeper/hyperlane.go (~56 lines) - Hyperlane utilities

Testing

Comprehensive test coverage included:

# Multi-position operations
go test ./keeper -run TestMultiPosition -v

# Inflight funds flow
go test ./keeper -run TestInflightFundsFlow -v

# Accounting system
go test ./keeper -run TestAccounting -v

Security Considerations

High-Risk Areas

1. Accounting Math: Residual tracking, overflow protection
2. Position Isolation: Ensure positions don't interfere
3. Oracle Trust: NAV updates from cross-chain messages
4. Inflight State: Consistency across chains

Dependencies

• Works with: PR A (Infrastructure)
• Required by: PR C (Integration)

Review Checklist

Critical

• Accounting math is correct and handles edge cases
• Position isolation is maintained
• Inflight state transitions are valid
• Oracle updates are properly validated
• No overflow/underflow vulnerabilities

Important

• Error handling is comprehensive
• Events are emitted for all state changes
• Gas consumption is reasonable
• Test coverage is adequate

Estimated Review Time

3-4 hours (deep review of business logic required)

---

Part 2 of 3 in the simplified Vaults V2 implementation.

[zmanian]

✅ Updated with latest changes

This PR has been updated with the latest changes from zaki/managed-vault-implementation (commit ce8a37b).

Key updates in this push:

• Complete removal of shares-based logic from accounting
• Position-based yield distribution using deposit_amount
• Comprehensive NAV yield tracking tests added

Files changed in Core Logic (this PR's focus):

• keeper/accounting.go - Now uses position.DepositAmount for yield calculations, no more shares references
• keeper/msg_server_vaults_v2_test.go - Updated tests to use position-based assertions
• keeper/msg_server_vaults_v2_nav_yield_test.go - NEW: Comprehensive test suite for NAV yield tracking

New test coverage includes:

1. Basic NAV update and yield accrual
2. Proportional yield distribution among multiple users
3. Users opting out of yield (receive_yield = false)
4. Cumulative yield across multiple NAV updates
5. Yield tracking with withdrawals
6. NAV decrease handling (no negative yield)
7. Cursor-based pagination for large user sets
8. Residual handling for fair distribution with rounding

The accounting logic now correctly distributes yield based on deposit amounts rather than shares.