@agoric/inter-protocol 0.13.3 → 0.13.4-dev-800c2bb.0

package/src/vpool-xyk-amm/constantProduct/internal-types.js

@@ -1,116 +0,0 @@
-// @ts-check
-
-/**
- * @typedef {object} ImprovedNoFeeSwapResult
- * @property {Amount<'nat'>} amountIn
- * @property {Amount<'nat'>} amountOut
- */
-
-/**
- * @typedef {object} FeePair
- *
- * @property {Amount<'nat'>} poolFee
- * @property {Amount<'nat'>} protocolFee
- */
-
-/**
- * @typedef {object} PoolAllocation
- *
- * @property {Amount<'nat'>} Central
- * @property {Amount<'nat'>} Secondary
- */
-
-/**
- * @typedef {object} NoFeeSwapFnInput
- * @property {Amount} amountGiven
- * @property {Amount} amountWanted
- * @property {Brand=} brand
- * @property {PoolAllocation} poolAllocation
- */
-
-/**
- * This is the type for swapInNoFees and swapOutNoFees. pricesForStatedInput()
- * uses swapInNoFees, while pricesForStatedOutput() uses swapOutNoFees.
- *
- * @callback NoFeeSwapFn
- * @param {NoFeeSwapFnInput} input
- * @returns {ImprovedNoFeeSwapResult}
- */
-
-/**
- * @typedef {FeePair & ImprovedNoFeeSwapResult} FeeEstimate
- */
-
-/**
- * @callback CalculateFees
- * @param {Amount} amountGiven
- * @param {PoolAllocation} poolAllocation
- * @param {Amount} amountWanted
- * @param {Ratio} protocolFeeRatio
- * @param {Ratio} poolFeeRatio
- * @param {NoFeeSwapFn} swapFn
- * @returns {FeeEstimate}
- */
-
-/**
- * @callback InternalSwap
- * @param {Amount} amountGiven
- * @param {PoolAllocation} poolAllocation
- * @param {Amount} amountWanted
- * @param {Ratio} protocolFeeRatio
- * @param {Ratio} poolFeeRatio
- * @param {NoFeeSwapFn} swapFn
- * @returns {SinglePoolSwapResult}
- */
-
-/**
- * @callback CalcSwapInPrices
- * @param {Amount} amountGiven
- * @param {PoolAllocation} poolAllocation
- * @param {Amount=} amountWanted
- * @param {Ratio} protocolFeeRatio
- * @param {Ratio} poolFeeRatio
- * @returns {SinglePoolSwapResult}
- */
-/**
- * @callback CalcSwapOutPrices
- * @param {Amount=} amountGiven
- * @param {PoolAllocation} poolAllocation
- * @param {Amount} amountWanted
- * @param {Ratio} protocolFeeRatio
- * @param {Ratio} poolFeeRatio
- * @returns {SinglePoolSwapResult}
- */
-
-/**
- * @typedef {object} GetXYParam
- * @property {Amount=} amountGiven
- * @property {PoolAllocation} poolAllocation
- * @property {Amount=} amountWanted
- */
-
-/**
- * @typedef {object} GetXYResultDeltaX
- * @property {Amount} x
- * @property {Amount} y
- * @property {Amount} deltaX
- * @property {Amount|undefined} deltaY
- */
-
-/**
- * @typedef {object} GetXYResultDeltaY
- * @property {Amount} x
- * @property {Amount} y
- * @property {Amount} deltaY
- * @property {Amount|undefined} deltaX
- */
-
-/**
- * @typedef {GetXYResultDeltaX & GetXYResultDeltaY} GetXYResult
- */
-
-/**
- * @callback GetXY
- * @param {GetXYParam} obj
- * @returns {GetXYResult}
- */

package/src/vpool-xyk-amm/constantProduct/invariants.js

