Devine OS Hyperliquid Vault Settlement

Devine OS Vaults

The Devine OS Hyperliquid Vault System Design runs on Arbitrum, providing and bridging institutional-grade proprietary quantitative trading strategies executed on the Hyperliquid L1 trading venue with the Devine OS DeFi ecosystem.

The System facilitates two main functions:

Allows DeFi users to deploy capital into institutional-grade quantitative trading strategies executed by asset managers, generating yield without active management.
Creates a credit bridge between the collateral embedded in Hyperliquid L1 trading strategies and DeFi protocols on Arbitrum, enabling that collateral to be reused as credit to compose layered yield opportunities.

Deposit Flow for Users

This document outlines the step-by-step process for users to deposit USDC into the Hyperliquid Vault. The flow ensures secure, traceable, and efficient programmatic handling of deposits, leveraging both on-chain smart contracts and off-chain infrastructure managed by Devine OS.

1. User Initiation (Frontend → Smart Contract)

The deposit process begins when a user submits a USDC deposit request through the platform's frontend interface, interacting with the Vault Smart Contract.

User Action: The user initiates a deposit by specifying the amount of USDC to deposit into a specific vault via the frontend interface.
Smart Contract Interaction: The frontend triggers a transaction to the HyperliquidVault smart contract, calling the depositUSDC(amount) function, which transfers USDC from the user’s wallet to the vault.
Contract Validation: The smart contract performs the following checks and actions:
- Balance Check: Verifies that the user has sufficient USDC balance and allowance for the vault contract.
- Fee Application: Applies a 0.1% protocol fee on the deposited amount.
- Net Amount Calculation: Calculates the net deposit amount (after fees) to be processed.
- Pending Deposit Record: Records the deposit as pending with a unique nonce (a sequential identifier for the user’s deposits) and stores details such as:
  - user: The user’s wallet address.
  - amount: The net USDC amount (in micro-USDC, with 6 decimal places).
  - nonce: The unique identifier for the deposit.
  - block.timestamp: The timestamp when the deposit was initiated.
- Event Emission: Emits a DepositInitiated event, containing:
  - User address
  - Deposit amount (net of fees)
  - Nonce
  This event signals the off-chain Devine OS infrastructure to begin processing.

2. Off-Chain Batch Processing (Devine OS → Deposit Router Wallet)

The Devine OS infrastructure listens for DepositInitiated events and aggregates deposits into batches for efficient transfer to the trading venue.

Event Detection: Devine OS monitors the HyperliquidVault contract for DepositInitiated events, which are processed in batches to optimize gas costs and transaction efficiency.
Batch Creation: Deposits are grouped into batches based on a predefined time window (e.g., every minute). Each batch is assigned:
- A unique batch_id (formatted as ISO 8601, e.g., 20250608T1410Z).
- A batch_nonce for on-chain tracking.
Transfer to Deposit Router Wallet: The net USDC amounts from multiple user deposits are transferred from the vault smart contract to the platform-controlled Deposit Router Wallet. This wallet stages funds before they are sent to the trading venue.
Reorg Protection: Devine OS checks for blockchain reorganizations by verifying block hashes against cached values, ensuring only valid deposits are processed.

3. Transfer to Trading Venue (Deposit Router Wallet → Hyperliquid L1 Trading Wallet)

The batched USDC is transferred from the Deposit Router Wallet to the Hyperliquid L1 Trading Wallet for deployment in trading strategies.

Batch Transfer: Devine OS initiates a transaction via the HyperBridge smart contract, calling batchedDepositWithPermit, which transfers the total USDC amount for the batch to the Hyperliquid L1 Trading Wallet. This transaction uses an EIP-712 signature to authorize the transfer.
Allowance Check: Before the transfer, Devine OS verifies that the Deposit Router Wallet has sufficient USDC allowance for the HyperBridge contract. If insufficient, it calls approve on the USDC contract to set the required allowance.
Balance Verification: Ensures the Deposit Router Wallet has sufficient USDC to cover the batch transfer.
Transaction Confirmation: The transaction is broadcasted. The system waits for the transaction hash from the USDC contract to confirm success.

4. Off-Chain Confirmation (Trading Venue → Devine OS)

Once the funds are credited to the Hyperliquid L1 Trading Wallet, the Asset managers begin executing allocating the funds to the quantitative trading strategy, and Devine OS confirms the deposit on-chain to finalize the process and mint the user ERC4626 tokens representing their portion of overall NAV of the quantitative trading strategy.

