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

package/src/psm/psmCharter.js

@@ -1,139 +0,0 @@
-// @ts-check
-
-import '@agoric/governance/src/exported.js';
-import { makeScalarMapStore, M, makeHeapFarInstance, fit } from '@agoric/store';
-import '@agoric/zoe/exported.js';
-import '@agoric/zoe/src/contracts/exported.js';
-import { InstanceHandleShape } from '@agoric/zoe/src/typeGuards.js';
-import { BrandShape } from '@agoric/ertp';
-import { TimestampShape } from '@agoric/swingset-vat/src/vats/timer/typeGuards.js';
-import { E } from '@endo/far';
-
-/**
- * @file
- *
- * This contract makes it possible for those who govern the PSM to call for
- * votes on changes. A more complete implementation would validate parameters,
- * constrain deadlines and possibly split the ability to call for votes into
- * separate capabilities for finer grain encapsulation.
- */
-
-/**
- * @typedef {object} ParamChangesOfferArgs
- * @property {bigint} deadline
- * @property {Instance} instance
- * @property {Record<string, unknown>} params
- * @property {{paramPath: { key: string }}} [path]
- */
-const ParamChangesOfferArgsShape = harden(
-  M.split(
-    {
-      deadline: TimestampShape,
-      instance: InstanceHandleShape,
-      params: M.recordOf(M.string(), M.any()),
-    },
-    M.partial({
-      path: { paramPath: { key: M.string() } },
-    }),
-  ),
-);
-
-/**
- * @param {ZCF<{binaryVoteCounterInstallation:Installation}>} zcf
- */
-export const start = async zcf => {
-  const { binaryVoteCounterInstallation: counter } = zcf.getTerms();
-  /** @type {MapStore<Instance,GovernedContractFacetAccess<{},{}>>} */
-  const instanceToGovernor = makeScalarMapStore();
-
-  const makeParamInvitation = () => {
-    /**
-     * @param {ZCFSeat} seat
-     * @param {ParamChangesOfferArgs} args
-     */
-    const voteOnParamChanges = (seat, args) => {
-      fit(args, ParamChangesOfferArgsShape);
-      seat.exit();
-
-      const {
-        params,
-        instance,
-        deadline,
-        path = { paramPath: { key: 'governedApi' } },
-      } = args;
-      const psmGovernor = instanceToGovernor.get(instance);
-      return E(psmGovernor).voteOnParamChanges(counter, deadline, {
-        ...path,
-        changes: params,
-      });
-    };
-
-    return zcf.makeInvitation(voteOnParamChanges, 'vote on param changes');
-  };
-
-  const makeOfferFilterInvitation = (instance, strings, deadline) => {
-    const voteOnOfferFilterHandler = seat => {
-      seat.exit();
-
-      const psmGovernor = instanceToGovernor.get(instance);
-      return E(psmGovernor).voteOnOfferFilter(counter, deadline, strings);
-    };
-
-    return zcf.makeInvitation(voteOnOfferFilterHandler, 'vote on offer filter');
-  };
-
-  const MakerShape = M.interface('PSM Charter InvitationMakers', {
-    VoteOnParamChange: M.call().returns(M.promise()),
-    VoteOnPauseOffers: M.call(
-      InstanceHandleShape,
-      M.arrayOf(M.string()),
-      TimestampShape,
-    ).returns(M.promise()),
-  });
-  const invitationMakers = makeHeapFarInstance(
-    'PSM Invitation Makers',
-    MakerShape,
-    {
-      VoteOnParamChange: makeParamInvitation,
-      VoteOnPauseOffers: makeOfferFilterInvitation,
-    },
-  );
-
-  const charterMemberHandler = seat => {
-    seat.exit();
-    return harden({ invitationMakers });
-  };
-
-  const psmCharterCreatorI = M.interface('PSM Charter creatorFacet', {
-    addInstance: M.call(InstanceHandleShape, M.any())
-      .optional(BrandShape, BrandShape)
-      .returns(),
-    makeCharterMemberInvitation: M.call().returns(M.promise()),
-  });
-
-  const creatorFacet = makeHeapFarInstance(
-    'PSM Charter creatorFacet',
-    psmCharterCreatorI,
-    {
-      /**
-       * @param {Instance} psmInstance
-       * @param {GovernedContractFacetAccess<{},{}>} psmGovernorFacet
-       * @param {Brand} [anchor] for diagnostic use only
-       * @param {Brand} [minted] for diagnostic use only
-       */
-      addInstance: (psmInstance, psmGovernorFacet, anchor, minted) => {
-        console.log('psmCharter: adding instance', { minted, anchor });
-        instanceToGovernor.init(psmInstance, psmGovernorFacet);
-      },
-      makeCharterMemberInvitation: () =>
-        zcf.makeInvitation(
-          charterMemberHandler,
-          'PSM charter member invitation',
-        ),
-    },
-  );
-
-  return harden({ creatorFacet });
-};
-
-export const INVITATION_MAKERS_DESC = 'PSM charter member invitation';

