DomFiVault

DomFiVault

Collateral vault for Domination Finance perpetual exchange

Intertwined with DomFiPerp. Holds LP funds. Provides an ERC4626 interface for users to deposit and withdraw, and for future staking integrations.

• Gets deposit/withdraw fee amounts from FeeCalculator and sends them to FeeDistributor.
• Optionally, triggers a RewardDistributor.

Addresses

Chain	Address
Arbitrum Sepolia	0xeB19A8991dfE23bbe746a683653Ac5D9E607209E
Base Sepolia	0x8619E0b5C3352Ef70C5dfF056a3e59DD6b8137Fc
Base Mainnet	0x16030cD4b46C94df63405c39bdd7E8254Bb63842

Functions

initialize

function initialize(
	struct StorageInstance app_,
	contract IERC20 collateral_,
	string name_,
	string symbol_
) external

_tryGetAssetDecimals

function _tryGetAssetDecimals(contract IERC20 asset_) internal view returns (bool, uint8)

Dev note

Attempts to fetch the asset decimals. A return value of false indicates that the attempt failed in some way.

decimals

function decimals() public view returns (uint8)

Dev note

Decimals are computed by adding the decimal offset on top of the underlying asset's decimals. This "original" value is cached during construction of the vault contract. If this read operation fails (e.g., the asset has not been created yet), a default of 18 is used to represent the underlying asset's decimals.

See {IERC20Metadata-decimals}.

asset

function asset() public view returns (address)

Dev note

Returns the address of the underlying token used for the Vault for accounting, depositing, and withdrawing.

• MUST be an ERC-20 token contract.
• MUST NOT revert.

convertToShares

function convertToShares(uint256 assets) public view returns (Shares)

Dev note

See {IERC4626-convertToShares}.

convertToAssets

function convertToAssets(Shares shares) public view virtual returns (uint256)

Dev note

See {IERC4626-convertToAssets}.

balance

function balance() public view returns (uint256)

name

function name() public view returns (string)

Dev note

Returns the name of the token.

symbol

function symbol() public view returns (string)

Dev note

Returns the symbol of the token, usually a shorter version of the name.

totalSupply

function totalSupply() public view returns (uint256)

Dev note

See {IERC20-totalSupply}.

balanceOf

function balanceOf(address account) public view returns (uint256)

Dev note

See {IERC20-balanceOf}.

transfer

function transfer(address to, uint256 value) public returns (bool)

Dev note

See {IERC20-transfer}.

Requirements:

• to cannot be the zero address.
• the caller must have a balance of at least value.

allowance

function allowance(address owner, address spender) public view returns (uint256)

Dev note

See {IERC20-allowance}.

approve

function approve(address spender, uint256 value) public returns (bool)

Dev note

See {IERC20-approve}.

NOTE: If value is the maximum uint256, the allowance is not updated on transferFrom. This is semantically equivalent to an infinite approval.

Requirements:

• spender cannot be the zero address.

transferFrom

function transferFrom(address from, address to, uint256 value) public returns (bool)

Dev note

See {IERC20-transferFrom}.

Emits an {Approval} event indicating the updated allowance. This is not required by the EIP. See the note at the beginning of {ERC20}.

NOTE: Does not update the allowance if the current allowance is the maximum uint256.

Requirements:

• from and to cannot be the zero address.
• from must have a balance of at least value.
• the caller must have allowance for from's tokens of at least value.

deposit

Deposit amount collateral to user with pre-approval instead of a signature. See deposit(..., signature).

function deposit(uint256 amount, address user) public returns (Shares shares)

Parameters

Name	Type	Description
amount	uint256	Collateral to deposit from msg.sender
user	address	Address credited with the deposit

Return Values

Name	Type	Description
shares	Shares	dfUSDC amount sent to user in exchange for this collateral

deposit

Deposit amount collateral to user with pre-approval instead of a signature. See deposit(..., signature).

function deposit(uint256 amount, address user, Shares minShares) public returns (Shares shares)

Parameters

Name	Type	Description
amount	uint256	Collateral to deposit from msg.sender
user	address	Address credited with the deposit
minShares	Shares	Revert if the deposit does not produce at least minShares

Return Values

Name	Type	Description
shares	Shares	dfUSDC amount sent to user in exchange for this collateral

deposit

Deposit amount collateral to user, calling ERC-2612 permit() using the attached signature and deadline. See EIP-4626.

function deposit(
	uint256 amount,
	address user,
	uint256 deadline,
	struct IVaultDomain.Signature signature,
	Shares minShares
) public returns (
	Shares shares
)

