FactorLPVault.sol

Contract Overview

FactorLPVault.sol manages the LP Vault configurations as well as the concentrated liquidity positions created via this vault. Positions in the vault are represented via a ERC721 NFT which is uniquely identified via the positionId.

The LP Vault builds on top of the Leverage Vault to enable leveraged LP positions thereby significantly amplifying the potential returns. All positions created on this vault share the same initial strategy implementation and LP fees configuration.

The vault implements OpenZeppelin's upgradeable proxy pattern. The vault owner is able to propose a new strategy contract implementation for the vault and upgrade the vault's strategy implementation if the strategy has been registered.

Properties

Public

Property	Type	Modifier	Description
FEE_SCALE	uint256	public; constant	The scale denominator for the fees. Defaulted to 1e18.
changeRangeFee	uint256	public	The fee that is charged on when the position's range is changed.
compoundFee	uint256	public	The fee that is charged on the harvested rewards whenever the accrued position rewards are claimed.
feeRecipient	address	public	The address of the fee recipient.
strategyImplementation	address	public	The address of the strategy contract that is implemented for this LP vault.
factorLPDescriptor	address	public	The address of the LP vault descriptor which facilitates sharing of encoded LP vault token data (i.e. URI).
currentPositionId	uint256	public	An integer which is used to track the positions created via this LP Vault. Incremented by 1 with every new position created (i.e. always 1 more than the last created positionId).
positions	mapping(uint256 => address)	public	Maps the position to their implemented strategy contract address.
isUpgrade	mapping(address => mapping(address => bool))	internal	A nested mapping of strategy contracts which have been registered as eligible by the Vault Manager owner. Enables registered proposed strategies to be implemented.
nonces	mapping(address => uint256)	public	An incremental counter which keeps track of the number of positions created by a depositor. Used to generate the corresponding strategy address.
allowedLeverageVaults	mapping(address => bool)	public	A mapping of whitelisted leverage vaults which the LP strategy can utilize.

Events

PositionCreated()

Emitted when a new position is created on the LP Vault.

Arguments

Argument	Type	Description
id	uint256	The identifier of the new position that was created.
vault	address	The address of the strategy implementation that was deployed with the newly created position.

UpgradeRegistered()

Emitted when a proposed strategy implementation address is registered by the LP Vault owner.

Arguments

Argument	Type	Description
baseImpl	address	The address of the existing strategy contract that is implemented by the vault.
upgradeImpl	address	The address of the proposed strategy contract to be implemented.

UpgradeRemoved()

Emitted when a proposed strategy implementation is removed from (i.e. deregistered) isUpgrade by the LP Vault owner.

Arguments

Argument	Type	Description
baseImpl	address	The address of the existing strategy contract that is implemented by the vault.
upgradeImpl	address	The address of the proposed strategy contract to be implemented.

DescriptorChanged()

Emitted when the leverage descriptor contract address is changed by the LP Vault owner.

Arguments

Argument	Type	Description
descriptor	address	The address of the msg.sender (i.e. depositor) that deposited into the vault.

Structs

PermitData

A struct that defines the signed permit signatures for the LP Vault token0 and token1.

Variables	Type	Description
v0	uint8	The recovery id (recid) that enables faster verification of the permit signature.
r0	bytes32	One half of a pair of integers (r and s) that forms the output signature of a signed permit transaction.
s0	bytes32	One half of a pair of integers (r and s) that forms the output signature of a signed permit transaction.
v1	uint8	The recovery id (recid) that enables faster verification of the permit signature.
r1	bytes32	One half of a pair of integers (r and s) that forms the output signature of a signed permit transaction.
s1	bytes32	One half of a pair of integers (r and s) that forms the output signature of a signed permit transaction.

Constructor

Factor Vault contracts implements OpenZeppelin's upgradeable contracts design and locks the Vault contract upon initialization to avoid contract takeover by an attacker. More info can be found on OpenZeppelin Docs.

Methods

initialize() - public initializer

The contract initialization function which initializes the contract with the vault params and initial fee configurations. Defaults the fee recipient to the msg.sender (i.e. LP vault creator).

Parameters

Params	Type	Description
_strategyImplementation	address	The address of the strategy contract to be implemented for this LP vault.
_factorLPDescriptor	address	The address of the LP vault descriptor that will describe the LP vault token.
_name	string	The name of the LP vault collection. Used as the NFT collection name.
_symbol	string	The symbol of the LP vault collection. Used as the NFT collection symbol.
_weth	address	The address of the WETH token.