Deposit Detection: The Asset Managers programmatically detect the successful credit of USDC to their designated non-custodial Hyperliquid L1 Trading Wallet to begin executing the strategy, this is traded like a traditional seperately managed account, where the custody of user funds remain under multi-signature control between the Devine DAO and its core contributors.
Confirmation Payload: Devine OS sends a confirmation payload via its backend API endpoint (/confirm-deposit). The payload includes:
- vault_id: The unique identifier of the vault (e.g., DG01).
- user: The user’s wallet address.
- amount: The net USDC amount (in micro-USDC, as a string).
- tx_hash: The transaction hash of the batch transfer to the trading wallet.
- nonce: The deposit nonce.
- confirm_id: A unique backend identifier derived from the transaction hash and user address (e.g., keccak256(tx_hash + user)).
Validation: Devine OS validates the payload by:
- Checking the transaction receipt to ensure the correct USDC amount was transferred from the Deposit Router Wallet to the Hyperliquid L1 Trading Wallet using the USDC contract as a proxy.
- Verifying that the deposit is still pending (not confirmed) and matches the recorded amount in the vault.
- Many other miscellaneous solvency and security checks.

5. On-Chain Finalization (Devine OS → Smart Contract)

After validation, Devine OS finalizes the deposit by updating the vault’s state and minting shares to the user.

Vault Update: Devine OS calls updateVaultExchangeBalance on the HyperliquidVaultRouter contract to reflect the new USDC balance available for trading.
Deposit Confirmation: Calls confirmDeposit(user, amount, tx_hash, nonce) on the vault contract, which:
- Verifies the pending deposit details (user, amount, nonce).
- Mints vault shares (collateral tokens) to the user’s address based on the net deposit amount and the current Net Asset Value (NAV).
- Marks the deposit as confirmed, removing it from the pending queue.
- Emits a DepositConfirmed event with details of the user, amount, transaction hash, and nonce.

6. User Notification and Finalization

Once the deposit is confirmed on-chain, the user receives their vault shares, and the frontend interface updates to reflect the completed deposit.

Share Minting: The user’s wallet receives vault shares proportional to their net deposit amount, based on the vault’s NAV at the time of confirmation.
Notification: The frontend notifies the user of the successful deposit, including:
- Transaction Hash: The tx_hash of the batch transfer and confirmation transaction, verifiable on the Arbitrum block explorer.
- Shares Minted: The number of vault shares credited to their wallet.
- Completion Timestamp: The time the deposit was finalized.
Audit Trail: All actions are logged with detailed on-chain metadata (e.g., batch IDs, transaction hashes, timestamps) for transparency and manual reconciliations upon system downtime.

Example Timeline

User Submits Deposit: At 2025-06-08 14:00:00, a user deposits 10,000 USDC via the frontend.
Smart Contract Processes: The HyperliquidVaultRouter applies a 0.2% fee (20 USDC), records 9,980 USDC as pending, and emits a DepositInitiated event.
Devine OS Batches: By 2025-06-08 14:01:00, Devine OS groups the deposit into a batch (20250608T1410Z) with other deposits, totaling 100,000 USDC.
Transfer to Trading Wallet: Devine OS transfers 100,000 USDC from the Deposit Router Wallet to the Hyperliquid L1 Trading Wallet via batchedDepositWithPermit.
Devine OS And Asset Managers Programmatically Confirm: At 2025-06-08 14:05:00, the Devine OS confirms the deposit and sends a payload to confirm the deposit, this is relayed to through the backend API.
On-Chain Finalization: Devine OS calls confirmDeposit, minting e.g 9,980 vault shares to the user based on the NAV and ERC4626 invariants, and emits a DepositConfirmed event.
User Notified: By 2025-06-08 14:06:00, the user receives 9,980 vault shares and a notification with transaction details.

This flow ensures a secure, efficient, and transparent deposit process, with robust safeguards to handle edge cases and maintain system integrity.

Withdrawal Flow for Users

This document outlines the step-by-step process for users to withdraw funds from the HyperliquidVaultRouter and associated quantitative trading strategy. The flow ensures secure, transparent, and efficient processing of withdrawal requests, leveraging both on-chain smart contracts and off-chain infrastructure managed by Devine OS.

1. User Initiation (Frontend → Smart Contract)

The withdrawal process begins when a user submits a request through the frontend interface of the platform. This section describes the initial steps and the smart contract interactions that occur.

