misc Orchestration cleanup (#9720)

_incidental_

## Description
Miscellaneous cleanups while starting #9719 for #9303.

See each commit title for changes

### Security Considerations
none

### Scaling Considerations
none

### Documentation Considerations
none

### Testing Considerations
CI

### Upgrade Considerations
not yet deployed

packages/orchestration/package.json

@@ -92,6 +92,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 98.04
+    "atLeast": 98.09
   }
 }

packages/orchestration/src/examples/sendAnywhere.contract.js

@@ -13,8 +13,9 @@ import { orchestrationFns } from './sendAnywhereFlows.js';
  * @import {TimerService} from '@agoric/time';
  * @import {LocalChain} from '@agoric/vats/src/localchain.js';
  * @import {NameHub} from '@agoric/vats';
- * @import {Remote} from '@agoric/vow';
+ * @import {Remote, Vow} from '@agoric/vow';
  * @import {Zone} from '@agoric/zone';
+ * @import {VBankAssetDetail} from '@agoric/vats/tools/board-utils.js';
  * @import {CosmosChainInfo, IBCConnectionInfo} from '../cosmos-api';
  * @import {CosmosInterchainService} from '../exos/cosmos-interchain-service.js';
  * @import {OrchestrationTools} from '../utils/start-helper.js';
@@ -60,6 +61,7 @@ const contract = async (
   );
 
   // TODO should be a provided helper