package/src/stakeFactory/README.md

@@ -1,62 +0,0 @@
-# stakeFactory design notes
-
-The stakeFactory contract provides loans on the basis of
-staked assets that earn rewards.
-
-The following sequence diagram shows an interaction between stakeFactory and:
-  - dapp: with rich interaction but low privilege
-  - walletBridge: with high privilege and constrained interaction
-  - attestation: a service within the stakeFactory contract
-  - Cosmos_SDK: the Cosmos SDK layer, including the `x/lien` module
-
-Before this interaction, an `ag123` account has been provisioned,
-which provides an `AttestationMaker` for that account to the wallet.
-
-Note that the account already has 4000 BLD liened before this interaction.
-
-```mermaid
-sequenceDiagram
-    actor dapp
-    participant walletBridge
-    participant attestation
-    participant stakeFactory
-    participant Cosmos_SDK
-
-    note right of dapp: How dapp finds the current state
-
-    note right of walletBridge: walletBridge is provided to dapps and controlled by Wallet UI
-    dapp ->>+ walletBridge: getPurseBalance("BLD")
-    dapp -->> walletBridge: 5000
-
-    note right of attestation: ag123 is a cosmos address
-    dapp ->> attestation: getMax(ag123)
-    attestation ->> Cosmos_SDK: getAccountState(ag123)
-    note right of Cosmos_SDK: Cosmos supports lien
-    Cosmos_SDK -->> attestation: account status in which 4000 BLD liened
-    attestation  -->> dapp: account status in which 4000 BLD liened
-    note right of dapp: Treasury now knows
-
-    note right of dapp: Want to get 450 IST by liening 500 BLD
-    dapp ->> walletBridge: getReturnableAttestation(want: 450 IST, give: 500 BLD-Att)
-    note right of walletBridge: Blocks on user approval in wallet
-    walletBridge ->> attestation: makeAttestation(500 BLD)
-    attestation ->> Cosmos_SDK: increaseLiened(+500 BLD)
-    Cosmos_SDK -->> attestation: new lien balance or throws
-
-    attestation -->> walletBridge: Payment of 500 BLD-Att liened on ag123
-
-    walletBridge ->> stakeFactory: offer w/payment for {give: 500 BLD-Att, want: 450 IST} 
-
-    stakeFactory --> walletBridge: Payment for 450 IST and offerResult
-    walletBridge --> dapp: notifiers from offerResult
-```
-
-## Components
-
-In addition to the `stakeFactory.js` module with the contract `start` function:
-
- - `params.js`: utilities for governance parameters
- - `stakeFactoryKit.js`: `makeStakeFactoryKit` is called once per loan
- - `stakeFactoryManager.js`: handles interest etc. for all loans
- - `attestation.js`: minting tokens that attest to liens,
-      and wrapping them in per-user attestation maker authorities.

package/src/stakeFactory/attestation.js

