@agoric/zone

Zones

Each Zone provides an API that allows the allocation of Exo objects and Stores (object collections) which use the same underlying persistence mechanism. This allows library code to be agnostic to whether its objects are backed purely by the JS heap (ephemeral), pageable out to disk (virtual) or can be revived after a vat upgrade (durable).

See SwingSet vat upgrade documentation for more example use of the zone API.

An example of making a Zone-aware vat might look something like this:

import { makeDurableZone } from '@agoric/zone/durable.js';
import { zoneFrobulator } from 'frob-package';
import { zoneWidget } from 'widget-package';

export const buildRootObject = (vatPowers, _args, baggage) => {
  const zone = makeDurableZone(baggage);

  // Ensure that Widgets cannot interfere with Frobs.
  const makeWidget = zoneWidget(zone.subZone('Widgets'));

  // Create a collection of frobulators.
  const frobZone = zone.subZone('Frobs');
  const makeFrobulator = zoneFrobulator(frobZone);
  const widgetToFrob = frobZone.mapStore('widgetToFrob');

  return Far('WidgetFrobulator', {
    makeWidget,
    registerWidget(w) {
      const frobulator = makeFrobulator();
      widgetToFrob.init(w, frobulator);
    },
    frobWidget(w) {
      const frobulator = widgetToFrob.get(w);
      return frobulator.frob(w);
    },
  });
}