@@ -1,43 +0,0 @@
-// @ts-check
-
-import { assert, details as X } from '@agoric/assert';
-import { AmountMath } from '@agoric/ertp';
-
-import { natSafeMath } from '@agoric/zoe/src/contractSupport/index.js';
-
-/**
- * xy <= (x + deltaX)(y - deltaY)
- *
- * @param {Amount} x - the amount of Brand X in pool, xPoolAllocation
- * @param {Amount} y - the amount of Brand Y in pool, yPoolAllocation
- * @param {Amount} deltaX - the amount of Brand X to be added
- * @param {Amount} deltaY - the amount of Brand Y to be taken out
- */
-export const checkKInvariantSellingX = (x, y, deltaX, deltaY) => {
-  const oldK = natSafeMath.multiply(x.value, y.value);
-  const newX = AmountMath.add(x, deltaX);
-  const newY = AmountMath.subtract(y, deltaY);
-  const newK = natSafeMath.multiply(newX.value, newY.value);
-  return oldK <= newK;
-};
-
-/**
- * xy <= (x + deltaX)(y - deltaY)
- *
- * @param {Amount} x - the amount of Brand X in pool, xPoolAllocation
- * @param {Amount} y - the amount of Brand Y in pool, yPoolAllocation
- * @param {Amount} deltaX - the amount of Brand X to be added
- * @param {Amount} deltaY - the amount of Brand Y to be taken out
- */
-export const assertKInvariantSellingX = (x, y, deltaX, deltaY) => {
-  assert(
-    checkKInvariantSellingX(x, y, deltaX, deltaY),
-    X`the constant product invariant was violated, with x=${x}, y=${y}, deltaX=${deltaX}, deltaY=${deltaY}, oldK=${natSafeMath.multiply(
-      x.value,
-      y.value,
-    )}, newK=${natSafeMath.multiply(
-      AmountMath.add(x, deltaX).value,
-      AmountMath.subtract(y, deltaY).value,
-    )}`,
-  );
-};

package/src/vpool-xyk-amm/constantProduct/swap.js