@@ -1,267 +0,0 @@
-// @ts-check
-// @jessie-check
-
-import { AmountMath, AssetKind } from '@agoric/ertp';
-import { E, Far } from '@endo/far';
-import { fit, M, makeCopyBag, makeStore, provideLazy } from '@agoric/store';
-import { assertProposalShape } from '@agoric/zoe/src/contractSupport/index.js';
-import { AttKW as KW } from './constants.js';
-import { makeAttestationTool } from './attestationTool.js';
-
-const { details: X } = assert;
-
-/**
- * @typedef {{
- *   mintAttestation: unknown,
- *   returnAttestation: OfferHandler,
- *   getLiened: (address: Address, brand: Brand<'nat'>) => Amount<'nat'>,
- *   getAccountState: unknown,
- *   wrapLienedAmount: unknown,
- *   unwrapLienedAmount: unknown,
- * }} LienMint
- */
-
-/**
- * To support `makeAttestation`, we directly mint attestation payments.
- * We still use a ZCFMint because returning attestations is done
- * through Zoe offers.
- *
- * @param {ZCF} zcf
- * @template {AssetKind} K
- * @param {ZCFMint<K>} zcfMint
- * @param {Amount<K>} amountToMint
- * @returns {Promise<Payment<K>>}
- */
-const mintZCFMintPayment = (zcf, zcfMint, amountToMint) => {
-  const { userSeat, zcfSeat } = zcf.makeEmptySeatKit();
-  zcfMint.mintGains(harden({ [KW.Attestation]: amountToMint }), zcfSeat);
-  zcfSeat.exit();
-  return E(userSeat).getPayout(KW.Attestation);
-};
-
-/**
- * Make a ZCFMint attentuated so that minting represents
- * putting a lien on staked assets. Payments can be returned,
- * releasing (part of) the lien.
- *
- * NOTE: Using Issuer.combine or AmountMath.add could result in
- * Payments / Amounts with multiple addresses.
- * Callers are responsible to split any such payment before returning.
- *
- * @param {ZCF} zcf
- * @param {Brand<'nat'>} stakeBrand brand of the staked assets
- * @param {ERef<StakingAuthority>} lienBridge bridge to account state
- */
-const makeAttestationIssuerKit = async (zcf, stakeBrand, lienBridge) => {
-  const { subtract, makeEmpty, isGTE, coerce } = AmountMath;
-  const empty = makeEmpty(stakeBrand);
-  /** @type { ZCFMint<'copyBag'> } */
-  const attMint = await zcf.makeZCFMint(KW.Attestation, AssetKind.COPY_BAG);
-  /** @type {{ issuer: Issuer<'copyBag'>, brand: Brand<'copyBag'>}} */
-  const { issuer, brand: attBrand } = attMint.getIssuerRecord();
-
-  /**
-   * @param {Address} address
-   * @param {Amount<'nat'>} lienedAmount
-   * @returns {Amount<'copyBag'>}
-   */
-  const wrapLienedAmount = (address, lienedAmount) =>
-    AmountMath.make(attBrand, makeCopyBag([[address, lienedAmount.value]]));
-
-  /** @param {Amount<'copyBag'>} attestationAmount */
-  const unwrapLienedAmount = attestationAmount => {
-    attestationAmount.brand === attBrand ||
-      assert.fail(
-        X`The escrowed attestation ${attestationAmount} was not of the attestation brand ${attBrand}`,
-      );
-    fit(
-      attestationAmount.value.payload,
-      harden([[M.string(), M.bigint()]]),
-      'attestationAmount',
-    );
-    /** @type {[Address, bigint][]} */
-    const [[address, valueReturned]] = attestationAmount.value.payload;
-    const lienedAmount = AmountMath.make(stakeBrand, valueReturned);
-    return { address, lienedAmount };
-  };
-
-  /**
-   * Non-authoritative store of nonzero lien amounts.
-   *
-   * @type {Store<Address, Amount<'nat'>>}
-   */
-  const amountByAddress = makeStore('amount');
-
-  /**
-   * Get non-authoritative liened amount from the JS store, without using the lienBridge.
-   *
-   * @param {Address} address
-   * @param {Brand<'nat'>} brand
-   */
-  const getLiened = (address, brand) => {
-    assert.typeof(address, 'string');
-    assert.equal(brand, stakeBrand);
-    if (amountByAddress.has(address)) {
-      return amountByAddress.get(address);
-    }
-    // Don't bother storing empty amounts.
-    return empty;
-  };
-
-  const getAccountState = async (address, brand) => {
-    const liened = getLiened(address, brand);
-    const s = await E(lienBridge).getAccountState(address, brand);
-    assert(AmountMath.isEqual(liened, s.liened));
-    return s;
-  };
-
-  /** @type {(m: Amount, s: Amount) => Amount} */
-  const subtractOrZero = (m, s) => (isGTE(m, s) ? subtract(m, s) : empty);
-  // check that x <= hi - lo
-  const checkDelta = (x, label, hi, lo) => {
-    const bound = subtractOrZero(hi, lo);
-    assert(
-      isGTE(bound, coerce(stakeBrand, x)),
-      // TODO: X`...${raw(label)}...`
-      X`Only ${bound} was ${label}, but an attestation was attempted for ${x}`,
-    );
-  };
-  const assertAccountStateOK = async (address, toLien) => {
-    const s = await getAccountState(address, stakeBrand);
-    const unlocked = subtractOrZero(s.total, s.locked);
-    checkDelta(toLien, 'unliened', s.total, s.liened);
-    checkDelta(toLien, 'bonded and unliened', s.bonded, s.liened);
-    checkDelta(toLien, 'unlocked and unliened', unlocked, s.liened);
-  };
-
-  /**
-   * @param {Address} address
-   * @param {Amount<'nat'>} lienDelta
-   */
-  const mintAttestation = async (address, lienDelta) => {
-    // This account state check is primarily to provide useful diagnostics.
-    // Since things like the bonded amount can change out from under us,
-    // we shouldn't rely on it completely.
-    // PERFORMANCE NOTE: this check shouldn't be necessary and skipping it
-    // may speed things up.
-    await assertAccountStateOK(address, lienDelta);
-
-    // Since our mint is not subject to normal supply/demand,
-    // minting here and failing in changeLiened below does no harm.
-    const attestationPayment = await mintZCFMintPayment(
-      zcf,
-      attMint,
-      wrapLienedAmount(address, lienDelta),
-    );
-
-    const newLiened = await E(lienBridge).increaseLiened(address, lienDelta);
-    // COMMIT: update the stored liened amount and issue the attestation.
-    if (amountByAddress.has(address)) {
-      amountByAddress.set(address, newLiened);
-    } else {
-      amountByAddress.init(address, newLiened);
-    }
-    return attestationPayment;
-  };
-
-  /** @param {ZCFSeat} seat */
-  const returnAttestation = async seat => {
-    assertProposalShape(seat, {
-      give: { [KW.Attestation]: null },
-      want: {},
-    });
-
-    const {
-      give: { [KW.Attestation]: attestationAmount },
-    } = seat.getProposal();
-    if (AmountMath.isEmpty(attestationAmount)) {
-      seat.exit();
-      return;
-    }
-    const { address, lienedAmount: amountReturned } =
-      unwrapLienedAmount(attestationAmount);
-    const newLiened = await E(lienBridge).decreaseLiened(
-      address,
-      amountReturned,
-    );
-    // COMMIT. Burn the escrowed attestation payment and exit the seat.
-    if (newLiened === empty) {
-      amountByAddress.delete(address);
-    } else {
-      amountByAddress.set(address, newLiened);
-    }
-    attMint.burnLosses(harden({ Attestation: attestationAmount }), seat);
-    seat.exit();
-  };
-
-  /** @type {ERef<LienMint>} */
-  const lienMint = Far('LienMint', {
-    mintAttestation,
-    returnAttestation,
-    getLiened,
-    getAccountState,
-    wrapLienedAmount,
-    /**
-     * @param {Amount<'copyBag'>} attAmt
-     * @throws if `attAmt` payload length is not 1
-     */
-    unwrapLienedAmount: attAmt => unwrapLienedAmount(attAmt).lienedAmount,
-  });
-  return harden({ issuer, brand: attBrand, lienMint });
-};
-
-/**
- * Authorize each account holder to lien some of their staked assets
- * and get an attestation that the lien is in place.
- *
- * @param {ZCF} zcf
- * @param {Brand<'nat'>} stakeBrand
- * @param {ERef<StakingAuthority>} lienBridge
- *
- * NOTE: the liened amount is kept both here in JS and on the
- * other side of the lienBridge. The mint created here
- * is the authority on the liened amount. The liened amount
- * on the other side of the bridge may lag. Do not create two
- * mints that share a bridge.
- *
- * The provideAttestationMaker method on the returned creatorFacet
- * provides the authorization for an address. The account holder
- * can then use attMaker.makeAttestation(lienDelta).
- *
- * The keyword for use in returnAttestation offers is `Attestation`.
- */
-export const makeAttestationFacets = async (zcf, stakeBrand, lienBridge) => {
-  /** @type {Store<Address, AttestationTool>} */
-  const attMakerByAddress = makeStore('address');
-
-  const { issuer, brand, lienMint } = await makeAttestationIssuerKit(
-    zcf,
-    stakeBrand,
-    lienBridge,
-  );
-
-  return harden({
-    publicFacet: Far('attestation publicFacet', {
-      getIssuer: () => issuer,
-      getBrand: () => brand,
-      makeReturnAttInvitation: () =>
-        zcf.makeInvitation(lienMint.returnAttestation, 'returnAttestation'),
-    }),
-    creatorFacet: Far('creator', {
-      /**
-       * IMPORTANT: The attestation maker should only be given to the owner of the
-       * address. Only the owner can authorize creation of attestations and
-       * the resulting liens on their underlying tokens.
-       *
-       * @param {Address} address
-       */
-      provideAttestationTool: address => {
-        assert.typeof(address, 'string');
-        return provideLazy(attMakerByAddress, address, () =>
-          makeAttestationTool(address, lienMint, stakeBrand, zcf),
-        );
-      },
-      getLiened: lienMint.getLiened,
-    }),
-  });
-};