+  /** @type {(brand: Brand) => Vow<VBankAssetDetail>} */
   const findBrandInVBank = vowTools.retriable(
     zone,
     'findBrandInVBank',

packages/orchestration/src/examples/sendAnywhereFlows.js

@@ -1,7 +1,10 @@
 import { M, mustMatch } from '@endo/patterns';
 
 /**
- * @import {Orchestrator, OrchestrationAccount} from '../types.js';
+ * @import {GuestOf} from '@agoric/async-flow';
+ * @import {VBankAssetDetail} from '@agoric/vats/tools/board-utils.js';
+ * @import {ZoeTools} from '../utils/zoe-tools.js';
+ * @import {Orchestrator, OrchestrationAccount, LocalAccountMethods, OrchestrationAccountI} from '../types.js';
  */
 
 const { entries } = Object;
@@ -13,9 +16,9 @@ export const orchestrationFns = harden({
   /**
    * @param {Orchestrator} orch
    * @param {object} ctx
-   * @param {{ account: OrchestrationAccount<any> }} ctx.contractState
-   * @param {any} ctx.localTransfer
-   * @param {any} ctx.findBrandInVBank
+   * @param {{ account?: OrchestrationAccountI & LocalAccountMethods }} ctx.contractState
+   * @param {GuestOf<ZoeTools['localTransfer']>} ctx.localTransfer
+   * @param {(brand: Brand) => Promise<VBankAssetDetail>} ctx.findBrandInVBank
    * @param {ZCFSeat} seat
    * @param {{ chainName: string; destAddr: string }} offerArgs
    */

packages/orchestration/src/exos/cosmos-orchestration-account.js

@@ -1,7 +1,4 @@
 /** @file Use-object for the owner of a staking account */
-import { Fail } from '@endo/errors';
-import { decodeBase64 } from '@endo/base64';
-import { E } from '@endo/far';
 import { toRequestQueryJson } from '@agoric/cosmic-proto';
 import {
   QueryBalanceRequest,
@@ -22,12 +19,14 @@ import { makeTracer } from '@agoric/internal';
 import { Shape as NetworkShape } from '@agoric/network';
 import { M } from '@agoric/vat-data';
 import { VowShape } from '@agoric/vow';
+import { decodeBase64 } from '@endo/base64';
+import { Fail } from '@endo/errors';
+import { E } from '@endo/far';
 import {
   AmountArgShape,
   ChainAddressShape,
-  ChainAmountShape,
-  CoinShape,
   DelegationShape,
+  DenomAmountShape,
 } from '../typeGuards.js';
 import { maxClockSkew, tryDecodeResponse } from '../utils/cosmos.js';
 import { orchestrationAccountMethods } from '../utils/orchestrationAccount.js';
@@ -78,9 +77,9 @@ export const IcaAccountHolderI = M.interface('IcaAccountHolder', {
     AmountArgShape,
   ).returns(VowShape),
   withdrawReward: M.call(ChainAddressShape).returns(
-    Vow$(M.arrayOf(ChainAmountShape)),
+    Vow$(M.arrayOf(DenomAmountShape)),
   ),
-  withdrawRewards: M.call().returns(Vow$(M.arrayOf(ChainAmountShape))),
+  withdrawRewards: M.call().returns(Vow$(M.arrayOf(DenomAmountShape))),
   undelegate: M.call(M.arrayOf(DelegationShape)).returns(VowShape),
 });
 
@@ -130,7 +129,7 @@ export const prepareCosmosOrchestrationAccountKit = (
       withdrawRewardWatcher: M.interface('withdrawRewardWatcher', {
         onFulfilled: M.call(M.string())
           .optional(M.arrayOf(M.undefined())) // empty context
-          .returns(M.arrayOf(CoinShape)),
+          .returns(M.arrayOf(DenomAmountShape)),
       }),
       holder: IcaAccountHolderI,
       invitationMakers: M.interface('invitationMakers', {

packages/orchestration/src/exos/local-orchestration-account.js

@@ -8,7 +8,6 @@ import { VowShape } from '@agoric/vow';
 import { E } from '@endo/far';
 import {
   ChainAddressShape,
-  ChainAmountShape,
   DenomAmountShape,
   DenomShape,
   IBCTransferOptionsShape,
@@ -105,7 +104,7 @@ export const prepareLocalOrchestrationAccountKit = (
           .optional({
             destination: ChainAddressShape,
             opts: M.or(M.undefined(), IBCTransferOptionsShape),
-            amount: ChainAmountShape,
+            amount: DenomAmountShape,
           })
           .returns(Vow$(M.record())),
       }),

packages/orchestration/src/facade.js

@@ -3,7 +3,7 @@
 import { assertAllDefined } from '@agoric/internal';
 
 /**
- * @import {AsyncFlowTools, GuestInterface, HostArgs} from '@agoric/async-flow';
+ * @import {AsyncFlowTools, GuestInterface, HostArgs, HostOf} from '@agoric/async-flow';
  * @import {Zone} from '@agoric/zone';
  * @import {Vow, VowTools} from '@agoric/vow';
  * @import {TimerService} from '@agoric/time';
@@ -14,6 +14,19 @@ import { assertAllDefined } from '@agoric/internal';
  * @import {Chain, ChainInfo, CosmosChainInfo, IBCConnectionInfo, OrchestrationAccount, Orchestrator} from './types.js';
  */
 
+/**
+ * For a given guest passed to orchestrate(), return the host-side form.
+ *
+ * @template {(orc: Orchestrator, ctx: any, ...args: any[]) => Promise<any>} GF
+ * @typedef {GF extends (
+ *   orc: Orchestrator,
+ *   ctx: any,
+ *   ...args: infer GA
+ * ) => Promise<infer GR>
+ *   ? (...args: HostArgs<GA>) => Vow<GR>
+ *   : never} HostForGuest
+ */
+
 /**
  * @param {{
  *   zone: Zone;
@@ -91,15 +104,27 @@ export const makeOrchestrationFacade = ({
    *
    * NOTE multiple calls to this with the same guestFn name will fail
    *
-   * @param {{ [durableName: string]: (...args: any[]) => any }} guestFns
-   * @param {any} hostCtx
+   * @template HC - host context
+   * @template {{
+   *   [durableName: string]: (
+   *     orc: Orchestrator,
+   *     ctx: GuestInterface<HC>,
+   *     ...args: any[]
+   *   ) => Promise<any>;
+   * }} GFM
+   *   guest fn map
+   * @param {GFM} guestFns
+   * @param {HC} hostCtx
+   * @returns {{ [N in keyof GFM]: HostForGuest<GFM[N]> }}
    */
   const orchestrateAll = (guestFns, hostCtx) =>
-    Object.fromEntries(
-      Object.entries(guestFns).map(([name, guestFn]) => [
-        name,
-        orchestrate(name, hostCtx, guestFn),
-      ]),
+    /** @type {{ [N in keyof GFM]: HostForGuest<GFM[N]> }} */ (
+      Object.fromEntries(
+        Object.entries(guestFns).map(([name, guestFn]) => [
+          name,
+          orchestrate(name, hostCtx, guestFn),
+        ]),
+      )
     );
 
   return harden({

packages/orchestration/src/typeGuards.js

@@ -35,13 +35,6 @@ export const Proto3Shape = {
   value: M.string(),
 };
 
-// XXX same as ChainAmountShape and DenomAmount type
-export const CoinShape = { value: M.bigint(), denom: M.string() };
-
-export const ChainAmountShape = harden({ denom: M.string(), value: M.nat() });
-
-export const AmountArgShape = M.or(AmountShape, ChainAmountShape);
-
 // FIXME missing `delegatorAddress` from the type
 /** @type {TypedPattern<Delegation>} */
 export const DelegationShape = harden({
@@ -111,6 +104,8 @@ export const BrandInfoShape = M.any();
 /** @type {TypedPattern<DenomAmount>} */
 export const DenomAmountShape = { denom: DenomShape, value: M.bigint() };
 
+export const AmountArgShape = M.or(AmountShape, DenomAmountShape);
+
 /** @see {Chain} */
 export const ChainFacadeI = M.interface('ChainFacade', {
   getChainInfo: M.call().returns(VowShape),

packages/orchestration/src/utils/orchestrationAccount.js

@@ -2,7 +2,11 @@ import { M } from '@endo/patterns';
 import { Shape as NetworkShape } from '@agoric/network';
 import { VowShape } from '@agoric/vow';
 import { TopicsRecordShape } from '@agoric/zoe/src/contractSupport/topics.js';
-import { AmountArgShape, ChainAddressShape, CoinShape } from '../typeGuards.js';
+import {
+  AmountArgShape,
+  ChainAddressShape,
+  DenomAmountShape,
+} from '../typeGuards.js';
 
 /** @import {OrchestrationAccountI} from '../orchestration-api.js'; */
 
@@ -11,8 +15,8 @@ const { Vow$ } = NetworkShape; // TODO #9611
 /** @see {OrchestrationAccountI} */
 export const orchestrationAccountMethods = {
   getAddress: M.call().returns(ChainAddressShape),
-  getBalance: M.call(M.any()).returns(Vow$(CoinShape)),
-  getBalances: M.call().returns(Vow$(M.arrayOf(CoinShape))),
+  getBalance: M.call(M.any()).returns(Vow$(DenomAmountShape)),
+  getBalances: M.call().returns(Vow$(M.arrayOf(DenomAmountShape))),
   send: M.call(ChainAddressShape, AmountArgShape).returns(VowShape),
   transfer: M.call(AmountArgShape, ChainAddressShape)
     .optional(M.record())

packages/orchestration/src/utils/zoe-tools.js

@@ -77,3 +77,4 @@ export const makeZoeTools = (zone, { zcf, vowTools }) => {
     localTransfer,
   });
 };
+/** @typedef {ReturnType<typeof makeZoeTools>} ZoeTools */