@agoric/deploy-script-support 0.10.4-20230923T000433-dev-63b1fb6.0 → 0.10.4-calypso-dev-84eb287.0

package/README.md

@@ -1,4 +1,108 @@
 # 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
+generate a proposal, and write a script to build the core proposal. The
+proposals have limited access to bootstrap powers, described by their manifests.
+
+There are collections of proposals in .../vats/src/proposals,
+smart-wallet/src/proposals, orchestration/src/proposals, pegasus/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.
+
+`.../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.
+
+`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
+[`app.go`](https://github.com/Agoric/agoric-sdk/blob/b13743a2cccf0cb63a412b54384435596d4e81ea/golang/cosmos/app/app.go#L881),
+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 }) => {
+  return harden({
+    sourceSpec: '@agoric/vats/src/proposals/foo.js',
+    getManifestCall: [
+      'getManifestForFoo',
+      {
+        fooRef: publishRef(install('@agoric/...')),
+        ...otherParams,
+      },
+    ],
+  });
+};
+`
+export default async (homeP, endowments) => {
+  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
+  await writeCoreProposal('proposalName', defaultProposalBuilder);
+};
+```
+
+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).
+

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@agoric/deploy-script-support",
-  "version": "0.10.4-20230923T000433-dev-63b1fb6.0+63b1fb6",
+  "version": "0.10.4-calypso-dev-84eb287.0+84eb287",
   "description": "Helpers and other support for writing deploy scripts",
   "type": "module",
   "main": "src/helpers.js",
   "engines": {
-    "node": ">=14.15.0"
+    "node": "^18.12 || ^20.9"
   },
   "scripts": {
     "build": "exit 0",
@@ -13,7 +13,7 @@
     "test:xs": "exit 0",
     "lint-fix": "yarn lint:eslint --fix",
     "lint:eslint": "eslint .",
-    "lint:types": "tsc -p jsconfig.json",
+    "lint:types": "tsc",
     "lint": "run-s --continue-on-error lint:*"
   },
   "repository": {
@@ -34,39 +34,45 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-20230923T000433-dev-63b1fb6.0+63b1fb6",
-    "@agoric/ertp": "0.16.3-20230923T000433-dev-63b1fb6.0+63b1fb6",
-    "@agoric/import-manager": "0.3.12-20230923T000433-dev-63b1fb6.0+63b1fb6",
-    "@agoric/internal": "0.3.3-20230923T000433-dev-63b1fb6.0+63b1fb6",
-    "@agoric/notifier": "0.6.3-20230923T000433-dev-63b1fb6.0+63b1fb6",
-    "@agoric/store": "0.9.3-20230923T000433-dev-63b1fb6.0+63b1fb6",
-    "@agoric/zoe": "0.26.3-20230923T000433-dev-63b1fb6.0+63b1fb6",
-    "@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/assert": "0.6.1-calypso-dev-84eb287.0+84eb287",
+    "@agoric/ertp": "0.16.3-calypso-dev-84eb287.0+84eb287",
+    "@agoric/import-manager": "0.3.12-calypso-dev-84eb287.0+84eb287",
+    "@agoric/internal": "0.3.3-calypso-dev-84eb287.0+84eb287",
+    "@agoric/notifier": "0.6.3-calypso-dev-84eb287.0+84eb287",
+    "@agoric/store": "0.9.3-calypso-dev-84eb287.0+84eb287",
+    "@agoric/time": "0.3.3-calypso-dev-84eb287.0+84eb287",
+    "@agoric/zoe": "0.26.3-calypso-dev-84eb287.0+84eb287",
+    "@endo/base64": "^1.0.5",
+    "@endo/bundle-source": "^3.2.3",
+    "@endo/far": "^1.1.2",
+    "@endo/marshal": "^1.5.0",
+    "@endo/nat": "^5.0.7",
+    "@endo/promise-kit": "^1.1.2",
+    "@endo/zip": "^1.0.5"
   },
   "devDependencies": {
-    "@agoric/vats": "0.15.2-20230923T000433-dev-63b1fb6.0+63b1fb6",
-    "@endo/init": "0.5.56",
-    "ava": "^5.2.0",
+    "@agoric/vats": "0.15.2-calypso-dev-84eb287.0+84eb287",
+    "@endo/init": "^1.1.2",
+    "ava": "^5.3.0",
     "import-meta-resolve": "^2.2.1"
   },
   "files": [
     "src",
-    "NEWS.md",
-    "exported.js"
+    "NEWS.md"
   ],
   "ava": {
     "files": [
-      "test/**/test-*.js"
+      "test/**/*.test.*"
+    ],
+    "require": [
+      "@endo/init/debug.js"
     ]
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "63b1fb6a532473af97b72a7b2215af9bc0d6da5f"
+  "typeCoverage": {
+    "atLeast": 81.63
+  },
+  "gitHead": "84eb287915c8255d68e845a9b6e10c790f0d54cb"
 }

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,70 @@ 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].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 +186,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/endo-pieces-contract.js

@@ -18,6 +18,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

@@ -10,37 +10,40 @@ 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>}
  */