@agoric/deploy-script-support 0.10.4-dev-b423dda.0 → 0.10.4-dev-b12a0f1.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-dev-b423dda.0+b423dda",
+  "version": "0.10.4-dev-b12a0f1.0+b12a0f1",
   "description": "Helpers and other support for writing deploy scripts",
   "type": "module",
   "main": "src/helpers.js",
@@ -34,13 +34,13 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/ertp": "0.16.3-dev-b423dda.0+b423dda",
-    "@agoric/import-manager": "0.3.12-dev-b423dda.0+b423dda",
-    "@agoric/internal": "0.3.3-dev-b423dda.0+b423dda",
-    "@agoric/notifier": "0.6.3-dev-b423dda.0+b423dda",
-    "@agoric/store": "0.9.3-dev-b423dda.0+b423dda",
-    "@agoric/time": "0.3.3-dev-b423dda.0+b423dda",
-    "@agoric/zoe": "0.26.3-dev-b423dda.0+b423dda",
+    "@agoric/ertp": "0.16.3-dev-b12a0f1.0+b12a0f1",
+    "@agoric/import-manager": "0.3.12-dev-b12a0f1.0+b12a0f1",
+    "@agoric/internal": "0.3.3-dev-b12a0f1.0+b12a0f1",
+    "@agoric/notifier": "0.6.3-dev-b12a0f1.0+b12a0f1",
+    "@agoric/store": "0.9.3-dev-b12a0f1.0+b12a0f1",
+    "@agoric/time": "0.3.3-dev-b12a0f1.0+b12a0f1",
+    "@agoric/zoe": "0.26.3-dev-b12a0f1.0+b12a0f1",
     "@endo/base64": "^1.0.7",
     "@endo/bundle-source": "^3.4.0",
     "@endo/errors": "^1.2.5",
@@ -51,7 +51,7 @@
     "@endo/zip": "^1.0.7"
   },
   "devDependencies": {
-    "@agoric/vats": "0.15.2-dev-b423dda.0+b423dda",
+    "@agoric/vats": "0.15.2-dev-b12a0f1.0+b12a0f1",
     "@endo/init": "^1.1.4",
     "ava": "^5.3.0",
     "import-meta-resolve": "^2.2.1"
@@ -74,5 +74,5 @@
   "typeCoverage": {
     "atLeast": 82.6
   },
-  "gitHead": "b423ddae8c6b5b4931c383afc286a7c66de2a638"
+  "gitHead": "b12a0f16a0a2240a172827e0fe4439843445b84d"
 }