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

package/src/vaultFactory/liquidateMinimum.js

@@ -1,100 +0,0 @@
-// @ts-check
-
-import { E } from '@endo/eventual-send';
-import {
-  ceilMultiplyBy,
-  offerTo,
-} from '@agoric/zoe/src/contractSupport/index.js';
-import { AmountMath } from '@agoric/ertp';
-import { Far } from '@endo/marshal';
-
-import { makeTracer } from '../makeTracer.js';
-
-const trace = makeTracer('LiqMin', false);
-
-/**
- * This contract liquidates the minimum amount of vault's collateral necessary
- * to satisfy the debt. It uses the AMM's swapOut, which sells no more than
- * necessary. Because it has offer safety, it can refuse the trade. When that
- * happens, we fall back to selling using the default strategy, which currently
- * uses the AMM's swapIn instead.
- *
- * @param {ZCF<{
- *   amm: XYKAMMPublicFacet,
- * }>} zcf
- */
-const start = async zcf => {
-  const { amm } = zcf.getTerms();
-  trace('start', zcf.getTerms());
-
-  /**
-   * @param {ZCFSeat} debtorSeat
-   * @param {object} options
-   * @param {Amount<'nat'>} options.debt Debt before penalties
-   * @param {Ratio} options.penaltyRate
-   */
-  const handleLiquidationOffer = async (
-    debtorSeat,
-    { debt: originalDebt, penaltyRate },
-  ) => {
-    // XXX does not distribute penalties anywhere
-    const { zcfSeat: penaltyPoolSeat } = zcf.makeEmptySeatKit();
-    const penalty = ceilMultiplyBy(originalDebt, penaltyRate);
-    const debtWithPenalty = AmountMath.add(originalDebt, penalty);
-    const debtBrand = originalDebt.brand;
-    const {
-      give: { In: amountIn },
-    } = debtorSeat.getProposal();
-
-    const swapInvitation = E(amm).makeSwapInvitation();
-    const liqProposal = harden({
-      give: { In: amountIn },
-      want: { Out: AmountMath.makeEmpty(debtBrand) },
-    });
-    trace(`OFFER TO DEBT: `, debtWithPenalty, amountIn);
-    const { deposited } = await offerTo(
-      zcf,
-      swapInvitation,
-      undefined, // The keywords were mapped already
-      liqProposal,
-      debtorSeat,
-      debtorSeat,
-      { stopAfter: debtWithPenalty },
-    );
-    const amounts = await deposited;
-    trace(`Liq results`, {
-      debtWithPenalty,
-      amountIn,
-      paid: debtorSeat.getCurrentAllocation(),
-      amounts,
-    });
-
-    // Now we need to know how much was sold so we can pay off the debt.
-    // We can use this seat because only liquidation adds debt brand to it..
-    const debtPaid = debtorSeat.getAmountAllocated('Out', debtBrand);
-    const penaltyPaid = AmountMath.min(penalty, debtPaid);
-
-    // Allocate penalty portion of proceeds to a seat that will hold it for transfer to reserve
-    penaltyPoolSeat.incrementBy(
-      debtorSeat.decrementBy(harden({ Out: penaltyPaid })),
-    );
-    zcf.reallocate(penaltyPoolSeat, debtorSeat);
-
-    debtorSeat.exit();
-  };
-
-  /**
-   * @type {ERef<Liquidator>}
-   */
-  const creatorFacet = Far('debtorInvitationCreator (minimum)', {
-    makeLiquidateInvitation: () =>
-      zcf.makeInvitation(handleLiquidationOffer, 'Liquidate'),
-  });
-
-  return harden({ creatorFacet });
-};
-
-/** @typedef {ContractOf<typeof start>} LiquidationContract */
-
-harden(start);
-export { start };

package/src/vpool-xyk-amm/AttackersGuide.md

