Cash Modules

This contract is the main neobank financial operations module for EtherFi Vault users. User interactions with the EtherFi Cash system occur via the CashModule contract.

CashModule allows users to:

• Spend funds in Direct Pay mode or Credit mode

• Set spending limits

• Request and process withdrawals

• Earn cashback rewards

• Repay borrowed funds

• Switch between operational modes

• Configure cashback splits

CashModule is implemented as a set of contracts following the proxy pattern with distinct components:

• CashModuleCore: Core financial operations

• CashModuleSetters: Configuration management

• CashModuleStorageContract: Storage implementation

• CashLens: Read-only views

Write Methods

setupModule

function setupModule(bytes calldata data) external

Initializes the Cash Module for a new Vault.

Function is invoked when the Cash Module is added to an EtherFi Vault.

Sets up default spending limits and mode configuration.

Input Parameters:

Name	Type	Description
data	bytes	The encoded initialization data containing daily limit, monthly limit, and timezone offset

spend

function spend(
    address vault,
    address spender,
    address referrer,
    bytes32 txId,
    BinSponsor binSponsor,
    address[] calldata tokens,
    uint256[] calldata amountsInUsd,
    bool shouldReceiveCashback
) external 

Processes a spending transaction, transferring funds from the Vault in either Direct Pay or Credit mode.

Requires the caller to have the ETHER_FI_WALLET_ROLE.

When spending in Direct Pay mode, tokens are transferred directly from the Vault to the settlement dispatcher. In Credit mode, tokens are borrowed against the Vault's collateral.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault
spender	address	The address of the user initiating the spend
referrer	address	The address of the referrer (or address(0) if none)
txId	bytes32	Unique transaction identifier
binSponsor	BinSponsor	Identifier of the bin sponsor (Rain or Reap)
tokens	address[]	Array of token addresses to spend
amountsInUsd	uint256[]	Array of amounts in USD value to spend (must match tokens array length)
shouldReceiveCashback	bool	Flag indicating if the transaction should earn cashback

repay

function repay(
    address vault,
    address token,
    uint256 amountInUsd
) public 

Repays borrowed tokens in Credit mode.

When repaying, the Vault must have sufficient balance of the token being used for repayment.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault
token	address	The address of the token used for repayment
amountInUsd	uint256	The amount to repay, expressed in USD value

requestWithdrawal

function requestWithdrawal(
    address vault,
    address[] calldata tokens,
    uint256[] calldata amounts,
    address recipient,
    address[] calldata signers,
    bytes[] calldata signatures
) external 

Requests a withdrawal of tokens from the Vault to a recipient address.

The function requires valid signatures from the Vault owners according to the Vault's threshold configuration.

Initiates a withdrawal request that will be available for processing after the withdrawal delay period.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault
tokens	address[]	Array of token addresses to withdraw
amounts	uint256[]	Array of token amounts to withdraw
recipient	address	Address that will receive the tokens
signers	address[]	Array of Vault owner addresses that signed the withdrawal request
signatures	bytes[]	Array of signatures corresponding to the signers

processWithdrawal

function processWithdrawal(address vault) public 

Processes a pending withdrawal request after the delay period has passed.

The function executes the token transfers to the recipient specified in the withdrawal request.

Fails if the withdrawal delay period has not yet elapsed.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault

setMode

function setMode(
    address vault,
    Mode mode,
    address signer,
    bytes calldata signature
) external 

Sets the operational mode for a Vault (Direct Pay or Credit).

Switching to Credit mode may have a delay period depending on configuration. Switching to Direct Pay mode happens immediately after verification.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault
mode	Mode	The target mode (Direct Pay or Credit)
signer	address	Address of the Vault admin signing the transaction
signature	bytes	Signature from the signer authorizing this mode change

updateSpendingLimit

function updateSpendingLimit(
    address vault,
    uint256 dailyLimitInUsd,
    uint256 monthlyLimitInUsd,
    address signer,
    bytes calldata signature
) external

Updates the spending limits for a Vault.

Changes to spending limits take effect after the configured delay period.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault
dailyLimitInUsd	uint256	New daily spending limit in USD
monthlyLimitInUsd	uint256	New monthly spending limit in USD
signer	address	Address of the Vault admin signing the transaction
signature	bytes	Signature from the signer authorizing this update

setCashbackSplitToSafeBps

function setCashbackSplitToSafeBps(
    address vault,
    uint256 splitInBps,
    address signer,
    bytes calldata signature
) external 

Sets the percentage of cashback that goes to the Vault (versus the spender).

The split is expressed in basis points, where 10000 represents 100%.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault
splitInBps	uint256	Percentage in basis points to allocate to the Vault
signer	address	Address of the Vault admin signing the transaction
signature	bytes	Signature from the signer authorizing this change

