Loan Contract (#1903)

* feat: add basic loan contract and tests

* chore: fix typo

Co-authored-by: Chris Hibbert <Chris-Hibbert@users.noreply.github.com>

* fix: fix egregious import error, remove mention of tokens

* Chore: update comment

Co-authored-by: Chris Hibbert <Chris-Hibbert@users.noreply.github.com>

* chore: update comment

Co-authored-by: Chris Hibbert <Chris-Hibbert@users.noreply.github.com>

* chore: address PR comments

* chore: address PR comments

* chore: test performing liquidation from borrow invitation.

* fix: schedule a liquidation every time the debt is updated

* chore: add test for malformed autoswap

* chore: capture info on the priceQuote

* chore: drop console.log

Co-authored-by: Chris Hibbert <Chris-Hibbert@users.noreply.github.com>

Author: katelynsills

packages/zoe/exported.js

@@ -1,6 +1,7 @@
 import './src/contractFacet/types';
 import './src/zoeService/types';
 import './src/contractSupport/types';
+import './src/contracts/exported';
 import './src/types';
 import './tools/types';
 import '@agoric/notifier/exported';

packages/zoe/src/contracts/exported.js

@@ -190,3 +190,213 @@
  * @property {(query: any, reply: any, requiredFee: Amount) => void} onReply
  * notice a successful reply
  */
+
+/**
+ * @typedef {AsyncIterable<undefined>} PeriodAsyncIterable
+ *
+ *  The asyncIterable used for notifications that a period has passed,
+ *  on which compound interest will be calculated using the
+ *  interestRate.
+ */
+
+/**
+ * @typedef {number} MMR
+ *  The Maintenance Margin Requirement, in percent. The default is
+ *  150, meaning that collateral should be worth at least 150% of the
+ *  loan. If the value of the collateral drops below mmr, liquidation
+ *  occurs.
+ */
+
+/**
+ * @typedef {Instance} AutoswapInstance
+ *   The running contract instance for an Autoswap or Multipool
+ *   Autoswap installation.  The publicFacet from the Autoswap
+ *   instance is used for producing an invitation to sell the
+ *   collateral on liquidation.
+ */
+
+/** @typedef {number} InterestRate
+ *
+ *   The rate in basis points that will be multiplied with the debt on
+ *   every period to compound interest.
+ */
+
+/**
+ * @typedef LoanTerms
+ *
+ * @property {MMR} [mmr=150]
+ *
+ * @property {AutoswapInstance} autoswapInstance
+ *
+ * @property {PriceAuthority} priceAuthority
+ *
+ *   Used for getting the current value of collateral and setting
+ *   liquidation triggers.
+ *
+ * @property {PeriodAsyncIterable} periodAsyncIterable
+ *
+ * @property {InterestRate} interestRate
+ */
+
+/**
+ * @typedef LenderSeatProperty
+ * @property {ZCFSeat} lenderSeat
+ *
+ *   The ZCFSeat representing the lender's position in the contract.
+ */
+
+/**
+ * @typedef {LoanTerms & LenderSeatProperty} LoanConfigWithLender
+ *
+ * The loan now has a lenderSeat, which is added to the config.
+ */
+
+/**
+ * @typedef BorrowerConfigProperties
+ *
+ * @property {ZCFSeat} collateralSeat
+ *
+ *   The ZCFSeat holding the collateral in escrow after the borrower
+ *   escrows it
+ *
+ * @property {() => Amount} getDebt
+ *
+ *   A function to get the current debt
+ *
+ * @property {PromiseKit} liquidationPromiseKit
+ *
+ *   PromiseKit that includes a promise that resolves to a PriceQuote
+ *   when liquidation is triggered
+ */
+
+/**
+ * @typedef BorrowerConfigPropertiesMinusDebt
+ *
+ * @property {ZCFSeat} collateralSeat
+ *
+ *   The ZCFSeat holding the collateral in escrow after the borrower
+ *   escrows it
+ *
+ * @property {PromiseKit} liquidationPromiseKit
+ *
+ *   PromiseKit that includes a promise that resolves to a PriceQuote
+ *   when liquidation is triggered
+ */
+
+/**
+ * @typedef {LoanConfigWithLender & BorrowerConfigProperties } LoanConfigWithBorrower
+ *
+ * The loan has a lender, a borrower, and collateral escrowed.
+ */
+
+/**
+ * @typedef {LoanConfigWithLender & BorrowerConfigPropertiesMinusDebt
+ * } LoanConfigWithBorrowerMinusDebt
+ */
+
+/**
+ * @callback ScheduleLiquidation
+ * @param {ContractFacet} zcf
+ * @param {LoanConfigWithBorrower} config
+ */
+
+/**
+ * @callback MakeLendInvitation
+ * @param {ContractFacet} zcf
+ * @param {LoanTerms} config
+ * @returns {Promise<Invitation>} lendInvitation
+ */
+
+/**
+ * @callback MakeBorrowInvitation
+ * @param {ContractFacet} zcf
+ * @param {LoanConfigWithLender} config
+ * @returns {Promise<Invitation>} borrowInvitation
+ */
+
+/**
+ * @callback MakeCloseLoanInvitation
+ * @param {ContractFacet} zcf
+ * @param {LoanConfigWithBorrower} config
+ * @returns {Promise<Invitation>} closeLoanInvitation
+ */
+
+/**
+ * Allows holder to add collateral to the contract. Exits the seat
+ * after adding.
+ *
+ * @callback MakeAddCollateralInvitation
+ * @param {ContractFacet} zcf
+ * @param {LoanConfigWithBorrower} config
+ * @returns {Promise<Invitation>} addCollateralInvitation
+ */
+
+/**
+ * @callback Liquidate
+ * @param {ContractFacet} zcf
+ * @param {LoanConfigWithBorrower} config
+ * @returns {void}
+ */
+
+/**
+ * @callback MakeDebtCalculator
+ * @param {DebtCalculatorConfig} debtCalculatorConfig
+ */
+
+/**
+ * @callback CalcInterestFn
+ * @param {number} oldDebtValue
+ * @param {number} interestRate
+ * @returns {number} interest
+ */
+
+/**
+ * @typedef {Object} DebtCalculatorConfig
+ * @property {CalcInterestFn} calcInterestFn
+ *
+ *   A function to calculate the interest, given the debt value and an
+ *   interest rate in basis points.
+ *
+ * @property {Amount} originalDebt
+ *
+ *   The debt at the start of the loan, in Loan brand
+ *
+ * @property {AmountMath} loanMath
+ *
+ *   AmountMath for the loan brand
+ *
+ * @property {PeriodAsyncIterable} periodAsyncIterable
+ *
+ *   The AsyncIterable to notify when a period has occurred
+ *
+ * @property {number} interestRate
+ *
+ * @property {ContractFacet} zcf
+ *
+ * @property {LoanConfigWithBorrowerMinusDebt} configMinusGetDebt
+ */
+
+/**
+ * @typedef {Object} BorrowFacet
+ *
+ * @property {() => Promise<Invitation>} makeCloseLoanInvitation
+ *
+ * Make an invitation to close the loan by repaying the debt
+ *   (including interest).
+ *
+ * @property {() => Promise<Invitation>} makeAddCollateralInvitation
+ *
+ * Make an invitation to add collateral to protect against liquidation
+ *
+ * @property {() => Promise<PriceQuote>} getLiquidationPromise
+ *
+ * Get a promise for a priceQuote that will resolve if liquidation
+ * occurs. The priceQuote is for the value of the collateral that
+ * triggered the liquidation. This may be lower than expected if the
+ * price is moving quickly.
+ *
+ * @property {() => Notifier<Amount>} getDebtNotifier
+ *
+ * Get notified when the current debt (an Amount in the Loan Brand) changes. This will
+ * increase as interest is added.
+ */

packages/zoe/src/contracts/loan/addCollateral.js

@@ -0,0 +1,45 @@
+// @ts-check
+
+import '../../../exported';
+
+import { assertProposalShape, trade } from '../../contractSupport';
+
+import { scheduleLiquidation } from './scheduleLiquidation';
+
+// Create an invitation to add collateral to the loan. Part of the
+// facet given to the borrower.
+
+/** @type {MakeAddCollateralInvitation} */
+export const makeAddCollateralInvitation = (zcf, config) => {
+  const { collateralSeat } = config;
+
+  /** @type {OfferHandler} */
+  const addCollateral = addCollateralSeat => {
+    assertProposalShape(addCollateralSeat, {
+      give: { Collateral: null },
+      want: {},
+    });
+
+    trade(
+      zcf,
+      {
+        seat: collateralSeat,
+        gains: {
+          Collateral: addCollateralSeat.getAmountAllocated('Collateral'),
+        },
+      },
+      {
+        seat: addCollateralSeat,
+        gains: {},
+      },
+    );
+    addCollateralSeat.exit();
+
+    // Schedule the new liquidation trigger. The old one will have an
+    // outdated quote and will be ignored
+    scheduleLiquidation(zcf, config);
+    return 'a warm fuzzy feeling that you are further away from default than ever before';
+  };
+
+  return zcf.makeInvitation(addCollateral, 'addCollateral');
+};