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

package/scripts/add-initial-liquidity.js

@@ -1,179 +0,0 @@
-import { AmountMath } from '@agoric/ertp';
-import { makeNotifierFromAsyncIterable } from '@agoric/notifier';
-import { E } from '@endo/far';
-
-const { entries } = Object;
-
-const dec6 = 10n ** 6n;
-const dec4 = 10n ** 4n;
-
-const config = {
-  Central: { IST: 10_000n * dec6 },
-  Secondary: { IbcATOM: 500n * dec4 }, // 20 IST per ATOM
-};
-
-const getOfferResult = async (instance, wallet, walletAdmin) => {
-  const offerIt = E(walletAdmin).getOffersNotifier();
-  let result;
-  console.log('awaiting offers...');
-  for await (const offers of makeNotifierFromAsyncIterable(offerIt)) {
-    console.log('offers iterator next:', offers);
-    offers
-      .filter(
-        ({ status, invitationQuery }) =>
-          status === 'complete' && invitationQuery.instance === instance,
-      )
-      .forEach(async ({ id }) => {
-        result = await E(wallet).lookup('offerResult', id);
-        console.log({ facet: result });
-      });
-    if (result) break;
-  }
-  return result;
-};
-
-/**
- *
- * @param { { agoricNames: ERef<NameHub>, scratch: ERef<import('@agoric/solo/src/scratch').ScratchPad>, wallet: ERef<WalletAdmin>, zoe: ERef<ZoeService>} } homeP
- * @param { {now?: () => number }} _endowments
- *
- * @typedef {ReturnType<typeof import('../../wallet/api/src/lib-wallet').makeWalletRoot>['admin']} Wallet
- */
-const addInitialLiquidity = async (homeP, { now = () => Date.now() }) => {
-  const { wallet, agoricNames, zoe, scratch } = E.get(homeP);
-
-  const walletBridge = E(wallet).getBridge();
-
-  const getService = async name => {
-    console.log('lookup instance', name);
-    const instance = await E(agoricNames).lookup('instance', name);
-    const pub = E(zoe).getPublicFacet(instance);
-    return { instance, pub };
-  };
-  const amm = await getService('amm');
-
-  const addUsingWallet = async () => {
-    console.log('getting purses from walletBridge...');
-    const { value: pStates } = await E(
-      E(walletBridge).getPursesNotifier(),
-    ).getUpdateSince();
-    console.log(pStates);
-
-    const toAmt = detail => {
-      const [[name, value]] = entries(detail);
-      const { pursePetname } =
-        pStates.find(p => p.brandPetname === name) ||
-        assert.fail(`cannot find purse ${name}`);
-      return { pursePetname, value };
-    };
-    const proposalTemplate = {
-      give: {
-        Central: toAmt(config.Central),
-        Secondary: toAmt(config.Secondary),
-      },
-    };
-    console.log({ proposalTemplate });
-
-    console.log('amm.makeAddLiquidityInvitation...');
-    const invitation = await E(amm.pub).makeAddLiquidityInvitation();
-    console.log({ invitation });
-
-    const offerConfig = {
-      id: `${now()}`,
-      invitation,
-      instanceHandle: amm.instance,
-      proposalTemplate,
-      requestContext: undefined,
-    };
-    console.log('addOffer', offerConfig);
-    const added = await E(walletBridge).addOffer(offerConfig);
-    console.log({ added });
-
-    const result = await getOfferResult(
-      amm.instance,
-      wallet,
-      E(wallet).getAdminFacet(),
-    );
-    console.log({ result });
-  };
-
-  const addUsingZoe = async () => {
-    const { keys, values } = Object;
-    /** @type {<K extends string, V>(entries: [K, V][]) => Record<K, V>} */
-    const toRecord = Object.fromEntries;
-
-    console.log('getting purses, issuers from wallet...');
-    const [purseEntries, { value: issuerEntries }] = await Promise.all([
-      E(wallet).getPurses(),
-      E(E(walletBridge).getIssuersNotifier()).getUpdateSince(),
-    ]);
-
-    // @ts-expect-error Petname can be string[]
-    const purses = toRecord(purseEntries);
-    // @ts-expect-error Petname can be string[]
-    const issuers = toRecord(issuerEntries);
-    console.log({ purses: keys(purses), issuers: keys(issuers) });
-    assert(
-      issuers.IbcATOM,
-      'Issuers not complete. Try again after purses are provisioned',
-    );
-    const liqIssuer = E(amm.pub).getLiquidityIssuer(issuers.IbcATOM.brand);
-    const liqBrand = await E(liqIssuer).getBrand();
-
-    /** @param {Record<string, bigint>} detail */
-    const toAmt = detail => {
-      const [[name, value]] = entries(detail);
-      const issuer = issuers[name];
-      assert(issuer);
-      return AmountMath.make(issuer.brand, value);
-    };
-    /** @param {Amount} amt */
-    const withdraw = async amt => {
-      for await (const purse of values(purses)) {
-        const b2 = await E(purse).getAllegedBrand();
-        if (b2 === amt.brand) {
-          return E(purse).withdraw(amt);
-        }
-      }
-      throw Error(`no purse found for ${amt.brand}`);
-    };
-    const proposal = {
-      want: {
-        Liquidity: AmountMath.makeEmpty(liqBrand),
-      },
-      give: {
-        Central: toAmt(config.Central),
-        Secondary: toAmt(config.Secondary),
-      },
-    };
-    console.log({ proposal });
-    console.log('withdraw payments...', proposal.give);
-    const payments = {
-      Central: await withdraw(proposal.give.Central),
-      Secondary: await withdraw(proposal.give.Secondary),
-    };
-    console.log('payments', payments);
-    console.log('amm.makeAddLiquidityInvitation...');
-    const invitation = await E(amm.pub).makeAddLiquidityInvitation();
-    console.log({ invitation });
-
-    const seat = await E(zoe).offer(invitation, proposal, payments);
-    console.log({ seat });
-
-    const result = await E(seat).getOfferResult();
-    console.log({ result });
-
-    const payouts = await E(seat).getPayouts();
-    console.log('initialLiquidityPayouts', keys(payouts));
-    await E(scratch).set('initialLiquidityPayouts', payouts);
-  };
-
-  console.log(
-    addUsingWallet,
-    'does not handle want Liquidity so we do not use it',
-  );
-  await addUsingZoe();
-};
-harden(addInitialLiquidity);
-
-export default addInitialLiquidity;

