@agoric/deploy-script-support 0.10.4-u17.0 → 0.10.4-u18.0

package/README.md

@@ -1,107 +1,100 @@
 # Deploy Script Support
 
 To install code on chain or in the a3p-integration environment, you'll have to
-generate a proposal, and write a script to build the core proposal. The
-proposals have limited access to bootstrap powers, described by their manifests.
+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.
+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 ProposalBuilder 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.
+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.
 
-`.../builders/scripts/vats/upgradeVaults.js` is a canonical example. It says the
-proposal to run is '@agoric/inter-protocol/src/proposals/upgrade-vaults.js',
-lists the manifest there as `'getManifestForUpgradeVaults'`, and directs the
-creation of a bundle from
-'@agoric/inter-protocol/src/vaultFactory/vaultFactory.js', which will be made
-available to the proposal as `vaultsRef` in options.
+Here's a simple example:
 
-`upgrade-vaults.js` defines `getManifestForUpgradeVaults()`, which returns a
-`manifest` that says `upgradeVaults()` should be executed, and specifies what
-powers it should have access to.
-
-### Proposal
-
-The proposal is called with `(powers, options)` available. The manifest
-detailing the powers that will be used 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. The usual format is
-```js
-export const foo = async (
-  {
-    consume: {
-      ...
-    },
-    brands: {
-      ...
-    }
-  },
- options,
-) => {
-  const { fooRef } = options;
-  // do the things using powers and options
-};
-
-export const getManifestForFoo = (powers, options) => {
-  manifest: {
-     [foo.name]: {
-       consume: {
-         ...
-      },
-  options,
-)};
 ```
