feat(sync-tools): add method to wait until offer has exited (#10462)

closes: https://github.com/Agoric/BytePitchPartnerEng/issues/38

## Description

This PR aims to extend the available `sync-tools` by providing a method that allows the developer to verify that an offer was successfully exited via the execution of a `tryExitOffer` call.

The method `waitUntilOfferExited` will poll the user's wallet `liveOffers` and check if the respective `offerId` is no longer present.

### Security Considerations


No new assumptions or dependencies were introduced.

### Scaling Considerations


No requirements for increased resources.

### Documentation Considerations


This additional tool does not impact backward compatibility.

Although it may be useful to inform the developer that intends to use this method to prevent a false positive, it should first verify that the offerID is indeed present in the user's wallet liveOffers before calling `tryExitOffer`.

### Testing Considerations


I have confirmed that this method works as expected when used locally at the a3p-integration acceptance tests.
The test used is not included in the PR, since it would be out of scope.

### Upgrade Considerations


No impact is expected for live production systems.

packages/client-utils/src/sync-tools.js

@@ -9,6 +9,7 @@
  *  - operation: query dest account's balance
  *  - condition: dest account has a balance >= sent token
  * - Making sure an offer resulted successfully
+ * - Making sure an offer was exited successfully
  *
  */
 
@@ -287,3 +288,40 @@ export const waitUntilInvitationReceived = (addr, io, options) => {
     { reusePromise: true, setTimeout, ...resolvedOptions },
   );
 };
+
+/// ////////// Making sure an offer was exited successfully /////////////
+
+const makeQueryWalletCurrent = follow => (/** @type {string} */ addr) =>
+  follow('-lF', `:published.wallet.${addr}.current`);
+
+/**
+ * @param {object} update
+ * @param {string} offerId
+ * @returns {boolean}
+ */
+const checkLiveOffers = (update, offerId) => {
+  const liveOffers = update.liveOffers;
+  if (!liveOffers) {
+    return false;
+  }
+  return !liveOffers.some(element => element.includes(offerId));
+};
+
+/**
+ * @param {string} addr
+ * @param {string} offerId
+ * @param {{ follow: () => object, log: typeof console.log, setTimeout: typeof global.setTimeout}} io
+ * @param {WaitUntilOptions} options
+ */
+export const waitUntilOfferExited = async (addr, offerId, io, options) => {
+  const { follow, setTimeout } = io;
+  const queryWalletCurrent = makeQueryWalletCurrent(follow);
+  const { errorMessage, ...resolvedOptions } = overrideDefaultOptions(options);
+
+  return retryUntilCondition(
+    async () => queryWalletCurrent(addr),
+    update => checkLiveOffers(update, offerId),
+    errorMessage,
+    { setTimeout, ...resolvedOptions },
+  );
+};

packages/client-utils/test/snapshots/exports.test.js.md

@@ -24,5 +24,6 @@ Generated by [AVA](https://avajs.dev).
       'waitUntilAccountFunded',
       'waitUntilContractDeployed',
       'waitUntilInvitationReceived',
+      'waitUntilOfferExited',
       'waitUntilOfferResult',
     ]

packages/client-utils/test/sync-tools.test.js

@@ -6,6 +6,7 @@ import {
   waitUntilAccountFunded,
   waitUntilContractDeployed,
   waitUntilInvitationReceived,
+  waitUntilOfferExited,
   waitUntilOfferResult,
 } from '../src/sync-tools.js';
 
@@ -403,3 +404,21 @@ test.serial('wait until invitation recevied', async t => {
 
   await t.notThrowsAsync(waitP);
 });
+
+test.serial('wait until offer exited', async t => {
+  const { setValue, follow } = makeFakeFollow();
+  setValue({});
+
+  const waitP = waitUntilOfferExited(
+    'agoric12345',
+    'my-offer',
+    { follow, log: t.log, setTimeout },
+    {
+      maxRetries: 5,
+      retryIntervalMs,
+      errorMessage: 'Offer not exited',
+    },
+  );
+
+  await t.throwsAsync(waitP);
+});