API for Upgradeable Zoe Contracts

[Chris-Hibbert]

An upgradeable Zoe contract has a vivify function instead of the start function. The first invocation of vivify, like start, must return at least one of creatorFacet and publicFacet. (creatorInvitation is deprecated; support will be dropped shortly.)

The parameters for vivify and start are zcf, privateArgs, and baggage. The baggage should be used by vivify (and can be used by start) to define kindHandles and durableKinds. The baggage in start is there to allow the contract to save state that might be useful to a later version of the contract with a vivify function to be able to handle upgrade and restore the state. A contract with a start function will not be used for upgrade.

If the contract defines vivify, then on initial creation, it will get an empty baggage, and should call vivifyKind (and similar functions) to define behavior. vivifyKind and its siblings (see below) use makeKindHandle and defineDurableKind to declare kinds and associate behavior. vivifyKind returns a maker function that is used to create new durable objects. Under upgrade, the same vivify function will be called with the baggage containing the previously saved state. That invocation will retrieve the kindHandle that was previously associated with the name, and attach behavior to it.

vivify works in both scenarios because it uses functions like provide. The most general version is provide(baggage, identifier, thunk). If the identifier is not present in the baggage, the thunk is executed and its result is stored in the baggage at that key and returned. If the baggage has something stored under the identifier, then the previous value is retrieved. This combination means that the caller is insensitive to whether the provided thing is found or created. vivify supplies new behavior that is attached to new or revived kinds.

The vivify helpers bundle calls to provideKindHandle and the various forms of defineDurableKind into simpler vivifyDurableKind variants:

• vivifyKind(baggage, kindName, init, methods, options)
• vivifyKindMulti(baggage, kindName, init, behavior, options)
• vivifySingleton(baggage, kindName, methods, options)

vivifyKind wraps defineDurableKind, which takes a methods parameter that describes a single facet. Methods is a record containing named functions that take a context parameter. vivifyKindMulti wraps defineDurableKindMulti, which takes a behavior that describes multiple facets. Behavior is a record containing named records containing methods records.

vivifySingleton wraps defineDurableKind, and passes an empty init. The methods access the state via lexical enclosure. (When "singleton" objects have mutable state, we use one of the vivifyKind variants instead, so "singleton" really means "stateless".) The init functions take whatever parameter will be required to create instance state. The resulting constructor takes exactly the parameters of the init function.

For readability, there's a trade-off between accessing persistent variables using a state parameter, or via lexical variables. For const values , lexical variables are often more convenient. For anything that is mutable, state is better. One consequence of these constraints is that local stores/collections (Maps, Sets, etc.) can be stored in baggage, and then the collection accessed lexically. We've also found a few variables that were defined using let because they can't be set up in the init function. These have mostly been put in state, with a @ts-expect-error where they get initialized, so they can be visibly immutable elsewhere.

/**
 * @param {ZCF} zcf
 * @param {any} privateArgs
 * @param {import('@agoric/vat-data').Baggage} installationBaggage
 */
const start = (zcf, privateArgs, installationBaggage) => {
  const myState = provideDurableMapStore(baggage, 'myState');

  // define durable kinds
  const fooMaker = vivifyKind(baggage, 'foo', init, methods);

  return harden({ creatorFacet, publicFacet });
};

Offer Handlers that should survive upgrade (not true of all Handlers!) need to be made durable. This should define a durable object with a handle method.

  const makeHandler = vivifyKind(
    baggage,
   'makeHandlerKindHandle',
    makeHandlerKindHandle,
    sellSeat => ({ sellSeat }),
    {
      handle: ({ state: { sellSeat } }, buySeat) => {
        assert(!sellSeat.hasExited(), sellSeatExpiredMsg);
        try {
          swapExact(zcf, sellSeat, buySeat);
        } catch (err) {
          console.log(
            'Swap failed.',
          );
          throw err;
        }
        zcf.shutdown('Swap completed.');
        return `The option was exercised. Please collect the assets in your payout.`;
      },
    },
  );

[erights]

Great start! Covers a lot of ground compactly.

Altogether, I wonder if we should teach first only the provideSomething and vivifySomething functions, and then treat the remaining functions as advanced details or separate topics. The use of non-durable virtual objects and virtual stores, for purposes only of high cardinality without concern for upgrade, would be such a separate topic.

I scanned our uses of the API and I think it fits this shift in perspective. All deviations that I found were making things durable but not reachably durable. Using only provideSomething and vivifySomething would shrink the gap between durable and reachably durable considerably.

Some local comments:

run in both scenarios is a set of functions that start with provide.

Should be "that start with provide or vivify."

In each case, the thunk is executed if the identifier is not present in the baggage, while the previous value is retrieved if it is already present

Need to also say that the result of the thunk is stored in the baggage at that same key and returned, so the caller of the provideSomething function can be insensitive to whether the provided thing is found or created.

There are special versions [of provideSomething] for providing stores, kindHandles, and durableKinds

The only special versions that provide durableKinds are vivifySomething.

For values that are read more than they are written, lexical variables are more convenient. For anything that is changed very much, state is often preferred; updating a lexical variable requires that the baggage be updated as well

I think it is more binary than this. Lexical variables for durable state are only a good choice when they are const lexical variables, i.e., when they are only read. If they are updated at all, it is probably better to use a state record. The consequence is that you need to use vivifyKind rather than vivifySingleton for those, even if the object actually is a singleton.

The offerHandler example should use vivifyKind rather than defineDurableKind, as the coveredCall-durable does. (I suspect this was snapshot from an earlier version of that code.)

[erights]

What is

?

[Chris-Hibbert]

I've been trying to figure that out myself. I keep hovering, and it doesn't tell me anything. I've concluded that it's an artifact of the 'discussion' format. By clicking, I see that the smiley face lets me add an emoticon, and the uparrow lets me up-vote.