package/src/interchainPool.js

@@ -1,134 +0,0 @@
-import { E, Far } from '@endo/far';
-import { AmountMath, AssetKind, makeIssuerKit } from '@agoric/ertp';
-import {
-  offerTo,
-  atomicTransfer,
-} from '@agoric/zoe/src/contractSupport/index.js';
-import { MIN_INITIAL_POOL_LIQUIDITY_KEY } from './vpool-xyk-amm/params.js';
-
-const { Fail, quote: q } = assert;
-
-const COSMOS_DECIMALS = 6;
-
-/**
- * Given sufficient IST, create an issuer for an IBC denom
- * and an invitation to add a pool for it to the AMM.
- *
- * @param {ZCF<InterchainPoolTerms>} zcf
- * @param {{
- *   bankManager: ERef<BankManager>,
- * }} privateArgs
- *
- * @typedef {{
- *   amm: Instance,
- * }} InterchainPoolTerms
- *
- * @typedef {{
- *   denom: string,
- *   decimalPlaces: number,
- * }} AssetDetail
- */
-export const start = (zcf, { bankManager }) => {
-  const { amm } = zcf.getTerms();
-
-  const zoe = zcf.getZoeService();
-  /** @type {ERef<GovernedPublicFacet<XYKAMMPublicFacet>>} */
-  const ammPub = E(zoe).getPublicFacet(amm);
-
-  let kwNonce = 0;
-
-  /**
-   * @param {ZCFSeat} seat
-   * @param {AssetDetail} detail
-   */
-  const step1Handler = async (seat, detail) => {
-    assert.typeof(
-      detail,
-      'object',
-      'offer arg must be { denom, decimalPlaces? }',
-    );
-    const { denom, decimalPlaces = COSMOS_DECIMALS } = detail;
-    assert.typeof(denom, 'string');
-    assert.typeof(decimalPlaces, 'number');
-
-    const minimumCentral = await E(ammPub).getAmount(
-      MIN_INITIAL_POOL_LIQUIDITY_KEY,
-    );
-
-    const {
-      give: { Central: centralAmt },
-    } = seat.getProposal();
-    AmountMath.isGTE(centralAmt, minimumCentral) ||
-      Fail`at least ${q(minimumCentral)} required; only ${q(centralAmt)} given`;
-
-    const interAsset = makeIssuerKit(
-      denom,
-      AssetKind.NAT,
-      harden({ decimalPlaces }),
-    );
-    kwNonce += 1;
-
-    await zcf.saveIssuer(interAsset.issuer, `Interchain${kwNonce}`);
-
-    /** @type { OfferHandler } */
-    const step2Handler = async seat2 => {
-      const {
-        give: { Secondary: secondaryAmt },
-      } = seat2.getProposal();
-      AmountMath.coerce(interAsset.brand, secondaryAmt);
-
-      const liquidityIssuer = await E(ammPub).addIssuer(
-        interAsset.issuer,
-        `Interchain${kwNonce}`,
-      );
-      await zcf.saveIssuer(liquidityIssuer, `Liquidity${kwNonce}`);
-
-      const proposal = harden({
-        give: {
-          Central: centralAmt,
-          Secondary: secondaryAmt,
-        },
-      });
-
-      atomicTransfer(zcf, seat, seat2, { Central: centralAmt });
-
-      const invitation = await E(ammPub).addPoolInvitation();
-      const { userSeatPromise, deposited } = await offerTo(
-        zcf,
-        invitation,
-        undefined,
-        proposal,
-        seat2,
-      );
-      return E.when(deposited, _ => {
-        seat.exit();
-        seat2.exit();
-
-        return E(userSeatPromise).getOfferResult();
-      });
-    };
-
-    const keyword = denom; // ISSUE #5412: should not show up in all wallets.
-    const proposedName = denom;
-    const [invitation] = await Promise.all([
-      zcf.makeInvitation(step2Handler, 'interchain pool step 2'),
-      E(bankManager).addAsset(
-        denom,
-        keyword,
-        proposedName,
-        interAsset, // with mint
-      ),
-    ]);
-
-    return harden({
-      issuer: interAsset.issuer,
-      invitation,
-    });
-  };
-
-  const publicFacet = Far('InterchainPoolGateway', {
-    makeInterchainPoolInvitation: () =>
-      zcf.makeInvitation(step1Handler, 'interchain pool step 1'),
-  });
-  return { publicFacet };
-};

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,221 +0,0 @@
-import {
-  assertProposalShape,
-  calcSecondaryRequired,
-  natSafeMath,
-} from '@agoric/zoe/src/contractSupport/index.js';
-import { AmountMath } from '@agoric/ertp';
-
-import '@agoric/zoe/exported.js';
-
-const { Fail, 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 ||
-      Fail`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;
-    /** @type {Amount<'nat'>} */
-    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 };