-
-`manifest` contains descriptions of powers to be provided to the proposals.
-
-**TODO**  what happens with the `installations` in [`startPsm.js`](https://github.com/Agoric/agoric-sdk/blob/b13743a2cccf0cb63a412b54384435596d4e81ea/packages/inter-protocol/src/proposals/startPSM.js#L496)?
-
-`options` allows the proposal to be provided with arbitray other powerful
-objects.
-
-### proposalBuilder Script
-
-The script describes how to build the core proposal. For
-`agoric-3-proposals` and uploading to the chain, the script must be named in the
-`CoreProposalSteps` section in [`upgrade.go`](../../golang/cosmos/app/upgrade.go),
-and its `defaultProposalBuilder` will be invoked directly.
-
-Script files should export `defaultProposalBuilder` and a `default` function
-that invokes `writeCoreProposal` one or more times to generate sets of files
-describing the proposal.
-
-```js
-export const defaultProposalBuilder = ({ publishRef, install }) => {
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
+const game1ProposalBuilder = async ({ publishRef, install }) => {
   return harden({
-    sourceSpec: '@agoric/vats/src/proposals/foo.js',
+    sourceSpec: '@agoric/smart-wallet/test/start-game1-proposal.js',
     getManifestCall: [
-      'getManifestForFoo',
+      getManifestForGame1.name,
       {
-        fooRef: publishRef(install('@agoric/...')),
-        ...otherParams,
+        game1Ref: publishRef(
+          install(
+            '@agoric/smart-wallet/test/gameAssetContract.js',
+            '../bundles/bundle-game1.js',
+            { persist: true },
+          ),
+        ),
       },
     ],
   });
 };
-`
+
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('proposalName', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('start-game1', game1ProposalBuilder);
 };
 ```
 
-The first element of `getManifestCall` is interpreted as the name of a proposal.
-The second element of `getManifestCall` produces the `options` argument passed
-to the proposal. (`fooRef` in the example above). A common thing to want to pass
-in options is a reference to code to be installed on-chain. The `fooRef` example
-above shows how. `publishRef(install(<path>))` is built from sources in the
-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 first element of `getManifestCall` is interpreted as the name of a function
+defining a behavior. The second element of `getManifestCall` produces the
+`options` argument passed to the function (`{ game1Red }` in the example
+above). A common thing to want to pass in `options` is a reference to code to be
+installed on-chain. The example above shows how. `publishRef(install(<path>))`
+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 CoreEvalBuilder says the proposal to run is
+'@agoric/smart-wallet/test/start-game1-proposal.js'. It says the manifest can be
+produced by running `getManifestForGame1`, and directs the creation of bundles
+from `@agoric/smart-wallet/test/gameAssetContract.js` which will be made
+available to the proposal as `game1Ref` in `options`.
+
+The manifest gives permissions for accessing objects in promise space, and
+passes installations to the proposalBuilder. Notice that `game1Ref` from the
+proposalBuilder is passed to `getManifestForGame1`, which adds it to
+`installations`, with the name `game1`. The name provided for installations will
+also be used to register the installation in `agoricNames`.
+
+```
+export const getManifestForGame1 = ({ restoreRef }, { game1Ref }) => {
+  return harden({
+    manifest: gameManifest,
+    installations: {
+      game1: restoreRef(game1Ref),
+    },
+  });
+};
+```
+
+### 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,6 +1,6 @@
 {
   "name": "@agoric/deploy-script-support",
-  "version": "0.10.4-u17.0",
+  "version": "0.10.4-u18.0",
   "description": "Helpers and other support for writing deploy scripts",
   "type": "module",
   "main": "src/helpers.js",
@@ -34,25 +34,25 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/ertp": "^0.16.3-u17.0",
-    "@agoric/import-manager": "^0.3.12-u17.0",
-    "@agoric/internal": "^0.4.0-u17.0",
-    "@agoric/notifier": "^0.7.0-u17.0",
-    "@agoric/store": "^0.9.3-u17.0",
-    "@agoric/time": "^0.3.3-u17.0",
-    "@agoric/zoe": "^0.26.3-u17.0",
-    "@endo/base64": "^1.0.7",
-    "@endo/bundle-source": "^3.4.0",
-    "@endo/errors": "^1.2.5",
-    "@endo/far": "^1.1.5",
-    "@endo/marshal": "^1.5.3",
-    "@endo/nat": "^5.0.10",
-    "@endo/promise-kit": "^1.1.5",
-    "@endo/zip": "^1.0.7"
+    "@agoric/ertp": "^0.16.3-u18.0",
+    "@agoric/import-manager": "^0.3.12-u18.0",
+    "@agoric/internal": "^0.4.0-u18.0",
+    "@agoric/notifier": "^0.7.0-u18.0",
+    "@agoric/store": "^0.9.3-u18.0",
+    "@agoric/time": "^0.3.3-u18.0",
+    "@agoric/zoe": "^0.26.3-u18.0",
+    "@endo/base64": "^1.0.8",
+    "@endo/bundle-source": "^3.4.2",
+    "@endo/errors": "^1.2.7",
+    "@endo/far": "^1.1.8",
+    "@endo/marshal": "^1.6.1",
+    "@endo/nat": "^5.0.12",
+    "@endo/promise-kit": "^1.1.7",
+    "@endo/zip": "^1.0.8"
   },
   "devDependencies": {
-    "@agoric/vats": "^0.16.0-u17.0",
-    "@endo/init": "^1.1.4",
+    "@agoric/vats": "^0.16.0-u18.0",
+    "@endo/init": "^1.1.6",
     "ava": "^5.3.0",
     "import-meta-resolve": "^2.2.1"
   },
@@ -74,5 +74,5 @@
   "typeCoverage": {
     "atLeast": 82.6
   },
-  "gitHead": "515c4c0efccfc91b97da30037c10fc4b076851e2"
+  "gitHead": "c22e7250188bbdb07bc021dffdb88af0309a7aa8"
 }

package/src/cachedBundleSpec.js

@@ -6,6 +6,9 @@ import { Fail } from '@endo/errors';
  */
 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

@@ -167,6 +167,7 @@ export const makeCoreProposalBehavior = ({
       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);
         }),

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
@@ -47,3 +51,42 @@ export {};
  * @param {...any} args
  * @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>}
+ */

package/src/helpers.js

@@ -52,6 +52,10 @@ const makeLazyObject = sourceObject => {
   return /** @type {T} */ (lazyObject);
 };
 
+/**
+ * @param {Promise<import('./externalTypes.js').CommonHome | import('./externalTypes.js').AgSoloHome>} homePromise
+ * @param {import('./externalTypes.js').DeployScriptEndownments} endowments
+ */
 export const makeHelpers = async (homePromise, endowments) => {
   // Endowments provided via `agoric run` or `agoric deploy`.
   const {
@@ -84,6 +88,7 @@ export const makeHelpers = async (homePromise, endowments) => {
       return E(deps.walletAdmin).getIssuerManager();
     },
     get offerAndFind() {
+      assert('wallet' in deps.home, 'expected AgSolo home');
       return makeOfferAndFindInvitationAmount(
         deps.walletAdmin,
         deps.home.zoe,
@@ -91,6 +96,7 @@ export const makeHelpers = async (homePromise, endowments) => {
       );
     },
     get walletAdmin() {
+      assert('wallet' in deps.home, 'expected AgSolo home');
       return E(deps.home.wallet).getAdminFacet();
     },
     get zoeInvitationPurse() {
@@ -110,6 +116,7 @@ export const makeHelpers = async (homePromise, endowments) => {
       return deps.offerAndFind.findInvitationAmount;
     },
     get install() {
+      assert('wallet' in deps.home, 'expected AgSolo home');
       return makeInstall(
         bundleSource,
         deps.home.zoe,
@@ -127,6 +134,7 @@ export const makeHelpers = async (homePromise, endowments) => {
       return makeSaveIssuer(deps.walletAdmin, deps.issuerManager);
     },
     get startInstance() {
+      assert('wallet' in deps.home, 'expected AgSolo home');
       return makeStartInstance(
         deps.issuerManager,
         deps.instanceManager,

package/src/writeCoreEvalParts.js

@@ -11,7 +11,8 @@ import {
 } from './coreProposalBehavior.js';
 
 /**
- * @import {CoreEvalDescriptor} from './externalTypes.js';
+ * @import {BundleSource, BundleSourceResult} from '@endo/bundle-source';
+ * @import {AgSoloHome, CanonicalHome, CommonHome, CoreEvalBuilder, CoreEvalDescriptor, ManifestBundleRef} from './externalTypes.js';
  */
 
 /**
@@ -27,20 +28,20 @@ import {
  *   summary to `${filePrefix}-plan.json), plus whatever bundles bundles the code loads)
  * see CoreEval in {@link '/golang/cosmos/x/swingset/types/swingset.pb.go'}
  * @param {string} filePrefix name on disk