Parameters

Name	Type	Description
amount	uint256	Collateral to deposit from msg.sender
user	address	Address credited with the deposit
deadline	uint256	deadline for permit
signature	struct IVaultDomain.Signature	permit entitling DomFiVault to amount collateral
minShares	Shares	Slippage control. Ignored if zero. If nonzero, revert if a deposit yields less than minShares

Return Values

Name	Type	Description
shares	Shares	dfUSDC amount sent to user in exchange for this collateral

mint

function mint(Shares shares, address receiver) public returns (uint256)

Dev note

Mints exactly shares Vault shares to receiver by depositing amount of underlying tokens.

• MUST emit the Deposit event.
• MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the mint execution, and are accounted for during mint.
• MUST revert if all of shares cannot be minted (due to deposit limit being reached, slippage, the user not approving enough underlying tokens to the Vault contract, etc).

NOTE: most implementations will require pre-approval of the Vault with the Vault’s underlying asset token.

mint

function mint(Shares shares, address receiver, uint256 maxAssets) public returns (uint256)

mint

Mint shares shares to receiver, calling ERC-2612 permit() using the attached signature and signatureAssets. See EIP-2626 mint.

function mint(
	Shares shares,
	address receiver,
	uint256 deadline,
	struct IVaultDomain.Signature signature,
	uint256 signatureAssets,
	uint256 maxAssets
) public returns (
	uint256 assets
)

Parameters

Name	Type	Description
shares	Shares	Shares to mint
receiver	address	Account credited with the deposit
deadline	uint256	deadline for permit
signature	struct IVaultDomain.Signature	permit entitling DomFiVault to assets collateral
signatureAssets	uint256	Assets permitted to DomFiVault. This should be the expected assets or higher, in case share price increases
maxAssets	uint256	Slippage control. Ignored if zero. If nonzero, revert if more than maxAssets are required to mint shares.

Return Values

Name	Type	Description
assets	uint256	Collateral sent to the vault in exchange for these shares

withdraw

Withdraw assets to receiver by burning shares from account. Reverts unless

• instantWithdrawAvailable() == true
• OR account has a WithdrawRequest with at least shares available.

See EIP-4626 withdraw().

function withdraw(uint256 assets, address receiver, address account) public returns (Shares shares)

Parameters

Name	Type	Description
assets	uint256	Collateral units to withdraw
receiver	address	Send withdrawn collateral to this address
account	address	Address from which to burn shares. msg.sender must be that address or its manager

Return Values

Name	Type	Description
shares	Shares	dfUSDC burnt from account to make the withdrawal

withdraw

Withdraw assets to receiver by burning shares from account. Reverts unless

• instantWithdrawAvailable() == true
• OR account has a WithdrawRequest with at least shares available.

See EIP-4626 withdraw().

function withdraw(
	uint256 assets,
	address receiver,
	address account,
	Shares maxShares
) public returns (
	Shares shares
)

Parameters

Name	Type	Description
assets	uint256	Collateral units to withdraw
receiver	address	Send withdrawn collateral to this address
account	address	Address from which to burn shares. msg.sender must be that address or its manager
maxShares	Shares	Slippage control. Ignored if zero. If nonzero, revert if more than maxShares would be burnt to make this withdrawal

Return Values

Name	Type	Description
shares	Shares	dfUSDC burnt from account to make the withdrawal

redeem

function redeem(Shares shares, address receiver, address account) public returns (uint256 assets)

redeem

Redeem shares from account, and send the resulting collateral to receiver. Reverts unless

• instantWithdrawAvailable() == true
• OR account has a WithdrawRequest with at least shares available.

See EIP-4626 withdraw().

function redeem(
	Shares shares,
	address receiver,
	address account,
	uint256 minAssets
) public returns (
	uint256 assets
)

Parameters

Name	Type	Description
shares	Shares	dfUSDC to burn from account
receiver	address	Send collateral to this address
account	address	Address from which to burn shares. msg.sender must be that address or its manager
minAssets	uint256	Slippage control. Ignored if zero. If nonzero, revert unless the redemption yields at least minAssets

Return Values

Name	Type	Description
assets	uint256	collateral sent to receiver

requestable

Get max shares/assets that a user can request to withdraw

function requestable(address owner) external view returns (Shares shares, uint256 assets)

Parameters

Name	Type	Description
owner	address	account which will be redeeming shares

Return Values

Name	Type	Description
shares	Shares	dfUSDC that owner can request to redeem
assets	uint256	max assets that owner might receive by redeeming shares