@@ -1,89 +0,0 @@
-# An Attacker's guide to the Constant Product AMM
-
-This is an incomplete list of potential weak points that an attacker might want to focus
-on when looking for ways to violate the integrity of the AMM. It's here to help defenders,
-as "attacker's mindset" is a good way to focus attention for the defender. The list should
-correspond pretty closely to the set of assurances that the AMM aims to support.
-
-The main guarantee that an
-[Automated Market Maker](https://mason.gmu.edu/~rhanson/mktscore.pdf) makes is that
-sufficiently liquid pools will always retain enough collateral through any sequence of
-trades to be able to continue trading. The caveat just means that when the amount of
-liquidity in the pool is quite small with respect to desired trades, trades will quickly
-push the balance to extreme enough prices that no further trading will take place. If the
-pool is liquid enough, trades will push the price enough out of equilibrium that it will
-be very attractive for arbitrageurs to restore the price. Anything that allows traders or
-liquidity providers to violate that expectation is a problem.
-
-## Multiple Pools
-
-`addPool` and `addLiquidity` are publicly available. That means someone could maliciously
-create pools or provide insufficient liquidity. The requirement of a minimum initial
-liquidity should be enough to prevent misuse of these APIs from hurting us.
-
-Since `addPool` is public, someone could add a look-alike issuer for a well-known
-currency and make it harder for people to find the pool they intend to trade with. As
-long as people are dealing wiht Brands and Issuers, they shouldn't be confused by
-this. Does the Wallet UI provide enough clarity in the face of this?
-
-Zoe holds the collaterral for all the pools in common. We segragate it by Pool, so each
-pool's allocation includes some IST (the central currency) and some of another
-collateral. The doublePool trades move IST between pools, but Zoe's rights conservation
-enforcement ensure that none is ever gained or lost.
-
-## Fees
-
-Fees are collected as trading takes place, and kept in a distinct Zoe seat. The creator of
-the AMM should be the only one who can collect the fees. Can that invitation be hijacked
-from whoever gets that facet during bootstrap?  Is there another way to steal fees?
-
-Can users structure trades so they can pay less in fees than intended?
-
-## Providing Liquidity
-
-Traders can provide liquidity and get liquidity tokens for a particular pool. The goal is
-that they earn a share of the fees that were collected while their liquidity remained in
-the pool. Can liquidity providers gain extra fees over other providers, or can they cause
-traders to be disadvantaged?
-
-Can liquidity providers extact more from the pool than they should be able to?
-
-## Math
-
-The whole design is predicated on the X*Y=K invariant.  That invariant says that trading
-should not change the product of X and Y, but in actuality, roundoff and fees are both
-allowed to change the product. Roundoff should increase it ever so slightly, except in
-cases where there are small amounts in the pool, where it can be significant. Fees are
-added to the pool, so they change the size of the pool, but should be interpreted as
-taking place after the trade rebalances the amounts. The equations are explained in detail
-in `constantProduct/README.md`.
-
-Adding liquidity adds funds to both pools so, of course, it changes X and Y. But (except
-in the case of `AddLiquidityAtRate`), it should keep X and Y in the same proportion.
-
-I don't know whether anyone else has done an implementation of the multi-pool swap that
-works like ours. If neither X nor Y is IST, then we trade X for IST and IST for
-Y. Attributing fees in this case took some art. This is also addressed in
-`constantProduct/README.md`.
-
-Adding liquidity while changing the ratio of assets is done in two steps in order to
-prevent people from using a single step as a way to avoid fees on trades. Users shouldn't
-be able to use `AddLiquidityAtRate` to avoid paying fees on what is effectively a trade.
-
-
-## Economics
-
-The Inter Protocol mechanism is envisioned as a major provider of liquidity. It may leave
-its liquidity in the pool over the long term, and never or seldom collect earnings. Does
-this affect prices or trading volumes adverselyj? (More liquidity is expected to provide
-better prices for traders, so this would be a surprise.)
-
-Other constant product markets have performed reasonably well through periods of high
-volatillity. Is there any reason to expect the design variations we've introduced to have
-trouble where others did not?
-
-## Governance
-
-The poolFee and protocolFee can be changed by governance. Can unauthorized parties
-interfere with this? Is there any hazard here beyond the possibility that the holders of
-this power might raise rates more than some users would be happy with?

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

@@ -1,222 +0,0 @@
-// @ts-check
-
-import {
-  assertProposalShape,
-  calcSecondaryRequired,
-  natSafeMath,
-} from '@agoric/zoe/src/contractSupport/index.js';
-import { AmountMath } from '@agoric/ertp';
-
-import '@agoric/zoe/exported.js';
-
-const { details: X, quote: q } = assert;
-
-const { add, multiply } = natSafeMath;
-/**
- * @param {ZCF} zcf
- * @param {(brand: Brand) => XYKPool} getPool
- */
-const makeMakeAddLiquidityInvitation = (zcf, getPool) => {
-  const addLiquidity = seat => {
-    assertProposalShape(seat, {
-      give: {
-        Central: null,
-        Secondary: null,
-      },
-    });
-
-    // Get the brand of the secondary token so we can identify the liquidity pool.
-    const secondaryBrand = seat.getProposal().give.Secondary.brand;
-    const pool = getPool(secondaryBrand);
-    const liquidityIssuer = pool.getLiquidityIssuer();
-    const liquidityBrand = zcf.getBrandForIssuer(liquidityIssuer);
-    seat.getProposal().want.Liquidity.brand === liquidityBrand ||
-      assert.fail(X`liquidity brand must be ${q(liquidityBrand)}`);
-
-    return pool.addLiquidity(seat);
-  };
-
-  const makeAddLiquidityInvitation = () =>
-    zcf.makeInvitation(addLiquidity, 'multipool amm add liquidity');
-
-  return makeAddLiquidityInvitation;
-};
-
-// The desired ratio requires a wider range than K would support.
-const imbalancedRequest = (desiredRatio, startK) => {
-  if (desiredRatio > 1.0) {
-    return desiredRatio > Number(startK);
-  } else {
-    return Number(startK) * desiredRatio < 1n;
-  }
-};
-harden(imbalancedRequest);
-// exported for testing only
-export { imbalancedRequest };
-
-/**
- * The pool has poolX and poolY currently. The user wants to add liquidity of
- * giveX and giveY, but the ratios are probably not the same. We want to adjust
- * the pool to have the ratio (poolX + giveX) / (poolY + giveY), without
- * changing K, the product of the two sides.
- *
- * Calculate targetX and targetY, which multiply to the same product as
- * poolX * poolY, but are in the ratio we'll end at. From this we can produce
- * a proposed trade that maintains K, but changes the ratio, so we can add
- * liquidity at the desired ratio.
- *
- * endX = poolX + giveX;   endY = poolY + giveY
- * desiredRatio = endX / endY
- * targetY = sqrt(startK / desiredRatio)
- * targetX = desiredRatio * targetY
- *   so targetK equals startK because we square targetY
- * targetK = targetX * targetY = desiredRatio * (startK / desiredRatio)
- *
- * Since startK/endK is less than one, and we have to worry about early loss of
- * precision, we round and convert to bigint as the last step
- *
- * If the desired ratio (the ratio of the sums of contributed amounts and pool
- * balances) is larger than K (which most often happens when the pool balances
- * are small) we somewhat arbitrarily refuse the transaction.
- * For instance, if the desired ratio is 1000:1 because one currency uses 12
- * digits and the other 9, and the pool has single digits of liquidity, then
- * it would be better to manually adjust rather than using this approach.
- *
- * @param {Amount<'nat'>} poolX
- * @param {Amount<'nat'>} poolY
- * @param {Amount<'nat'>} giveX
- * @param {Amount<'nat'>} giveY
- * @returns {{targetX: Amount<'nat'>, targetY: Amount<'nat'> }}
- */
-export const balancesToReachRatio = (poolX, poolY, giveX, giveY) => {
-  const startK = multiply(poolX.value, poolY.value);
-  const endX = add(poolX.value, giveX.value);
-  const endY = add(poolY.value, giveY.value);
-  const desiredRatio = Number(endX) / Number(endY);
-
-  if (imbalancedRequest(desiredRatio, startK)) {
-    return {
-      targetX: AmountMath.makeEmpty(poolX.brand),
-      targetY: AmountMath.makeEmpty(poolY.brand),
-    };
-  }
-  const targetY = Math.sqrt(Number(startK) / desiredRatio);
-  const targetX = targetY * desiredRatio;
-
-  return {
-    targetX: AmountMath.make(poolX.brand, BigInt(Math.trunc(targetX))),
-    targetY: AmountMath.make(poolY.brand, BigInt(Math.trunc(targetY))),
-  };
-};
-
-/**
- * @param {ZCF} zcf
- * @param {(b: Brand) => XYKPool} getPool
- * @param {(i: Brand) => VirtualPool} provideVPool
- * @param {ZCFSeat} feeSeat
- * @param {(b: Brand) => PoolFacets['helper']} getPoolHelper
- */
-const makeMakeAddLiquidityAtRateInvitation = (
-  zcf,
-  getPool,
-  provideVPool,
-  feeSeat,
-  getPoolHelper,
-) => {
-  const addLiquidityAtRate = seat => {
-    assertProposalShape(seat, {
-      give: {
-        Central: null,
-        Secondary: null,
-      },
-      want: { Liquidity: null },
-    });
-
-    const giveAlloc = seat.getProposal().give;
-    const secondaryAmount = giveAlloc.Secondary;
-    const secondaryBrand = secondaryAmount.brand;
-    const centralBrand = giveAlloc.Central.brand;
-    const pool = getPool(secondaryBrand);
-    // Step 1: trade to adjust the pool's price
-    //   A  figure out the ratio of the inputs
-    //   B  figure out how X*Y changes to reach that ratio (ignoring fees)
-    const centralPoolAmount = pool.getCentralAmount();
-    const secondaryPoolAmount = pool.getSecondaryAmount();
-
-    if (
-      AmountMath.isEmpty(centralPoolAmount) &&
-      AmountMath.isEmpty(secondaryPoolAmount)
-    ) {
-      return pool.addLiquidity(seat);
-    }
-
-    const { targetX: newCentral, targetY: newSecondary } = balancesToReachRatio(
-      centralPoolAmount,
-      secondaryPoolAmount,
-      giveAlloc.Central,
-      giveAlloc.Secondary,
-    );
-
-    const vPool = provideVPool(secondaryBrand);
-    const poolSeat = pool.getPoolSeat();
-    const transferForTrade = (prices, incrementKey, decrementKey) => {
-      seat.decrementBy(harden({ [incrementKey]: prices.swapperGives }));
-      poolSeat.decrementBy(harden({ [decrementKey]: prices.yDecrement }));
-      seat.incrementBy(harden({ [decrementKey]: prices.swapperGets }));
-      feeSeat.incrementBy(harden({ Fee: prices.protocolFee }));
-      poolSeat.incrementBy(harden({ [incrementKey]: prices.xIncrement }));
-    };
-
-    //   1C  Stage the changes for the trade
-    if (AmountMath.isGTE(newCentral, centralPoolAmount)) {
-      const prices = vPool.getPriceForOutput(
-        AmountMath.makeEmpty(centralBrand),
-        AmountMath.subtract(secondaryPoolAmount, newSecondary),
-      );
-      transferForTrade(prices, 'Central', 'Secondary');
-    } else {
-      const prices = vPool.getPriceForInput(
-        AmountMath.subtract(newSecondary, secondaryPoolAmount),
-        AmountMath.makeEmpty(centralBrand),
-      );
-      transferForTrade(prices, 'Secondary', 'Central');
-    }
-
-    // Step 2: add remaining liquidity
-    const stagedAllocation = poolSeat.getStagedAllocation();
-    const centralPoolAfterTrade = stagedAllocation.Central;
-    const secondaryPoolAfterTrade = stagedAllocation.Secondary;
-    const userAllocation = seat.getStagedAllocation();
-
-    const secondaryRequired = AmountMath.make(
-      secondaryBrand,
-      calcSecondaryRequired(
-        userAllocation.Central.value,
-        centralPoolAfterTrade.value,
-        secondaryPoolAfterTrade.value,
-        userAllocation.Secondary.value,
-      ),
-    );
-
-    return getPoolHelper(secondaryBrand).addLiquidityActual(
-      pool,
-      seat,
-      secondaryRequired,
-      poolSeat.getStagedAllocation().Central,
-      feeSeat,
-    );
-  };
-
-  const makeAddLiquidityInvitation = () =>
-    zcf.makeInvitation(
-      addLiquidityAtRate,
-      'multipool amm add liquidity at rate',
-    );
-
-  return makeAddLiquidityInvitation;
-};
-
-harden(makeMakeAddLiquidityInvitation);
-harden(makeMakeAddLiquidityAtRateInvitation);
-
-export { makeMakeAddLiquidityInvitation, makeMakeAddLiquidityAtRateInvitation };

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

@@ -1,197 +0,0 @@
-// @ts-check
-
-import { E } from '@endo/eventual-send';
-import { AmountMath, AssetKind } from '@agoric/ertp';
-import { assertProposalShape } from '@agoric/zoe/src/contractSupport/index.js';
-
-import { definePoolKind } from './pool.js';
-
-const { details: X, quote: q } = assert;
-
-const DISPLAY_INFO = harden({ decimalPlaces: 6 });
-
-/** @typedef {import('@agoric/vat-data').Baggage} Baggage */
-
-/**
- * @param {ZCF} zcf
- * @param {(Brand) => boolean} isInSecondaries
- * @param {import('@agoric/store/src/stores/store-utils.js').AtomicProvider<Brand, ZCFMint>} brandToLiquidityMintProvider
- * @param {() => (secondaryBrand: Brand) => Promise<void>} getAddIssuerToReserve
- */
-export const makeAddIssuer = (
-  zcf,
-  isInSecondaries,
-  brandToLiquidityMintProvider,
-  getAddIssuerToReserve,
-) => {
-  /**
-   * Add a new issuer. If we previously received a request for the same issuer,
-   * we'll return the issuer or a promise for it.
-   *
-   * @param {import('./pool.js').MethodContext} _context
-   * @param {Issuer} secondaryIssuer
-   * @param {string} keyword
-   */
-  const addIssuer = async (_context, secondaryIssuer, keyword) => {
-    const [secondaryAssetKind, secondaryBrand] = await Promise.all([
-      E(secondaryIssuer).getAssetKind(),
-      E(secondaryIssuer).getBrand(),
-    ]);
-    // AWAIT ///////////////
-    secondaryAssetKind === AssetKind.NAT ||
-      assert.fail(X`${q(keyword)} asset not fungible (must use NAT math)`);
-
-    /** @type {(brand: Brand) => Promise<ZCFMint>} */
-    const makeLiquidityMint = brand => {
-      !isInSecondaries(brand) ||
-        assert.fail(X`issuer ${secondaryIssuer} already has a pool`);
-
-      const liquidityKeyword = `${keyword}Liquidity`;
-      zcf.assertUniqueKeyword(liquidityKeyword);
-
-      return E.when(
-        Promise.all([
-          zcf.saveIssuer(secondaryIssuer, keyword),
-          zcf.makeZCFMint(liquidityKeyword, AssetKind.NAT, DISPLAY_INFO),
-        ]),
-        ([issuer, mint]) => {
-          console.log(
-            X`Saved issuer ${secondaryIssuer} to keyword ${keyword} and got back ${issuer}`,
-          );
-          return mint;
-        },
-      ).catch(e => {
-        console.error(
-          X`Failure Saving issuer ${secondaryIssuer}. Not added to Reserve`,
-        );
-        throw e;
-      });
-    };
-
-    /** @type {(brand: Brand) => Promise<void>} */
-    const finish = brand => {
-      // defer lookup until necessary. more aligned with governed
-      // param we expect this to be eventually.
-      const addIssuerToReserve = getAddIssuerToReserve();
-
-      // tell the reserve about this brand, which it will validate by
-      // calling back to AMM for the issuer
-      return addIssuerToReserve(brand);
-    };
-
-    return brandToLiquidityMintProvider
-      .provideAsync(secondaryBrand, makeLiquidityMint, finish)
-      .then(mint => mint.getIssuerRecord().issuer);
-  };
-
-  return addIssuer;
-};
-
-/**
- * @param {Baggage} baggage
- * @param {import('./multipoolMarketMaker.js').AmmPowers} ammPowers
- * @param {(secondaryBrand: Brand, reserveLiquidityTokenSeat: ZCFSeat, liquidityKeyword: Keyword) => Promise<void>} onOfferHandled
- * @param {ERef<StorageNode>} storageNode
- * @param {ERef<Marshaller>} marshaller
- */
-export const makeAddPoolInvitation = (
-  baggage,
-  ammPowers,
-  onOfferHandled,
-  storageNode,
-  marshaller,
-) => {
-  const { zcf } = ammPowers;
-  const makePool = definePoolKind(baggage, ammPowers, storageNode, marshaller);
-
-  /** @type {(Brand) => Promise<{poolFacets: PoolFacets, liquidityZcfMint: ZCFMint}>} */
-  const addPool = async secondaryBrand => {
-    const liquidityZcfMint =
-      ammPowers.secondaryBrandToLiquidityMint.get(secondaryBrand);
-
-    const { zcfSeat: poolSeat } = ammPowers.zcf.makeEmptySeatKit();
-    const poolFacets = makePool(liquidityZcfMint, poolSeat, secondaryBrand);
-
-    ammPowers.secondaryBrandToPool.init(secondaryBrand, poolFacets);
-    return { liquidityZcfMint, poolFacets };
-  };
-
-  /** @param {ZCFSeat} seat */
-  const handleAddPoolOffer = async seat => {
-    assertProposalShape(seat, {
-      give: { Central: null, Secondary: null },
-    });
-
-    const {
-      give: { Central: centralAmount, Secondary: secondaryAmount },
-      want: proposalWant,
-    } = seat.getProposal();
-    const secondaryBrand = secondaryAmount.brand;
-
-    const { brand: liquidityBrand, issuer } =
-      ammPowers.secondaryBrandToLiquidityMint
-        .get(secondaryBrand)
-        .getIssuerRecord();
-
-    const minPoolLiquidity = ammPowers.params.getMinInitialPoolLiquidity();
-
-    if (proposalWant.Liquidity) {
-      const { Liquidity: wantLiquidityAmount } = proposalWant;
-      const centralAboveMinimum =
-        // @ts-expect-error central is NAT
-        centralAmount.value - minPoolLiquidity.value;
-      // when providing initial liquidity, the liquidity tokens issued will be
-      // equal to the central provided. Here, the reserve gets the minimum
-      const funderLiquidityAmount = AmountMath.make(
-        liquidityBrand,
-        centralAboveMinimum,
-      );
-      AmountMath.isGTE(funderLiquidityAmount, wantLiquidityAmount) ||
-        assert.fail(
-          X`Requested too many liquidity tokens (${wantLiquidityAmount}, max: ${funderLiquidityAmount}`,
-        );
-    }
-    AmountMath.isGTE(centralAmount, minPoolLiquidity) ||
-      assert.fail(
-        X`The minimum initial liquidity is ${minPoolLiquidity}, rejecting ${centralAmount}`,
-      );
-    const minLiqAmount = AmountMath.make(
-      liquidityBrand,
-      // @ts-expect-error known nat
-      minPoolLiquidity.value,
-    );
-
-    // @ts-expect-error find might return undefined
-    const [liquidityKeyword] = Object.entries(zcf.getTerms().issuers).find(
-      ([_, i]) => i === issuer,
-    );
-    assert(liquidityKeyword, 'liquidity brand required');
-
-    // COMMIT POINT /////////////////////
-
-    const {
-      poolFacets: { pool, helper },
-    } = await addPool(secondaryBrand);
-
-    // in addLiquidityInternal, funder provides centralAmount & secondaryAmount,
-    // and receives liquidity tokens equal to centralAmount. Afterward, we'll
-    // transfer minPoolLiquidity in tokens from the funder to the reserve.
-    helper.addLiquidityInternal(seat, secondaryAmount, centralAmount);
-
-    seat.decrementBy({ Liquidity: minLiqAmount });
-    const { zcfSeat: reserveLiquidityTokenSeat } = zcf.makeEmptySeatKit();
-    reserveLiquidityTokenSeat.incrementBy({ [liquidityKeyword]: minLiqAmount });
-    zcf.reallocate(reserveLiquidityTokenSeat, seat);
-    seat.exit();
-    pool.updateState();
-
-    await onOfferHandled(
-      secondaryBrand,
-      reserveLiquidityTokenSeat,
-      liquidityKeyword,
-    );
-    return 'Added liquidity.';
-  };
-
-  return () => zcf.makeInvitation(handleAddPoolOffer, 'Add Pool and Liquidity');
-};