@agoric/inter-protocol 0.13.2-dev-70ba9b0.0 → 0.13.2-dev-ed5ee58.0

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

@@ -1,200 +0,0 @@
-import { E } from '@endo/eventual-send';
-import { AmountMath, AssetKind } from '@agoric/ertp';
-import {
-  assertProposalShape,
-  atomicTransfer,
-} from '@agoric/zoe/src/contractSupport/index.js';
-
-import { definePoolKind } from './pool.js';
-
-const { quote: q, Fail } = 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<'nat'>, ZCFMint<'nat'>>} brandToLiquidityMintProvider
- * @param {() => (secondaryBrand: Brand<'nat'>) => 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<'nat'>} 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 ||
-      Fail`${q(keyword)} asset not fungible (must use NAT math)`;
-
-    /** @type {(brand: Brand<'nat'>) => Promise<ZCFMint<'nat'>>} */
-    const makeLiquidityMint = brand => {
-      !isInSecondaries(brand) ||
-        Fail`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(
-            `Saved issuer ${secondaryIssuer} to keyword ${keyword} and got back ${issuer}`,
-          );
-          return mint;
-        },
-      ).catch(e => {
-        console.error(
-          `Failure Saving issuer ${secondaryIssuer}. Not added to Reserve`,
-        );
-        throw e;
-      });
-    };
-
-    /** @type {(brand: Brand<'nat'>) => 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();
-
-    /** @type {Amount<'nat'>} */
-    // @ts-expect-error cast governance types
-    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) ||
-        Fail`Requested too many liquidity tokens (${wantLiquidityAmount}, max: ${funderLiquidityAmount}`;
-    }
-    AmountMath.isGTE(centralAmount, minPoolLiquidity) ||
-      Fail`The minimum initial liquidity is ${minPoolLiquidity}, rejecting ${centralAmount}`;
-    const minLiqAmount = AmountMath.make(
-      liquidityBrand,
-      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);
-
-    const { zcfSeat: reserveLiquidityTokenSeat } = zcf.makeEmptySeatKit();
-    atomicTransfer(
-      zcf,
-      seat,
-      reserveLiquidityTokenSeat,
-      { Liquidity: minLiqAmount },
-      { [liquidityKeyword]: minLiqAmount },
-    );
-
-    seat.exit();
-    pool.updateState();
-
-    await onOfferHandled(
-      secondaryBrand,
-      reserveLiquidityTokenSeat,
-      liquidityKeyword,
-    );
-    return 'Added liquidity.';
-  };
-
-  return () => zcf.makeInvitation(handleAddPoolOffer, 'Add Pool and Liquidity');
-};

package/src/vpool-xyk-amm/constantProduct/README.md

@@ -1,204 +0,0 @@
-# Constant Product AMM
-
-A constant product automatic market maker based on our Ratio library. It charges
-two kinds of fees: a pool fee remains in the pool to reward the liquidity
-providers and a protocol fee is extracted to fund the economy. The external
-entry point is a call to `pricesForStatedInput()` or `pricesForStatedOutput()`.
-
-This algorithm uses the x*y=k formula directly, without fees. Briefly, there are
-two kinds of assets, whose values are kept roughly in balance through the
-actions of arbitrageurs. At any time a trader can trade with the pool by
-offering to deposit one of the two assets. They will receive an amount
-of the complementary asset that will maintain the invariant that the product of
-the balances doesn't decrease. (Rounding is done in favor of the
-pool.)
-
-The user can specify a maximum amount they want to pay or a minimum amount they
-want to receive. Unlike Uniswap, this approach will charge less than the user
-offered or pay more than they asked for when appropriate. By analogy, if a user
-is willing to pay up to $20 when the price of soda is $3 per bottle, it would
-give 6 bottles and only charge $18. (We refer to these as "improved" prices.)
-Uniswap doesn't adjust the provided price, so it would charge $20 in that trade.
-This matters whenever the values of the smallest unit of the currencies are
-significantly different, which is common in DeFi.
-
-The rules that drive the design include
-
-* When the user specifies an input (or output) price, they shouldn't pay more
-  (or receive less) than they said.
-* The pool fee is charged against the side not specified by the user (the
-  "computed side"). This increases the pool balance without impacting the amount
-  that the user specified.
-* The protocol fee is always charged in IST.
-* The fees are calculated based on the pool balances before the transaction.
-* Computations are rounded in favor of the pool.
-
-We start by estimating the exchange rate, and calculate fees based on that. Once
-we know the fees, we add or subtract them directly to the amounts added to and
-extracted from the pools to adhere to those rules.
-
-## Calculating fees
-
-In these tables BLD represents any collateral. The user can specify how much
-they want or how much they're willing to pay. We'll call the value they
-specified **sGive** or **sGet** and bold it. We'll always refer to the currency
-being added as X and the currency the user gets as Y. X and Y are the amounts
-used to maintain the constant product invariant. On every transaction the pool
-balance will also increase on one side or the other by the pool fee, and the
-protocol fee will be extracted outside the pool. So the amount produced is less
-(or the amount paid is more) because the invariant is maintained on the amounts
-remaining after fees have been charged. 
-
-In the final table, we'll see what the user pays or gets (sGet, sGive), how much
-the pool balances change (xIncr, yDecr) and the changes that impact the constant
-product calculation(ΔX, ΔY). The amount paid and received by the
-trader and changes to the pool are calculated relative to ΔX and ΔY
-so that the pool grows by the poolFee and the protocolFee can be paid from the
-proceeds.
-
-This table shows which brands the amounts each have, as well as what is computed
-vs. given. The PoolFee is computed based on the calculated amount (BLD in rows 1
-and 2; IST in rows 3 and 4). The Protocol fee is always in IST.
-
-|          | In (X) | Out (Y) | PoolFee | Protocol Fee | Specified | Computed |
-|---------|-----|-----|--------|-----|------|-----|
-| **IST in** | IST | BLD | BLD | IST | **sGive** | sGet |
-| **IST out** | BLD | IST | BLD | IST | **sGet** | sGive |
-| **BLD in** | BLD | IST | IST | IST | **sGive** | sGet |
-| **BLD out** | IST | BLD | IST | IST | **sGet** | sGive |
-
-We'll calculate how much the pool balances would change in the no-fee, improved
-price case using the constant product formulas. We call these results δX,
-and δY. This table uses lower case δ to distinguish estimates from
-final values, which use capital Δ.
-
-The fees are based on δX, and δY. ρ is the poolFee (e.g., 30
-basis points). φ is the protocol fee (e.g., 6 basis points). The pool fee
-will be ρ times whichever of δX and δY was calculated. The
-protocol fee will be φ * δX when IST is paid in, and φ * δY
-when BLD is paid in. (α and β in this table are the no-fee versions.)
-
-|          | δX | δY | PoolFee | Protocol Fee |
-|---------|-----|-----|--------|-----|
-| **IST in**  | **sGive** | y * α / (1 + α) | ρ × δY | φ × **sGive** (= φ × δX) |
-| **IST out** | x * β / (1 - β) | **sGet** | ρ × δX | φ × **sGet** (= φ × δY) |
-| **BLD in**  | **sGive**  | y * α / (1 + α) | ρ × δY | φ × δY |
-| **BLD out** | x * β / (1 - β) | **sGet** | ρ × δX | φ × δX |
-
-In rows 1 and 3, **sGive** was specified and sGet will be calculated. In rows 2
-and 4, **sGet** was specified and sGive will be calculated. Once we know the
-fees, we can add or subtract the fees and calculate the pool changes.
-
-The next table shows how the amount added to and subtracted from the pool (xIncr
-and yIncr) differs from what the trader gives or gets and the change in the pool
-values. While X' and Y' are the values resulting from the constant product
-formula, xHat and yHat are the new values in the pool, reflecting the
-contribution of the pool fee. From the diagram, xIncr is the difference between
-X and xHat, while yIncr is the difference between Y and yHat.
-
-The protocol fee (φ) is always charged on the IST side, and doesn't go in
-the pool. The pool fee (ρ) is charged on the amount that is calculated
-(ΔX or ΔY) and is included in yHat. 
-
-We use the estimate of the amount in or out to calculate improved values of
-ΔX and ΔY. These values tell us how much the trader will pay, the
-changes in pool balances, and what the trader will receive. As before, ΔX
-reflects a balance that will be growing, and ΔY one that will be
-shrinking.
-
-![AMM Diagram](./AMM-Trade.jpeg)
-
-When IST is specified (in or out), we adjust by the protocol Fee to get the
-change to the IST balance (which gives X' or Y'); use that to calculate the
-BLD component of the constant product, and then adjust δ by the pool fee.
-When BLD is specified, the entire amount will affect the pool balance (so the
-value in the constant product formula is the final BLD balance.) Both the pool
-and protocol fees are charged in IST so they respectively reduce sGet or
-increase sGive. 
-
-This table shows how the pool's growth and trader's values differ from the
-amounts that match the constant product formula. X is in IST on lines 1 and 4,
-and BLD on lines 2 and 3. 
-
-|          | xIncr | yDecr | pay In (sGive) | pay Out (sGet) |
-|---------|-----|-----|-----|-----|
-| **IST in**  | ΔX | ΔY - PoolFee | ΔX + protocolFee | ΔY - PoolFee |
-| **IST out**  | ΔX + PoolFee | ΔY | ΔX + protocolFee + PoolFee | ΔY |
-| **BLD in**  | ΔX | ΔY - PoolFee | ΔX + ProtocolFee | ΔY - PoolFee |
-| **BLD out**  | ΔX + PoolFee | ΔY | ΔX + PoolFee + ProtocolFee | ΔY |
-
-In the two right columns the protocolFee is either added to the amount the
-trader pays, or subtracted from the proceeds. The poolFee does the same on the
-left side, and it is either added to the amount deposited in the pool (xIncr)
-or deducted from the amount removed from the pool (yDecr).
-
-
-* line 1: the trader provides **sGive** IST; the pool will gain that minus
-  the protocol fee in IST. The value in the IST pool after (X') will be used to
-  calculate Y'.  The pool fee is calculated from δY and the trader gets
-  &deltaY; - poolFee
-* line 2: the trader asked for **sGet** IST; the pool will be reduced by that
-  amount plus the protocol fee. Y' will be used to calculate X'. The trader
-  must provide &deltaX; plus poolFee
-* Line 3: the trader pays **sGive** BLD; the pool will increase by that minus
-  both fees
-* line 4: the trader specified **sGet** BLD; the pool will be reduced by that
-  plus the protocol fee.
-
-
-## Example
-
-For example, let's say the pool has 40,000,000 IST and 3,000,000 BLD. Alice
-requests a swapIn with inputAmount of 30,000 IST, and outputAmount of 2000 BLD.
-(SwapIn means the inputValue is the basis of the computation, while outputAmount
-is treated as a minimum). To make the numbers concrete, we'll say the pool fee
-is 25 Basis Points, and the protocol fee is 5 Basis Points.
-
-The first step is to compute the trade that would take place with no fees. 30K
-will be added to 40M IST. To keep the product just above 120MM, the BLD will be
-reduced to 2,997,752.
-
-```
-40,030,000 * 2,997,752 > 40,000,000 * 3,000,000 > 40,030,000 * 2,997,751
-   120000012560000     >    120000000000000     >   119999972530000
-```
-
-But we get an even tighter bound by reducing the amount Alice has to spend
-
-```
-40,029,996 * 2,997,752 > 40,000,000 * 3,000,000 > 40,029,995 * 2,997,752
-    120000000568992    >    120000000000000     >   119999997571240
-```
-
-The initial price estimate is that 29,996 IST would get 2248 BLD in a no-fee
-pool. We base fees on this estimate, so the **protocol Fee will be 15 IST**
-(always in IST, ⌈29,996 * 0.0005⌉) and the **pool fee will be 6 BLD**
-(in the computed side, ⌈2248 * 0.0025⌉).  The "computed side" for
-`swapIn` is output and for `swapOut` is input.
-
-Now we calculate the actual ΔX and ΔY, since the fees affect the
-size of the changes to the pool. From the first row of the third table we see
-that the calculation starts from ΔX of
-`sGive - ProtocolFee (i.e. 30,000 - 15 = 29,985)`
-
-```
-40,029,985 * 2,997,753 > 40,000,000 * 3,000,000 > 40,029,985 * 2,997,752
-```
-
-and knowing that 2,997,753 BLD must remain in the pool, we refine the required
-amount of IST:
-
-```
-40,029,983 * 2,997,753 > 40,000,000 * 3,000,000 > 40,029,982 * 2,997,753
-```
-
-**ΔX is 29,983, and ΔY is 2247**.
-
- * Alice pays ΔX + protocolFee, which is 29,983 + 15  (29998 IST)
- * Alice will receive ΔY - PoolFee which is 2247 - 6  (2241 BLD)
- * The IST in the pool will increase by ΔX   (29983 IST)
- * The BLD in the pool will decrease by ΔY   (2247 BLD)
-
-The Pool grew by 6 BLD more than was required to maintain the constant product
-invariant. 15 IST were extracted for the protocol fee.
-

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

@@ -1,93 +0,0 @@
-import { AmountMath } from '@agoric/ertp';
-import {
-  ceilMultiplyBy,
-  makeRatio,
-} from '@agoric/zoe/src/contractSupport/ratio.js';
-
-import './types.js';
-import './internal-types.js';
-
-import { BASIS_POINTS } from './defaults.js';
-
-const { Fail } = assert;
-
-/**
- * Make a ratio given a nat representing basis points and a brand.
- *
- * @type {MakeFeeRatio}
- */
-const makeFeeRatio = (feeBP, brandOfFee) =>
-  makeRatio(feeBP, brandOfFee, BASIS_POINTS);
-
-/** @type {Maximum} */
-const maximum = (left, right) => {
-  // If left is greater or equal, return left. Otherwise return right.
-  return AmountMath.isGTE(left, right) ? left : right;
-};
-
-/** @type {AmountGT} */
-const amountGT = (left, right) =>
-  AmountMath.isGTE(left, right) && !AmountMath.isEqual(left, right);
-
-/**
- * Apply the feeRatio to the amount that has a matching brand. This used to
- * calculate fees in the single pool case.
- *
- * @param {{ amountIn: Amount<'nat'>, amountOut: Amount<'nat'>}} amounts - a record with two
- *   amounts in different brands.
- * @param {Ratio} feeRatio
- * @returns {Amount<'nat'>}
- */
-const calcFee = ({ amountIn, amountOut }, feeRatio) => {
-  feeRatio.numerator.brand === feeRatio.denominator.brand ||
-    Fail`feeRatio numerator and denominator must use the same brand ${feeRatio}`;
-
-  let sameBrandAmount;
-  if (amountIn.brand === feeRatio.numerator.brand) {
-    sameBrandAmount = amountIn;
-  } else if (amountOut.brand === feeRatio.numerator.brand) {
-    sameBrandAmount = amountOut;
-  } else {
-    throw Fail`feeRatio's brand (${feeRatio.numerator.brand}) must match one of the amounts [${amountIn}, ${amountOut}].`;
-  }
-
-  // Always round fees up
-  const fee = ceilMultiplyBy(sameBrandAmount, feeRatio);
-
-  // Fee cannot exceed the amount on which it is levied
-  AmountMath.isGTE(sameBrandAmount, fee) ||
-    Fail`The feeRatio can't be greater than 1 ${feeRatio}`;
-
-  return fee;
-};
-
-/**
- * Estimate the swap values, then calculate fees. The swapFn provided by the
- * caller will be swapInNoFees or swapOutNoFees.
- * SwapOut.
- *
- * @type {CalculateFees}
- */
-const calculateFees = (
-  amountGiven,
-  poolAllocation,
-  amountWanted,
-  protocolFeeRatio,
-  poolFeeRatio,
-  swapFn,
-) => {
-  // Get a rough estimation in both brands of the amount to be swapped
-  const estimation = swapFn({ amountGiven, poolAllocation, amountWanted });
-
-  const protocolFee = calcFee(estimation, protocolFeeRatio);
-  const poolFee = calcFee(estimation, poolFeeRatio);
-
-  return harden({ protocolFee, poolFee, ...estimation });
-};
-
-harden(amountGT);
-harden(maximum);
-harden(makeFeeRatio);
-harden(calculateFees);
-
-export { amountGT, maximum, makeFeeRatio, calculateFees };

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