getInstantRedeemAvailable

Whether instant redeems are available. When true, ERC4626 methods will work without a pre-existing request, and attempting to increase a request will instantly execute it.

function getInstantRedeemAvailable() public returns (bool available)

Dev note

DomFiPerp.getTotalPnL() is extremely expensive, call _computeUtilizationRatio() and save results if reuse is necessary.

Return Values

Name	Type	Description
available	bool	Whether instant redeems and withdraws are available

getUtilizationRatio

Compute current utilization ratio of the vault. Utilization ratio is the total size of all positions divided by the effective vault balance: the vault balance minus pending trader PnL, minus pending withdrawals.

function getUtilizationRatio() external returns (FPSigned utilizationRatio)

Return Values

Name	Type	Description
utilizationRatio	FPSigned	Current utilization ratio of the vault

_computeUtilizationRatio

function _computeUtilizationRatio() internal returns (bool instantRedeemAvailable, FPSigned utilizationRatio)

getPendingWithdraw

Get the amount of collateral tied up in redeem requests. This is the lesser of pendingWithdraw and the current value of pendingRedeem.

function getPendingWithdraw() public view returns (uint256)

previewRedeemRequest

Preview a withdraw request

function previewRedeemRequest(Shares shares, address account) external returns (uint64 duration, int64 offset)

Parameters

Name	Type	Description
shares	Shares	Shares that would be requested
account	address	Account for which to preview the request

Return Values

Name	Type	Description
duration	uint64	Duration of the resulting WithdrawRequest
offset	int64	Time until the resulting request begins.

availableFraction

function availableFraction(address account) public view returns (FPUnsigned)

makeRedeemRequest

Create or update a request to redeem shares from account. If instant redeems are available and receiver is set, immediately redeem shares from account.

function makeRedeemRequest(
	Shares shares,
	address account,
	address receiver,
	uint256 minAssets
) external returns (
	uint64 duration,
	uint64 beginsAt
)

Parameters

Name	Type	Description
shares	Shares	request permission to redeem shares from account. If a request already exists, the new shares must be at least as large
account	address	Address from which to redeem shares. Sender must be this address or its manager.
receiver	address	Instantly redeem to this address if possible. If 0x00, do not instantly redeem. Ignored if instant redeems are unavailable.
minAssets	uint256	Slippage parameter. If instant redeems are available, receiver is nonzero, and minAssets is nonzero, revert if the resulting instant redemption would yield less than minAssets. Ignored if instant redeems are unavailable.

maxWithdraw

Compute the max withdrawable assets for a user, based on instant withdrawal (if available) or any available withdraw request. Inclusive of fees.

function maxWithdraw(address owner) public returns (uint256 maxAssets)

Parameters

Name	Type	Description
owner	address	Account which will be making the withdrawal

Return Values

Name	Type	Description
maxAssets	uint256	Max assets owner could withdraw right now

_maxWithdraw

function _maxWithdraw(
	address owner
) internal returns (
	uint256 maxAssets,
	bool instantRedeemAvailable,
	FPSigned utilizationRatio
)

maxRedeem

Compute the max redeemable shares for a user, based on instant redemption (if available) or any available redeem request.

function maxRedeem(address owner) public returns (Shares maxShares)

Parameters

Name	Type	Description
owner	address	Account which will be making the withdrawal

Return Values

Name	Type	Description
maxShares	Shares	Max shares owner could cash in right now

_maxRedeem

function _maxRedeem(
	address owner
) internal returns (
	Shares maxShares,
	bool instantRedeemAvailable,
	FPSigned utilizationRatio
)

activeWithdrawRequest

Whether owner has an active withdraw request

function activeWithdrawRequest(address owner) public view returns (bool status)

Parameters

Name	Type	Description
owner	address	Address for which to check request

Return Values

Name	Type	Description
status	bool	false if request is nonexistent, complete, or expired, true otherwise

expiredWithdrawRequest

Whether owner has an expired withdraw request

function expiredWithdrawRequest(address owner) public view returns (bool status)

Parameters

Name	Type	Description
owner	address	Address for which to check request

Return Values

Name	Type	Description
status	bool	true if request expired, false if it's active, nonexistent, or completed

previewDeposit

Preview a deposit, with fees. See EIP-4626

function previewDeposit(uint256 assets) public view returns (Shares shares)

Parameters

Name	Type	Description
assets	uint256	Collateral to deposit

Return Values

Name	Type	Description
shares	Shares	dfUSDC that would be minted in exchange for assets

