feat(ertp): add purse.getCurrentAmountNotifier

Author: michaelfig

packages/ERTP/NEWS.md

@@ -1,5 +1,10 @@
 User-visible changes in ERTP:
 
+## Next Release
+
+* Purses now support `getCurrentAmountNotifier()` that notifies of balance
+  changes.
+
 ## Release v0.7.0 (21-July-2020)
 
 * Rename `extent` to `value`

packages/ERTP/package.json

@@ -46,6 +46,7 @@
     "@agoric/import-manager": "^0.1.3",
     "@agoric/marshal": "^0.2.7",
     "@agoric/nat": "^2.0.1",
+    "@agoric/notifier": "^0.2.3",
     "@agoric/promise-kit": "^0.1.7",
     "@agoric/same-structure": "^0.0.12",
     "@agoric/store": "^0.3.1"

packages/ERTP/src/issuer.js

@@ -6,6 +6,7 @@ import { assert, details } from '@agoric/assert';
 import { makeExternalStore } from '@agoric/store';
 import { E } from '@agoric/eventual-send';
 import { Remotable } from '@agoric/marshal';
+import { makeNotifierKit } from '@agoric/notifier';
 import { isPromise } from '@agoric/promise-kit';
 
 import { makeAmountMath, MathKind } from './amountMath';