@@ -1,272 +0,0 @@
-// @ts-check
-
-import { AmountMath } from '@agoric/ertp';
-import { calculateFees, amountGT } from './calcFees.js';
-
-const { details: X } = assert;
-
-/**
- * The fee might not be in the same brand as the amount. If they are the same,
- * subtract the fee from the amount. Otherwise return the unadjusted amount.
- *
- * We return empty if the fee is larger because an empty amount indicates that
- * the trader didn't place a limit on the inputAmount.
- *
- * @param {Amount} amount
- * @param {Amount} fee
- * @returns {Amount}
- */
-const subtractRelevantFees = (amount, fee) => {
-  if (amount.brand === fee.brand) {
-    if (AmountMath.isGTE(fee, amount)) {
-      return AmountMath.makeEmptyFromAmount(amount);
-    }
-
-    return AmountMath.subtract(amount, fee);
-  }
-  return amount;
-};
-
-/**
- * PoolFee and ProtocolFee each identify their brand. If either (or both) match
- * the brand of the Amount, subtract it/them from the amount.
- *
- * @param {Amount} amount
- * @param {FeePair} fee
- * @returns {Amount}
- */
-const subtractFees = (amount, { poolFee, protocolFee }) => {
-  return subtractRelevantFees(
-    subtractRelevantFees(amount, protocolFee),
-    poolFee,
-  );
-};
-
-/**
- * The fee might not be in the same brand as the amount. If they are the same,
- * add the fee to the amount. Otherwise return the unadjusted amount.
- *
- * @param {Amount} amount
- * @param {Amount} fee
- * @returns {Amount}
- */
-const addRelevantFees = (amount, fee) => {
-  if (amount.brand === fee.brand) {
-    return AmountMath.add(amount, fee);
-  }
-  return amount;
-};
-
-/**
- * PoolFee and ProtocolFee each identify their brand. If either (or both) match
- * the brand of the Amount, add it/them to the amount.
- *
- * @param {Amount} amount
- * @param {FeePair} fee
- * @returns {Amount}
- */
-const addFees = (amount, { poolFee, protocolFee }) => {
-  return addRelevantFees(addRelevantFees(amount, protocolFee), poolFee);
-};
-
-/**
- * Increment or decrement a pool balance by an amount. The amount's brand might
- * match the Central or Secondary balance of the pool. Return the adjusted
- * balance. The caller knows which amount they provided, so they're expecting a
- * single Amount whose brand matches the amount parameter.
- *
- * The first parameter specifies whether we're incrementing or decrementing from the pool
- *
- * @param {(amountLeft: Amount, amountRight: Amount, brand?: Brand) => Amount} addOrSub
- * @param {PoolAllocation} poolAllocation
- * @param {Amount} amount
- * @returns {Amount}
- */
-const addOrSubtractFromPool = (addOrSub, poolAllocation, amount) => {
-  if (poolAllocation.Central.brand === amount.brand) {
-    return addOrSub(poolAllocation.Central, amount);
-  } else {
-    return addOrSub(poolAllocation.Secondary, amount);
-  }
-};
-
-const isGreaterThanZero = amount => {
-  return amount && amountGT(amount, AmountMath.makeEmptyFromAmount(amount));
-};
-
-const assertGreaterThanZero = (amount, name) => {
-  (amount && isGreaterThanZero(amount)) ||
-    assert.fail(X`${name} must be greater than 0: ${amount}`);
-};
-
-const isWantedAvailable = (poolAllocation, amountWanted) => {
-  // The question is about a poolAllocation. If it has exactly amountWanted,
-  // that's not sufficient, since it would leave the pool empty.
-  return amountWanted.brand === poolAllocation.Central.brand
-    ? !AmountMath.isGTE(amountWanted, poolAllocation.Central)
-    : !AmountMath.isGTE(amountWanted, poolAllocation.Secondary);
-};
-
-/**
- * We've identified a violation of constraints that means we won't be able to
- * satisfy the user's request. (Not enough funds in the pool, too much was
- * requested, the proceeds would be empty, etc.) Return a result that says no
- * trade will take place and the pool balances won't change.
- *
- * @param {Amount} amountGiven
- * @param {Amount} amountWanted
- * @param {PoolAllocation} poolAllocation
- * @param {Ratio} poolFee
- */
-const makeNoTransaction = (
-  amountGiven,
-  amountWanted,
-  poolAllocation,
-  poolFee,
-) => {
-  const emptyGive = AmountMath.makeEmptyFromAmount(amountGiven);
-  const emptyWant = AmountMath.makeEmptyFromAmount(amountWanted);
-
-  let newX;
-  let newY;
-  if (poolAllocation.Central.brand === amountGiven.brand) {
-    newX = poolAllocation.Central;
-    newY = poolAllocation.Secondary;
-  } else {
-    newX = poolAllocation.Secondary;
-    newY = poolAllocation.Central;
-  }
-
-  const result = harden({
-    protocolFee: AmountMath.makeEmpty(poolAllocation.Central.brand),
-    poolFee: AmountMath.makeEmpty(poolFee.numerator.brand),
-    swapperGives: emptyGive,
-    swapperGets: emptyWant,
-    xIncrement: emptyGive,
-    yDecrement: emptyWant,
-    newX,
-    newY,
-  });
-  return result;
-};
-
-/**
- * This is the heart of the calculation. See README.md for the long explanation.
- * calculate how much should be added to and removed from the pool, the fees,
- * and what the user will pay and receive.
- *
- * As soon as we detect that we won't be able to satisfy the request, we return
- * noTransaction, indicating that no trade should take place. This can be due to
- * a request for more assets than the pool holds, a specified price the current
- * assets won't support, or the trade would require more than the trader allowed,
- * or provide less, or fees would eat up all the trader's proceeds.
- *
- * We start by calculating the amounts that would be traded if no fees were
- * charged. The actual fees are based on these amounts. Once we know the actual
- * fees, we calculate the deltaX and deltaY that will best maintain the
- * constant product invariant.
- *
- * The amounts by which the pool will be adjusted, that the trader will pay and
- * receive, and the fees are then computed based on deltaX and deltaY.
- *
- * @type {InternalSwap}
- */
-export const swap = (
-  amountGiven,
-  poolAllocation,
-  amountWanted,
-  protocolFeeRatio,
-  poolFeeRatio,
-  swapFn,
-) => {
-  const noTransaction = makeNoTransaction(
-    amountGiven,
-    amountWanted,
-    poolAllocation,
-    poolFeeRatio,
-  );
-  assertGreaterThanZero(poolAllocation.Central, 'poolAllocation.Central');
-  assertGreaterThanZero(poolAllocation.Secondary, 'poolAllocation.Secondary');
-
-  if (!isGreaterThanZero(amountGiven) && !isGreaterThanZero(amountWanted)) {
-    return noTransaction;
-  }
-
-  if (!isWantedAvailable(poolAllocation, amountWanted)) {
-    return noTransaction;
-  }
-
-  // The protocol fee must always be collected in `Fee`, but the pool
-  // fee is collected in the amount opposite of what is specified.
-  // This call gives us improved amountIn or amountOut
-  const fees = calculateFees(
-    amountGiven,
-    poolAllocation,
-    amountWanted,
-    protocolFeeRatio,
-    poolFeeRatio,
-    swapFn,
-  );
-
-  if (!isWantedAvailable(poolAllocation, addFees(amountWanted, fees))) {
-    return noTransaction;
-  }
-
-  // Calculate no-fee amounts. swapFn will only pay attention to the `specified`
-  // value. The pool fee is always charged on the unspecified side, so it is an
-  // output of the calculation. When the specified value is in `Fee`, the protocol fee will
-  // be deducted from amountGiven before adding to the pool or added to
-  // amountWanted to calculate amountOut. Otherwise we add the protocol fee
-  // to amountWanted.
-  const { amountIn, amountOut } = swapFn({
-    amountGiven: subtractFees(amountGiven, fees),
-    poolAllocation,
-    amountWanted: addFees(amountWanted, fees),
-  });
-
-  if (AmountMath.isEmpty(amountOut)) {
-    return noTransaction;
-  }
-
-  // The swapper pays extra or receives less to cover the fees.
-  const swapperGives = addFees(amountIn, fees);
-  const swapperGets = subtractFees(amountOut, fees);
-
-  // return noTransaction if fees would eat up all the trader's proceeds,
-  // the trader specified an amountGiven, and the trade would require more, or
-  // the trade would require them to give more than they specified.
-  if (
-    AmountMath.isEmpty(swapperGets) ||
-    (!AmountMath.isEmpty(amountGiven) && amountGT(swapperGives, amountGiven)) ||
-    amountGT(amountWanted, swapperGets)
-  ) {
-    return noTransaction;
-  }
-
-  const xIncrement = addRelevantFees(amountIn, fees.poolFee);
-  const yDecrement = subtractRelevantFees(amountOut, fees.poolFee);
-
-  // poolFee is the amount the pool will grow over the no-fee calculation.
-  // protocolFee is to be separated and sent to an external purse.
-  // The swapper amounts are what will be paid and received.
-  // xIncrement and yDecrement are what will be added and removed from the pools.
-  //   Either xIncrement will be increased by the pool fee or yDecrement will be
-  //   reduced by it in order to compensate the pool.
-  // newX and newY are the new pool balances, for comparison with start values.
-  const result = harden({
-    protocolFee: fees.protocolFee,
-    poolFee: fees.poolFee,
-    swapperGives,
-    swapperGets,
-    xIncrement,
-    yDecrement,
-    newX: addOrSubtractFromPool(AmountMath.add, poolAllocation, xIncrement),
-    newY: addOrSubtractFromPool(
-      AmountMath.subtract,
-      poolAllocation,
-      yDecrement,
-    ),
-  });
-
-  return result;
-};

