Skip to main content

TokenController

Git Source

Inherits: InitializablePair, ITokenController

Wrapper of the ERC20 tokens that has some functionality similar to the ERC1155.

State Variables​

tokenX​

IERC20 private tokenX;

tokenY​

IERC20 private tokenY;

_tokenDepositL​

IAmmalgamERC20 private _tokenDepositL;

_tokenDepositX​

IAmmalgamERC20 private _tokenDepositX;

_tokenDepositY​

IAmmalgamERC20 private _tokenDepositY;

_tokenBorrowL​

IAmmalgamERC20 private _tokenBorrowL;

_tokenBorrowX​

IAmmalgamERC20 private _tokenBorrowX;

_tokenBorrowY​

IAmmalgamERC20 private _tokenBorrowY;

factory​

IFactoryCallback internal factory;

saturationAndGeometricTWAPState​

ISaturationAndGeometricTWAPState internal saturationAndGeometricTWAPState;

allShares​

uint112[6] private allShares;

allAssets​

The first position in this array is never stored because it is instead computed as reserveX⋅reserveY+borrowedLAssets\sqrt{reserveX\cdot reserveY}+borrowedLAssets. We keep this storage spot because we heavily use DEPOSIT_L, DEPOSIT_X, DEPOSIT_Y, BORROW_L, BORROW_X, BORROW_Y to look up positions throughout the code and didn't want to change all those references.

uint112[6] private allAssets;

reserveXAssets​

uint112 private reserveXAssets;

reserveYAssets​

uint112 private reserveYAssets;

lastUpdateTimestamp​

uint32 internal lastUpdateTimestamp;

referenceReserveX​

uint112 internal referenceReserveX;

referenceReserveY​

uint112 internal referenceReserveY;

lastLendingTimestamp​

uint32 internal lastLendingTimestamp;

externalLiquidity​

uint112 public override externalLiquidity;

fragileLiquidityShares​

uint112 public override fragileLiquidityShares;

userFragileLiquidityShares​

mapping(address => uint256) internal userFragileLiquidityShares;

totalDepositLAssets​

uint112 internal transient totalDepositLAssets;

totalDepositXAssets​

uint112 internal transient totalDepositXAssets;

totalDepositYAssets​

uint112 internal transient totalDepositYAssets;

totalBorrowLAssets​

uint112 internal transient totalBorrowLAssets;

totalBorrowXAssets​

uint112 internal transient totalBorrowXAssets;

totalBorrowYAssets​

uint112 internal transient totalBorrowYAssets;

activeLiquidityAssets​

uint112 internal transient activeLiquidityAssets;

Functions​

_initialize​

function _initialize() internal virtual override;

onlyFeeToSetter​

modifier onlyFeeToSetter();

_onlyFeeToSetter​

function _onlyFeeToSetter() private view;

underlyingTokens​

function underlyingTokens() public view virtual override returns (IERC20, IERC20);

updateAssets​

function updateAssets(uint256 tokenType, uint112 assets) internal;

updateExternalLiquidity​

function updateExternalLiquidity(
    uint112 _externalLiquidity
) external virtual onlyFeeToSetter;

mintId​

function mintId(uint256 tokenType, address sender, address to, uint256 assets, uint256 shares_) internal;

burnId​

function burnId(uint256 tokenType, address sender, address receiver, uint256 assets, uint256 shares_) internal;

tokens​

function tokens(
    uint256 tokenType
) public view virtual override returns (IAmmalgamERC20);

balanceOf​

function balanceOf(address account, uint256 tokenType) internal view returns (uint256);

totalShares​

function totalShares(
    uint256 tokenType
) internal view returns (uint256);

rawTotalAssets​

function rawTotalAssets(
    uint256 tokenType
) internal view returns (uint256 assetAmount);

getRawReserves​

function getRawReserves() internal view returns (uint112 _reserveXAssets, uint112 _reserveYAssets);

getReserves​

function getReserves()
    public
    view
    virtual
    returns (uint112 _reserveXAssets, uint112 _reserveYAssets, uint32 _lastUpdateTimestamp);

referenceReserves​

function referenceReserves() external view virtual returns (uint112, uint112);

totalAssetsAndShares​

function totalAssetsAndShares(
    bool withInterest
) public view virtual returns (uint112[6] memory _allAssets, uint112[6] memory _allShares);

fragileLiquidityAssets​

Computes fragile liquidity and validates it can be removed from active liquidity.

function fragileLiquidityAssets(
    uint256 _activeLiquidityAssets
) internal view returns (uint256 _fragileLiquidityAssets);

Parameters

NameTypeDescription
_activeLiquidityAssetsuint256The active liquidity available before the fragile liquidity decrement.

updateFragileLiquidity​

used to update fragileLiquidityShares that have a borrow of x or y against them

*We then need to increase fragile liquidity when

  1. a new borrow of x or y is made when none existed and the user has l deposits.
  2. l deposits are minted to a user with existing borrows of x or y.
  3. l deposits are transferred to a user with no existing l and but borrows of x or y.
  4. debt of x or y is transferred to a user with l shares but no debt existing x or y debt. Fragile liquidity then needs to be decreased when
  5. all borrows of x and y are repaid for a user with l deposits.
  6. l deposits are burned from a user with existing borrows of x or y.
  7. l deposits are transferred from a user with borrows of x or y to a user with no borrow of x or y.
  8. last debt of x or y is transferred from a user with l deposits to a user with no l deposits.*
function updateFragileLiquidity(
    address user
) internal;

Parameters

NameTypeDescription
useraddressthe address to update fragile liquidity for.

computeAssetsState​