@@ -91,6 +92,11 @@ function makeIssuerKit(
 
   const { makeInstance: makePurse } = makeExternalStore('purse', () => {
     let currentBalance = amountMath.getEmpty();
+    /** @type {NotifierRecord<Amount>} */
+    const {
+      notifier: balanceNotifier,
+      updater: balanceUpdater,
+    } = makeNotifierKit(currentBalance);
 
     /** @type {Purse} */
     const purse = Remotable(
@@ -116,6 +122,7 @@ function makeIssuerKit(
           // source payment, such that total assets are conserved.
           paymentLedger.delete(srcPayment);
           currentBalance = newPurseBalance;
+          balanceUpdater.updateState(currentBalance);
           return srcPaymentBalance;
         },
         withdraw: amount => {
@@ -126,10 +133,12 @@ function makeIssuerKit(
           // Move the withdrawn assets from this purse into a new payment
           // which is returned. Total assets must remain conserved.
           currentBalance = newPurseBalance;
+          balanceUpdater.updateState(currentBalance);
           paymentLedger.init(payment, amount);
           return payment;
         },
         getCurrentAmount: () => currentBalance,
+        getCurrentAmountNotifier: () => balanceNotifier,
         getAllegedBrand: () => brand,
         // eslint-disable-next-line no-use-before-define
         getDepositFacet: () => depositFacet,

packages/ERTP/src/types.js

@@ -264,6 +264,9 @@
  * @property {() => Amount} getCurrentAmount
  * Get the amount contained in this purse.
  *
+ * @property {() => Notifier<Amount>} getCurrentAmountNotifier
+ * Get a lossy notifier for changes to this purse's balance.
+ *
  * @property {(payment: Payment, optAmount: Amount=) => Amount} deposit
  * Deposit all the contents of payment into this purse, returning the
  * amount. If the optional argument `optAmount` does not equal the

packages/ERTP/test/unitTests/test-issuerObj.js

@@ -71,19 +71,32 @@ test('issuer.getAmountMathKind', t => {
 });
 
 test('issuer.makeEmptyPurse', async t => {
-  t.plan(6);
+  t.plan(9);
   const { issuer, mint, amountMath, brand } = makeIssuerKit('fungible');
   const purse = issuer.makeEmptyPurse();
   const payment = mint.mintPayment(amountMath.make(837));
 
+  const notifier = purse.getCurrentAmountNotifier();
+  let nextUpdate = notifier.getUpdateSince();
+
+  const checkNotifier = async () => {
+    const { value: balance, updateCount } = await nextUpdate;
+    t.assert(
+      amountMath.isEqual(purse.getCurrentAmount(), balance),
+      `the notifier balance is the same as the purse`,
+    );
+    nextUpdate = notifier.getUpdateSince(updateCount);
+  };
+
   t.assert(
     amountMath.isEqual(purse.getCurrentAmount(), amountMath.getEmpty()),
     `empty purse is empty`,
   );
+  await checkNotifier();
   t.is(purse.getAllegedBrand(), brand, `purse's brand is correct`);
   const fungible837 = amountMath.make(837);
 
-  const checkDeposit = newPurseBalance => {
+  const checkDeposit = async newPurseBalance => {
     t.assert(
       amountMath.isEqual(newPurseBalance, fungible837),
       `the balance returned is the purse balance`,
@@ -92,11 +105,12 @@ test('issuer.makeEmptyPurse', async t => {
       amountMath.isEqual(purse.getCurrentAmount(), fungible837),
       `the new purse balance is the payment's old balance`,
     );
+    await checkNotifier();
   };
 
   const performWithdrawal = () => purse.withdraw(fungible837);
 
-  const checkWithdrawal = newPayment => {
+  const checkWithdrawal = async newPayment => {
     issuer.getAmountOf(newPayment).then(amount => {
       t.assert(
         amountMath.isEqual(amount, fungible837),
@@ -107,6 +121,7 @@ test('issuer.makeEmptyPurse', async t => {
       amountMath.isEqual(purse.getCurrentAmount(), amountMath.getEmpty()),
       `the purse is empty again`,
     );
+    await checkNotifier();
   };
 
   await E(purse)
@@ -117,21 +132,33 @@ test('issuer.makeEmptyPurse', async t => {
 });
 
 test('purse.deposit', async t => {
-  t.plan(4);
+  t.plan(7);
   const { issuer, mint, amountMath } = makeIssuerKit('fungible');
   const fungible0 = amountMath.getEmpty();
   const fungible17 = amountMath.make(17);
   const fungible25 = amountMath.make(25);
   const fungibleSum = amountMath.add(fungible17, fungible25);
 
   const purse = issuer.makeEmptyPurse();
+  const notifier = purse.getCurrentAmountNotifier();
   const payment17 = mint.mintPayment(fungible17);
   const payment25 = mint.mintPayment(fungible25);
 
+  let nextUpdate = notifier.getUpdateSince();
+
+  const checkNotifier = async () => {
+    const { value: balance, updateCount } = await nextUpdate;
+    t.assert(
+      amountMath.isEqual(purse.getCurrentAmount(), balance),
+      `the notifier balance is the same as the purse`,
+    );
+    nextUpdate = notifier.getUpdateSince(updateCount);
+  };
+
   const checkDeposit = (
     expectedOldBalance,
     expectedNewBalance,
-  ) => depositResult => {
+  ) => async depositResult => {
     const delta = amountMath.subtract(expectedNewBalance, expectedOldBalance);
     t.assert(
       amountMath.isEqual(depositResult, delta),
@@ -141,8 +168,10 @@ test('purse.deposit', async t => {
       amountMath.isEqual(purse.getCurrentAmount(), expectedNewBalance),
       `the new purse balance ${depositResult.value} is the expected amount: ${expectedNewBalance.value}`,
     );
+    await checkNotifier();
   };
 
+  await checkNotifier();
   await E(purse)
     .deposit(payment17, fungible17)
     .then(checkDeposit(fungible0, fungible17));
@@ -169,14 +198,25 @@ test('purse.deposit promise', async t => {
 });
 
 test('purse.getDepositFacet', async t => {
-  t.plan(2);
+  t.plan(4);
   const { issuer, mint, amountMath } = makeIssuerKit('fungible');
   const fungible25 = amountMath.make(25);
 
   const purse = issuer.makeEmptyPurse();
   const payment = mint.mintPayment(fungible25);
+  const notifier = purse.getCurrentAmountNotifier();
+
+  let nextUpdate = notifier.getUpdateSince();
+  const checkNotifier = async () => {
+    const { value: balance, updateCount } = await nextUpdate;
+    nextUpdate = notifier.getUpdateSince(updateCount);
+    t.assert(
+      amountMath.isEqual(purse.getCurrentAmount(), balance),
+      `the notifier balance is the same as the purse's`,
+    );
+  };
 
-  const checkDeposit = newPurseBalance => {
+  const checkDeposit = async newPurseBalance => {
     t.assert(
       amountMath.isEqual(newPurseBalance, fungible25),
       `the balance returned is the purse balance`,
@@ -185,8 +225,10 @@ test('purse.getDepositFacet', async t => {
       amountMath.isEqual(purse.getCurrentAmount(), fungible25),
       `the new purse balance is the payment's old balance`,
     );
+    await checkNotifier();
   };
 
+  await checkNotifier();
   await E(purse)
     .getDepositFacet()
     .then(({ receive }) => receive(payment))