@agoric/smart-wallet 0.5.3 → 0.5.4-calypso-dev-84eb287.0

package/src/marshal-contexts.js

@@ -6,7 +6,11 @@ import { DEFAULT_PREFIX } from '@agoric/vats/src/lib-board.js';
 
 const { Fail, quote: q } = assert;
 
-/** @typedef {import('@agoric/vats/src/lib-board.js').BoardId} BoardId */
+/**
+ * @import {PassableCap, RemotableObject} from '@endo/marshal';
+ * @import {Key} from '@endo/patterns';
+ * @import {BoardId} from '@agoric/vats/src/lib-board.js';
+ */
 
 /**
  * ID from a board made with { prefix: DEFAULT_PREFIX }
@@ -19,11 +23,10 @@ const isDefaultBoardId = specimen => {
 };
 
 /**
- * When marshaling a purse, payment, etc. we partition the slots
- * using prefixes.
+ * When marshaling a purse, payment, etc. we partition the slots using prefixes.
  *
- * @template {Record<string, IdTable<*,*>>} T
- * @typedef {`${string & keyof T}:${Digits}`} WalletSlot<T>
+ * @template {Record<string, IdTable<any, any>>} T
+ * @typedef {`${string & keyof T}:${Digits}`} WalletSlot
  */
 /**
  * @template {string} K
@@ -31,7 +34,7 @@ const isDefaultBoardId = specimen => {
  */
 
 /**
- * @template {Record<string, IdTable<*,*>>} T
+ * @template {Record<string, IdTable<any, any>>} T
  * @param {T} _tables
  * @param {string & keyof T} kind
  * @param {number} id
@@ -43,10 +46,10 @@ const makeWalletSlot = (_tables, kind, id) => {
 };
 
 /**
- * @template {Record<string, IdTable<*,*>>} T
+ * @template {Record<string, IdTable<any, any>>} T
  * @param {T} record
  * @param {(value: string, index: number, obj: string[]) => boolean} predicate
- * @returns {string & keyof T | undefined}
+ * @returns {(string & keyof T) | undefined}
  */
 const findKey = (record, predicate) => {
   const key = Object.keys(record).find(predicate);
@@ -54,10 +57,10 @@ const findKey = (record, predicate) => {
 };
 
 /**
- * @template {Record<string, IdTable<*,*>>} T
+ * @template {Record<string, IdTable<any, any>>} T
  * @param {T} tables
  * @param {string} slot
- * @returns {{ kind: undefined | string & keyof T, id: number }}
+ * @returns {{ kind: undefined | (string & keyof T); id: number }}
  */
 const parseWalletSlot = (tables, slot) => {
   const kind = findKey(tables, k => slot.startsWith(`${k}:`));
@@ -66,32 +69,30 @@ const parseWalletSlot = (tables, slot) => {
 };
 
 /**
- * Since KindSlots always include a colon and BoardIds never do,
- * we an mix them without confusion.
+ * Since KindSlots always include a colon and BoardIds never do, we an mix them
+ * without confusion.
  *
- * @template {Record<string, IdTable<*,*>>} T
- * @typedef {WalletSlot<T> | BoardId} MixedSlot<T>
+ * @template {Record<string, IdTable<any, any>>} T
+ * @typedef {WalletSlot<T> | BoardId} MixedSlot
  */
 /**
- * @typedef {`1` | `12` | `123`} Digits - 1 or more digits.
- * NOTE: the typescript definition here is more restrictive than
- * actual usage.
+ * @typedef {`1` | `12` | `123`} Digits - 1 or more digits. NOTE: the typescript
+ *   definition here is more restrictive than actual usage.
  */
 
 /**
- * @template Slot
- * @template Val
- *
+ * @template {Key} Slot
+ * @template {PassableCap} Val
  * @typedef {{
- *   bySlot: MapStore<Slot, Val>,
- *   byVal: MapStore<Val, Slot>,
+ *   bySlot: MapStore<Slot, Val>;
+ *   byVal: MapStore<Val, Slot>;
  * }} IdTable<Value>
  */
 
 /**
- * @template Slot
- * @template Val
- * @param {IdTable<Slot, Val>} table
+ * @template {Key} Slot
+ * @template {PassableCap} Val
+ * @param {IdTable<Slot, PassableCap>} table
  * @param {Slot} slot
  * @param {Val} val
  */
@@ -101,17 +102,20 @@ const initSlotVal = (table, slot, val) => {
 };
 
 /**
- * Make context for exporting wallet data where brands etc. can be recognized by boardId.
- * Export for use outside the smart wallet.
+ * Make context for exporting wallet data where brands etc. can be recognized by
+ * boardId. Export for use outside the smart wallet.
  *
  * When serializing wallet state for, there's a tension between
  *
- *  - keeping purses etc. closely held
- *  - recognizing identity of brands also referenced in the state of contracts such as the AMM
+ * - keeping purses etc. closely held
+ * - recognizing identity of brands also referenced in the state of contracts such
+ *   as the AMM
  *
- * `makeMarshal()` is parameterized by the type of slots. Here we use a disjoint union of
- *   - board ids for widely shared objects
- *   - kind:seq ids for closely held objects; for example purse:123
+ * `makeMarshal()` is parameterized by the type of slots. Here we use a disjoint
+ * union of
+ *
+ * - board ids for widely shared objects
+ * - kind:seq ids for closely held objects; for example purse:123
  */
 export const makeExportContext = () => {
   const walletObjects = {
@@ -126,27 +130,26 @@ export const makeExportContext = () => {
       byVal: makeScalarMapStore(),
     },
     // TODO: offer, contact, dapp
-    /** @type {IdTable<number, unknown>} */
+    /** @type {IdTable<number, PassableCap>} */
     unknown: {
       bySlot: makeScalarMapStore(),
       byVal: makeScalarMapStore(),
     },
   };
-  /** @type {IdTable<BoardId, unknown>} */
+  /** @type {IdTable<BoardId, PassableCap>} */
   const boardObjects = {
     bySlot: makeScalarMapStore(),
     byVal: makeScalarMapStore(),
   };
 
   /**
-   * Look up the slot in mappings from published data
-   * else try walletObjects that we have seen.
-   *
-   * @throws if not found (a slotToVal function typically
-   *         conjures a new identity)
+   * Look up the slot in mappings from published data else try walletObjects
+   * that we have seen.
    *
    * @param {MixedSlot<typeof walletObjects>} slot
    * @param {string} _iface
+   * @throws if not found (a slotToVal function typically conjures a new
+   *   identity)
    */
   const slotToVal = (slot, _iface) => {
     if (isDefaultBoardId(slot) && boardObjects.bySlot.has(slot)) {
@@ -161,7 +164,7 @@ export const makeExportContext = () => {
   let unknownNonce = 0;
 
   /**
-   * @param {unknown} val
+   * @param {PassableCap} val
    * @returns {MixedSlot<typeof walletObjects>}
    */
   const valToSlot = val => {
@@ -181,7 +184,7 @@ export const makeExportContext = () => {
   };
 
   /**
-   * @template V
+   * @template {PassableCap} V
    * @param {string & keyof typeof walletObjects} kind
    * @param {IdTable<number, V>} table
    */
@@ -208,14 +211,14 @@ export const makeExportContext = () => {
     purseEntries: walletObjects.purse.bySlot.entries,
     /**
      * @param {BoardId} id
-     * @param {unknown} val
+     * @param {RemotableObject} val
      */
     initBoardId: (id, val) => {
       initSlotVal(boardObjects, id, val);
     },
     /**
      * @param {BoardId} id
-     * @param {unknown} val
+     * @param {RemotableObject} val
      */
     ensureBoardId: (id, val) => {
       if (boardObjects.byVal.has(val)) {
@@ -235,38 +238,38 @@ const defaultMakePresence = iface => {
 };
 
 /**
- * Make context for marshalling wallet or board data.
- * To be imported into the client, which never exports objects.
+ * Make context for marshalling wallet or board data. To be imported into the
+ * client, which never exports objects.
  *
- * @param {(iface: string) => unknown} [makePresence]
+ * @param {(iface: string) => PassableCap} [makePresence]
  */
 export const makeImportContext = (makePresence = defaultMakePresence) => {
   const walletObjects = {
-    /** @type {IdTable<number, unknown>} */
+    /** @type {IdTable<number, PassableCap>} */
     purse: {
       bySlot: makeScalarMapStore(),
       byVal: makeScalarMapStore(),
     },
-    /** @type {IdTable<number, unknown>} */
+    /** @type {IdTable<number, PassableCap>} */
     payment: {
       bySlot: makeScalarMapStore(),
       byVal: makeScalarMapStore(),
     },
-    /** @type {IdTable<number, unknown>} */
+    /** @type {IdTable<number, PassableCap>} */
     unknown: {
       bySlot: makeScalarMapStore(),
       byVal: makeScalarMapStore(),
     },
   };
-  /** @type {IdTable<BoardId, unknown>} */
+  /** @type {IdTable<BoardId, PassableCap>} */
   const boardObjects = {
     bySlot: makeScalarMapStore(),
     byVal: makeScalarMapStore(),
   };
 
   /**
-   * @template Slot
-   * @template Val
+   * @template {Key} Slot
+   * @template {PassableCap} Val
    * @param {IdTable<Slot, Val>} table
    * @param {Slot} slot
    * @param {string} iface
@@ -308,7 +311,7 @@ export const makeImportContext = (makePresence = defaultMakePresence) => {
 
   const valToSlot = {
     fromBoard: val => boardObjects.byVal.get(val),
-    /** @param {unknown} val */
+    /** @param {PassableCap} val */
     fromMyWallet: val => {
       const kind = findKey(walletObjects, k => walletObjects[k].byVal.has(val));
       if (kind === undefined) {
@@ -334,14 +337,14 @@ export const makeImportContext = (makePresence = defaultMakePresence) => {
   return harden({
     /**
      * @param {BoardId} id
-     * @param {unknown} val
+     * @param {PassableCap} val
      */
     initBoardId: (id, val) => {
       initSlotVal(boardObjects, id, val);
     },
     /**
      * @param {BoardId} id
-     * @param {unknown} val
+     * @param {PassableCap} val
      */
     ensureBoardId: (id, val) => {
       if (boardObjects.byVal.has(val)) {
@@ -359,13 +362,17 @@ export const makeImportContext = (makePresence = defaultMakePresence) => {
 /**
  * @param {string} iface
  * @param {{
- *   applyMethod: (target: unknown, method: string | symbol, args: unknown[]) => void,
- *   applyFunction: (target: unknown, args: unknown[]) => void,
+ *   applyMethod: (
+ *     target: unknown,
+ *     method: string | symbol,
+ *     args: unknown[],
+ *   ) => void;
+ *   applyFunction: (target: unknown, args: unknown[]) => void;
  * }} handler
  */
 const makePresence = (iface, handler) => {
   let obj;
-  // eslint-disable-next-line no-new
+
   void new HandledPromise((resolve, reject, resolveWithPresence) => {
     obj = resolveWithPresence(handler);
   });

package/src/offerWatcher.d.ts

@@ -0,0 +1,48 @@
+export function watchOfferOutcomes(watchers: OutcomeWatchers, seat: UserSeat): Promise<any[]>;
+export function prepareOfferWatcher(baggage: import("@agoric/vat-data").Baggage): (walletHelper: any, deposit: any, offerSpec: OfferSpec, address: string, invitationAmount: import("@agoric/ertp/src/types.js").SetAmount<import("@endo/patterns").Key>, seatRef: UserSeat<unknown>) => import("@endo/exo").GuardedKit<{
+    helper: {
+        /**
+         * @param {Record<string, unknown>} offerStatusUpdates
+         */
+        updateStatus(offerStatusUpdates: Record<string, unknown>): void;
+        /**
+         * @param {string} offerId
+         * @param {Amount<'set'>} invitationAmount
+         * @param {import('./types.js').InvitationMakers} invitationMakers
+         * @param {import('./types.js').PublicSubscribers} publicSubscribers
+         */
+        onNewContinuingOffer(offerId: string, invitationAmount: Amount<"set">, invitationMakers: import("./types.js").InvitationMakers, publicSubscribers: import("./types.js").PublicSubscribers): void;
+        /** @param {Passable | ContinuingOfferResult} result */
+        publishResult(result: Passable | ContinuingOfferResult): void;
+        /**
+         * Called when the offer result promise rejects. The other two watchers
+         * are waiting for particular values out of Zoe but they settle at the
+         * same time and don't need their own error handling.
+         *
+         * @param {Error} err
+         */
+        handleError(err: Error): void;
+    };
+    /** @type {OutcomeWatchers['paymentWatcher']} */
+    paymentWatcher: OutcomeWatchers["paymentWatcher"];
+    /** @type {OutcomeWatchers['resultWatcher']} */
+    resultWatcher: OutcomeWatchers["resultWatcher"];
+    /** @type {OutcomeWatchers['numWantsWatcher']} */
+    numWantsWatcher: OutcomeWatchers["numWantsWatcher"];
+}>;
+/**
+ * <T, [UserSeat]
+ */
+export type OfferPromiseWatcher<T extends unknown> = PromiseWatcher<T, [UserSeat]>;
+export type OutcomeWatchers = {
+    resultWatcher: OfferPromiseWatcher<Passable>;
+    numWantsWatcher: OfferPromiseWatcher<number>;
+    paymentWatcher: OfferPromiseWatcher<PaymentPKeywordRecord>;
+};
+export type MakeOfferWatcher = ReturnType<typeof prepareOfferWatcher>;
+export type OfferWatcher = ReturnType<MakeOfferWatcher>;
+import type { OfferSpec } from "./offers.js";
+import type { Passable } from '@endo/pass-style';
+import type { ContinuingOfferResult } from "./types.js";
+import type { PromiseWatcher } from '@agoric/swingset-liveslots';
+//# sourceMappingURL=offerWatcher.d.ts.map

package/src/offerWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offerWatcher.d.ts","sourceRoot":"","sources":["offerWatcher.js"],"names":[],"mappings":"AAwEO,6CAHI,eAAe,QACf,QAAQ,kBAWlB;AAkCM,6CAFI,OAAO,kBAAkB,EAAE,OAAO,iNAoHnB,WAAW;;QA3F7B;;WAEG;yCADQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;QAQlC;;;;;WAKG;sCAJQ,MAAM,oBACN,MAAM,CAAC,KAAK,CAAC,oBACb,OAAO,YAAY,EAAE,gBAAgB,qBACrC,OAAO,YAAY,EAAE,iBAAiB;QAkBjD,uDAAuD;8BAA3C,QAAQ,GAAG,qBAAqB;QAoC5C;;;;;;WAMG;yBADQ,KAAK;;IAclB,gDAAgD;oBAArC,eAAe,CAAC,gBAAgB,CAAC;IA+B5C,+CAA+C;mBAApC,eAAe,CAAC,eAAe,CAAC;IAwB3C,iDAAiD;qBAAtC,eAAe,CAAC,iBAAiB,CAAC;GA2BlD;;;;gCAzRkB,CAAC,oBACP,eAAe,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;8BAI7B;IACZ,aAAiB,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACjD,eAAmB,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IACjD,cAAkB,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;CAC5D;+BAmRU,UAAU,CAAC,OAAO,mBAAmB,CAAC;2BACtC,UAAU,CAAC,gBAAgB,CAAC;+BApSd,aAAa;8BAEd,kBAAkB;2CADL,YAAY;oCAEnB,4BAA4B"}

package/src/offerWatcher.js

@@ -0,0 +1,311 @@
+import { E, passStyleOf } from '@endo/far';
+
+import { isUpgradeDisconnection } from '@agoric/internal/src/upgrade-api.js';
+import { prepareExoClassKit, watchPromise } from '@agoric/vat-data';
+import { M } from '@agoric/store';
+import {
+  PaymentPKeywordRecordShape,
+  SeatShape,
+} from '@agoric/zoe/src/typeGuards.js';
+import { AmountShape } from '@agoric/ertp/src/typeGuards.js';
+import { deeplyFulfilledObject, objectMap } from '@agoric/internal';
+import { heapVowTools } from '@agoric/vow/vat.js';
+
+import { UNPUBLISHED_RESULT } from './offers.js';
+
+const { when, allVows } = heapVowTools;
+
+/**
+ * @import {OfferSpec} from "./offers.js";
+ * @import {ContinuingOfferResult} from "./types.js";
+ * @import {Passable} from '@endo/pass-style';
+ * @import {PromiseWatcher} from '@agoric/swingset-liveslots';
+ */
+
+/**
+ * @template {any} T
+ * @typedef {PromiseWatcher<T, [UserSeat]>} OfferPromiseWatcher<T, [UserSeat]
+ */
+
+/**
+ * @typedef {{
+ *   resultWatcher: OfferPromiseWatcher<Passable>;
+ *   numWantsWatcher: OfferPromiseWatcher<number>;
+ *   paymentWatcher: OfferPromiseWatcher<PaymentPKeywordRecord>;
+ * }} OutcomeWatchers
+ */
+
+/**
+ * @param {OutcomeWatchers} watchers
+ * @param {UserSeat} seat
+ */
+const watchForOfferResult = ({ resultWatcher }, seat) => {
+  // NOTE: this enables upgrade of the contract, NOT upgrade of the smart-wallet. See #9308
+  const p = when(E(seat).getOfferResult());
+  watchPromise(p, resultWatcher, seat);
+  return p;
+};
+
+/**
+ * @param {OutcomeWatchers} watchers
+ * @param {UserSeat} seat
+ */
+const watchForNumWants = ({ numWantsWatcher }, seat) => {
+  const p = E(seat).numWantsSatisfied();
+  watchPromise(p, numWantsWatcher, seat);
+  return p;
+};
+
+/**
+ * @param {OutcomeWatchers} watchers
+ * @param {UserSeat} seat
+ */
+const watchForPayout = ({ paymentWatcher }, seat) => {
+  const p = E(seat).getPayouts();
+  watchPromise(p, paymentWatcher, seat);
+  return p;
+};
+
+/**
+ * @param {OutcomeWatchers} watchers
+ * @param {UserSeat} seat
+ */
+export const watchOfferOutcomes = (watchers, seat) => {
+  // NOTE: this enables upgrade of the contract, NOT upgrade of the smart-wallet. See #9308
+  return when(
+    allVows([
+      watchForOfferResult(watchers, seat),
+      watchForNumWants(watchers, seat),
+      watchForPayout(watchers, seat),
+    ]),
+  );
+};
+
+const offerWatcherGuard = harden({
+  helper: M.interface('InstanceAdminStorage', {
+    updateStatus: M.call(M.any()).returns(),
+    onNewContinuingOffer: M.call(
+      M.or(M.number(), M.string()),
+      AmountShape,
+      M.any(),
+    )
+      .optional(M.record())
+      .returns(),
+    publishResult: M.call(M.any()).returns(),
+    handleError: M.call(M.error()).returns(),
+  }),
+  paymentWatcher: M.interface('paymentWatcher', {
+    onFulfilled: M.call(PaymentPKeywordRecordShape, SeatShape).returns(
+      M.promise(),
+    ),
+    onRejected: M.call(M.any(), SeatShape).returns(),
+  }),
+  resultWatcher: M.interface('resultWatcher', {
+    onFulfilled: M.call(M.any(), SeatShape).returns(),
+    onRejected: M.call(M.any(), SeatShape).returns(),
+  }),
+  numWantsWatcher: M.interface('numWantsWatcher', {
+    onFulfilled: M.call(M.number(), SeatShape).returns(),
+    onRejected: M.call(M.any(), SeatShape).returns(),
+  }),
+});
+
+/**
+ * @param {import('@agoric/vat-data').Baggage} baggage
+ */
+export const prepareOfferWatcher = baggage => {
+  return prepareExoClassKit(
+    baggage,
+    'OfferWatcher',
+    offerWatcherGuard,
+    /**
+     * @param {any} walletHelper
+     * @param {any} deposit
+     * @param {OfferSpec} offerSpec
+     * @param {string} address
+     * @param {Amount<'set'>} invitationAmount
+     * @param {UserSeat} seatRef
+     */
+    (walletHelper, deposit, offerSpec, address, invitationAmount, seatRef) => ({
+      walletHelper,
+      deposit,
+      status: offerSpec,
+      address,
+      invitationAmount,
+      seatRef,
+    }),
+    {
+      helper: {
+        /**
+         * @param {Record<string, unknown>} offerStatusUpdates
+         */
+        updateStatus(offerStatusUpdates) {
+          const { state } = this;
+          state.status = harden({ ...state.status, ...offerStatusUpdates });
+
+          state.walletHelper.updateStatus(state.status);
+        },
+        /**
+         * @param {string} offerId
+         * @param {Amount<'set'>} invitationAmount
+         * @param {import('./types.js').InvitationMakers} invitationMakers
+         * @param {import('./types.js').PublicSubscribers} publicSubscribers
+         */
+        onNewContinuingOffer(
+          offerId,
+          invitationAmount,
+          invitationMakers,
+          publicSubscribers,
+        ) {
+          const { state } = this;
+
+          void state.walletHelper.addContinuingOffer(
+            offerId,
+            invitationAmount,
+            invitationMakers,
+            publicSubscribers,
+          );
+        },
+
+        /** @param {Passable | ContinuingOfferResult} result */
+        publishResult(result) {
+          const { state, facets } = this;
+
+          const passStyle = passStyleOf(result);
+          // someday can we get TS to type narrow based on the passStyleOf result match?
+          switch (passStyle) {
+            case 'bigint':
+            case 'boolean':
+            case 'null':
+            case 'number':
+            case 'string':
+            case 'symbol':
+            case 'undefined':
+              facets.helper.updateStatus({ result });
+              break;
+            case 'copyRecord':
+              // @ts-expect-error narrowed by passStyle
+              if ('invitationMakers' in result) {
+                // save for continuing invitation offer
+
+                void facets.helper.onNewContinuingOffer(
+                  String(state.status.id),
+                  state.invitationAmount,
+                  // @ts-expect-error narrowed by passStyle
+                  result.invitationMakers,
+                  result.publicSubscribers,
+                );
+              }
+              facets.helper.updateStatus({ result: UNPUBLISHED_RESULT });
+              break;
+            default:
+              // drop the result
+              facets.helper.updateStatus({ result: UNPUBLISHED_RESULT });
+          }
+        },
+        /**
+         * Called when the offer result promise rejects. The other two watchers
+         * are waiting for particular values out of Zoe but they settle at the
+         * same time and don't need their own error handling.
+         *
+         * @param {Error} err
+         */
+        handleError(err) {
+          const { facets } = this;
+          facets.helper.updateStatus({ error: err.toString() });
+          const { seatRef } = this.state;
+          void E.when(E(seatRef).hasExited(), hasExited => {
+            if (!hasExited) {
+              void E(seatRef).tryExit();
+            }
+          });
+        },
+      },
+
+      /** @type {OutcomeWatchers['paymentWatcher']} */
+      paymentWatcher: {
+        async onFulfilled(payouts) {
+          const { state, facets } = this;
+
+          // This will block until all payouts succeed, but user will be updated
+          // since each payout will trigger its corresponding purse notifier.
+          const amountPKeywordRecord = objectMap(payouts, paymentRef =>
+            E.when(paymentRef, payment => state.deposit.receive(payment)),
+          );
+          const amounts = await deeplyFulfilledObject(amountPKeywordRecord);
+          facets.helper.updateStatus({ payouts: amounts });
+        },
+        /**
+         * If promise disconnected, watch again. Or if there's an Error, handle
+         * it.
+         *
+         * @param {Error
+         *   | import('@agoric/internal/src/upgrade-api.js').UpgradeDisconnection} reason
+         * @param {UserSeat} seat
+         */
+        onRejected(reason, seat) {
+          const { facets } = this;
+          if (isUpgradeDisconnection(reason)) {
+            void watchForPayout(facets, seat);
+          } else {
+            facets.helper.handleError(reason);
+          }
+        },
+      },
+
+      /** @type {OutcomeWatchers['resultWatcher']} */
+      resultWatcher: {
+        onFulfilled(result) {
+          const { facets } = this;
+          facets.helper.publishResult(result);
+        },
+        /**
+         * If promise disconnected, watch again. Or if there's an Error, handle
+         * it.
+         *
+         * @param {Error
+         *   | import('@agoric/internal/src/upgrade-api.js').UpgradeDisconnection} reason
+         * @param {UserSeat} seat
+         */
+        onRejected(reason, seat) {
+          const { facets } = this;
+          if (isUpgradeDisconnection(reason)) {
+            void watchForOfferResult(facets, seat);
+          } else {
+            facets.helper.handleError(reason);
+          }
+        },
+      },
+
+      /** @type {OutcomeWatchers['numWantsWatcher']} */
+      numWantsWatcher: {
+        onFulfilled(numSatisfied) {
+          const { facets } = this;
+
+          facets.helper.updateStatus({ numWantsSatisfied: numSatisfied });
+        },
+        /**
+         * If promise disconnected, watch again.
+         *
+         * Errors are handled by the paymentWatcher because numWantsSatisfied()
+         * and getPayouts() settle the same (they await the same promise and
+         * then synchronously return a local value).
+         *
+         * @param {Error
+         *   | import('@agoric/internal/src/upgrade-api.js').UpgradeDisconnection} reason
+         * @param {UserSeat} seat
+         */
+        onRejected(reason, seat) {
+          const { facets } = this;
+          if (isUpgradeDisconnection(reason)) {
+            void watchForNumWants(facets, seat);
+          }
+        },
+      },
+    },
+  );
+};
+harden(prepareOfferWatcher);
+
+/** @typedef {ReturnType<typeof prepareOfferWatcher>} MakeOfferWatcher */
+/** @typedef {ReturnType<MakeOfferWatcher>} OfferWatcher */