Component: Ledger

Description

The Ledger contract serves as the core record keeper of the system. It holds the on-chain state for user accounts, including balances and open positions, and coordinates major actions like deposits, withdrawals, settlements, and liquidations. It is split into multiple implementation contracts (LedgerImplA, LedgerImplB, LedgerImplC).

Invariants

1. Account-state consistency

   • Each user’s token balances and open positions must be accurately updated whenever deposits, withdrawals, or trades occur.

   • Balances frozen for withdrawals are always subtracted from the user’s available balance and remain frozen until finalization.

2. Strict role validation

   • Only the designated cross-chain manager can notify the ledger of deposits (accountDeposit).

   • Only the authorized operator manager can initiate settlement, liquidation, or withdrawal actions.

   • Ownership controls define who can change critical addresses or set a new implementation contract addresses.

3. Signature and broker checks

   • EIP-712 typed signatures are used for user-generated withdrawals to ensure authenticity (Signature.verifyWithdraw).

   • All deposit and withdrawal requests must involve an allowed broker and token hash as validated by the VaultManager.

4. Delegation integrity

   • Calls to LedgerImplA, LedgerImplB, and LedgerImplC via _delegatecall must revert on failure or invalid data, preventing partial or inconsistent state updates.

Test coverage

Key cases covered

1. EIP-712 verification (test_verify_EIP712)

   • Confirms that a valid chainId and signature data pass the Signature.verifyWithdraw check successfully

2. EIP-712 failure (testRevert_verify_EIP712)

   • Tests that using an incorrect chainId causes the signature verification to fail, ensuring invalid withdrawals are rejected

3. Depositing funds (test_deposit)

   • Verifies that a deposit triggered by the cross-chain manager correctly updates ledger balances and vault balances in the VaultManager

4. Withdrawal approval (test_withdraw_approve)

   • Confirms that when the operator manager initiates a withdrawal, the user's tokens are immediately frozen in the ledger and the vault, awaiting final completion

5. Broker allowance reversion (testRevert_depositNotAllowedBroker)

   • Ensures that attempting a deposit with a broker hash not on the allowed list causes a revert, protecting the system from unauthorized brokers

6. Finalizing withdrawal (test_withdraw_finish)

   • Demonstrates the entire withdrawal life cycle from deposit through freezing and eventual unfreezing

   • Verifies that cross-chain communication triggers the final state changes, unfreezing balances once the transfer is complete

Attack surface

• Cross-chain--manager compromise

  • The Ledger trusts calls from crossChainManagerAddress to record deposits. If the cross-chain manager is compromised, false deposits could be processed. However, each deposit is validated against broker and token allowlists, reducing risk.

• OperatorManager misuse

  • The operator manager can initiate withdrawals, settlements, and liquidations. If compromised, it could attempt unauthorized operations. Role checks and signature verifications mitigate this.

• Implementation-contract updates

  • Only the contract owner can set new addresses for LedgerImplA, LedgerImplB, and LedgerImplC. A malicious owner or an owner role compromise could point these to malicious logic.

• Invalid EIP-712 signatures

  • Withdrawals require correct signatures aligned to the user's chainId. If the signature does not match or the chainId is incorrect, the withdrawal fails. This protects against replay attacks and unauthorized requests.