Component: VaultManager

Description

The VaultManager contract tracks and manages the balances of various tokens across multiple chains. It maintains information about which tokens, brokers, and trading symbols are allowed. It also handles the freezing and unfreezing of balances for withdrawals or cross-chain rebalancing. This ensures that only approved operations can modify on-chain and frozen balances.

Invariants

1. Balance-tracking consistency

   • All on-chain balances for tokens are accurately increased or decreased when addBalance or subBalance is called.

   • Amounts frozen via frozenBalance must appear as a corresponding reduction in the normal balance and an increase in the frozen balance.

2. Whitelist enforcement

   • Only tokens, brokers, and symbols explicitly enabled via setAllowed* methods are considered valid.

3. Ledger authorization

   • Only the ledger, via onlyLedger, can modify token balances, ensuring external contracts or EOA addresses cannot directly manipulate vault balances.

Test coverage

Key cases covered

1. Add and sub balance

   • Verifies that calls to addBalance and subBalance correctly update on-chain token balances

2. Overflow check

   • Ensures a revert occurs if an operation attempts to subtract more than the current balance

3. Freeze and finalize

   • Confirms that freezing and finalizing correctly moves amounts from the normal balance to the frozen balance and back

4. Freeze overflow revert

   • Verifies the contract reverts if attempting to freeze more tokens than are available

5. Set and unset whitelists

   • Tests dynamically adding and then removing a token, broker, or symbol from the allowed sets, ensuring the whitelist logic remains consistent

Attack surface

• Unauthorized ledger calls

  • Functions that change balances (frozenBalance, addBalance, subBalance) are restricted to the ledger contract, protected via onlyLedger.

• Whitelist manipulation

  • The owner-only methods setAllowed* ensure that adding or removing items from the broker, token, or symbol whitelist is access-restricted.

• Rebalance life cycle

  • Burn and mint operations follow a pending → success/failure flow. If the life-cycle checks or status tracking were flawed, tokens could be lost, minted incorrectly, or remain stuck in a partially frozen state.