explicit heapVowTools (#9548)

refs: #9449

## Description

It was a surprise to me that the `when` from `@agoric/vow/vat.js` was heap-only. It makes sense when thinking about it, but nothing about the import triggered that thinking.

This exports `heapVowTools` to make that explicit. The consumer destructures from it what they need.

### Security Considerations
none
### Scaling Considerations
none

### Documentation Considerations
none

### Testing Considerations
CI

### Upgrade Considerations
not yet deployed, TMK

packages/boot/test/bootstrapTests/ibcClientMock.js

@@ -1,7 +1,7 @@
 /** @file Mock IBC Server */
 // @ts-check
 import { Far } from '@endo/far';
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 
 /**
  * @import {Connection, PortAllocator} from '@agoric/network';

packages/boot/test/bootstrapTests/ibcServerMock.js

@@ -2,7 +2,7 @@
 // @ts-check
 import { Far } from '@endo/far';
 import { makePromiseKit } from '@endo/promise-kit';
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 
 const { quote: q, Fail } = assert;
 const { log } = console;

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

@@ -1,8 +1,7 @@
 import { withdrawFromSeat } from '@agoric/zoe/src/contractSupport/zoeHelpers.js';
 import { InvitationShape } from '@agoric/zoe/src/typeGuards.js';
-import { E } from '@endo/far';
 import { M, mustMatch } from '@endo/patterns';
-import { V } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { AmountShape } from '@agoric/ertp';
 import { CosmosChainInfoShape } from '../typeGuards.js';
 import { provideOrchestration } from '../utils/start-helper.js';
@@ -17,6 +16,7 @@ const { Fail } = assert;
  * @import {LocalChain} from '@agoric/vats/src/localchain.js';
  * @import {OrchestrationService} from '../service.js';
  * @import {NameHub} from '@agoric/vats';
+ * @import {VBankAssetDetail} from '@agoric/vats/tools/board-utils.js';
  * @import {Remote} from '@agoric/vow';
  */
 
@@ -57,10 +57,15 @@ export const start = async (zcf, privateArgs, baggage) => {
 
   const findBrandInVBank = async brand => {
     const assets = await E(
-      E(privateArgs.agoricNames).lookup('vbankAsset'),
+      // XXX heapVowE
+      /** @type {Promise<Promise<NameHub<VBankAssetDetail>>>} */ (
+        E(privateArgs.agoricNames).lookup('vbankAsset')
+      ),
     ).values();
     const it = assets.find(a => a.brand === brand);
-    it || Fail`brand ${brand} not in agoricNames.vbankAsset`;
+    if (!it) {
+      throw Fail`brand ${brand} not in agoricNames.vbankAsset`;
+    }
     return it;
   };
 
@@ -84,12 +89,12 @@ export const start = async (zcf, privateArgs, baggage) => {
       if (!contractAccount) {
         const agoricChain = await orch.getChain('agoric');
         // XXX when() until membrane
-        contractAccount = await V.when(agoricChain.makeAccount());
+        contractAccount = await E.when(agoricChain.makeAccount());
         console.log('contractAccount', contractAccount);
       }
 
       // XXX when() until membrane
-      const info = await V.when(chain.getChainInfo());
+      const info = await E.when(chain.getChainInfo());
       console.log('info', info);
       const { chainId } = info;
       assert(typeof chainId === 'string', 'bad chainId');
@@ -141,7 +146,7 @@ export const start = async (zcf, privateArgs, baggage) => {
         const chainKey = `${chainInfo.chainId}-${(nonce += 1n)}`;
         // when() because chainHub methods return vows. If this were inside
         // orchestrate() the membrane would wrap/unwrap automatically.
-        const agoricChainInfo = await V.when(chainHub.getChainInfo('agoric'));
+        const agoricChainInfo = await E.when(chainHub.getChainInfo('agoric'));
         chainHub.registerChain(chainKey, chainInfo);
         chainHub.registerConnection(
           agoricChainInfo.chainId,

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

@@ -6,8 +6,7 @@ import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport/record
 import { withdrawFromSeat } from '@agoric/zoe/src/contractSupport/zoeHelpers.js';
 import { InvitationShape } from '@agoric/zoe/src/typeGuards.js';
 import { makeDurableZone } from '@agoric/zone/durable.js';
-import { prepareVowTools, V } from '@agoric/vow/vat.js';
-import { E } from '@endo/far';
+import { prepareVowTools, heapVowE as E } from '@agoric/vow/vat.js';
 import { deeplyFulfilled } from '@endo/marshal';
 import { M } from '@endo/patterns';
 import { prepareLocalOrchestrationAccountKit } from '../exos/local-orchestration-account.js';
@@ -58,8 +57,8 @@ export const start = async (zcf, privateArgs, baggage) => {
   const bldAmountShape = await E(BLD).getAmountShape();
 
   async function makeLocalAccountKit() {
-    const account = await V(privateArgs.localchain).makeAccount();
-    const address = await V(account).getAddress();
+    const account = await E(privateArgs.localchain).makeAccount();
+    const address = await E(account).getAddress();
     // FIXME 'address' is implied by 'account'; use an async maker that get the value itself
     return makeLocalOrchestrationAccountKit({
       account,
@@ -92,7 +91,7 @@ export const start = async (zcf, privateArgs, baggage) => {
             const { In } = await deeplyFulfilled(
               withdrawFromSeat(zcf, seat, give),
             );
-            await V(holder).deposit(In);
+            await E(holder).deposit(In);
             seat.exit();
             return harden({
               publicSubscribers: holder.getPublicTopics(),

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

@@ -2,7 +2,7 @@
 
 import { makeTracer, StorageNodeShape } from '@agoric/internal';
 import { TimerServiceShape } from '@agoric/time';
-import { V as E, prepareVowTools } from '@agoric/vow/vat.js';
+import { heapVowE as E, prepareVowTools } from '@agoric/vow/vat.js';
 import {
   prepareRecorderKitMakers,
   provideAll,

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

@@ -4,7 +4,7 @@ import { withdrawFromSeat } from '@agoric/zoe/src/contractSupport/zoeHelpers.js'
 import { Far } from '@endo/far';
 import { deeplyFulfilled } from '@endo/marshal';
 import { M, objectMap } from '@endo/patterns';
-import { when } from '@agoric/vow/vat.js';
+import { heapVowTools } from '@agoric/vow/vat.js';
 import { orcUtils } from '../utils/orc.js';
 import { provideOrchestration } from '../utils/start-helper.js';
 
@@ -97,9 +97,9 @@ export const start = async (zcf, privateArgs, baggage) => {
 
       const [omniAccount, localAccount] = await Promise.all([
         // XXX when() until membrane
-        when(omni.makeAccount()),
+        heapVowTools.when(omni.makeAccount()),
         // XXX when() until membrane
-        when(agoric.makeAccount()),
+        heapVowTools.when(agoric.makeAccount()),
       ]);
 
       const omniAddress = omniAccount.getAddress();

packages/orchestration/src/exos/chain-hub.js

@@ -1,10 +1,13 @@
 import { VowShape } from '@agoric/vow';
-import { allVows, watch } from '@agoric/vow/vat.js';
+import { heapVowTools } from '@agoric/vow/vat.js';
 import { makeHeapZone } from '@agoric/zone';
 import { E } from '@endo/far';
 import { M } from '@endo/patterns';
 import { CosmosChainInfoShape, IBCConnectionInfoShape } from '../typeGuards.js';
 
+// FIXME test thoroughly whether heap suffices for ChainHub
+const { allVows, watch } = heapVowTools;
+
 const { Fail } = assert;
 
 /**

packages/orchestration/src/exos/local-chain-facade.js

@@ -1,5 +1,5 @@
 /** @file ChainAccount exo */
-import { V, watch } from '@agoric/vow/vat.js';
+import { heapVowE as E, heapVowTools } from '@agoric/vow/vat.js';
 
 import { ChainFacadeI } from '../typeGuards.js';
 
@@ -45,17 +45,17 @@ export const prepareLocalChainFacade = (
     },
     {
       getChainInfo() {
-        return watch(this.state.localChainInfo);
+        return heapVowTools.watch(this.state.localChainInfo);
       },
 
       // FIXME parameterize on the remoteChainInfo to make()
       // That used to work but got lost in the migration to Exo
       /** @returns {Vow<OrchestrationAccount<ChainInfo>>} */
       makeAccount() {
         const { localChainInfo } = this.state;
-        const lcaP = V(localchain).makeAccount();
+        const lcaP = E(localchain).makeAccount();
         // FIXME use watch() from vowTools
-        return watch(allVows([lcaP, V(lcaP).getAddress()]), {
+        return heapVowTools.watch(allVows([lcaP, E(lcaP).getAddress()]), {
           onFulfilled: ([lca, address]) => {
             const { holder: account } = makeLocalOrchestrationAccountKit({
               account: lca,

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

@@ -4,10 +4,9 @@ import { AmountShape, PaymentShape } from '@agoric/ertp';
 import { makeTracer } from '@agoric/internal';
 import { M } from '@agoric/vat-data';
 import { VowShape } from '@agoric/vow';
-import { V } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { TopicsRecordShape } from '@agoric/zoe/src/contractSupport/index.js';
 import { InvitationShape } from '@agoric/zoe/src/typeGuards.js';
-import { E } from '@endo/far';
 import {
   ChainAddressShape,
   ChainAmountShape,
@@ -285,7 +284,7 @@ export const prepareLocalOrchestrationAccountKit = (
               ? [/** @type {any} */ (null), denomArg]
               : [denomArg, 'FIXME'];
 
-          const natAmount = await V.when(
+          const natAmount = await E.when(
             E(this.state.account).getBalance(brand),
           );
           return harden({ denom, value: natAmount.value });
@@ -338,14 +337,14 @@ export const prepareLocalOrchestrationAccountKit = (
             denom: 'ubld',
           };
           const { account: lca } = this.state;
+          /** @type {any} XXX heapVowE */
           const results = E(lca).executeTx([
             typedJson('/cosmos.staking.v1beta1.MsgUndelegate', {
               amount,
               validatorAddress,
               delegatorAddress: this.state.address.address,
             }),
           ]);
-          // @ts-expect-error  Type 'JsonSafe<MsgUndelegateResponse & { '@type': "/cosmos.staking.v1beta1.MsgUndelegateResponse"; }>' is not assignable to type 'MsgUndelegateResponse'.
           return when(watch(results, this.facets.undelegateWatcher));
         },
         /**

packages/orchestration/src/exos/remote-chain-facade.js

@@ -1,6 +1,6 @@
 /** @file ChainAccount exo */
 import { makeTracer } from '@agoric/internal';
-import { V, watch } from '@agoric/vow/vat.js';
+import { heapVowE as E, heapVowTools } from '@agoric/vow/vat.js';
 
 import { ChainFacadeI } from '../typeGuards.js';
 
@@ -55,7 +55,7 @@ export const prepareRemoteChainFacade = (
     },
     {
       getChainInfo() {
-        return watch(this.state.remoteChainInfo);
+        return heapVowTools.watch(this.state.remoteChainInfo);
       },
 
       // FIXME parameterize on the remoteChainInfo to make()
@@ -69,14 +69,14 @@ export const prepareRemoteChainFacade = (
           throw Fail`chain info lacks staking denom`;
         }
 
-        const icaP = V(orchestration).makeAccount(
+        const icaP = E(orchestration).makeAccount(
           remoteChainInfo.chainId,
           connectionInfo.id,
           connectionInfo.counterparty.connection_id,
         );
 
         // FIXME use watch() from vowTools
-        return watch(allVows([icaP, V(icaP).getAddress()]), {
+        return heapVowTools.watch(allVows([icaP, E(icaP).getAddress()]), {
           onFulfilled: ([account, address]) => {
             return makeCosmosOrchestrationAccount(address, stakingDenom, {
               account,

packages/orchestration/src/proposals/start-stakeAtom.js

@@ -1,7 +1,6 @@
 import { makeTracer } from '@agoric/internal';
 import { makeStorageNodeChild } from '@agoric/internal/src/lib-chainStorage.js';
-import { E } from '@endo/far';
-import { V } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { makeChainHub } from '../exos/chain-hub.js';
 
 /**
@@ -47,7 +46,7 @@ export const startStakeAtom = async ({
 
   const chainHub = makeChainHub(await agoricNames);
 
-  const [_, cosmoshub, connectionInfo] = await V.when(
+  const [_, cosmoshub, connectionInfo] = await E.when(
     chainHub.getChainsAndConnection('agoric', 'cosmoshub'),
   );
 

packages/orchestration/src/proposals/start-stakeOsmo.js

@@ -1,7 +1,6 @@
 import { makeTracer } from '@agoric/internal';
 import { makeStorageNodeChild } from '@agoric/internal/src/lib-chainStorage.js';
-import { V } from '@agoric/vow/vat.js';
-import { E } from '@endo/far';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { makeChainHub } from '../exos/chain-hub.js';
 
 /**
@@ -48,7 +47,7 @@ export const startStakeOsmo = async ({
 
   const chainHub = makeChainHub(await agoricNames);
 
-  const [_, osmosis, connectionInfo] = await V.when(
+  const [_, osmosis, connectionInfo] = await E.when(
     chainHub.getChainsAndConnection('agoric', 'osmosis'),
   );
 

packages/orchestration/test/examples/stake-bld.contract.test.ts

@@ -2,9 +2,8 @@ import { test } from '@agoric/zoe/tools/prepare-test-env-ava.js';
 
 import { AmountMath } from '@agoric/ertp';
 import { eventLoopIteration } from '@agoric/internal/src/testing-utils.js';
-import { V } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { setUpZoeForTest } from '@agoric/zoe/tools/setup-zoe.js';
-import { E } from '@endo/far';
 import path from 'path';
 import { commonSetup } from '../supports.js';
 
@@ -54,7 +53,7 @@ test('makeAccount, deposit, withdraw', async t => {
   t.truthy(account, 'account is returned');
 
   t.log('deposit 100 bld to account');
-  const depositResp = await V(account).deposit(
+  const depositResp = await E(account).deposit(
     await utils.pourPayment(bld.units(100)),
   );
   // FIXME #9211
@@ -63,7 +62,7 @@ test('makeAccount, deposit, withdraw', async t => {
   await eventLoopIteration();
 
   t.log('withdraw bld from account');
-  const withdrawResp = await V(account).withdraw(bld.units(100));
+  const withdrawResp = await E(account).withdraw(bld.units(100));
   const withdrawAmt = await bld.issuer.getAmountOf(withdrawResp);
   t.true(AmountMath.isEqual(withdrawAmt, bld.units(100)), 'withdraw');
 

packages/orchestration/test/exos/chain-hub.test.ts

@@ -2,7 +2,7 @@
 import test from '@endo/ses-ava/prepare-endo.js';
 
 import { makeNameHubKit } from '@agoric/vats';
-import { V } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { makeChainHub } from '../../src/exos/chain-hub.js';
 
 const connection = {
@@ -38,11 +38,11 @@ test('getConnectionInfo', async t => {
 
   // Look up by string or info object
   t.deepEqual(
-    await V.when(chainHub.getConnectionInfo(aChain.chainId, bChain.chainId)),
+    await E.when(chainHub.getConnectionInfo(aChain.chainId, bChain.chainId)),
     connection,
   );
   t.deepEqual(
-    await V.when(chainHub.getConnectionInfo(aChain, bChain)),
+    await E.when(chainHub.getConnectionInfo(aChain, bChain)),
     connection,
   );
 });

packages/orchestration/test/exos/local-orchestration-account-kit.test.ts

@@ -2,7 +2,7 @@ import { test } from '@agoric/zoe/tools/prepare-test-env-ava.js';
 
 import { AmountMath } from '@agoric/ertp';
 import { eventLoopIteration } from '@agoric/internal/src/testing-utils.js';
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { prepareRecorderKitMakers } from '@agoric/zoe/src/contractSupport/recorder.js';
 import { Far } from '@endo/far';
 import { prepareLocalOrchestrationAccountKit } from '../../src/exos/local-orchestration-account.js';

packages/orchestration/test/facade.test.ts

@@ -1,6 +1,6 @@
 import { test as anyTest } from '@agoric/zoe/tools/prepare-test-env-ava.js';
 
-import { V } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { setupZCFTest } from '@agoric/zoe/test/unitTests/zcf/setupZcfTest.js';
 import type { CosmosChainInfo, IBCConnectionInfo } from '../src/cosmos-api.js';
 import type { Chain } from '../src/orchestration-api.js';
@@ -74,7 +74,7 @@ test('chain info', async t => {
   });
 
   const result = (await handle()) as Chain<any>;
-  t.deepEqual(await V.when(result.getChainInfo()), mockChainInfo);
+  t.deepEqual(await E.when(result.getChainInfo()), mockChainInfo);
 });
 
 test.todo('contract upgrade');

packages/vats/src/proposals/localchain-test.js

@@ -1,5 +1,5 @@
 // @ts-check
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { typedJson } from '@agoric/cosmic-proto/vatsafe';
 
 /**

packages/vats/src/proposals/network-proposal.js

@@ -9,7 +9,9 @@ import { makeScalarBigMapStore } from '@agoric/vat-data';
 
 // Heap-based vow resolution is used for this module because the
 // bootstrap vat can't yet be upgraded.
-import { when } from '@agoric/vow/vat.js';
+import { heapVowTools } from '@agoric/vow/vat.js';
+
+const { when } = heapVowTools;
 
 /**
  * @import {ProtocolHandler} from '@agoric/network';

packages/vats/src/repl.js

@@ -2,7 +2,7 @@
 
 import { isPromise } from '@endo/promise-kit';
 import { Far } from '@endo/far';
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import * as vowExports from '@agoric/vow/vat.js';
 import * as farExports from '@endo/far';