doc improvements
This commit is contained in:
tim
@@ -4,9 +4,18 @@ pragma solidity ^0.8.30;
|
||||
import "@openzeppelin/contracts/token/ERC20/extensions/IERC20Metadata.sol";
|
||||
|
||||
/// @title PartyPool - LMSR-backed multi-asset pool with LP ERC20 token
|
||||
/// @notice Uses LMSRStabilized library; stores per-token uint bases to convert to/from 64.64 fixed point.
|
||||
/// - Caches qInternal[] (int128 64.64) and cachedUintBalances[] to minimize balanceOf() calls.
|
||||
/// - swap and swapToLimit mimic core lib; mint/burn call updateForProportionalChange() and manage LP tokens.
|
||||
/// @notice A multi-asset liquidity pool backed by the LMSRStabilized pricing model.
|
||||
/// The pool issues an ERC20 LP token representing proportional ownership.
|
||||
/// It supports:
|
||||
/// - Proportional minting and burning of LP tokens,
|
||||
/// - Single-token mint (swapMint) and single-asset withdrawal (burnSwap),
|
||||
/// - Exact-input swaps and swaps-to-price-limits,
|
||||
/// - Flash loans via a callback interface.
|
||||
///
|
||||
/// @dev The contract stores per-token uint "bases" used to scale token units into the internal Q64.64
|
||||
/// representation used by the LMSR library. Cached on-chain uint balances are kept to reduce balanceOf calls.
|
||||
/// The contract uses ceiling/floor rules described in function comments to bias rounding in favor of the pool
|
||||
/// (i.e., floor outputs to users, ceil inputs/fees where appropriate).
|
||||
interface IPartyPool is IERC20Metadata {
|
||||
// All int128's are ABDKMath64x64 format
|
||||
|
||||
@@ -47,25 +56,51 @@ interface IPartyPool is IERC20Metadata {
|
||||
|
||||
|
||||
// Immutable pool configuration (public getters)
|
||||
/// @notice Token addresses comprising the pool. Effectively immutable after construction.
|
||||
/// @dev tokens[i] corresponds to the i-th asset and maps to index i in the internal LMSR arrays.
|
||||
function tokens(uint256) external view returns (address); // get single token
|
||||
|
||||
/// @notice Returns the number of tokens (n) in the pool.
|
||||
function numTokens() external view returns (uint256);
|
||||
|
||||
/// @notice Returns the list of all token addresses in the pool (copy).
|
||||
function allTokens() external view returns (address[] memory);
|
||||
|
||||
/// @notice Per-token uint base denominators used to convert uint token amounts <-> internal Q64.64 representation.
|
||||
/// @dev denominators()[i] is the base for tokens[i]. These bases are chosen by deployer and must match token decimals.
|
||||
function denominators() external view returns (uint256[] memory);
|
||||
|
||||
/// @notice Trade fraction (Q64.64) representing a reference trade size as fraction of one asset's inventory.
|
||||
/// @dev Used by the LMSR stabilization logic to compute target slippage.
|
||||
function tradeFrac() external view returns (int128); // ABDK 64x64
|
||||
|
||||
/// @notice Target slippage (Q64.64) applied for the reference trade size specified by tradeFrac.
|
||||
function targetSlippage() external view returns (int128); // ABDK 64x64
|
||||
|
||||
/// @notice Per-swap fee in parts-per-million (ppm). Fee is taken from input amounts before LMSR computations.
|
||||
function swapFeePpm() external view returns (uint256);
|
||||
|
||||
/// @notice Flash-loan fee in parts-per-million (ppm) applied to flash borrow amounts.
|
||||
function flashFeePpm() external view returns (uint256);
|
||||
|
||||
/// @notice Mapping from token address => (index+1). A zero value indicates the token is not in the pool.
|
||||
/// @dev Use index = tokenAddressToIndexPlusOne[token] - 1 when non-zero.
|
||||
function tokenAddressToIndexPlusOne(address) external view returns (uint);
|
||||
|
||||
// Initialization / Mint / Burn (LP token managed)
|
||||
|
||||
/// @notice Calculate the proportional deposit amounts required for a given LP token amount
|
||||
/// @dev Returns the minimum token amounts (rounded up) that must be supplied to receive lpTokenAmount
|
||||
/// LP tokens at current pool proportions. If the pool is empty (initial deposit) returns zeros
|
||||
/// because the initial deposit is handled by transferring tokens then calling mint().
|
||||
/// @param lpTokenAmount The amount of LP tokens desired
|
||||
/// @return depositAmounts Array of token amounts to deposit (rounded up)
|
||||
function mintDepositAmounts(uint256 lpTokenAmount) external view returns (uint256[] memory depositAmounts);
|
||||
|
||||
/// @notice Proportional mint (or initial supply if first call).
|
||||
/// For initial supply: assumes tokens have already been transferred to the pool
|
||||
/// For subsequent mints: payer must approve tokens beforehand, receiver gets the LP tokens
|
||||
/// @dev - For initial supply: assumes tokens have already been transferred to the pool prior to calling.
|
||||
/// - For subsequent mints: payer must approve the required token amounts before calling.
|
||||
/// Rounds follow the pool-favorable conventions documented in helpers (ceil inputs, floor outputs).
|
||||
/// @param payer address that provides the input tokens (ignored for initial deposit)
|
||||
/// @param receiver address that receives the LP tokens
|
||||
/// @param lpTokenAmount desired amount of LP tokens to mint (ignored for initial deposit)
|
||||
@@ -73,12 +108,15 @@ interface IPartyPool is IERC20Metadata {
|
||||
function mint(address payer, address receiver, uint256 lpTokenAmount, uint256 deadline) external;
|
||||
|
||||
/// @notice Calculate the proportional withdrawal amounts for a given LP token amount
|
||||
/// @dev Returns the maximum token amounts (rounded down) that will be withdrawn when burning lpTokenAmount.
|
||||
/// If the pool is uninitialized or supply is zero, returns zeros.
|
||||
/// @param lpTokenAmount The amount of LP tokens to burn
|
||||
/// @return withdrawAmounts Array of token amounts to withdraw (rounded down)
|
||||
function burnReceiveAmounts(uint256 lpTokenAmount) external view returns (uint256[] memory withdrawAmounts);
|
||||
|
||||
/// @notice Burn LP tokens and withdraw the proportional basket to receiver.
|
||||
/// Payer must own the LP tokens; withdraw amounts are computed from current proportions.
|
||||
/// @dev Payer must own or approve the LP tokens being burned. The function updates LMSR state
|
||||
/// proportionally to reflect the reduced pool size after the withdrawal.
|
||||
/// @param payer address that provides the LP tokens to burn
|
||||
/// @param receiver address that receives the withdrawn tokens
|
||||
/// @param lpAmount amount of LP tokens to burn (proportional withdrawal)
|
||||
@@ -89,73 +127,114 @@ interface IPartyPool is IERC20Metadata {
|
||||
// Swaps
|
||||
|
||||
/// @notice External view to quote exact-in swap amounts (gross input incl. fee and output), matching swap() computations
|
||||
/// @param inputTokenIndex index of input token
|
||||
/// @param outputTokenIndex index of output token
|
||||
/// @param maxAmountIn maximum gross input allowed (inclusive of fee)
|
||||
/// @param limitPrice maximum acceptable marginal price (pass 0 to ignore)
|
||||
/// @return amountIn gross input amount to transfer (includes fee), amountOut output amount user would receive, fee fee amount taken
|
||||
function swapAmounts(
|
||||
uint256 i,
|
||||
uint256 j,
|
||||
uint256 inputTokenIndex,
|
||||
uint256 outputTokenIndex,
|
||||
uint256 maxAmountIn,
|
||||
int128 limitPrice
|
||||
) external view returns (uint256 amountIn, uint256 amountOut, uint256 fee);
|
||||
|
||||
/// @notice Swap input token inputTokenIndex -> token outputTokenIndex. Payer must approve token inputTokenIndex.
|
||||
/// @dev This function transfers the exact gross input (including fee) from payer and sends the computed output to receiver.
|
||||
/// Non-standard tokens (fee-on-transfer, rebasers) are rejected via balance checks.
|
||||
/// @param payer address of the account that pays for the swap
|
||||
/// @param receiver address that will receive the output tokens
|
||||
/// @param inputTokenIndex index of input asset
|
||||
/// @param outputTokenIndex index of output asset
|
||||
/// @param maxAmountIn maximum amount of token inputTokenIndex (uint256) to transfer in (inclusive of fees)
|
||||
/// @param limitPrice maximum acceptable marginal price (64.64 fixed point). Pass 0 to ignore.
|
||||
/// @param deadline timestamp after which the transaction will revert. Pass 0 to ignore.
|
||||
/// @return amountIn actual input used (uint256), amountOut actual output sent (uint256), fee fee taken from the input (uint256)
|
||||
function swap(
|
||||
address payer,
|
||||
address receiver,
|
||||
uint256 i,
|
||||
uint256 j,
|
||||
uint256 inputTokenIndex,
|
||||
uint256 outputTokenIndex,
|
||||
uint256 maxAmountIn,
|
||||
int128 limitPrice,
|
||||
uint256 deadline
|
||||
) external returns (uint256 amountIn, uint256 amountOut, uint256 fee);
|
||||
|
||||
/// @notice External view to quote swap-to-limit amounts (gross input incl. fee and output), matching swapToLimit() computations
|
||||
/// @param inputTokenIndex index of input token
|
||||
/// @param outputTokenIndex index of output token
|
||||
/// @param limitPrice target marginal price to reach (must be > 0)
|
||||
/// @return amountIn gross input amount to transfer (includes fee), amountOut output amount user would receive, fee fee amount taken
|
||||
function swapToLimitAmounts(
|
||||
uint256 i,
|
||||
uint256 j,
|
||||
uint256 inputTokenIndex,
|
||||
uint256 outputTokenIndex,
|
||||
int128 limitPrice
|
||||
) external view returns (uint256 amountIn, uint256 amountOut, uint256 fee);
|
||||
|
||||
/// @notice Swap up to the price limit; computes max input to reach limit then performs swap.
|
||||
/// @dev If balances prevent fully reaching the limit, the function caps and returns actuals.
|
||||
/// The payer must transfer the exact gross input computed by the view.
|
||||
/// @param payer address of the account that pays for the swap
|
||||
/// @param receiver address that will receive the output tokens
|
||||
/// @param inputTokenIndex index of input asset
|
||||
/// @param outputTokenIndex index of output asset
|
||||
/// @param limitPrice target marginal price to reach (must be > 0)
|
||||
/// @param deadline timestamp after which the transaction will revert. Pass 0 to ignore.
|
||||
/// @return amountInUsed actual input used excluding fee (uint256), amountOut actual output sent (uint256), fee fee taken from the input (uint256)
|
||||
function swapToLimit(
|
||||
address payer,
|
||||
address receiver,
|
||||
uint256 i,
|
||||
uint256 j,
|
||||
uint256 inputTokenIndex,
|
||||
uint256 outputTokenIndex,
|
||||
int128 limitPrice,
|
||||
uint256 deadline
|
||||
) external returns (uint256 amountInUsed, uint256 amountOut, uint256 fee);
|
||||
|
||||
/// @notice Single-token mint: deposit a single token, charge swap-LMSR cost, and mint LP.
|
||||
/// @dev swapMint executes as an exact-in planned swap followed by proportional scaling of qInternal.
|
||||
/// The function emits SwapMint (gross, net, fee) and also emits Mint for LP issuance.
|
||||
/// @param payer who transfers the input token
|
||||
/// @param receiver who receives the minted LP tokens
|
||||
/// @param i index of the input token
|
||||
/// @param inputTokenIndex index of the input token
|
||||
/// @param maxAmountIn maximum uint token input (inclusive of fee)
|
||||
/// @param deadline optional deadline
|
||||
/// @return lpMinted actual LP minted (uint)
|
||||
function swapMint(
|
||||
address payer,
|
||||
address receiver,
|
||||
uint256 i,
|
||||
uint256 inputTokenIndex,
|
||||
uint256 maxAmountIn,
|
||||
uint256 deadline
|
||||
) external returns (uint256 lpMinted);
|
||||
|
||||
/// @notice Burn LP tokens then swap the redeemed proportional basket into a single asset `i` and send to receiver.
|
||||
/// @notice Burn LP tokens then swap the redeemed proportional basket into a single asset `inputTokenIndex` and send to receiver.
|
||||
/// @dev The function burns LP tokens (authorization via allowance if needed), sends the single-asset payout and updates LMSR state.
|
||||
/// @param payer who burns LP tokens
|
||||
/// @param receiver who receives the single asset
|
||||
/// @param lpAmount amount of LP tokens to burn
|
||||
/// @param i index of target asset to receive
|
||||
/// @param inputTokenIndex index of target asset to receive
|
||||
/// @param deadline optional deadline
|
||||
/// @return amountOutUint uint amount of asset i sent to receiver
|
||||
/// @return amountOutUint uint amount of asset inputTokenIndex sent to receiver
|
||||
function burnSwap(
|
||||
address payer,
|
||||
address receiver,
|
||||
uint256 lpAmount,
|
||||
uint256 i,
|
||||
uint256 inputTokenIndex,
|
||||
uint256 deadline
|
||||
) external returns (uint256 amountOutUint);
|
||||
|
||||
/// @notice Receive token0 and/or token1 and pay it back, plus a fee, in the callback
|
||||
/// @dev The caller of this method receives a callback in the form of IPartyFlashCallback#partyFlashCallback
|
||||
/// @notice Compute repayment amounts (principal + flash fee) for a proposed flash loan.
|
||||
/// @param loanAmounts array of per-token loan amounts; must match the pool's token ordering.
|
||||
/// @return repaymentAmounts array where repaymentAmounts[i] = loanAmounts[i] + ceil(loanAmounts[i] * flashFeePpm)
|
||||
function flashRepaymentAmounts(uint256[] memory loanAmounts) external view
|
||||
returns (uint256[] memory repaymentAmounts);
|
||||
|
||||
/// @notice Receive token amounts and require them to be repaid plus a fee inside a callback.
|
||||
/// @dev The caller must implement IPartyFlashCallback#partyFlashCallback which receives (amounts, repaymentAmounts, data).
|
||||
/// This function verifies that, after the callback returns, the pool's balances have increased by at least the fees
|
||||
/// for each borrowed token. Reverts if repayment (including fee) did not occur.
|
||||
/// @param recipient The address which will receive the token amounts
|
||||
/// @param amounts The amount of each token to send
|
||||
/// @param amounts The amount of each token to send (array length must equal pool size)
|
||||
/// @param data Any data to be passed through to the callback
|
||||
function flash(
|
||||
address recipient,
|
||||
|
||||
Reference in New Issue
Block a user