refactor: clarify zcfZygote setInstallation/setupInstance

Agoric · Jun 30, 2022 · 57970ce · 57970ce
1 parent 915ecae
commit 57970ce
Show file tree

Hide file tree

Showing 2 changed files with 50 additions and 46 deletions.
diff --git a/packages/zoe/src/contractFacet/vatRoot.js b/packages/zoe/src/contractFacet/vatRoot.js
@@ -42,6 +42,7 @@ export function buildRootObject(powers, vatParameters, baggage) {
     baggage.init('invitationIssuer', invitationIssuer);
   }
 
+  // make zcfZygote with contract-general state and kinds initialized
   const zcfZygote = makeZCFZygote(
     powers,
     zoeService,
@@ -53,6 +54,7 @@ export function buildRootObject(powers, vatParameters, baggage) {
   // snapshot zygote here //////////////////
 
   return Far('executeContract', {
+    // initialize instance-specific state of the contract (1st time)
     startContract: (
       zoeInstanceAdmin, // in 1st message post-clone
       instanceRecordFromZoe, // in 1st msg post-clone (could split out installation)
@@ -70,6 +72,7 @@ export function buildRootObject(powers, vatParameters, baggage) {
         privateArgs,
       );
     },
+    // re-initialize instance-specific state of the contract (not 1st time)
     restartContract: (
       zoeInstanceAdmin, // in 1st message post-clone
       instanceRecordFromZoe, // in 1st msg post-clone (could split out installation)

diff --git a/packages/zoe/src/contractFacet/zcfZygote.js b/packages/zoe/src/contractFacet/zcfZygote.js
@@ -277,13 +277,15 @@ export const makeZCFZygote = async (
   const { setupInstallation, start } = await evaluateContract();
 
   const contractBaggage = provideDurableMapStore(zcfBaggage, 'contractBaggage');
-  // allow the contract (any version) to set up its installation Kinds
-  const setupInstance = await setupInstallation(contractBaggage);
 
-  // const zcfHandle1 = provideHandle(baggage, 'zcfHandle1', 'zcfIface1');
-  // const zcfHandle2 = provideHandle(baggage, 'zcfHandle2', 'zcfIface2');
-  // const makeZcfThing1 = defineDurableKind(zcfHandle1, undefined, {});  // makeZcfSeat
-  // const makeZcfThing2 = defineDurableKind(zcfHandle2, undefined, {});
+  const doSetupInstance = async setupInstance => {
+    // maybe do some defineDurableKinds here
+    // const { zcfThing1, zcfThing2 } = provideZcfThings(baggage, perInstanceZoeStuff);
+    // const zcfThing1 = makeZcfThing1(perInstanceZoeStuff);
+    // const zcfThing2 = makeZcfThing2(perInstanceZoeStuff);
+
+    return setupInstance();
+  };
 
   /**
    * A zygote is a pre-image of a vat that can quickly be instantiated because
@@ -297,6 +299,11 @@ export const makeZCFZygote = async (
    * @type {ZCFZygote}
    * */
   const zcfZygote = {
+    // wire zcf up to zoe instance-specific interfaces, make any instance-specific
+    // zcf state, ask the contract to initialize kinds before the contract
+    // starts running.
+    // There will shortly be a restartContract parallel to this for the contract
+    // restart case.
     startContract: async (
       instanceAdminFromZoe,
       instanceRecordFromZoe,
@@ -307,8 +314,7 @@ export const makeZCFZygote = async (
       instantiateInstanceRecordStorage(instanceRecordFromZoe);
       instantiateIssuerStorage(issuerStorageFromZoe);
 
-      const didStart = contractBaggage.has('didStart'); // false for v1, true for v2
-
+      // If it's a non-upgradeable contract, start it now.
       if (!setupInstallation) {
         // fall back to old non-upgradable scheme
         // Next, execute the contract code, passing in zcf
@@ -332,48 +338,43 @@ export const makeZCFZygote = async (
         return result;
       }
 
-      // For the version-1 installation, we stop doing work here: we
-      // define more function and objects, but none will be invoked in
-      // this heap. Instead, they will be invoked in a zygote/clone of
-      // this heap.
-
-      let makeInstanceKit;
-
-      const doSetupInstance = async _perInstanceZoeStuff => {
-        // maybe do some defineDurableKinds here
-
-        // const { zcfThing1, zcfThing2 } = provideZcfThings(baggage, perInstanceZoeStuff);
-
-        // const zcfThing1 = makeZcfThing1(perInstanceZoeStuff);
-        // const zcfThing2 = makeZcfThing2(perInstanceZoeStuff);
-        makeInstanceKit = await setupInstance(/* zcfThing1, zcfThing2 */);
-      };
-
-      const start2 = async perInstanceZoeStuff => {
-        // the version-1 *instance* will see this zcRoot.start() get
-        // invoked (in a clone of the original vat) exactly once per
-        // instance
-        contractBaggage.init('didStart', true);
-        contractBaggage.init('perInstanceZoeStuff', perInstanceZoeStuff);
-        // now that our clone is differentiated, we can do
-        // instance-specific setup
-        await doSetupInstance(perInstanceZoeStuff);
-        // and we can invoke makeInstanceKit() for the first and only time
-        const { publicFacet, privateFacet } = makeInstanceKit();
-        return harden({ publicFacet, privateFacet });
-      };
-
-      // For version-2 or later, we know we've already been started, so
-      // allow the contract to set up its instance Kinds
-      if (didStart) {
-        const perInstanceZoeStuff = contractBaggage.get('perInstanceZoeStuff');
-        doSetupInstance(perInstanceZoeStuff);
-        // however we do not call makeInstanceKit() again
-      }
+      // setupInstallation is a fn returned by the contract that sets up
+      // installation-specific state, and returns setupInstance. setupInstance
+      // does instane-specific setup and returns makeInstanceKit.
+      E.when(
+        setupInstallation(contractBaggage, zcf, privateArgs),
+        async setupInstance => {
+          // allow the contract (any version) to set up its installation Kinds
+          // const zcfHandle1 = provideHandle(baggage, 'zcfHandle1', 'zcfIface1');
+          // const zcfHandle2 = provideHandle(baggage, 'zcfHandle2', 'zcfIface2');
+          // const makeZcfThing1 = defineDurableKind(zcfHandle1, undefined, {});  // makeZcfSeat
+          // const makeZcfThing2 = defineDurableKind(zcfHandle2, undefined, {});
+
+          // the version-1 *instance* will see this zcRoot.start() get
+          // invoked (in a clone of the original vat) exactly once per
+          // instance
+
+          // now that our clone is differentiated, we can do
+          // instance-specific setup
+          const makeInstanceKit = await doSetupInstance(setupInstance);
+          // and we can invoke makeInstanceKit() for the first and only time
+          const { publicFacet, privateFacet } = makeInstanceKit();
+          return harden({ publicFacet, privateFacet });
+        },
+      );
 
       const zcfRoot = Far('zcfRoot', { start2 });
       return zcfRoot;
     },
+    restartContract: async () => {
+      // code like startContract
+
+      // For version-2 or later, we know we've already been started, so
+      // allow the contract to set up its instance Kinds
+      const perInstanceZoeStuff = contractBaggage.get('perInstanceZoeStuff');
+      doSetupInstance(perInstanceZoeStuff);
+      // however we do not call makeInstanceKit() again
+    },
   };
   return harden(zcfZygote);
 };