Cash Modules

This contract is the main neobank financial operations module for EtherFi Safe 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 Safe.

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

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 safe,
    address spender,
    address referrer,
    bytes32 txId,
    BinSponsor binSponsor,
    address[] calldata tokens,
    uint256[] calldata amountsInUsd,
    bool shouldReceiveCashback
) external whenNotPaused onlyEtherFiWallet onlyEtherFiSafe(safe)

Processes a spending transaction, transferring funds from the Safe 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 Safe to the settlement dispatcher. In Credit mode, tokens are borrowed against the Safe's collateral.

Input Parameters:

Name	Type	Description
safe	address	The address of the EtherFi Safe
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 safe,
    address token,
    uint256 amountInUsd
) public whenNotPaused onlyEtherFiWallet onlyEtherFiSafe(safe)

Repays borrowed tokens in Credit mode.

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

Input Parameters:

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

requestWithdrawal

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

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

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

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

Input Parameters:

Name	Type	Description
safe	address	The address of the EtherFi Safe
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 Safe owner addresses that signed the withdrawal request
signatures	bytes[]	Array of signatures corresponding to the signers

processWithdrawal

function processWithdrawal(address safe) public onlyEtherFiSafe(safe)

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
safe	address	The address of the EtherFi Safe

setMode

function setMode(
    address safe,
    Mode mode,
    address signer,
    bytes calldata signature
) external onlyEtherFiSafe(safe) onlySafeAdmin(safe, signer)

Sets the operational mode for a Safe (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
safe	address	The address of the EtherFi Safe
mode	Mode	The target mode (Direct Pay or Credit)
signer	address	Address of the Safe admin signing the transaction
signature	bytes	Signature from the signer authorizing this mode change

updateSpendingLimit

function updateSpendingLimit(
    address safe,
    uint256 dailyLimitInUsd,
    uint256 monthlyLimitInUsd,
    address signer,
    bytes calldata signature
) external onlyEtherFiSafe(safe) onlySafeAdmin(safe, signer)

Updates the spending limits for a Safe.

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

Input Parameters:

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

setCashbackSplitToSafeBps

function setCashbackSplitToSafeBps(
    address safe,
    uint256 splitInBps,
    address signer,
    bytes calldata signature
) external onlyEtherFiSafe(safe) onlySafeAdmin(safe, signer)

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

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

Input Parameters:

Name	Type	Description
safe	address	The address of the EtherFi Safe
splitInBps	uint256	Percentage in basis points to allocate to the Safe
signer	address	Address of the Safe 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 safe) external view returns (Mode)

Gets the current operational mode of a Safe.

Considers pending mode changes that have passed their delay period.

Input Parameters:

Name	Type	Description
safe	address	The address of the EtherFi Safe

Return Values:

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

canSpend

function canSpend(
    address safe,
    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 Safe has sufficient balance or borrowing power for the specified tokens and amounts.

Input Parameters:

Name	Type	Description
safe	address	The address of the EtherFi Safe
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 safe,
    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
safe	address	The address of the EtherFi Safe
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 safe
) external view returns (SafeCashData memory safeCashData)

Gets comprehensive cash data for a Safe.

Aggregates data from multiple sources including DebtManager and CashModule.

Input Parameters:

Name	Type	Description
safe	address	The address of the EtherFi Safe

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 (Safe or spender)

Return Values:

Type	Description
uint256	Pending cashback amount in USD

getData

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

Retrieves cash configuration data for a Safe.

Input Parameters:

Name	Type	Description
safe	address	Address of the EtherFi Safe

Return Values:

Type	Description
SafeData	Data structure containing Safe cash configuration

Events

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

WithdrawalRequested

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

Emitted when a withdrawal is requested.

WithdrawalProcessed

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

Emitted when a withdrawal is processed.

Spend

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

Emitted when tokens are spent from a Safe.

Cashback

event Cashback(
    address indexed safe,
    address indexed spender,
    uint256 spendingInUsd,
    address cashbackToken,
    uint256 cashbackAmountToSafe,
    uint256 cashbackInUsdToSafe,
    uint256 cashbackAmountToSpender,
    uint256 cashbackInUsdToSpender,
    bool indexed paid
)

Emitted when cashback is calculated and potentially distributed.

ReferrerCashback

event ReferrerCashback(
    address indexed safe,
    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 safe,
    Mode prevMode,
    Mode newMode,
    uint256 incomingModeStartTime
)

Emitted when the operational mode of a Safe is changed.

SpendingLimitChanged

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

Emitted when a spending limit is changed.