previewWithdraw

Preview an instant withdrawal at the current rate, with fees. See EIP-4626

function previewWithdraw(uint256 assets) public view returns (Shares shares)

Parameters

Name	Type	Description
assets	uint256	Collateral to withdraw

Return Values

Name	Type	Description
shares	Shares	dfUSDC that would be burnt to withdraw assets

previewRedeem

Preview an instant redemption at the current rate, with fees. See EIP-4626

function previewRedeem(Shares shares) public view returns (uint256 assets)

Parameters

Name	Type	Description
shares	Shares	dfUSDC to redeem

Return Values

Name	Type	Description
assets	uint256	collateral yielded by burning shares

totalAssets

Total withdrawable assets: deposits + fees - trader PnL.

function totalAssets() public view returns (uint256 totalManagedAssets)

Dev note

Unlike balanceOf(vault), this does not include position margin, since LPs are not entitled to position margin until positions are liquidated or closed.

Return Values

Name	Type	Description
totalManagedAssets	uint256	Total uncommitted assets in the vault

maxDeposit

Max deposit that receiver can receive. See EIP-4626.

function maxDeposit(address receiver) public view returns (uint256 maxAssets)

Parameters

Name	Type	Description
receiver	address	address that will be receiving the deposit

Return Values

Name	Type	Description
maxAssets	uint256	Maximum collateral that can be deposited for receiver

maxMint

Max shares that can be minted to receiver. See EIP-4626.

function maxMint(address receiver) public view returns (Shares maxShares)

Parameters

Name	Type	Description
receiver	address	address that will be receiving the minted shares

Return Values

Name	Type	Description
maxShares	Shares	Maximum collateral that can be minted for receiver

previewMint

Preview a mint, with fees. See EIP-4626

function previewMint(Shares shares) public view returns (uint256 assets)

Parameters

Name	Type	Description
shares	Shares	dfUSDC to mint

Return Values

Name	Type	Description
assets	uint256	collateral required to mint shares

enableUserDeposits

Enable or disable deposits by senders other than the owner.

function enableUserDeposits(bool allowDeposits) external

Parameters

Name	Type	Description
allowDeposits	bool	Whether users should be able to make additional deposits.

validateOI

function validateOI() public view returns (bool)

isTotalOpenInterestExceeded

function isTotalOpenInterestExceeded(uint256 balance_) external view returns (bool)

validateOIOnTransfer

Enable or disable calling DomFiPerp.validateOI on token transfer

function validateOIOnTransfer(bool validateOI_) external

Parameters

Name	Type	Description
validateOI_	bool	True if function should be called, false if not

maxCollateral

function maxCollateral() public view returns (uint256)

setMaxCollateral

Reject deposits and donations that would raise totalAssets beyond a maximum. Trader losses and fees can still raise balance above the max.

function setMaxCollateral(uint256 maxCollateral_) external

Parameters

Name	Type	Description
maxCollateral_	uint256	New maximum collateral balance

pendingRedeem

function pendingRedeem() public view returns (Shares)

pendingWithdraw

function pendingWithdraw() public view returns (uint256)

HEALTHY_UTILIZATION_RATIO

function HEALTHY_UTILIZATION_RATIO() public view returns (FPUnsigned)

setHealthyUtilizationRatio

Set the utilization ratio below which it's safe to let LPs withdraw immediately

function setHealthyUtilizationRatio(FPUnsigned healthyUtilizationRatio) external

Parameters

Name	Type	Description
healthyUtilizationRatio	FPUnsigned	new value for HEALTHY_UTILIZATION_RATIO

MAX_WITHDRAW_DURATION

function MAX_WITHDRAW_DURATION() public view returns (uint256)

setMaxWithdrawDuration

Set the worst-case duration for collateral withdrawals, in seconds. Request durations will be capped to this duration.

function setMaxWithdrawDuration(uint256 maxWithdrawDuration) external

Parameters

Name	Type	Description
maxWithdrawDuration	uint256	New value for MAX_WITHDRAW_DURATION

TOTAL_DURATION_PER_UTILIZATION_RATIO

function TOTAL_DURATION_PER_UTILIZATION_RATIO() public view returns (uint256)

setTotalDurationPerUtilizationRatio

Set TOTAL_DURATION_PER_UTILIZATION_RATIO, in seconds per (utilization % above healthy level) per (100% collateral withdrawal). To determine withdraw duration, we multiply this duration by the fraction of the vault being withdrawn, and then by the % utilization above the unhealthy utilization threshold.