setAllowedLeverageVault() - external onlyOwner

Allows the owner of the LP vault contract to configure the list of permitted underlying Leverage vaults. LP vaults are built atop of Leverage vaults to enable greater capital efficiency through utilizing leveraged positions for liquidity management.

Parameters

Params	Type	Description
vault	address	The address of the underlying Leverage vault.
allowed	bool	The address of the asset lending pool to be changed to.

createDepositAndExecute() - external payable returns

Creates a new position representing the configurations of a depositor's position in the leverage vault (only consists of the position structure and not actual liquidity).

To create the position, a new instance of the strategyImplementation contract is initalized with every newly created position ID for this vault. The relevant token amounts are transferred to the newly created Strategy contract address.

The newly created position NFT (representing a position in the LP vault) is sent to the msg.sender.

Parameters

Params	Type	Description
token0	address	The address of the liquidity position's token0 (i.e. 1 half of the token pair sorted alphabetically by address).
token1	address	The address of the liquidity position's token1 (i.e. the other half of the token pair sorted alphabetically by address).
amount0	uint256	The amount of token0 being deposited into the LP vault.
amount1	uint256	The amount of token1 being deposited into the LP vault.
data	bytes[]	A bytes array that contains the encoded liquidity position data (i.e. token amount, price range, etc.)
newNonce	uint256	The nonce for the msg.sender incremented by 1 that tracks the position count for the depositor.
leverageVault	address	The address of the underlying Leverage vault for the newly created position.

Returns

Type	Description
uint256	The new currentPositionId after a position is created (i.e. newly created position ID plus 1).
strategy	The address of the newly deployed strategy contract which was implemented for the position.

Events

Events	Description
PositionCreated()	Emits the currentPositionId and the implemented strategy address.

permit() - external payable

Handles the ERC20 permit() function that enables the LP Vault to spend token0 and token1 from the msg.sender (i.e. depositor) address.

Leverages the Multicallable.sol contract.

Parameters

Params	Type	Description
token	address	The address of the token which is being permitted.
amount	uint256	The amount of token which the LP Vault is allowed to spend.
paramsPermit	bytes	The ERC20 permit parameters.

refund() - external payable onlyOwner

Allows the owner of the LP Vault to refund any remaining tokenAddress in the vault.

Leverages the Multicallable.sol contract.

Parameters

Params	Type	Description
tokenAddress	address	The address of the token remaining in the vault.
amount	uint256	The amount of token to be refunded form the vault.

deposit() - external payable

Allows the safe transfer of a specified amount of token from the msg.sender (i.e. depositor) to the LP Vault contract.

Parameters

Params	Type	Description
token	address	The address of the token being deposited.
amount	uint256	The amount of token being deposited.

_decodeParamsPermit() - internal pure returns

An internal helper function that facilitates the decoding of permit parameters for LP vault token0 and token1.

Parameters

Params	Type	Description
paramsPermit	bytes	The encoded bytes representation of the permit signatures.

Returns

Type	Description
PermitData	The decoded permit signature parameters which includes the recovery id and output signatures.

burnPosition() - external

Allows the owner of the position to burn the NFT representing their zero-balance position.

Parameters

Params	Type	Description
positionId	uint256	The identifier for the position to be burned.

tokenURI() - public view override returns

Returns the encoded Uniform Resource Identifier (URI) of the position id that is being queried.

Parameters

Params	Type	Description
id	uint256	The positionId of the position whose URI data is being queried.

Returns

Type	Description
string	The encoded URI for the token representing the position in the LP Vault.

setDescriptor() - external onlyOwner

Allows the owner of the LP Vault to change the address of the factorLPDescriptor.

Events

Events	Description
DescriptorChanged()	Emits the address of the new LP Vault descriptor.

getNextStrategyAddress() - public view returns

Checks whether the upgrade from baseImplementation to upgradeImplementation has been registered by the Leverage Vault owner.

Parameters

Params	Type	Description
user	address	The address of user for which the Strategy contract will be deployed with the newly created position.
nonce	uint256	The internal tracker for the number of positions created by the user. To get the address of the next Strategy contract to be deployed, the current user nonce (tracked under the nonces mapping) must be incremented by 1.

