@agoric/deploy-script-support 0.10.4-other-dev-8f8782b.0 → 0.10.4-other-dev-fbe72e7.0.fbe72e7

package/README.md

@@ -1,4 +1,122 @@
 # Deploy Script Support
 
-Import this code in your dapp deploy scripts to more easily install and
-interact with Zoe contracts.
+To install code on chain or in the a3p-integration environment, you'll have to
+write a script to build the core proposal. The proposals' access to bootstrap
+powers is limited by their manifests.
+
+There are collections of proposals in /vats/src/proposals,
+smart-wallet/src/proposals, orchestration/src/proposals, pegasus/src/proposals,
+and inter-protocol/src/proposals.
+
+The overall format is a proposalBuilder script (There are several in
+.../builders/scripts/vats/) which has a default export that passes resources to
+the proposal. The resources include bundled source code and string-value
+parameters. The script exports a CoreEvalBuilder named `defaultProposalBuilder`
+that specifies (as an import string) the proposal it uses, identifies the
+"manifest", (which associates permissions to access powers in the bootstrap
+space with functions to be called), and builds bundles of source code needed by
+the proposal.
+
+Here's a simple example:
+
+```js
+import { makeHelpers } from '@agoric/deploy-script-support';
+import { getManifestForGame1 } from '@agoric/smart-wallet/test/start-game1-proposal.js';
+
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
+const game1ProposalBuilder = async ({ publishRef, install }) => {
+  return harden({
+    sourceSpec: '@agoric/smart-wallet/test/start-game1-proposal.js',
+    getManifestCall: [
+      getManifestForGame1.name,
+      {
+        game1Ref: publishRef(
+          install(
+            '@agoric/smart-wallet/test/gameAssetContract.js',
+            '../bundles/bundle-game1.js',
+            { persist: true },
+          ),
+        ),
+      },
+    ],
+  });
+};
+
+export default async (homeP, endowments) => {
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('start-game1', game1ProposalBuilder);
+};
+```
+
+This CoreEvalBuilder returns an object whose "sourceSpec" indicates that the
+proposal to run is "@agoric/smart-wallet/test/start-game1-proposal.js" and whose
+"getManifestCall" is a [functionName, ...args] array describing an invocation of
+`getManifestForGame1` exported from that file which is expected to return an
+object including a "manifest" as described below (but the actual invocation will
+insert as the first argument a "powers" object that includes functions such as
+`restoreRef`). A common thing to want to pass in `args` is a reference to code
+to be installed on-chain, and the example above shows how.
+`publishRef(install(...))` is built from sources in agoric-sdk, and passed as a
+`bundleRef`, which contains a `bundleID` suitable for passing to Zoe (for
+contracts) or `vatAdminService` (for non-contract vat code).
+
+The manifest from such an invocation is a JSON-serializable object in which each
+key is the name of a function to itself be invoked and the corresponding value
+is a "permit" describing an attenuation of the core-eval promise space to be
+provided as its first argument. A permit is either `true` or a string (_both
+meaning no attenuation of the respective subtree of the promise space, with a
+string serving as a grouping label for convenience and/or diagram generation_),
+or an object whose keys identify child properties and whose corresponding values
+are theirselves (recursive) permits. See `BootstrapManifiest` in
+[lib-boot.js](../vats/src/core/lib-boot.js).
+
+The manifest object returned from a "getManifestCall" invocation may also
+include "installations" (they'll be registered with `agoricNames` and in the
+bootstrap promise space) and/or "options" (they'll be provided as the "options"
+property of the second argument for each call of the manifest's functions):
+
+```js
+/** @type {import('@agoric/vats/src/core/lib-boot').BootstrapManifest} */
+const gameManifest = harden({
+  [startGameContract.name]: {
+    consume: {...},
+    brand: {...},
+    issuer: {...},
+    ...
+  },
+});
+
+export const getManifestForGame1 = ({ restoreRef }, { game1Ref }) => {
+  return harden({
+    manifest: gameManifest,
+    // a reference to the game1 bundle will be published in agoricNames as "game1"
+    installations: {
+      game1: restoreRef(game1Ref),
+    },
+    // the second argument of `startGameContract` will be `{ options: ["foo"] }`
+    options: ["foo"],
+  });
+};
+```
+
+### Invoking the coreEval Behavior
+
+The proposalBuilder script's default export is responsible for calling
+`writeCoreEval()` to produce the scripts that will be evaluated by the chain.
+These define behavior functions that will be invoked based on the keys in the
+manifest and passed arguments declared in the manifest. The manifest is usually
+in the same file, and conventionally provided by a function named
+`getManifestForFoo`. The manifest needs to have a unique name, since it will be
+referenced by name from the script. 
+
+### proposalBuilder Script
+
+The script describes how to build the core proposal. Script files should export
+`defaultProposalBuilder` and a `default` function that invokes
+`writeCoreProposal` one or more times to generate sets of files describing the
+proposal.
+
+Chain-halting SoftwareUpgrades can include coreEvals, by adding them to the
+`CoreProposalSteps` section in [`upgrade.go`](../../golang/cosmos/app/upgrade.go). To execute a proposal via
+CoreEval, follow [the instructions at
+docs.agoric.com](https://docs.agoric.com/guides/coreeval/local-testnet.html).

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@agoric/deploy-script-support",
-  "version": "0.10.4-other-dev-8f8782b.0+8f8782b",
+  "version": "0.10.4-other-dev-fbe72e7.0.fbe72e7",
   "description": "Helpers and other support for writing deploy scripts",
   "type": "module",
   "main": "src/helpers.js",
   "engines": {
-    "node": ">=14.15.0"
+    "node": "^20.9 || ^22.11"
   },
   "scripts": {
     "build": "exit 0",
     "test": "ava",
     "test:xs": "exit 0",
     "lint-fix": "yarn lint:eslint --fix",
-    "lint:eslint": "eslint .",
-    "lint:types": "tsc -p jsconfig.json",
-    "lint": "run-s --continue-on-error lint:*"
+    "lint:eslint": "yarn run -T eslint .",
+    "lint:types": "yarn run -T tsc",
+    "lint": "yarn run -T run-s --continue-on-error 'lint:*'"
   },
   "repository": {
     "type": "git",
@@ -34,39 +34,46 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-other-dev-8f8782b.0+8f8782b",
-    "@agoric/ertp": "0.16.3-other-dev-8f8782b.0+8f8782b",
-    "@agoric/import-manager": "0.3.12-other-dev-8f8782b.0+8f8782b",
-    "@agoric/internal": "0.3.3-other-dev-8f8782b.0+8f8782b",
-    "@agoric/notifier": "0.6.3-other-dev-8f8782b.0+8f8782b",
-    "@agoric/store": "0.9.3-other-dev-8f8782b.0+8f8782b",
-    "@agoric/zoe": "0.26.3-other-dev-8f8782b.0+8f8782b",
-    "@endo/base64": "0.2.31",
-    "@endo/bundle-source": "2.5.2-upstream-rollup",
-    "@endo/far": "0.2.18",
-    "@endo/marshal": "0.8.5",
-    "@endo/nat": "4.1.27",
-    "@endo/promise-kit": "0.2.56",
-    "@endo/zip": "0.2.31"
+    "@agoric/ertp": "0.16.3-other-dev-fbe72e7.0.fbe72e7",
+    "@agoric/import-manager": "0.3.12-other-dev-fbe72e7.0.fbe72e7",
+    "@agoric/internal": "0.3.3-other-dev-fbe72e7.0.fbe72e7",
+    "@agoric/notifier": "0.6.3-other-dev-fbe72e7.0.fbe72e7",
+    "@agoric/pola-io": "0.1.1-other-dev-fbe72e7.0.fbe72e7",
+    "@agoric/store": "0.9.3-other-dev-fbe72e7.0.fbe72e7",
+    "@agoric/time": "0.3.3-other-dev-fbe72e7.0.fbe72e7",
+    "@agoric/zoe": "0.26.3-other-dev-fbe72e7.0.fbe72e7",
+    "@endo/base64": "^1.0.12",
+    "@endo/bundle-source": "^4.1.2",
+    "@endo/errors": "^1.2.13",
+    "@endo/far": "^1.1.14",
+    "@endo/marshal": "^1.8.0",
+    "@endo/nat": "^5.1.3",
+    "@endo/promise-kit": "^1.1.13",
+    "@endo/zip": "^1.0.11"
   },
   "devDependencies": {
-    "@agoric/vats": "0.15.2-other-dev-8f8782b.0+8f8782b",
-    "@endo/init": "0.5.56",
-    "ava": "^5.2.0",
-    "import-meta-resolve": "^2.2.1"
+    "@agoric/vats": "0.15.2-other-dev-fbe72e7.0.fbe72e7",
+    "@endo/init": "^1.1.12",
+    "ava": "^5.3.0",
+    "import-meta-resolve": "^4.1.0"
   },
   "files": [
     "src",
-    "NEWS.md",
-    "exported.js"
+    "NEWS.md"
   ],
   "ava": {
     "files": [
-      "test/**/test-*.js"
+      "test/**/*.test.*"
+    ],
+    "require": [
+      "@endo/init/debug.js"
     ]
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8f8782bc52393e9d4fc82523ecf31cab429b11b3"
+  "typeCoverage": {
+    "atLeast": 83.26
+  },
+  "gitHead": "fbe72e72107f9997f788674e668c660d92ec4492"
 }

package/src/assertOfferResult.js

@@ -1,7 +1,11 @@
 // @ts-check
-import { Fail } from '@agoric/assert';
+import { Fail } from '@endo/errors';
 import { E } from '@endo/far';
 
+/**
+ * @import {InvitationDetails, PaymentPKeywordRecord, Proposal, UserSeat} from '@agoric/zoe';
+ */
+
 /**
  * @param {ERef<UserSeat>} seat
  * @param {string} expectedOfferResult

package/src/cachedBundleSpec.js

@@ -1,4 +1,4 @@
-const { Fail } = assert;
+import { Fail } from '@endo/errors';
 
 /**
  * @param {string} cacheDir
@@ -6,6 +6,9 @@ const { Fail } = assert;
  */
 export const makeCacheAndGetBundleSpec =
   (cacheDir, { now, fs, pathResolve }) =>
+  /**
+   * @param {Promise<import('@endo/bundle-source').BundleSourceResult<'endoZipBase64'>>} bundleP
+   */
   async bundleP => {
     const bundle = await bundleP;
     const { endoZipBase64Sha512: hash } = bundle;

package/src/coreProposalBehavior.js

@@ -1,6 +1,10 @@
 // @ts-check
 const t = 'makeCoreProposalBehavior';
 
+/**
+ * @import {Installation} from '@agoric/zoe/src/zoeService/utils.js';
+ */
+
 /**
  * TODO import these from @agoric/vats when the types are better managed
  *
@@ -8,7 +12,20 @@ const t = 'makeCoreProposalBehavior';
  * @typedef {*} BootstrapPowers
  */
 
-// These permits apply to `allPowers` in `behavior` below.
+/**
+ * @import {ManifestBundleRef} from './externalTypes.js'
+ * @typedef {[methodName: string, ...args: unknown[]]} FlatMethargs
+ * @typedef {Record<string, Record<string, unknown>>} Manifest
+ */
+
+/**
+ * These permits are expected to be the minimum powers required by the
+ * `coreProposalBehavior` function returned from `makeCoreProposalBehavior`.
+ * They are merged with all of the manifest getter's permits to produce the
+ * total permits needed by the resulting core proposal (such as might be---and
+ * generally are---written into a *-permit.json file).
+ * @see {@link ./writeCoreEvalParts.js}
+ */
 export const permits = {
   consume: { agoricNamesAdmin: t, vatAdminSvc: t, zoe: t },
   evaluateBundleCap: t,
@@ -23,43 +40,74 @@ export const permits = {
  * for catching bugs.  Thus, this maker must not reference any other modules or
  * definitions.
  *
- * @param {object} opts
- * @param {{ bundleName: string } | { bundleID: string }} opts.manifestBundleRef
- * @param {[string, ...unknown[]]} opts.getManifestCall
- * @param {Record<string, Record<string, unknown>>} [opts.overrideManifest]
- * @param {typeof import('@endo/far').E} opts.E
- * @param {(...args: unknown[]) => void} [opts.log]
- * @param {(ref: unknown) => Promise<unknown>} [opts.restoreRef]
+ * @param {object} inputs
+ * @param {ManifestBundleRef} inputs.manifestBundleRef
+ * @param {FlatMethargs} inputs.getManifestCall
+ * @param {Manifest} [inputs.customManifest]
+ * @param {typeof import('@endo/far').E} inputs.E
+ * @param {(...args: unknown[]) => void} [inputs.log]
+ * @param {(ref: import('./externalTypes.js').ManifestBundleRef) => Promise<import('@agoric/zoe/src/zoeService/utils.js').Installation<unknown>>} [inputs.customRestoreRef]
  * @returns {(vatPowers: unknown) => Promise<unknown>}
  */
 export const makeCoreProposalBehavior = ({
   manifestBundleRef,
-  getManifestCall,
-  overrideManifest,
+  getManifestCall: [manifestGetterName, ...manifestGetterArgs],
+  customManifest,
   E,
   log = console.info,
-  restoreRef: overrideRestoreRef,
+  customRestoreRef,
 }) => {
   const { entries, fromEntries } = Object;
 
-  // deeplyFulfilled is a bit overkill for what we need.
+  /**
+   * Given an object whose properties may be promise-valued, return a promise
+   * for an analogous object in which each such value has been replaced with its
+   * fulfillment.
+   * This is a non-recursive form of endo `deeplyFulfilled`.
+   *
+   * @template T
+   * @param {{[K in keyof T]: (T[K] | Promise<T[K]>)}} obj
+   * @returns {Promise<T>}
+   */
   const shallowlyFulfilled = async obj => {
     if (!obj) {
       return obj;
     }
-    const ents = await Promise.all(
+    const awaitedEntries = await Promise.all(
       entries(obj).map(async ([key, valueP]) => {
         const value = await valueP;
         return [key, value];
       }),
     );
-    return fromEntries(ents);
+    return fromEntries(awaitedEntries);
+  };
+
+  const makeRestoreRef = (vatAdminSvc, zoe) => {
+    /** @type {(ref: import('./externalTypes.js').ManifestBundleRef) => Promise<Installation<unknown>>} */
+    const defaultRestoreRef = async bundleRef => {
+      // extract-proposal.js creates these records, and bundleName is
+      // the optional name under which the bundle was installed into
+      // config.bundles
+      const bundleIdP =
+        'bundleName' in bundleRef
+          ? E(vatAdminSvc).getBundleIDByName(bundleRef.bundleName)
+          : bundleRef.bundleID;
+      const bundleID = await bundleIdP;
+      const label = bundleID.slice(0, 8);
+      return E(zoe).installBundleID(bundleID, label);
+    };
+    return defaultRestoreRef;
   };
 
-  /** @param {ChainBootstrapSpace & BootstrapPowers & { evaluateBundleCap: any }} allPowers */
-  const behavior = async allPowers => {
-    // NOTE: If updating any of these names extracted from `allPowers`, you must
-    // change `permits` above to reflect their accessibility.
+  /** @param {ChainBootstrapSpace & BootstrapPowers & { evaluateBundleCap: any }} powers */
+  const coreProposalBehavior = async powers => {
+    // NOTE: `powers` is expected to match or be a superset of the above `permits` export,
+    // which should therefore be kept in sync with this deconstruction code.
+    // HOWEVER, do note that this function is invoked with at least the *union* of powers
+    // required by individual moduleBehaviors declared by the manifest getter, which is
+    // necessary so it can use `runModuleBehaviors` to provide the appropriate subset to
+    // each one (see ./writeCoreEvalParts.js).
+    // Handle `powers` with the requisite care.
     const {
       consume: { vatAdminSvc, zoe, agoricNamesAdmin },
       evaluateBundleCap,
@@ -67,70 +115,71 @@ export const makeCoreProposalBehavior = ({
       modules: {
         utils: { runModuleBehaviors },
       },
-    } = allPowers;
-    const [exportedGetManifest, ...manifestArgs] = getManifestCall;
-
-    const defaultRestoreRef = async ref => {
-      // extract-proposal.js creates these records, and bundleName is
-      // the name under which the bundle was installed into
-      // config.bundles
-      const p = ref.bundleName
-        ? E(vatAdminSvc).getBundleIDByName(ref.bundleName)
-        : ref.bundleID;
-      const bundleID = await p;
-      const label = bundleID.slice(0, 8);
-      return E(zoe).installBundleID(bundleID, label);
-    };
-    const restoreRef = overrideRestoreRef || defaultRestoreRef;
+    } = powers;
 
     // Get the on-chain installation containing the manifest and behaviors.
-    console.info('evaluateBundleCap', {
+    log('evaluateBundleCap', {
       manifestBundleRef,
-      exportedGetManifest,
+      manifestGetterName,
       vatAdminSvc,
     });
     let bcapP;
     if ('bundleName' in manifestBundleRef) {
       bcapP = E(vatAdminSvc).getNamedBundleCap(manifestBundleRef.bundleName);
-    } else {
+    } else if ('bundleID' in manifestBundleRef) {
       bcapP = E(vatAdminSvc).getBundleCap(manifestBundleRef.bundleID);
+    } else {
+      const keys = Reflect.ownKeys(manifestBundleRef).map(key =>
+        typeof key === 'string' ? JSON.stringify(key) : String(key),
+      );
+      const keysStr = `[${keys.join(', ')}]`;
+      throw Error(
+        `bundleRef must have own bundleName or bundleID, missing in ${keysStr}`,
+      );
     }
     const bundleCap = await bcapP;
 
-    const manifestNS = await evaluateBundleCap(bundleCap);
+    const proposalNS = await evaluateBundleCap(bundleCap);
 
-    console.error('execute', {
-      exportedGetManifest,
-      behaviors: Object.keys(manifestNS),
+    // Get the manifest and its metadata.
+    log('execute', {
+      manifestGetterName,
+      bundleExports: Object.keys(proposalNS),
     });
+    const restoreRef = customRestoreRef || makeRestoreRef(vatAdminSvc, zoe);
     const {
       manifest,
       options: rawOptions,
       installations: rawInstallations,
-    } = await manifestNS[exportedGetManifest](
+    } = await proposalNS[manifestGetterName](
       harden({ restoreRef }),
-      ...manifestArgs,
+      ...manifestGetterArgs,
     );
 
-    // Await references in the options or installations.
+    // Await promises in the returned options and installations records.
     const [options, installations] = await Promise.all(
       [rawOptions, rawInstallations].map(shallowlyFulfilled),
     );
 
-    // Publish the installations for behavior dependencies.
-    const installAdmin = E(agoricNamesAdmin).lookupAdmin('installation');
-    await Promise.all(
-      entries(installations || {}).map(([key, value]) => {
-        produceInstallations[key].resolve(value);
-        return E(installAdmin).update(key, value);
-      }),
-    );
+    // Publish the installations for our dependencies.
+    const installationEntries = entries(installations || {});
+    if (installationEntries.length > 0) {
+      const installAdmin = E(agoricNamesAdmin).lookupAdmin('installation');
+      await Promise.all(
+        installationEntries.map(([key, value]) => {
+          produceInstallations[key].reset();
+          produceInstallations[key].resolve(value);
+          return E(installAdmin).update(key, value);
+        }),
+      );
+    }
 
-    // Evaluate the manifest for our behaviors.
+    // Evaluate the manifest.
     return runModuleBehaviors({
-      allPowers,
-      behaviors: manifestNS,
-      manifest: overrideManifest || manifest,
+      // Remember that `powers` may be arbitrarily broad.
+      allPowers: powers,
+      behaviors: proposalNS,
+      manifest: customManifest || manifest,
       makeConfig: (name, _permit) => {
         log('coreProposal:', name);
         return { options };
@@ -138,22 +187,31 @@ export const makeCoreProposalBehavior = ({
     });
   };
 
-  // Make the behavior the completion value.
-  return behavior;
+  return coreProposalBehavior;
 };
 
-export const makeEnactCoreProposalsFromBundleRef =
-  ({ makeCoreProposalArgs, E }) =>
-  async allPowers => {
+/**
+ * @param {object} inputs
+ * @param {Array<{ ref: ManifestBundleRef, call: FlatMethargs, customManifest?: Manifest }>} inputs.metadataRecords
+ * @param {typeof import('@endo/far').E} inputs.E
+ */
+export const makeEnactCoreProposalsFromBundleRef = ({ metadataRecords, E }) => {
+  /**
+   * @param {ChainBootstrapSpace & BootstrapPowers & { evaluateBundleCap: any }} powers
+   * @returns {Promise<void>}
+   */
+  const enactCoreProposals = async powers => {
     await Promise.all(
-      makeCoreProposalArgs.map(async ({ ref, call, overrideManifest }) => {
-        const subBehavior = makeCoreProposalBehavior({
+      metadataRecords.map(async ({ ref, call, customManifest }) => {
+        const coreProposalBehavior = makeCoreProposalBehavior({
           manifestBundleRef: ref,
           getManifestCall: call,
-          overrideManifest,
+          customManifest,
           E,
         });
-        return subBehavior(allPowers);
+        return coreProposalBehavior(powers);
       }),
     );
   };
+  return enactCoreProposals;
+};

package/src/depositInvitation.js

@@ -1,6 +1,11 @@
 // @ts-check
 import { E } from '@endo/far';
 
+/**
+ * @import {Amount, Brand, Issuer, Payment, Purse} from '@agoric/ertp';
+ * @import {InvitationDetails} from '@agoric/zoe';
+ */
+
 /**
  * @param {ERef<Purse>} zoeInvitationPurse
  */

package/src/endo-pieces-contract.js

@@ -1,10 +1,9 @@
 // @ts-check
+import { Fail, q } from '@endo/errors';
 import { E, Far } from '@endo/far';
 import { encodeBase64, decodeBase64 } from '@endo/base64';
 import { ZipWriter } from '@endo/zip';
 
-const { Fail, quote: q } = assert;
-
 export const start = () => {
   /** @type { Map<string, [string, Uint8Array]>} */
   const hashToEntry = new Map();
@@ -18,6 +17,9 @@ export const start = () => {
     });
   };
 
+  /**
+   * @param {{ zoe: ERef<ZoeService> }} opts
+   */
   const makeBundler = ({ zoe }) => {
     /** @type { Map<string, [string, Uint8Array]>} */
     const nameToContent = new Map();

package/src/externalTypes.js

@@ -1,6 +1,10 @@
 // @ts-check
 export {};
 
+/**
+ * @import {NameHub} from '@agoric/vats';
+ */
+
 // TODO move this type somewhere better
 /**
  * @typedef {string | string[]} Petname A petname can either be a plain string
@@ -10,37 +14,79 @@ export {};
  */
 
 /**
- * @typedef ProposalResult
- * @property {string} sourceSpec
- * @property {[exportedGetManifest: string, ...manifestArgs: any[]]} getManifestCall
+ * @typedef {{fileName?: string} & ({ bundleName: string } | { bundleID: string}) } ManifestBundleRef
  */
 
 /**
- * @typedef BundleHandle
- * @property {string} [bundleName]
+ * @callback PublishBundleRef
+ * @param {ERef<ManifestBundleRef>} bundle
+ * @returns {Promise<ManifestBundleRef>}
  */
 
 /**
- * @callback PublishBundleRef
- * @param {ERef<BundleHandle>} bundle
- * @returns {Promise<BundleHandle>}
+ * @callback InstallEntrypoint
+ * @param {string} srcSpec
+ * @param {string} [bundlePath]
+ * @param {unknown} [opts]
+ * @returns {Promise<ManifestBundleRef>}
  */
 
 /**
- * @callback InstallBundle
- * @param {string} srcSpec
- * @param {string} bundlePath
- * @param {any} [opts]
- * @returns {BundleHandle}
+ * @typedef CoreEvalDescriptor
+ * @property {string} sourceSpec import specifier for a module
+ * @property {[manifestGetterName: string, ...manifestGetterArgs: any[]]} getManifestCall
+ *   the name of a function exported by the module and arguments to invoke it
+ *   with in order to get a manifest (a Record that associates functions to be
+ *   invoked and permits defining bootstrap-space powers they will have access
+ *   to, see {@link ../README.md} and {@link runModuleBehaviors})
  */
 
 /**
- * @callback ProposalBuilder
+ * @callback CoreEvalBuilder
  * @param {{
  *   publishRef: PublishBundleRef,
- *   install: InstallBundle,
- *   wrapInstall?: <T>(f: T) => T }
+ *   install: InstallEntrypoint,
+ *   wrapInstall?: <T extends InstallEntrypoint>(f: T) => T }
  * } powers
  * @param {...any} args
- * @returns {Promise<ProposalResult>}
+ * @returns {Promise<CoreEvalDescriptor>}
+ */
+
+/**
+ * @typedef {{
+ *  bundleSource: typeof import('@endo/bundle-source').default,
+ *  cacheDir: string,
+ *  lookup: (...path: string[]) => unknown,
+ *  now: () => number,
+ *  pathResolve: (...path: string[]) => string,
+ *  publishBundle: PublishBundleRef,
+ *  scriptArgs?: string[],
+ * }} DeployScriptEndownments
+ */
+
+/**
+ * @typedef {{
+ *   scratch: ERef<import('@agoric/internal/src/scratch.js').ScratchPad>,
+ * }} CommonHome
+ */
+
+// TODO wallet as import('@agoric/wallet-backend/src/types').WalletAdmin once it's a module
+/**
+ * @typedef {CommonHome & {
+ * agoricNames: ERef<NameHub>,
+ * bank: ERef<import("@agoric/vats/src/vat-bank.js").Bank>,
+ * board: ERef<import("@agoric/vats").Board>,
+ * faucet: unknown,
+ * myAddressNameAdmin: ERef<import("@agoric/vats").NameAdmin>,
+ * namesByAddress: ERef<NameHub>,
+ * wallet: any,
+ * zoe: ERef<ZoeService>,
+ * }} AgSoloHome
+ */
+
+/**
+ * @callback DeployScriptFunction
+ * @param {Promise<CommonHome>} homeP
+ * @param {DeployScriptEndownments} endowments
+ * @returns {Promise<void>}
  */