User Action: The user specifies the number of vault shares they wish to redeem via the platform's frontend interface.
Smart Contract Interaction: The request is sent to the HyperliquidVaultRouter smart contract by calling the initiateWithdrawal(shares) function.
Contract Validation: The smart contract performs the following checks and actions:
- Share Verification: Ensures the user has sufficient shares in their balance to cover the withdrawal request.
- Snapshot Creation: Captures a WithdrawalQuote snapshot, which includes:
  - shares: The number of shares the user wishes to withdraw.
  - NAV: At the start of each batch settlement window, the system snapshots the vault’s Net Asset Value (NAV). All withdrawals submitted within that window are calculated for settlement using that NAV and are processed in the order they were received, with the earliest withdrawal in the window determining the sequencing.
  - totalSupply: The total number of vault shares in circulation.
  - confirmedUserDeposits: The user's total confirmed deposits.
  - userTotalShares: The total shares held by the user.
  - totalConfirmedDeposits: The total confirmed deposits in the vault.
- Pending Status: Records the withdrawal request under a unique nonce (a sequential identifier for the user's withdrawals) and marks it as pending.
- Event Emission: Emits a WithdrawalInitiated event, which includes details of the user, shares, and nonce. This event signals off-chain systems to begin processing.

2. Off-Chain Settlement Execution (Devine OS → Asset Manager)

Once the WithdrawalInitiated event is emitted, the Devine OS off-chain infrastructure takes over to process the withdrawal request. This involves batching withdrawals, coordinating with the asset manager, and ensuring liquidity for settlement.

Event Detection: Devine OS listens for WithdrawalInitiated events emitted by the HyperliquidVaultRouter smart contract. These events are processed in batches to optimize efficiency and reduce transaction costs.
Batch Creation: Withdrawal requests are grouped into batches based on a predefined time window (e.g., every minute). The Batch Withdrawal Settlement Quote is issued based on the first withdrawal within the batch. Each batch is assigned a unique batch_id (formatted as ISO 8601, e.g., 20250608T1410Z) and a batch_nonce for on-chain tracking.
Settlement Instruction: For each batch, Devine OS generates a SettlementInstruction object and sends it to the asset manager (or an automated system developed by the Devine OS manager API) to prepare the necessary funds. The instruction contains critical parameters to ensure solvency and alignment with the current NAV.

What Devine OS Sends to the Asset Manager

The SettlementInstruction object includes the following fields to guide the asset manager in preparing funds:

vault_id: A unique string identifier for the vault associated with the withdrawal batch (e.g., DG01).
batch_id: A unique ISO 8601-formatted identifier for the batch (e.g., 20250608T1410Z), ensuring no duplication or replay.
total_usdc_required: The total amount of USDC (in micro-USDC, with 6 decimal places, as a string) required to fulfill the batch, net of fees, calculated based on the latest NAV snapshot.
total_shares: The total number of vault shares being redeemed in the batch, ensuring alignment between off-chain and on-chain accounting.
deadline: A strict UTC deadline (ISO 8601, e.g., 2025-06-08 14:10:00) by which the batch must be settled. If exceeded, the batch is considered stale and may be rejected and quarantined or processed in the next window depending on specific conditions.
quote_time: The exact UTC timestamp (ISO 8601, e.g., 2025-06-08 14:00:00) of the NAV quote used to calculate the per-share value, ensuring deterministic pricing.
notes (optional): Freeform text providing additional context, special instructions, or batch-specific metadata (e.g., "High-priority batch due to large withdrawal volume").

This SettlementInstruction serves as the canonical directive for the batch, providing all necessary metadata for deterministic execution and auditability.

3. Asset Manager Response (Asset Manager → Devine OS)

The asset manager algorithmically processes the SettlementInstruction and responds with a ManagerConfirmation payload to confirm the availability of funds or report any issues. This step closes the settlement loop and enables the vault to finalize withdrawals on-chain.

What the Asset Manager Sends Back

The ManagerConfirmation object includes the following fields:

vault_id: The unique identifier of the vault, matching the vault_id from the SettlementInstruction.
batch_id: The same ISO 8601-formatted batch ID from the SettlementInstruction, ensuring correct linkage between instruction and confirmation.
status: The outcome of the asset manager’s execution process. Valid values are:
- "completed": All required funds (USDC) have been prepared and are available for redemption.
- "failed": The batch could not be processed, requiring review or retry by Devine OS.
tx_hash: The on-chain transaction hash (e.g., 0x...) representing the liquidation, transfer, or operation that made the USDC available. This is used for traceability and audit purposes.
usdc_ready: The actual USDC amount available to the vault (in micro-USDC, as a string with 6 decimal places), reflecting real-time adjustments for volatility between the snapshot NAV at the start of the batch window and the manager’s settlement time. This value is checked against total_usdc_required with an allowed deviation threshold to ensure solvency.
timestamp: The UTC datetime (ISO 8601, e.g., 2025-06-08 14:05:00) when the confirmation was sent, enabling temporal consistency checks and deadline enforcement.

This confirmation acts as the final attestation that the manager has fulfilled the required liquidity provision per the batch instruction. It is a prerequisite for:

Unlocking and finalizing user withdrawals
Triggering the on-chain confirmWithdrawalWithPnL() or equivalent logic
Updating vault solvency state and archival logs
Burning users shares against settled NAV.

Devine OS then coordinates withdrawal execution by first retrieving funds from the designated Hyperliquid Layer 1 wallet, then forwarding the net USDC to the appropriate HyperliquidVaultRouter contract. Upon receipt, the router processes the corresponding withdrawal confirmations, returns collateral to the user, and burns the associated vault shares, completing the settlement loop with full solvency and share reconciliation.

4. Batch Confirmation and On-Chain Settlement (Devine OS → Smart Contract)

Once the asset manager confirms the availability of funds, Devine OS proceeds to finalize the withdrawal batch on-chain.

Batch Confirmation: Devine OS submits a transaction to the vault contract by calling confirmBatchUsdcReceived(quote_timestamp, batch_nonce, usdc_ready_net). This records the available USDC for the batch on-chain, ensuring the vault has sufficient liquidity.
Liquidity Verification: The system verifies that the vault’s liquidity (getVaultLiquidity) meets or exceeds the required USDC for the batch. If insufficient, the batch is re-queued for the next settlement window, and users are notified of the delay.
Individual Withdrawal Confirmation: For each withdrawal in the batch, Devine OS calls the confirmWithdrawalWithPnL(user, shares, tx_hash, nonce, user_pnl, batch_nonce) function on the vault contract. This:
- Validates the pending withdrawal data (shares, nonce, and quote timestamp).
- Verifies backend fee calculations and the user’s net payout and profit/loss (PnL), applying a 30% fee on positive PnL.
- Burns the associated shares
- Transfers the calculated USDC amount to the user’s address.
- Marks the withdrawal as confirmed, removing it from the pending queue.
Batch Cleanup: After all withdrawals in the batch are confirmed, Devine OS removes the batch from the active batch set in and updates audit records.

This flow ensures a secure, efficient, and transparent withdrawal process, with robust safeguards to handle edge cases and maintain system integrity.

5. User Notification and Finalization

Once the withdrawal is confirmed on-chain, the user receives their USDC payout directly to their wallet address. The frontend interface updates to reflect the completed withdrawal, and the user is notified of the successful transaction, including:

Transaction Hash: The on-chain tx_hash for the withdrawal, allowing the user to verify the transaction on the blockchain (e.g., via Arbitrum block explorer).
Amount Received: The net USDC amount credited to their wallet, after fees.
Completion Timestamp: The time the withdrawal was finalized.

Example Timeline

User Submits Request: At 2025-06-08T14:00:00Z, a user requests to withdraw 1000 shares via the frontend.
Smart Contract Records: The HyperliquidVaultRouter captures a WithdrawalQuote and emits a WithdrawalInitiated event.
Devine OS Processes: By 2025-06-08T14:01:00Z, Devine OS groups the request into a batch (20250608T1410Z) and sends a SettlementInstruction to the asset manager, requesting 10,000,000 µUSDC for 1000 shares.
Asset Manager Confirms: At 2025-06-08T14:05:00Z, the asset manager responds with a ManagerConfirmation, indicating status: "completed", usdc_ready: "10000000", and a tx_hash.
On-Chain Confirmation: Devine OS calls confirmBatchUsdcReceived and confirmWithdrawalWithPnL, transferring 9,700,000 µUSDC (after a 30% fee on positive PnL) to the user’s wallet.
User Notified: By 2025-06-08T14:06:00Z, the user receives the USDC and a notification with the transaction details.

PreviousOverview NextHyperliquidVaultRouter Contract

Last updated 8 days ago