package/src/stakeFactory/attestationTool.js

@@ -1,66 +0,0 @@
-// @ts-check
-/**
- * @typedef {Readonly<{
- *   address: Address,
- *   lienMint: *,
- *   stakeBrand: Brand<'nat'>,
- *   zcf: ZCF,
- * }>} State
- * @typedef {{
- *   state: State,
- * }} MethodContext
- */
-
-import { defineKind } from '@agoric/vat-data';
-/**
- * @param {Address} address
- * @param {import('./attestation').LienMint} lienMint
- * @param {Brand<'nat'>} stakeBrand
- * @param {ZCF} zcf
- */
-const initState = (address, lienMint, stakeBrand, zcf) => {
-  return { address, lienMint, stakeBrand, zcf };
-};
-
-const behavior = {
-  /**
-   * @param {MethodContext} context
-   * @param {Amount<'nat'>} lienedDelta
-   */
-  makeAttestation: ({ state }, lienedDelta) =>
-    state.lienMint.mintAttestation(state.address, lienedDelta),
-
-  /** @param {MethodContext} context */
-  getAccountState: ({ state }) =>
-    state.lienMint.getAccountState(state.address, state.stakeBrand),
-
-  /** @param {MethodContext} context */
-  makeReturnAttInvitation: ({ state }) =>
-    state.zcf.makeInvitation(
-      state.lienMint.returnAttestation,
-      'returnAttestation',
-    ),
-
-  /**
-   * @param {MethodContext} context
-   * @param {Amount<'nat'>} lienedAmount
-   */
-  wrapLienedAmount: ({ state }, lienedAmount) =>
-    state.lienMint.wrapLienedAmount(state.address, lienedAmount),
-
-  /**
-   * @param {MethodContext} context
-   * @param {Amount<'copyBag'>} attAmount
-   */
-  unwrapLienedAmount: ({ state }, attAmount) =>
-    state.lienMint.unwrapLienedAmount(attAmount),
-};
-
-/**
- * @returns {AttestationTool}
- */
-export const makeAttestationTool = defineKind(
-  'AttestationTool',
-  initState,
-  behavior,
-);