Recalculates current total assets, reserves, and protocol fees, accounting for elapsed time and interest.

*Core logic for interest accrual and state updates (used by totalAssetsAndShares when withInterest is true):

  1. Fetches raw reserves before computing interest.
  2. If totalDepositLAssets is not 0, returns transient asset values immediately (no interest to accrue).
  3. Calculates time elapsed since last update (deltaUpdateTimestamp) and last lending state check (deltaLendingTimestamp).
  4. If no time has elapsed since last lending check (deltaLendingTimestamp == 0), returns stored values without recalculation.
  5. Otherwise:
  • Computes the current market tick via getTickFromReserves() and bounds it to valid ranges.
  • Determines active lending state tick and saturation percentage using getLendingStateTick().
  • Calls Interest.accrueInterestWithAssets() to calculate interest, update asset values, and compute protocol fees.
  • Adds LP-earned interest portions to X and Y reserves.*
function computeAssetsState()
    internal
    view
    returns (
        uint112[6] memory _allAssets,
        uint112 _reserveXAssets,
        uint112 _reserveYAssets,
        uint256[3] memory protocolFees
    );

Returns

NameTypeDescription
_allAssetsuint112[6]Array of six uint112 values: Recalculated total assets for each of the 6 Ammalgam token types (post-interest).
_reserveXAssetsuint112Reserve balance for Asset X, updated with LP-earned interest.
_reserveYAssetsuint112Reserve balance for Asset Y, updated with LP-earned interest.
protocolFeesuint256[3]Array of three uint256 values: Accumulated protocol fees for DEPOSIT_L, DEPOSIT_X, and DEPOSIT_Y (from interest accrual).

accrueSaturationPenaltiesAndInterest​

function accrueSaturationPenaltiesAndInterest(
    address affectedAccount,
    uint256 minimumTimeBeforeUpdate
) internal returns (uint256 _reserveXAssets, uint256 _reserveYAssets, uint256 balanceXAssets, uint256 balanceYAssets);

updateObservation​

function updateObservation(
    uint256 _reserveXAssets,
    uint256 _reserveYAssets,
    uint32 currentTimestamp,
    uint32 deltaUpdateTimestamp
) private;

mintPenalties​

function mintPenalties(address account, uint32 deltaLendingTimestamp) internal;

getAssets​

function getAssets(
    uint112[6] memory _totalAssets,
    uint112[6] memory _totalShares,
    address toCheck
) internal view returns (uint256[6] memory userAssets);

updateTokenController​

function updateTokenController(
    uint32 currentTimestamp,
    uint32 deltaUpdateTimestamp,
    uint32 deltaLendingTimestamp,
    uint256 _reserveXAssets,
    uint256 _reserveYAssets
) internal returns (uint256 updatedReservesX, uint256 updatedReservesY);

updateReferenceReserve​

function updateReferenceReserve(
    int256 newTick
) internal;

mintProtocolFees​

function mintProtocolFees(
    uint256 tokenType,
    address feeTo,
    uint256 protocolFee,
    bool feeIncludedInTotalAssets
) internal;

updateReserves​

function updateReserves(uint256 newReserveXAssets, uint256 newReserveYAssets) internal;

updateReservesAndReference​

function updateReservesAndReference(
    uint256 _reserveXAssets,
    uint256 _reserveYAssets,
    uint256 newReserveXAssets,
    uint256 newReserveYAssets
) internal;

_castReserves​

function _castReserves(uint256 _reserveXAssets, uint256 _reserveYAssets) internal pure returns (uint112, uint112);

getNetBalances​

function getNetBalances(uint256 _reserveXAssets, uint256 _reserveYAssets) internal view returns (uint256, uint256);

missingAssets​

function missingAssets() internal view returns (uint112 missingXAssets, uint112 missingYAssets);

calculateActiveLiquidityAssets​

Active liquidity from reserves, using the same depletion adjustment as the swap K-check in calculateReserveAdjustmentsForMissingAssets. Caching raw sqrt(X*Y) is non-monotonic across depletion cycles, letting saturation-tree leaves register above the post-recovery maxLeaf and bricking the pair with MaxTrancheOverSaturated().

function calculateActiveLiquidityAssets(
    uint256 _reserveXAssets,
    uint256 _reserveYAssets
) internal view returns (uint256);

Parameters

NameTypeDescription
_reserveXAssetsuint256The reserve X used for the active-liquidity calculation.
_reserveYAssetsuint256The reserve Y used for the active-liquidity calculation.

Returns

NameTypeDescription
<none>uint256The depletion-adjusted active liquidity, i.e. sqrt of the adjusted-reserve product.

getDepositAndActiveLiquidityAssets​

Get the deposit, and active liquidity assets.

function getDepositAndActiveLiquidityAssets()
    internal
    view
    returns (uint256 depositLiquidityAssets, uint256 currentActiveLiquidityAssets);

Returns

NameTypeDescription
depositLiquidityAssetsuint256The deposit liquidity assets.
currentActiveLiquidityAssetsuint256The current active liquidity assets.

burnBadDebt​

function burnBadDebt(address borrower, uint256 tokenType, uint256 reserve) internal;

getUpdatedReferenceReserves​

Get the updated reference reserves based on the newTick.

function getUpdatedReferenceReserves(
    int256 newTick
) internal view returns (uint112, uint112);

Parameters

NameTypeDescription
newTickint256The current tick.

Returns

NameTypeDescription
<none>uint112_referenceReserveX The updated reference reserve X.
<none>uint112_referenceReserveY The updated reference reserve Y.

Errors​

Forbidden​

error Forbidden();