Returns

Type	Description
address	The address of the Strategy contract implemented for this LP Vault.

isRegisteredUpgrade() - external view returns

Checks whether the upgrade from baseImplementation to upgradeImplementation has been registered by the LP Vault owner.

Parameters

Params	Type	Description
baseImplementation	address	The address of the previous strategy contract.
upgradeImplementation	address	The address of the proposed updated strategy contract.

Returns

Type	Description
bool	true = Proposed strategy has been registered by owner. false = Proposed strategy has not been registered by owner.

registerUpgrade() - external onlyOwner

Allows the LP Vault owner to register a strategy upgrade from baseImplementation to upgradeImplementation. Proposed strategies must be registered before it can be implemented.

Parameters

Params	Type	Description
baseImplementation	address	The address of the previous strategy contract.
upgradeImplementation	address	The address of the proposed updated strategy contract.

Events

Events	Description
UpgradeRegistered()	Emits the registered strategy upgrade proposal.

removeUpgrade() - external onlyOwner

Allows the LP Vault owner to remove a previously registered strategy upgrade proposal from isUpgrade.

Parameters

Params	Type	Description
baseImplementation	address	The address of the previous strategy contract.
upgradeImplementation	address	The address of the proposed updated strategy contract.

Events

Events	Description
UpgradeRemoved()	Emits the strategy upgrade proposal that was removed.

updateImplementation() - external onlyOwner

Allows the LP Vault owner to update the strategyImplementation with a newly provided address.

Parameters

Params	Type	Description
_strategyImplementation	address	The address of the new strategy implementation contract.

setFeeRecipient() - external onlyOwner

Allows the LP Vault owner to update the feeRecipient with a newly provided address.

Parameters

Params	Type	Description
recipient	address	The address that receives the LP fees.

setChangeRangeFee() - external onlyOwner

Allows the LP Vault owner to update the changeRangeFee that is charged on the collected trading fees that have accrued to the position whose range is being changed.

The original changeRangeFee is defaulted to 1e15 (i.e. 0.1%). The newFee provided is scaled by the LP Vault contract's FEE_SCALE which is defaulted to 1e18 on vault initialization. That is, a newFee of 1e16 is equivalent to 1% fee (i.e. 1e16/1e18).

Parameters

Params	Type	Description
newFee	uint256	The amount of change range fee to charge.

setCompoundFee() - external onlyOwner

Allows the LP Vault owner to update the compoundFee that is charged on the accrued trading fees which is being reinvested (i.e. compounded) into the position.

The original compoundFee is defaulted to 1e15 (i.e. 0.1%). The newFee provided is scaled by the LP Vault contract's FEE_SCALE which is defaulted to 1e18 on vault initialization. That is, a newFee of 1e16 is equivalent to 1% fee (i.e. 1e16/1e18).

Parameters

Params	Type	Description
newFee	uint256	The amount of compounding fee to charge.

version() - external pure returns

Returns the LP Vault version which is hardcoded based on contract deployment.

Returns

Type	Description
string	The LP Vault version.

_increaseBalance() - internal virtual override

An internal function that overrides the ERC721 _increaseBalance() function meant to increase the number of NFT collection tokens held by the account.

Parameters

Params	Type	Description
account	address	The address of the position holder.
amount	uint128	The amount of LP Vault token count to be added to the existing account balances.

_update() - internal virtual override returns

An internal function that overrides the ERC721 _update() function meant to update the owner of the tokenId.

Parameters

Params	Type	Description
to	address	The address to transfer ownership of tokenId to. Mints (or burns) the position NFT if the current owner (or to) is the zero address.
tokenId	uint128	The identifier for the LP Vault NFT to be updated.
auth	address	An optional params where passing in a non-zero value checks if the provided address has the rights to transfer the token (i.e. owner or approved).

Returns

Type	Description
address	The address of the LP Vault NFT (representing the position) before the update.

supportsInterface() - public view override returns

An internal function that overrides the ERC721 supportsInterface() function that returns true if this LP Vault contract implements the interface defined by interfaceId.

Parameters

Params	Type	Description
interfaceId	bytes4	The encoded bytes data representing the interface being queried.

Returns

Type	Description
bool	true = interfaceId is supported by the LP Vault contract false = interfaceId is not supported by the LP Vault contract

receive() - public view override returns

Fallback function that enables the contract to receive ETH.