Component: Protocol Vault Ledger

Description

The Protocol Vault Ledger manages token information for both liquidity providers (LPs) and strategy providers (SPs) by processing cross-chain messages from the Protocol Vault. It updates the net asset value (NAV) of strategy funds and finalizes token information for all providers. These operations are executed by the operator (backend engine), and the period ID is updated after all processes are completed. The process follows these steps:

1. Call updateStrategyFundAssets to update the NAV of each strategy fund.

2. Call updateLPAndStrategyFund to handle deposit and withdraw operations.

3. Call allocateToFunds to distribute the deposit and withdraw amounts to each strategy fund.

4. Call settleMainAndStrategyFunds and settleAccounts to finalize the token information.

5. Call updatePeriodId to update the period ID.

Invariants

1. Cross-chain--message processing

   • When receiving a cross-chain message from the Protocol Vault, it updates the pending amount of token information, which will be finalized after all processes are completed.

2. Strategy fund asset updates

   • Performance fees are deducted from strategy funds based on high water mark (HWM) value.

   • After updating all strategy funds, isUpdateStrategyFundAssets[periodId] is set to true to prevent double-updating.

3. Token-information updates

   • Each deposit and withdraw operation has a unique requestId.

   • The isOpHandled is set to true after processing to prevent double-handling.

4. Withdraw operations

   • When handling withdrawals, the userClaimInfo mapping is updated to manage claimable amounts for each provider.

5. Fund allocation

   • Total deposit and withdraw amounts are distributed to each strategy fund based on their respective share amounts.

   • The isAllocatedToFunds[periodId] is set to true after allocation to prevent double-allocation.

6. Settlement process

   • Token information for each provider and fund is updated by converting pending amounts to final amounts.

7. Period-ID management

   • The period ID increases by one when updated; old period IDs cannot be reused.

8. Claim updates

   • The operator updates claimable amounts for providers in target chains.

   • The isUserClaimHandled prevents double-claiming.

   • Cross-chain claim-update messages are sent via the VaultCrossChainManager contract.

9. Asset distribution

   • The operator distributes assets to target chains.

   • The isAssetDistributed[periodId] prevents double-distribution.

   • Cross-chain asset-distribution messages are sent via the VaultCrossChainManager contract.

Test coverage

Key cases covered

1. Asset distribution

   • Verifies correct distribution of assets to target chains

2. Claim updates

   • Tests updates to claimable amounts for providers in target chains

3. Operation handling

   • Validates proper handling of deposit and withdraw operations

4. Token-information updates

   • Confirms successful updates for all token information

Attack surface

• Cross-chain--message processing

  • Messages are protected by the VaultCrossChainManager's security measures.

  • Message content cannot be manipulated by other users.

  • There is replay protection through the nonce.

• Unauthorized calls

  • Only the operator can call the functions.

  • Only the cross-chain manager can send cross-chain messages.

  • All processes verify signatures of data from the backend engine.