9281 provideOrchestration to provide asyncTools (#9518)

refs: #9281 ## Description Orchestration API needs asyncTools. This makes it required for construction. That made the boilerplate in `start` quite large so this also adds a helper to do all the setup that any orchestration contract needs. ### Security Considerations none ### Scaling Considerations none ### Documentation Considerations Part of these example contracts ### Testing Considerations Existing coverage suffics ### Upgrade Considerations Not yet deployed
Agoric · Jun 18, 2024 · a035bbe · a035bbe
2 parents f908f89 + f096604
commit a035bbe
Show file tree

Hide file tree

Showing 28 changed files with 238 additions and 95 deletions.
diff --git a/packages/async-flow/src/async-flow.js b/packages/async-flow/src/async-flow.js
@@ -10,7 +10,14 @@ import { prepareBijection } from './bijection.js';
 import { LogEntryShape, FlowStateShape } from './type-guards.js';
 
 /**
- * @import { WeakMapStore } from '@agoric/store'
+ * @import {WeakMapStore} from '@agoric/store'
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {MapStore} from '@agoric/store';
+ * @import {LogStore} from '../src/log-store.js';
+ * @import {Bijection} from '../src/bijection.js';
+ * @import {FlowState, GuestAsyncFunc, HostAsyncFuncWrapper, PreparationOptions} from '../src/types.js';
+ * @import {ReplayMembrane} from '../src/replay-membrane.js';
  */
 
 const { defineProperties } = Object;

diff --git a/packages/async-flow/src/bijection.js b/packages/async-flow/src/bijection.js
@@ -4,6 +4,12 @@ import { Far } from '@endo/pass-style';
 import { toPassableCap } from '@agoric/vow';
 import { makeEphemera } from './ephemera.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {Ephemera} from './types.js';
+ */
+
 const BijectionI = M.interface('Bijection', {
   reset: M.call().returns(),
   init: M.call(M.any(), M.any()).returns(),

diff --git a/packages/async-flow/src/convert.js b/packages/async-flow/src/convert.js
@@ -10,6 +10,10 @@ import {
 import { isVow } from '@agoric/vow/src/vow-utils.js';
 import { objectMap } from '@endo/common/object-map.js';
 
+/**
+ * @import {Passable} from '@endo/pass-style'
+ */
+
 const makeConvert = (convertRemotable, convertPromiseOrVow, convertError) => {
   const convertRecur = (specimen, label) => {
     // Open code the synchronous part of applyLabelingError, because

diff --git a/packages/async-flow/src/ephemera.js b/packages/async-flow/src/ephemera.js
@@ -1,3 +1,9 @@
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {Ephemera} from './types.js';
+ */
+
 /**
  * Used by a possibly-durable exo to store per-instance ephemeral state.
  * Each ephemera is created at the exo class prepare level, and then

diff --git a/packages/async-flow/src/log-store.js b/packages/async-flow/src/log-store.js
@@ -5,7 +5,10 @@ import { LogEntryShape } from './type-guards.js';
 import { makeEphemera } from './ephemera.js';
 
 /**
- * @import {MapStore} from '@agoric/store'
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {MapStore} from '@agoric/store';
+ * @import {Ephemera, LogEntry} from './types.js';
  */
 
 const LogStoreI = M.interface('LogStore', {

diff --git a/packages/async-flow/src/replay-membrane.js b/packages/async-flow/src/replay-membrane.js
@@ -8,6 +8,12 @@ import { makeConvertKit } from './convert.js';
 
 /**
  * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {Vow, VowTools} from '@agoric/vow'
+ * @import {AsyncFlow} from '../src/async-flow.js'
+ * @import {LogStore} from '../src/log-store.js';
+ * @import {Bijection} from '../src/bijection.js';
+ * @import {Host, HostVow, LogEntry, Outcome} from '../src/types.js';
  */
 
 const { fromEntries, defineProperties, assign } = Object;

diff --git a/packages/async-flow/src/types.js b/packages/async-flow/src/types.js
@@ -1,5 +1,7 @@
+// Ensure this is a module.
+export {};
+
 /**
- * @import {PromiseKit} from '@endo/promise-kit'
  * @import {Passable} from '@endo/pass-style'
  * @import {Zone} from '@agoric/base-zone'
  * @import {Vow, VowTools} from '@agoric/vow'

diff --git a/packages/async-flow/test/async-flow-crank.test.js b/packages/async-flow/test/async-flow-crank.test.js
@@ -16,6 +16,12 @@ import { makeDurableZone } from '@agoric/zone/durable.js';
 
 import { prepareAsyncFlowTools } from '../src/async-flow.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {Ephemera} from './types.js';
+ */
+
 const neverSettlesP = new Promise(() => {});
 
 /**

diff --git a/packages/async-flow/test/async-flow-early-completion.test.js b/packages/async-flow/test/async-flow-early-completion.test.js
@@ -18,6 +18,8 @@ import { makeDurableZone } from '@agoric/zone/durable.js';
 import { prepareAsyncFlowTools } from '../src/async-flow.js';
 
 /**
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {Vow, VowTools} from '@agoric/vow'
  * @import {AsyncFlow} from '../src/async-flow.js'
  */
 

diff --git a/packages/async-flow/test/async-flow-no-this.js b/packages/async-flow/test/async-flow-no-this.js
@@ -9,6 +9,12 @@ import { makeDurableZone } from '@agoric/zone/durable.js';
 
 import { prepareAsyncFlowTools } from '../src/async-flow.js';
 
+/**
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {Vow, VowTools} from '@agoric/vow'
+ * @import {AsyncFlow} from '../src/async-flow.js'
+ */
+
 const { apply } = Reflect;
 
 /**

diff --git a/packages/async-flow/test/async-flow.test.js b/packages/async-flow/test/async-flow.test.js
@@ -21,6 +21,9 @@ import { prepareAsyncFlowTools } from '../src/async-flow.js';
 
 /**
  * @import {AsyncFlow} from '../src/async-flow.js'
+ * @import {Vow, VowTools} from '@agoric/vow'
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
  */
 
 /**

diff --git a/packages/async-flow/test/bad-host.test.js b/packages/async-flow/test/bad-host.test.js
@@ -17,6 +17,11 @@ import { makeDurableZone } from '@agoric/zone/durable.js';
 
 import { prepareAsyncFlowTools } from '../src/async-flow.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ */
+
 const nonPassableFunc = () => 'non-passable-function';
 harden(nonPassableFunc);
 const guestCreatedPromise = harden(Promise.resolve('guest-created'));

diff --git a/packages/async-flow/test/bijection.test.js b/packages/async-flow/test/bijection.test.js
@@ -15,6 +15,12 @@ import { makeDurableZone } from '@agoric/zone/durable.js';
 
 import { prepareBijection } from '../src/bijection.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {Ephemera} from './types.js';
+ */
+
 /**
  * @param {any} t
  * @param {Zone} zone

diff --git a/packages/async-flow/test/convert.test.js b/packages/async-flow/test/convert.test.js
@@ -18,6 +18,11 @@ import { makeDurableZone } from '@agoric/zone/durable.js';
 import { makeConvertKit } from '../src/convert.js';
 import { prepareBijection } from '../src/bijection.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ */
+
 /**
  * @param {any} t
  * @param {Zone} zone

diff --git a/packages/async-flow/test/equate.test.js b/packages/async-flow/test/equate.test.js
@@ -18,6 +18,10 @@ import { makeDurableZone } from '@agoric/zone/durable.js';
 import { prepareBijection } from '../src/bijection.js';
 import { makeEquate } from '../src/equate.js';
 
+/**
+ * @import {Zone} from '@agoric/base-zone'
+ */
+
 /**
  * @param {any} t
  * @param {Zone} zone

diff --git a/packages/async-flow/test/log-store.test.js b/packages/async-flow/test/log-store.test.js
@@ -14,6 +14,14 @@ import { makeDurableZone } from '@agoric/zone/durable.js';
 
 import { prepareLogStore } from '../src/log-store.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {Vow, VowTools} from '@agoric/vow'
+ * @import {LogStore} from '../src/log-store.js';
+ * @import {Bijection} from '../src/bijection.js';
+ */
+
 /**
  * @param {any} t
  * @param {Zone} zone

diff --git a/packages/async-flow/test/replay-membrane-eventual.test.js b/packages/async-flow/test/replay-membrane-eventual.test.js
@@ -18,6 +18,13 @@ import { prepareLogStore } from '../src/log-store.js';
 import { prepareBijection } from '../src/bijection.js';
 import { makeReplayMembrane } from '../src/replay-membrane.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {LogStore} from '../src/log-store.js';
+ * @import {Bijection} from '../src/bijection.js';
+ */
+
 const watchWake = _vowish => {};
 const panic = problem => Fail`panic over ${problem}`;
 

diff --git a/packages/async-flow/test/replay-membrane-settlement.test.js b/packages/async-flow/test/replay-membrane-settlement.test.js
@@ -17,6 +17,13 @@ import { prepareLogStore } from '../src/log-store.js';
 import { prepareBijection } from '../src/bijection.js';
 import { makeReplayMembrane } from '../src/replay-membrane.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {LogStore} from '../src/log-store.js';
+ * @import {Bijection} from '../src/bijection.js';
+ */
+
 const watchWake = _vowish => {};
 const panic = problem => Fail`panic over ${problem}`;
 

diff --git a/packages/async-flow/test/replay-membrane-zombie.test.js b/packages/async-flow/test/replay-membrane-zombie.test.js
@@ -17,6 +17,11 @@ import { prepareLogStore } from '../src/log-store.js';
 import { prepareBijection } from '../src/bijection.js';
 import { makeReplayMembrane } from '../src/replay-membrane.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ */
+
 const watchWake = _vowish => {};
 const panic = problem => Fail`panic over ${problem}`;
 

diff --git a/packages/async-flow/test/replay-membrane.test.js b/packages/async-flow/test/replay-membrane.test.js
@@ -18,6 +18,14 @@ import { prepareLogStore } from '../src/log-store.js';
 import { prepareBijection } from '../src/bijection.js';
 import { makeReplayMembrane } from '../src/replay-membrane.js';
 
+/**
+ * @import {PromiseKit} from '@endo/promise-kit'
+ * @import {Zone} from '@agoric/base-zone'
+ * @import {MapStore} from '@agoric/store';
+ * @import {LogStore} from '../src/log-store.js';
+ * @import {Bijection} from '../src/bijection.js';
+ */
+
 const watchWake = _vowish => {};
 const panic = problem => Fail`panic over ${problem}`;
 

diff --git a/packages/orchestration/package.json b/packages/orchestration/package.json
@@ -32,6 +32,7 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
+    "@agoric/async-flow": "^0.1.0",
     "@agoric/assert": "^0.6.0",
     "@agoric/cosmic-proto": "^0.4.0",
     "@agoric/ertp": "^0.16.2",

diff --git a/packages/orchestration/src/examples/sendAnywhere.contract.js b/packages/orchestration/src/examples/sendAnywhere.contract.js
@@ -1,15 +1,11 @@
-import { makeDurableZone } from '@agoric/zone/durable.js';
-import { M, mustMatch } from '@endo/patterns';
+import { withdrawFromSeat } from '@agoric/zoe/src/contractSupport/zoeHelpers.js';
 import { InvitationShape } from '@agoric/zoe/src/typeGuards.js';
 import { E } from '@endo/far';
-import { withdrawFromSeat } from '@agoric/zoe/src/contractSupport/zoeHelpers.js';
+import { M, mustMatch } from '@endo/patterns';
 
 import { AmountShape } from '@agoric/ertp';
-import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport/recorder.js';
 import { CosmosChainInfoShape } from '../typeGuards.js';
-import { makeOrchestrationFacade } from '../facade.js';
-import { prepareLocalChainAccountKit } from '../exos/local-chain-account-kit.js';
-import { makeChainHub } from '../utils/chainHub.js';
+import { provideOrchestration } from '../utils/start-helper.js';
 
 const { entries } = Object;
 const { Fail } = assert;
@@ -49,28 +45,12 @@ export const SingleAmountRecord = M.and(
  * @param {Baggage} baggage
  */
 export const start = async (zcf, privateArgs, baggage) => {
-  const zone = makeDurableZone(baggage);
-
-  const chainHub = makeChainHub(privateArgs.agoricNames);
-
-  // TODO once durability is settled, provide some helpers to reduce boilerplate
-  const { marshaller, ...orchPowers } = privateArgs;
-  const { makeRecorderKit } = prepareRecorderKitMakers(baggage, marshaller);
-  const makeLocalChainAccountKit = prepareLocalChainAccountKit(
-    zone,
-    makeRecorderKit,
+  const { chainHub, orchestrate, zone } = provideOrchestration(
     zcf,
-    privateArgs.timerService,
-    chainHub,
+    baggage,
+    privateArgs,
+    privateArgs.marshaller,
   );
-  const { orchestrate } = makeOrchestrationFacade({
-    zcf,
-    zone,
-    chainHub,
-    makeLocalChainAccountKit,
-    makeRecorderKit,
-    ...orchPowers,
-  });
 
   let contractAccount;
 

diff --git a/packages/orchestration/src/examples/swapExample.contract.js b/packages/orchestration/src/examples/swapExample.contract.js
@@ -1,16 +1,11 @@
 import { StorageNodeShape } from '@agoric/internal';
 import { TimerServiceShape } from '@agoric/time';
 import { withdrawFromSeat } from '@agoric/zoe/src/contractSupport/zoeHelpers.js';
-import { makeDurableZone } from '@agoric/zone/durable.js';
-import { E, Far } from '@endo/far';
+import { Far } from '@endo/far';
 import { deeplyFulfilled } from '@endo/marshal';
 import { M, objectMap } from '@endo/patterns';
-import { provideAll } from '@agoric/zoe/src/contractSupport';
-import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport/recorder.js';
-import { makeOrchestrationFacade } from '../facade.js';
 import { orcUtils } from '../utils/orc.js';
-import { makeChainHub } from '../utils/chainHub.js';
-import { prepareLocalChainAccountKit } from '../exos/local-chain-account-kit.js';
+import { provideOrchestration } from '../utils/start-helper.js';
 
 /**
  * @import {Orchestrator, IcaAccount, CosmosValidatorAddress} from '../types.js'
@@ -58,10 +53,6 @@ export const makeNatAmountShape = (brand, min) =>
  * @param {Baggage} baggage
  */
 export const start = async (zcf, privateArgs, baggage) => {
-  const { brands } = zcf.getTerms();
-
-  const zone = makeDurableZone(baggage);
-
   const {
     agoricNames,
     localchain,
@@ -71,30 +62,20 @@ export const start = async (zcf, privateArgs, baggage) => {
     marshaller,
   } = privateArgs;
 
-  const chainHub = makeChainHub(agoricNames);
-  const { makeRecorderKit } = prepareRecorderKitMakers(baggage, marshaller);
-  const makeLocalChainAccountKit = prepareLocalChainAccountKit(
-    zone,
-    makeRecorderKit,
+  const { orchestrate } = provideOrchestration(
     zcf,
-    timerService,
-    chainHub,
+    baggage,
+    {
+      agoricNames,
+      localchain,
+      orchestrationService,
+      storageNode,
+      timerService,
+    },
+    marshaller,
   );
-  const { accountsStorageNode } = await provideAll(baggage, {
-    accountsStorageNode: () => E(storageNode).makeChildNode('accounts'),
-  });
 
-  const { orchestrate } = makeOrchestrationFacade({
-    localchain,
-    orchestrationService,
-    storageNode: accountsStorageNode,
-    timerService,
-    zcf,
-    zone,
-    chainHub,
-    makeLocalChainAccountKit,
-    makeRecorderKit,
-  });
+  const { brands } = zcf.getTerms();
 
   /** deprecated historical example */
   /**