Functions
ERC20 Functions
transfer(_to : address, amount : uint256) -> bool
The transfer function allows a user (identified by msg.sender) to transfer a specified amount of tokens to another address (_to). This function updates the balances of the sender and the recipient and emits a Transfer event.
Returns
bool: Returns True indicating the successful completion of the function.
Parameters
_to (address): The recipient's address.
amount (uint256): The number of tokens to transfer from the caller (msg.sender) to the recipient (_to).
Implementation Details
Deduct the specified amount from the balance of msg.sender.
Add the specified amount to the balance of the recipient (_to).
Emit the Transfer event to log the token transfer details.
Return True to indicate successful execution.
Usage
Any user holding tokens can call the transfer function to send a portion or all of their tokens to another address. The user must ensure they have a sufficient balance before attempting to transfer.
transferFrom(_from : address, _to : address, amount : uint256) -> bool
The transferFrom function is utilized for transferring tokens on behalf of another address. Before calling this function, the token holder (_from address) should have granted permission to the caller (identified by msg.sender) to spend tokens on their behalf. This is usually achieved via the approve function in the ERC20 standard. This function updates the balances of the sender (_from) and the recipient (_to), decrements the allowance of msg.sender for _from by the transferred amount, and emits a Transfer event.
Returns
bool: Returns True indicating the successful completion of the function.
Parameters
_from (address): The address of the sender from which tokens will be debited.
_to (address): The recipient's address where tokens will be credited.
amount (uint256): The number of tokens to transfer from _from to _to.
Implementation Details
Deduct the specified amount from the balance of _from.
Add the specified amount to the balance of the recipient (_to).
Decrease the allowed amount for the msg.sender to spend on behalf of _from.
Emit the Transfer event to log the token transfer details.
Return True to indicate successful execution.
Usage
This function is typically used when a user wants to allow a third party (like a smart contract or another user) to transfer tokens on their behalf. Before doing so, the user must have approved the third party for the specified amount using the approve function.
approve(_spender : address, _value : uint256) -> bool
The approve function is utilized for the token owner (identified by msg.sender) to grant permission to another address (_spender) to spend up to _value tokens on their behalf. This function internally calls the _approve utility function and returns True upon successful execution.
Returns
bool: Returns True indicating the successful completion of the function.
Parameters
_spender (address): The address that is being granted permission to spend on behalf of the caller.
_value (uint256): The number of tokens the spender is allowed to spend.
Implementation Details
Set the allowance of _spender for _owner to the specified _value.
Emit the Approval event to log the approval details.
Usage
This function is typically used when a token owner wants to allow a third party (like a smart contract or another user) to transfer tokens on their behalf. Once the permission is granted, the _spender can use the transferFrom function to move the approved tokens.
permit(_owner: address, _spender: address, _value: uint256, _deadline: uint256, _v: uint8, _r: bytes32, _s: bytes32,) -> bool
The permit function is an implementation of the EIP-2612 permit pattern, which allows token approvals (as described by the ERC20 standard) to be made via a signature, rather than requiring a separate transaction. The function allows a token owner to approve a spender to spend a specified amount by providing a valid signature. It's particularly useful for enabling gasless transactions.
Returns
bool: Returns True indicating the successful completion of the function.
Parameters
_owner (address): The address of the token owner who is granting permission to spend.
_spender (address): The address that is being granted permission to spend on behalf of the owner.
_value (uint256): The number of tokens the spender is allowed to spend.
_deadline (uint256): The timestamp after which the permit signature becomes invalid.
_v (uint8), _r (bytes32), _s (bytes32): ECDSA signature parameters.
Implementation Details
Ensure the _owner is not an empty address and the current timestamp is not past the _deadline.
Compute the domain separator and digest from the provided parameters and signature.
Use the ecrecover function to extract the signer's address from the signature and ensure it matches the _owner.
Increment the nonce of the _owner to prevent signature replays.
Call the _approve utility function to set the allowance.
Usage
This function is typically used in scenarios where token owners wish to delegate the allowance setting process to third parties, without needing the owners to send a transaction from their account. This can be useful in dApps to improve user experience or enable gasless interactions.
Notes
The function uses the EIP-712 typed data specification to ensure that the signed data is clear and unambiguous. This is why there's a need for a domain separator.
The function checks against a deadline to ensure the validity of the signature for a certain period.
The nonce is incremented to ensure each signature can only be used once.
FFS Pair Functions
getReserves() -> (uint112, uint112, uint32)
The getReserves function provides a way to fetch the current reserves of the two tokens in the liquidity pair as well as the last timestamp when the reserves were updated. Reserves are crucial in automated market makers (AMMs) as they determine the pricing for swapping between the two tokens.
Returns
uint112: The reserve of the first token (typically referred to as token0).
uint112: The reserve of the second token (typically referred to as token1).
uint32: The last timestamp when the reserves were updated.
Implementation Details
Directly return the values of reserve0, reserve1, and blockTimestampLast from the contract's state.
Usage
This function is typically used by external consumers (like dApps or other contracts) to get insight into the current state of the liquidity pool. It can be used to determine swap prices, inform decisions on providing/removing liquidity, or for general analytics.
Notes
The returned reserves are crucial for the functioning of AMMs, and they change every time a swap is made, liquidity is added, or liquidity is removed.
The blockTimestampLast can be useful to understand how "fresh" the reserve data is, especially in the context of arbitrage opportunities or other time-sensitive operations.
mint(to: address) -> uint256
Mints LP (Liquidity Provider) tokens to a given address. This function assumes that the caller has sent reserves (token0 and token1) to the contract. Once the reserves are received, LP tokens are minted in proportion to the amount of liquidity added.
Parameters
to (address): The address to which the newly minted LP tokens will be sent.
Returns
liquidity (uint256): The amount of LP tokens that were minted and sent to the specified to address.
Implementation Details
Retrieves current reserves and balances of token0 (ERC1155) and token1 (ERC20) held by the contract.
Calculates the amounts of token0 and token1 added to the pool.
Determines if fees need to be applied based on _mintFee function.
Computes the liquidity to be minted based on the provided liquidity and the total supply of LP tokens.
Checks to ensure the liquidity amount is valid and non-zero.
Mints the LP tokens to the specified address (to).
Updates the reserves based on the new balances.
If fees are enabled, updates the kLast value (used for fee calculations in other functions).
Emits the Mint event.
Returns the minted liquidity amount.
Notes
Ensure that the correct amounts of token0 and token1 are sent to the contract before calling this function.
The Mint event is emitted to provide transparency on the minting actions.
A special case is handled when the total supply of LP tokens is 0, which usually indicates the first provision of liquidity. Here, a minimum liquidity amount (often a small constant to avoid issues with rounding) is minted and sent to a burn or null address.
burn(to: address) -> (uint256, uint256)
Burns LP (Liquidity Provider) tokens from the contract (indicating liquidity removal) and sends the corresponding reserves (token0 and token1) to a specified address.
Parameters
to (address): The address to which the corresponding reserves (token0 and token1) will be sent after burning the LP tokens.
Returns
amount0 (uint256): The amount of token0 (ERC1155 type) removed from the pool and sent to the `to` address.
amount1 (uint256): The amount of token1 (ERC20 type) removed from the pool and sent to the `to` address.
Implementation Details
Retrieves current reserves and balances of token0 (ERC1155) and token1 (ERC20) held by the contract.
Determines if fees need to be applied based on _mintFee function.
Calculates the exact amounts of token0 and token1 corresponding to the LP tokens to be burned, using precision division.
Asserts that either amount0 or amount1 is greater than 0.
Burns the LP tokens from the contract.
Transfers the calculated amounts of token0 and token1 to the specified address (to).
Updates the reserves based on the new balances.
If fees are enabled, updates the kLast value.
Emits the Burn event.
Returns the removed amounts of token0 and token1.
Notes
Ensure that the contract has sufficient LP tokens before calling this function.
The precision division ensures that even tokens with zero decimals are handled correctly.
The Burn event provides transparency on the burning and liquidity removal actions.
This function can be used to remove liquidity from the pool in return for the original tokens.
swap(amount0Out: uint256, amount1Out: uint256, to: address, data: Bytes[256])
Executes a swap of tokens within the liquidity pool. The swap can be from token0 to token1 or the other way around. Additionally, this function can trigger a callback using a custom-defined interface FiveFiveCallee.
Parameters
amount0Out (uint256): The amount of token0 (ERC1155 type) to swap out.
amount1Out (uint256): The amount of token1 (ERC20 type) to swap out.
to (address): The address to send the swapped tokens to.
data (Bytes[256]): Encoded data that is forwarded to FiveFiveSwapCallee via the FiveFiveCall hook.
Implementation Details
Asserts that either amount0Out or amount1Out is greater than 0.
Retrieves current reserves of token0 (ERC1155) and token1 (ERC20) held by the contract.
Ensures that there's sufficient liquidity in the pool for the swap.
Checks the `to` address to make sure it's not equal to token0 or token1 addresses.
Transfers the specified amount of tokens (token0 and/or token1) to the `to` address.
Calls the FiveFiveCall function of the FiveFiveCallee contract if data length is greater than 0.
Determines the amount of input tokens by comparing the balance after the swap with the balance before the swap.
Adjusts the balances to account for potential fees.
Ensures that the invariant K is not reduced as a result of the swap.
Updates the reserves with the new balances.
Emits the Swap event.
Notes
This function is the primary mechanism for users to swap tokens within the pool.
The callback mechanism (FiveFiveCallee) allows for extended functionality, such as complex trading strategies or interactions with other contracts.
Users must have approved the contract to access their tokens before they can swap.
skim(to: address)
The skim function is designed to force the real balances of token0 and token1 held by the contract to match the internally recorded reserves. If the actual balance of a token exceeds its reserve, the excess amount is transferred to the specified `to` address. This mechanism ensures that the real balances never exceed the reserves, effectively removing any surplus tokens.
Parameters
to (address): The recipient address to which the excess reserves (if any) will be transferred.
Implementation Details
Determine the excess amount of token0 by subtracting the internally recorded reserve from the actual balance.
If there's an excess of token0, it is transferred safely to the `to` address.
Determine the excess amount of token1 by subtracting the internally recorded reserve from the actual balance.
If there's an excess of token1, it is transferred to the `to` address.
Usage
This function can be beneficial in scenarios where, due to unforeseen circumstances, the contract's real balances of token0 and token1 exceed the internally recorded reserves. By invoking skim, any excess tokens can be retrieved and transferred to a specified address.
sync()
The sync function is designed to force the internal reserve values of the contract to match the real balances of token0 and token1. It can be seen as a mechanism to reconcile and correct the reserves in case of any discrepancies.
Implementation Details
Fetches the current balance of token0 (of type ERC1155) that the contract holds.
Fetches the current balance of token1 (of type ERC20) that the contract holds.
Invokes the internal _update function using the fetched balances and the current reserves. This will ensure that the reserves are correctly set to the actual balances and will emit the Sync event with the updated reserves.
Usage
This function might be useful in scenarios where, due to any unforeseen circumstance or bug, the internal reserves of the contract don't match the actual token balances. Calling sync will effectively recalibrate the reserves to reflect the real state of the contract's holdings.
Notes
This function does not take any parameters and does not return any value. Its sole purpose is to update the internal reserves to match the actual token balances.
Last updated