EvolvingProteus.sol

Github Link: https://github.com/Shell-Protocol/Shell-Protocol/blob/main/src/proteus/EvolvingProteus.sol

constructor()

/**
* @param _py_init The initial price at the y axis
* @param _px_init The initial price at the x axis
* @param _py_final The final price at the y axis
* @param _px_final The final price at the y axis
* @param _curveEvolutionStartTime curve evolution start time
* @param _curveEvolutionDuration duration for which the curve will evolve
*/
constructor(
    int128 _py_init,
    int128 _px_init,
    int128 _py_final,
    int128 _px_final,
    uint256 _curveEvolutionStartTime,
    uint256 _curveEvolutionDuration
)

Parameter Name	Type	Description
_py_init	int128	initial price on the y axis
_px_init	int128	initial price on the x axis
_py_final	int128	final price on the y axis
_px_final	int128	initial price on the x axis
_curveEvolutionStartTime	uint256	timestamp in seconds
_curveEvolutionDuration	uint256	evolution duration in seconds

This method is called whenever a new EvolvingProteus pool is deployed.

params()

/**
* @notice Returns all the pool configuration params in a tuple
*/
function params() public view returns (
    int128,
    int128,
    int128,
    int128,
    uint256,
    uint256,
    uint256
);

This function returns all the pool configuration.

It should...

1. Return a tuple of all the pool configuration params (py_init, px_init, py_final, px_final, t_init, t_final, curveEvolutionDuration).

elapsed()

/**
* @notice Calculates the time that has passed since deployment
*/
function elapsed() public view returns (
    uint256
);

This function returns the time that has passed since contract deployment.

t()

/**
* @notice Calculates the time as a percent of total duration
*/
function t() public view returns (
    int128
);

This function returns percentage of how much time has passed since the evolution started.

p_min()

/**
* notice The minimum price (at the x asymptote) at the current block
*/
function p_min() public view returns (
    int128
);

This function returns the minimum price at the current block.

p_max()

/**
* @notice The maximum price (at the y asymptote) at the current block
*/
function p_max() public view returns (
    int128
);

This function returns the maximum price at the current block.

a()

/**
* @notice Calculates the a variable in the curve eq which is basically a sq. root
* of the inverse of y instantaneous price
*/
function a() public view returns (
    int128
);

This function returns a sq. root of the inverse of y instantaneous price.

b()

/**
* @notice Calculates the b variable in the curve eq which is basically a sq. root
* of the inverse of x instantaneous price
*/
function b() public view returns (
    int128
);

This function returns a sq. root of the inverse of x instantaneous price.

swapGivenInputAmount()

/**
* @dev Given an input amount of one reserve token, we compute the output
* amount of the other reserve token, keeping utility invariant.
* @dev We use FEE_DOWN because we want to decrease the perceived
* input amount and decrease the observed output amount.
*/
function swapGivenInputAmount(
   uint256 xBalance,
   uint256 yBalance,
   uint256 inputAmount,
   SpecifiedToken inputToken
) external view returns (
   uint256 outputAmount
);

Parameter Name	Type	Description
xBalance	unit256	x token balance
yBalance	unit256	y token balance
inputAmount	unit256	amount of input tokens to swap for output tokens
inputToken	SpecifiedToken enum	SpecifiedToken.X or SpecifiedToken.Y

SpecifiedToken enum:

Enum Member Name	Type	Description
X	enum member (technically token Ocean ID)	an indicator stating usage of token X in the operation
Y	enum member (technically token Ocean ID)	an indicator stating usage of token Y in the operation

This function computes output amount of the reserve token based on the input amount of the reserved token.

It should...

1. Revert if the function is invoked before the pool evolution start date.

2. Return the output amount based on the input amount.

swapGivenOutputAmount()

/**
* @dev Given an output amount of a reserve token, we compute an input
*  amount of the other reserve token, keeping utility invariant.
* @dev We use FEE_UP because we want to increase the perceived output
*  amount and increase the observed input amount.
*/
function swapGivenOutputAmount(
   uint256 xBalance,
   uint256 yBalance,
   uint256 outputAmount,
   SpecifiedToken outputToken
) external view returns (
   uint256 inputAmount
);

Parameter Name	Type	Description
xBalance	unit256	x token balance
yBalance	unit256	y token balance
outputAmount	unit256	amount of output tokens to swap for input tokens
outputToken	SpecifiedToken enum	SpecifiedToken.X or SpecifiedToken.Y

SpecifiedToken enum:

Enum Member Name	Type	Description
X	enum member (technically token Ocean ID)	an indicator stating usage of token X in the operation
Y	enum member (technically token Ocean ID)	an indicator stating usage of token Y in the operation

This function computes input amount of the reserve token necessary to get for the desired amount of the output token.

It should...

1. Revert if the function is invoked before the pool evolution start date.

2. Return input amount necessary to receive the output amount.

depositGivenInputAmount()

/**
* @dev Given an input amount of a reserve token, we compute an output
*  amount of LP tokens, scaling the total supply of the LP tokens with the
*  utility of the pool.
* @dev We use FEE_DOWN because we want to decrease the perceived amount
*  deposited and decrease the amount of LP tokens minted.
*/
function depositGivenInputAmount(
   uint256 xBalance,
   uint256 yBalance,
   uint256 totalSupply,
   uint256 depositedAmount,
   SpecifiedToken depositedToken
) external view returns (
   uint256 mintedAmount
);