@@ -1,83 +0,0 @@
-import { Far } from '@endo/marshal';
-
-import { swap } from './swap.js';
-import { assertKInvariantSellingX } from './invariants.js';
-import { getXY } from './getXY.js';
-import { swapInNoFees, swapOutNoFees } from './core.js';
-
-// pricesForStatedOutput() and pricesForStatedInput are the external entrypoints
-// to the constantProduct module. The amountWanted is optional for
-// pricesForStatedInput and amountgiven is optional for pricesForStatedOutput.
-
-// The two methods call swap, passing in different functions for noFeeSwap.
-// pricesForStatedInput uses swapInNoFees, while pricesForStatedOutput uses
-// swapOutNoFees. the noFeesSwap functions
-const makeCalcSwapPrices = noFeesSwap => {
-  return Far(
-    'calcSwapPrices',
-    (
-      amountGiven,
-      poolAllocation,
-      amountWanted,
-      protocolFeeRatio,
-      poolFeeRatio,
-    ) => {
-      const result = swap(
-        amountGiven,
-        poolAllocation,
-        amountWanted,
-        protocolFeeRatio,
-        poolFeeRatio,
-        noFeesSwap,
-      );
-      const { x, y } = getXY({
-        amountGiven,
-        poolAllocation,
-        amountWanted,
-      });
-      assertKInvariantSellingX(x, y, result.xIncrement, result.yDecrement);
-      return result;
-    },
-  );
-};
-
-/** @type {CalcSwapInPrices} */
-const pricesForStatedInput = (
-  amountGiven,
-  poolAllocation,
-  amountWanted,
-  protocolFeeRatio,
-  poolFeeRatio,
-) => {
-  const calcSwapPrices = makeCalcSwapPrices(swapInNoFees);
-  return calcSwapPrices(
-    amountGiven,
-    poolAllocation,
-    amountWanted,
-    protocolFeeRatio,
-    poolFeeRatio,
-  );
-};
-
-/** @type {CalcSwapOutPrices} */
-const pricesForStatedOutput = (
-  amountGiven,
-  poolAllocation,
-  amountWanted,
-  protocolFeeRatio,
-  poolFeeRatio,
-) => {
-  const calcSwapPrices = makeCalcSwapPrices(swapOutNoFees);
-  return calcSwapPrices(
-    amountGiven,
-    poolAllocation,
-    amountWanted,
-    protocolFeeRatio,
-    poolFeeRatio,
-  );
-};
-
-harden(pricesForStatedInput);
-harden(pricesForStatedOutput);
-
-export { pricesForStatedOutput, pricesForStatedInput };