package/src/stakeFactory/constants.js

@@ -1,16 +0,0 @@
-export const AttKW = /** @type { const } */ ({
-  /** seat keyword for use in offers to return an attestation. */
-  Attestation: 'Attestation',
-});
-
-export const ManagerKW = /** @type { const } */ ({
-  [AttKW.Attestation]: AttKW.Attestation,
-  Debt: 'Debt',
-});
-
-export const ParamKW = /** @type { const } */ ({
-  DebtLimit: 'DebtLimit',
-  MintingRatio: 'MintingRatio',
-  InterestRate: 'InterestRate',
-  LoanFee: 'LoanFee',
-});

package/src/stakeFactory/params.js

@@ -1,31 +0,0 @@
-// @ts-check
-// @jessie-check
-
-import { CONTRACT_ELECTORATE, ParamTypes } from '@agoric/governance';
-import { ParamKW as PKey } from './constants.js';
-
-export const makeStakeFactoryTerms = (
-  { timerService, chargingPeriod, recordingPeriod },
-  {
-    electorateInvitationAmount,
-    debtLimit,
-    mintingRatio,
-    interestRate,
-    loanFee,
-  },
-) => ({
-  timerService,
-  chargingPeriod,
-  recordingPeriod,
-  governedParams: harden({
-    [PKey.DebtLimit]: { type: ParamTypes.AMOUNT, value: debtLimit },
-    [PKey.MintingRatio]: { type: ParamTypes.RATIO, value: mintingRatio },
-    [PKey.InterestRate]: { type: ParamTypes.RATIO, value: interestRate },
-    [PKey.LoanFee]: { type: ParamTypes.RATIO, value: loanFee },
-    [CONTRACT_ELECTORATE]: {
-      type: ParamTypes.INVITATION,
-      value: electorateInvitationAmount,
-    },
-  }),
-});
-harden(makeStakeFactoryTerms);