Parameter Name	Type	Description
xBalance	unit256	x token balance
yBalance	unit256	y token balance
totalSupply	unit256	total supply of the LP tokens that exists currently
depositedAmount	unit256	the amount of token to be deposited
depositedToken	SpecifiedToken enum	SpecifiedToken.X or SpecifiedToken.Y

SpecifiedToken enum:

Enum Member Name	Type	Description
X	enum member (technically token Ocean ID)	an indicator stating usage of token X in the operation
Y	enum member (technically token Ocean ID)	an indicator stating usage of token Y in the operation

This function computes output amount of LP tokens based on the amount of the input token.

It should...

1. Revert if the function is invoked before the pool evolution start date.

2. Return amount of LP tokens minted for the amount of the provided token.

depositGivenOutputAmount()

/**
* @dev Given an output amount of the LP token, we compute an amount of
*  a reserve token that must be deposited to scale the utility of the pool
*  in proportion to the change in total supply of the LP token.
* @dev We use FEE_UP because we want to increase the perceived change in
*  total supply and increase the observed amount deposited.
*/
function depositGivenOutputAmount(
   uint256 xBalance,
   uint256 yBalance,
   uint256 totalSupply,
   uint256 mintedAmount,
   SpecifiedToken depositedToken
) external view returns (
   uint256 depositedAmount
);

Parameter Name	Type	Description
xBalance	unit256	x token balance
yBalance	unit256	y token balance
totalSupply	unit256	total supply of the LP tokens that exists currently
mintedAmount	unit256	the amount of LP token to be minted
depositedToken	SpecifiedToken enum	SpecifiedToken.X or SpecifiedToken.Y

SpecifiedToken enum:

Enum Member Name	Type	Description
X	enum member (technically token Ocean ID)	an indicator stating usage of token X in the operation
Y	enum member (technically token Ocean ID)	an indicator stating usage of token Y in the operation

This function computes deposit amount necessary to in order to receive desired amount of LP tokens (minted amount).

It should...

1. Revert if the function is invoked before the pool evolution start date.

2. Return amount of deposited token necessary to get the desired amount of LP tokens.

withdrawGivenOutputAmount()

/**
* @dev Given an output amount of a reserve token, we compute an amount of
*  LP tokens that must be burned in order to decrease the total supply in
*  proportion to the decrease in utility.
* @dev We use FEE_UP because we want to increase the perceived amount
*  withdrawn from the pool and increase the observed decrease in total
*  supply.
*/
function withdrawGivenOutputAmount(
   uint256 xBalance,
   uint256 yBalance,
   uint256 totalSupply,
   uint256 withdrawnAmount,
   SpecifiedToken withdrawnToken
) external view returns (
   uint256 burnedAmount
);

Parameter Name	Type	Description
xBalance	unit256	x token balance
yBalance	unit256	y token balance
totalSupply	unit256	total supply of the LP tokens that exists currently
withdrawnAmount	unit256	the amount of token to be withdrawn
withdrawnToken	SpecifiedToken enum	SpecifiedToken.X or SpecifiedToken.Y

SpecifiedToken enum:

Enum Member Name	Type	Description
X	enum member (technically token Ocean ID)	an indicator stating usage of token X in the operation
Y	enum member (technically token Ocean ID)	an indicator stating usage of token Y in the operation

This function computes how many LP tokens should be burned in exchange for the withdraw amount of the specified token.

It should...

1. Revert if the function is invoked before the pool evolution start date.

2. Return amount of LP tokens burned for the request amount of withdraw token.

withdrawGivenInputAmount()

/**
* @dev Given an input amount of the LP token, we compute an amount of
*  a reserve token that must be output to decrease the pool's utility in
*  proportion to the pool's decrease in total supply of the LP token.
* @dev We use FEE_UP because we want to increase the perceived amount of
*  reserve tokens leaving the pool and to increase the observed amount of
*  LP tokens being burned.
*/
function withdrawGivenInputAmount(
   uint256 xBalance,
   uint256 yBalance,
   uint256 totalSupply,
   uint256 burnedAmount,
   SpecifiedToken withdrawnToken
) external view returns (
   uint256 withdrawnAmount
);

Parameter Name	Type	Description
xBalance	unit256	x token balance
yBalance	unit256	y token balance
totalSupply	unit256	total supply of the LP tokens that exists currently
burnedAmount	unit256	the amount of LP tokens that are going to be burned
withdrawnToken	SpecifiedToken enum	SpecifiedToken.X or SpecifiedToken.Y

SpecifiedToken enum:

Enum Member Name	Type	Description
X	enum member (technically token Ocean ID)	an indicator stating usage of token X in the operation
Y	enum member (technically token Ocean ID)	an indicator stating usage of token Y in the operation

This function computes amount of specified withdrawn token to be received for the given amount of burned LP tokens.

It should...

1. Revert if the function is invoked before the pool evolution start date.

2. Return amount of withdraw tokens to be received for the amount of burned LP tokens.