With the default value of 100 days, withdrawing 10% of the vault would take 1 day for each 10% utilization ratio above the minimum.

function setTotalDurationPerUtilizationRatio(uint256 secondsPerUtilizationRatio) external

Parameters

Name	Type	Description
secondsPerUtilizationRatio	uint256	new value for TOTAL_DURATION_PER_UTILIZATION_RATIO

WITHDRAW_WINDOW

function WITHDRAW_WINDOW() public view returns (uint64)

setWithdrawWindow

Set WITHDRAW_WINDOW, in seconds. After request.duration has elapsed, users have this long to execute a request before it expires.

function setWithdrawWindow(uint64 withdrawWindow) external

Parameters

Name	Type	Description
withdrawWindow	uint64	new value for WITHDRAW_WINDOW

PENALTY_DURATION_MULTIPLIER

function PENALTY_DURATION_MULTIPLIER() public view returns (FPUnsigned)

setPenaltyDurationMultiplier

Set a new value for PENALTY_DURATION_MULTIPLIER

Penalty length is determined by multiplying duration by a scaling factor, PENALTY_DURATION_MULTIPLIER. At a 1x multiplier, repeatedly letting a request expire will result in a penalty of X, then a duration of X, then a penalty of X, etc. If a bank run occurs at a random time, the expected withdraw delay ([duration + penalty]/2) of the continuous withdraw attempts is exactly the same as that of a naive user who makes a withdraw request once the bank run begins: duration. However, this continuous withdraw strategy results in some tokens being immediately available, whereas the naive user starts from 0. It is not clear how to value this availability, so the contract owner should increase PENALTY_DURATION_MULTIPLIER if they notice users using continuous withdrawal strategies.

function setPenaltyDurationMultiplier(FPUnsigned penaltyDurationMultiplier) external

Parameters

Name	Type	Description
penaltyDurationMultiplier	FPUnsigned	New value of PENALTY_DURATION_MULTIPLIER

pendingWithdrawRequest

function pendingWithdrawRequest(address owner) public view returns (struct IVaultDomain.WithdrawRequest)

nextPenaltyRate

function nextPenaltyRate(address owner) public view returns (PerShare)

remainingPenaltySeconds

function remainingPenaltySeconds(address owner) public view returns (uint256)

transferRewardAmount

Donate collateral to the vault

function transferRewardAmount(uint256 rewardAmount) external

Dev note

Receives fees, rewards, etc. for distribution to depositors.

Parameters

Name	Type	Description
rewardAmount	uint256	collateral tokens to transfer from sender to vault

addReferralFee

Deposit a referral fee from FeeDistributor.

function addReferralFee(uint256 amount, address user) external returns (Shares shares)

Dev note

Does not apply deposit fees; only can be called by feeDistributor.

Parameters

Name	Type	Description
amount	uint256	Referral fee to deposit on behalf of user
user	address	Address to credit with this referral fee

distributeDecrease

Pay out any claimed PnL, and distribute trade fee, when a position is decreased.

function distributeDecrease(
	uint256 margin,
	address owner,
	address recipient,
	uint256 totalFee,
	int256 netPnl
) external

Dev note

Only callable by DomFiPerp. Decreases balance by PnL.

Parameters

Name	Type	Description
margin	uint256	Margin amount being decreased
owner	address	Owner of position being decreased; for fee redirect.
recipient	address	Address to receive any realized positive PnL
totalFee	uint256	Fee amount paid by the position's owner
netPnl	int256	PnL, with fee already applied, realized by decrease

approveAndUpdateLiquidatorReward

Process a liquidation

function approveAndUpdateLiquidatorReward(
	uint256 remainingReward,
	uint256 liquidatorReward,
	uint256 increaseBalance,
	address liquidator
) external

Dev note

Only callable by DomFiPerp

Parameters

Name	Type	Description
remainingReward	uint256	Leftover margin after liquidator reward and PnL
liquidatorReward	uint256	Collateral amount paid out to liquidator
increaseBalance	uint256	Increase vault balance by this much
liquidator	address	Address which will be approved for liquidatorReward

withdrawWithoutFee

Remove collateral from the Vault and send it to recipient.

function withdrawWithoutFee(address recipient, uint256 amount) external

Dev note

Only callable by DomFiPerp. Does not update balance; this is for adjusting position margin (which does not contribute to balance).

Parameters

Name	Type	Description
recipient	address	Address to receive collateral
amount	uint256	Collateral amount to remove

Events

VaultUpdated

event VaultUpdated(uint256 maxCollateral, uint256 balance)