package/src/vpool-xyk-amm/constantProduct/types.js

@@ -1,32 +0,0 @@
-// @ts-check
-
-/**
- * @callback Maximum
- * @param {Amount} left
- * @param {Amount} right
- * @returns {Amount}
- */
-
-/**
- * A bigint representing a number that will be divided by 10,0000. Financial
- * ratios are often represented in basis points.
- *
- * @typedef {bigint} BASIS_POINTS
- */
-
-/**
- * Make a Ratio representing a fee expressed in Basis Points.  (hundredths of a
- *    percent)
- *
- * @callback MakeFeeRatio
- * @param {BASIS_POINTS} feeBP
- * @param {Brand} brandOfFee
- * @returns {Ratio}
- */
-
-/**
- * @callback AmountGT
- * @param {Amount} left
- * @param {Amount} right
- * @returns {boolean}
- */

package/src/vpool-xyk-amm/doublePool.js

@@ -1,194 +0,0 @@
-// @ts-check
-
-import { AmountMath } from '@agoric/ertp';
-import { Far } from '@endo/marshal';
-import { makeFeeRatio } from './constantProduct/calcFees.js';
-import {
-  pricesForStatedInput,
-  pricesForStatedOutput,
-} from './constantProduct/calcSwapPrices.js';
-
-const { details: X } = assert;
-
-// Price calculations and swap using a pair of pools. Both pools map between RUN
-// and some collateral. We arrange the trades so collateralInPool will have
-// collateral added and collateralOutPool subtracted. When traders specify an
-// input price, that brand will be the inPool; when they specify the output
-// price that brand is the outPool.
-
-/**
- * doublePool is the virtualPool implementation for calculating prices when
- * transiting through two pools. virtual pools wrap something that can do a swap
- * and calculate prices. Current wrapped pools are single pools and pairs of
- * pools, but we've also contemplated using a similar virtual wrapper for other
- * curves.
- *
- * @param {ZCF} zcf
- * @param {XYKPool} collateralInPool
- * @param {XYKPool} collateralOutPool
- * @param {() => bigint} getProtocolFeeBP - retrieve governed protocol fee value
- * @param {() => bigint} getPoolFeeBP - retrieve governed pool fee value
- * @param {ZCFSeat} feeSeat
- * @returns {VirtualPool<'double'>}
- */
-export const makeDoublePool = (
-  zcf,
-  collateralInPool,
-  collateralOutPool,
-  getProtocolFeeBP,
-  getPoolFeeBP,
-  feeSeat,
-) => {
-  const inCentral = collateralInPool.getCentralAmount();
-  const inSecondary = collateralInPool.getSecondaryAmount();
-
-  const outCentral = collateralOutPool.getCentralAmount();
-  const outSecondary = collateralOutPool.getSecondaryAmount();
-
-  const inAllocation = { Central: inCentral, Secondary: inSecondary };
-  const outAllocation = { Central: outCentral, Secondary: outSecondary };
-
-  const centralBrand = inCentral.brand;
-  const emptyCentralAmount = AmountMath.makeEmpty(centralBrand);
-  centralBrand === outCentral.brand ||
-    assert.fail(
-      X`The central brands on the two pools must match: ${centralBrand}, ${outCentral.brand}`,
-    );
-
-  const allocateGainsAndLosses = (seat, prices) => {
-    const inPoolSeat = collateralInPool.getPoolSeat();
-    const outPoolSeat = collateralOutPool.getPoolSeat();
-
-    seat.decrementBy(harden({ In: prices.swapperGives }));
-    inPoolSeat.decrementBy(harden({ Central: prices.inPoolDecrement }));
-    outPoolSeat.decrementBy(harden({ Secondary: prices.outPoolDecrement }));
-    seat.incrementBy(harden({ Out: prices.swapperGets }));
-    inPoolSeat.incrementBy(harden({ Secondary: prices.inPoolIncrement }));
-    outPoolSeat.incrementBy(harden({ Central: prices.outPoolIncrement }));
-    feeSeat.incrementBy(harden({ Fee: prices.protocolFee }));
-
-    zcf.reallocate(outPoolSeat, inPoolSeat, feeSeat, seat);
-    seat.exit();
-    collateralInPool.updateState();
-    collateralOutPool.updateState();
-    return `Swap successfully completed.`;
-  };
-
-  const getPriceForInput = (amountIn, amountOut) => {
-    const protocolFeeRatio = makeFeeRatio(getProtocolFeeBP(), centralBrand);
-    const poolFeeRatioCentral = makeFeeRatio(getPoolFeeBP(), centralBrand);
-    const poolFeeRatioAmountOut = makeFeeRatio(getPoolFeeBP(), amountOut.brand);
-
-    // We must do two consecutive swapInPrice() calls,
-    // followed by a call to swapOutPrice().
-    // 1) from amountIn to the central token, which tells us how much central
-    //  would be provided for amountIn,
-    // 2) from that amount of central to brandOut, which tells us how much of
-    //  brandOut will be provided as well as the minimum price in central
-    //  tokens, then finally
-    // 3) call swapOutPrice() to see if the same proceeds can be purchased for
-    //  less.
-    // Notice that in the second call, the original amountOut is used, and in
-    // the third call, the original amountIn is used.
-    const interimInpoolPrices = pricesForStatedInput(
-      amountIn,
-      inAllocation,
-      emptyCentralAmount,
-      protocolFeeRatio,
-      poolFeeRatioCentral,
-    );
-    const outPoolPrices = pricesForStatedInput(
-      interimInpoolPrices.swapperGets,
-      outAllocation,
-      amountOut,
-      protocolFeeRatio,
-      poolFeeRatioAmountOut,
-    );
-    const finalInPoolPrices = pricesForStatedOutput(
-      amountIn,
-      inAllocation,
-      outPoolPrices.swapperGives,
-      protocolFeeRatio,
-      poolFeeRatioCentral,
-    );
-
-    // When finalInPoolPrices has a price improvement that makes the difference
-    // between finalInPoolPrices.yDecrement and outPoolPrices.xIncrement more
-    // than the calculated protocol fees add the excess to the protocol fee.
-    const protocolFee = AmountMath.max(
-      AmountMath.add(finalInPoolPrices.protocolFee, outPoolPrices.protocolFee),
-      AmountMath.subtract(
-        finalInPoolPrices.yDecrement,
-        outPoolPrices.xIncrement,
-      ),
-    );
-
-    return harden({
-      swapperGives: finalInPoolPrices.swapperGives,
-      swapperGets: outPoolPrices.swapperGets,
-      inPoolIncrement: finalInPoolPrices.xIncrement,
-      inPoolDecrement: finalInPoolPrices.yDecrement,
-      outPoolIncrement: outPoolPrices.xIncrement,
-      outPoolDecrement: outPoolPrices.yDecrement,
-      protocolFee,
-    });
-  };
-
-  const getPriceForOutput = (amountIn, amountOut) => {
-    const protocolFeeRatio = makeFeeRatio(getProtocolFeeBP(), centralBrand);
-    const poolFeeRatioCentral = makeFeeRatio(getPoolFeeBP(), centralBrand);
-    const poolFeeRatioAmountIn = makeFeeRatio(getPoolFeeBP(), amountIn.brand);
-
-    // We must do two consecutive swapOutPrice() calls, followed by a call to
-    // swapInPrice().
-    // 1) from amountOut to the central token, which tells us how much central
-    //  is required to obtain amountOut,
-    // 2) from that amount of central to brandIn, which tells us how much of
-    //  brandIn is required as well as the max proceeds in central tokens, then
-    //  finally
-    // 3) call swapInPrice() to see if those central proceeds could purchase
-    //  larger amount
-    // Notice that the amountIn parameter to the first call to swapOutPrice
-    // specifies an empty amount. This is interpreted as "no limit", which is
-    // necessary since we can't guess a reasonable maximum of the central token.
-    const interimOutpoolPrices = pricesForStatedOutput(
-      emptyCentralAmount,
-      outAllocation,
-      amountOut,
-      protocolFeeRatio,
-      poolFeeRatioCentral,
-    );
-    const inpoolPrices = pricesForStatedOutput(
-      amountIn,
-      inAllocation,
-      interimOutpoolPrices.swapperGives,
-      protocolFeeRatio,
-      poolFeeRatioAmountIn,
-    );
-    const finalOutpoolPrices = pricesForStatedInput(
-      inpoolPrices.swapperGets,
-      outAllocation,
-      amountOut,
-      protocolFeeRatio,
-      poolFeeRatioCentral,
-    );
-    return harden({
-      swapperGives: inpoolPrices.swapperGives,
-      swapperGets: finalOutpoolPrices.swapperGets,
-      inPoolIncrement: inpoolPrices.xIncrement,
-      inPoolDecrement: inpoolPrices.yDecrement,
-      outPoolIncrement: finalOutpoolPrices.xIncrement,
-      outPoolDecrement: finalOutpoolPrices.yDecrement,
-      protocolFee: AmountMath.add(
-        finalOutpoolPrices.protocolFee,
-        inpoolPrices.protocolFee,
-      ),
-    });
-  };
-
-  return Far('double pool', {
-    getPriceForInput,
-    getPriceForOutput,
-    allocateGainsAndLosses,
-  });
-};