- * @param {import('./externalTypes.js').CoreEvalBuilder} builder
+ * @param {CoreEvalBuilder} builder
  * @returns {Promise<CoreEvalPlan>}
  */
 
 /**
  *
- * @param {*} homeP
+ * @param {Promise<CommonHome | AgSoloHome>} homeP
  * @param {{
- *   bundleSource: (path: string) => Promise<NodeModule>,
+ *   bundleSource: BundleSource,
  *   pathResolve: (path: string) => string,
  * }} endowments
  * @param {{
  *   getBundlerMaker: () => Promise<import('./getBundlerMaker.js').BundleMaker>,
- *   getBundleSpec: (...args: *) => Promise<import('./externalTypes.js').ManifestBundleRef>,
+ *   getBundleSpec: (bundle: Promise<BundleSourceResult<'endoZipBase64'>>, getBundle: () => import('./getBundlerMaker.js').Bundler, opts?: any) => Promise<ManifestBundleRef>,
  *   log?: typeof console.log,
  *   writeFile?: typeof fs.promises.writeFile
  * }} io
@@ -63,6 +64,7 @@ export const makeWriteCoreEval = (
   const getBundler = () => {
     if (!bundlerCache) {
       bundlerCache = E(getBundlerMaker()).makeBundler({
+        // @ts-expect-error lazily resolved for AgSoloHome
         zoe: E.get(homeP).zoe,
       });
     }
@@ -95,17 +97,16 @@ export const makeWriteCoreEval = (
     };
   };
 
-  let mutex =
-    /** @type {Promise<import('./externalTypes.js').ManifestBundleRef | undefined>} */ (
-      Promise.resolve()
-    );
+  let mutex = /** @type {Promise<ManifestBundleRef | undefined>} */ (
+    Promise.resolve()
+  );
   /** @type {WriteCoreEval} */
   const writeCoreEval = async (filePrefix, builder) => {
     /**
      *
      * @param {string} entrypoint
      * @param {string} [bundlePath]
-     * @returns {Promise<NodeModule>}
+     * @returns {Promise<BundleSourceResult<'endoZipBase64'>>}
      */
     const getBundle = async (entrypoint, bundlePath) => {
       if (!bundlePath) {
@@ -125,7 +126,7 @@ export const makeWriteCoreEval = (
      * @param {string} entrypoint
      * @param {string} [bundlePath]
      * @param {unknown} [opts]
-     * @returns {Promise<import('./externalTypes.js').ManifestBundleRef>}
+     * @returns {Promise<ManifestBundleRef>}
      */
     const install = async (entrypoint, bundlePath, opts) => {
       const bundle = getBundle(entrypoint, bundlePath);
@@ -146,7 +147,7 @@ export const makeWriteCoreEval = (
 
     // Await a reference then publish to the board.
     const cmds = [];
-    /** @param {Promise<import('./externalTypes.js').ManifestBundleRef>} refP */
+    /** @param {Promise<ManifestBundleRef>} refP */
     const publishRef = async refP => {
       const { fileName, ...ref } = await refP;
       if (fileName) {