clearPendingCashback

function clearPendingCashback(address[] calldata users) external whenNotPaused

Clears pending cashback for a list of users.

Attempts to retrieve any pending cashback and distribute it to the specified users.

Input Parameters:

Name	Type	Description
users	address[]	Array of user addresses to clear pending cashback for

Read Methods

getMode

function getMode(address vault) external view returns (Mode)

Gets the current operational mode of a Vault.

Considers pending mode changes that have passed their delay period.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault

Return Values:

Type	Description
Mode	The current operational mode (Direct Pay or Credit)

canSpend

function canSpend(
    address vault,
    bytes32 txId,
    address[] calldata tokens,
    uint256[] calldata amountsInUsd
) public view returns (bool, string memory)

Checks if a spending transaction can be executed.

Validates if the Vault has sufficient balance or borrowing power for the specified tokens and amounts.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault
txId	bytes32	Transaction identifier
tokens	address[]	Array of token addresses to spend
amountsInUsd	uint256[]	Array of amounts in USD to spend

Return Values:

Type	Description
bool	Whether the spending is allowed
string	Error message if spending is not allowed

maxCanSpend

function maxCanSpend(
    address vault,
    address token
) public view returns (
    uint256 returnAmtInCreditModeUsd,
    uint256 returnAmtInDebitModeUsd,
    uint256 spendingLimitAllowance
)

Calculates the maximum amount that can be spent in both Credit and Direct Pay modes.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault
token	address	The address of the token to spend

Return Values:

Type	Description
uint256	Maximum amount that can be spent in Credit mode (USD)
uint256	Maximum amount that can be spent in Direct Pay mode (USD)
uint256	Remaining spending limit allowance

getSafeCashData

function getSafeCashData(
    address vault
) external view returns (SafeCashData memory safeCashData)

Gets comprehensive cash data for a Vault.

Aggregates data from multiple sources including DebtManager and CashModule.

Input Parameters:

Name	Type	Description
vault	address	The address of the EtherFi Vault

Return Values:

Type	Description
SafeCashData	Comprehensive data structure containing mode, balances, borrowing power, and more

getPendingCashback

function getPendingCashback(address account) external view returns (uint256)

Gets the pending cashback amount for an account in USD.

Input Parameters:

Name	Type	Description
account	address	Address of the account (Vault or spender)

Return Values:

Type	Description
uint256	Pending cashback amount in USD

getData

function getData(address vault) external view returns (SafeData memory)

Retrieves cash configuration data for a Vault.

Input Parameters:

Name	Type	Description
vault	address	Address of the EtherFi Vault

Return Values:

Type	Description
SafeData	Data structure containing Vault cash configuration

Events

The CashModule emits events for all major operations through the CashEventEmitter:

WithdrawalRequested

event WithdrawalRequested(
    address indexed vault,
    address[] tokens,
    uint256[] amounts,
    address indexed recipient,
    uint256 finalizeTimestamp
)

Emitted when a withdrawal is requested.

WithdrawalProcessed

event WithdrawalProcessed(
    address indexed vault,
    address[] tokens,
    uint256[] amounts,
    address indexed recipient
)

Emitted when a withdrawal is processed.

Spend

event Spend(
    address indexed vault,
    bytes32 indexed txId,
    BinSponsor indexed binSponsor,
    address[] tokens,
    uint256[] amounts,
    uint256[] amountInUsd,
    uint256 totalUsdAmt,
    Mode mode
)

Emitted when tokens are spent from a Vault.

Cashback

event Cashback(
    address indexed vault,
    address indexed spender,
    uint256 spendingInUsd,
    address cashbackToken,
    uint256 cashbackAmountToVault,
    uint256 cashbackInUsdToVault,
    uint256 cashbackAmountToSpender,
    uint256 cashbackInUsdToSpender,
    bool indexed paid
)

Emitted when cashback is calculated and potentially distributed.

ReferrerCashback

event ReferrerCashback(
    address indexed vault,
    address indexed referrer,
    uint256 spendingInUsd,
    address cashbackToken,
    uint256 referrerCashbackAmt,
    uint256 referrerCashbackInUsd,
    bool indexed paid
)

Emitted when referral cashback is calculated and potentially distributed.

ModeSet

event ModeSet(
    address indexed vault,
    Mode prevMode,
    Mode newMode,
    uint256 incomingModeStartTime
)

Emitted when the operational mode of a Vault is changed.

SpendingLimitChanged

event SpendingLimitChanged(
    address indexed vault,
    SpendingLimit oldLimit,
    SpendingLimit newLimit
)

Emitted when a spending limit is changed.