Component: ManagementAccount

Description

The ManagementAccount is a noncustodial smart contract wallet that serves as the core of the Hyperbeat Pay system. It allows users to maintain custody of their crypto assets while enabling card payment settlements through the Hyperbeat backend. It operates in two distinct modes: SPENDING mode, which directly debits the settlement token held in the account for card payments, and CREDIT mode, which authorizes the operator to borrow settlement tokens on behalf of the user against collateral deposited in services.

The ManagementAccount is responsible for the following:

• Asset management. Users can deposit funds into the account via the deposit function or by directly transferring tokens to the contract. The available balance is calculated as the current settlement-token balance in the contract minus the amount requested for withdrawal. For withdrawals, settlement-token withdrawals in SPENDING mode require a cooldown period and operator approval after the cooldown expires. All other token withdrawals are instant. Withdrawal fees are deducted from the withdrawal amount when finalizing the withdrawal.

• Settlement operations. The operator can call settle to debit settlement tokens for card payments; settle consumes the spending-limit allowance configured by the user. In CREDIT mode, the user must authorize the operator to borrow settlement tokens on behalf of the user.

• Service integration. Services (e.g., MorphoService) implement the IService interface and return Call[] arrays that the ManagementAccount executes. The ManagementAccount maintains a list of approved services and executes protocol-specific sequences by requesting a service to build low-level calls (deposit/withdraw/borrow/repay/custom) that it then executes.

Invariants

Settlement protection

• Operator-settlement transfers must not exceed the remaining spending allowance.

• In SPENDING mode, the available settlement-token balance must remain above the spending allowance configured by the user.

• In SPENDING mode, user withdrawals of the settlement token require a cooldown period and operator approval before processing. The Hyperbeat backend must ensure there are no pending card payments before approving such withdrawals.

• In CREDIT mode, user withdrawals from the current credit service to the account require cooldown and operator approval before processing. The Hyperbeat backend must ensure there are no pending card payments before approving such withdrawals.

• Mode changes require operator approval. The Hyperbeat backend must ensure there are no pending card payments before approving mode changes.

Token whitelist enforcement

• Any token used in deposits, service actions, settlement, or withdrawals must be whitelisted by the TokenWhitelistRegistry.

• The settlement-token address must be retrieved from the factory.

Service integrity

• A service must be registered and active in the ServiceRegistry and explicitly approved by the owner before use; unapproved services cannot be called.

• The credit service cannot be revoked if it is the current _creditService and the account is in CREDIT mode.

Upgrade safety

• Upgrades are UPGRADER_ROLE-gated and only allowed to implementations whitelisted by the factory.

Attack surface

• Operator approval-restriction bypass. Users can change the operator, which could bypass the approval restrictions enforced by the onlyOperator modifier (see Finding ref↗).

• The token input surface. The token input is validated to ensure it is whitelisted in the TokenWhitelistRegistry during deposit and withdrawal operations, preventing users from inputting malicious token addresses.

• The service input surface. The _validateRegisteredService check in executeServiceAction ensures the service is registered and active in the ServiceRegistry, preventing users from inputting malicious services for actions.

• Contract upgrade surface. Upgrade implementations are limited by the factory whitelist, preventing arbitrary implementations from being set.