@agoric/zoe 0.26.3-dev-121b677.0 → 0.26.3-dev-d2ea4b4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/zoe",
-  "version": "0.26.3-dev-121b677.0+121b677",
+  "version": "0.26.3-dev-d2ea4b4.0+d2ea4b4",
   "description": "Zoe: the Smart Contract Framework for Offer Enforcement",
   "type": "module",
   "main": "./src/zoeService/zoe.js",
@@ -43,17 +43,20 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-dev-121b677.0+121b677",
-    "@agoric/ertp": "0.16.3-dev-121b677.0+121b677",
-    "@agoric/internal": "0.3.3-dev-121b677.0+121b677",
-    "@agoric/notifier": "0.6.3-dev-121b677.0+121b677",
-    "@agoric/store": "0.9.3-dev-121b677.0+121b677",
-    "@agoric/swingset-liveslots": "0.10.3-dev-121b677.0+121b677",
-    "@agoric/swingset-vat": "0.32.3-dev-121b677.0+121b677",
-    "@agoric/time": "0.3.3-dev-121b677.0+121b677",
-    "@agoric/vat-data": "0.5.3-dev-121b677.0+121b677",
+    "@agoric/assert": "0.6.1-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/base-zone": "0.1.1-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/ertp": "0.16.3-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/internal": "0.3.3-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/notifier": "0.6.3-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/store": "0.9.3-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/swingset-liveslots": "0.10.3-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/swingset-vat": "0.32.3-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/time": "0.3.3-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/vat-data": "0.5.3-dev-d2ea4b4.0+d2ea4b4",
+    "@agoric/zone": "0.2.3-dev-d2ea4b4.0+d2ea4b4",
     "@endo/bundle-source": "^3.0.2",
     "@endo/captp": "^4.0.2",
+    "@endo/common": "^1.0.2",
     "@endo/eventual-send": "^1.1.0",
     "@endo/far": "^1.0.2",
     "@endo/import-bundle": "^1.0.2",
@@ -64,7 +67,7 @@
     "yargs-parser": "^21.1.1"
   },
   "devDependencies": {
-    "@agoric/kmarshal": "0.1.1-dev-121b677.0+121b677",
+    "@agoric/kmarshal": "0.1.1-dev-d2ea4b4.0+d2ea4b4",
     "@endo/init": "^1.0.2",
     "ava": "^5.3.0",
     "c8": "^7.13.0",
@@ -137,5 +140,5 @@
   "typeCoverage": {
     "atLeast": 84.82
   },
-  "gitHead": "121b67747aaa842adff618c610dbb0835d88cc33"
+  "gitHead": "d2ea4b46b9efa61e97eec8711830d9fdd741ca55"
 }

package/src/contractFacet/types-ambient.d.ts

@@ -7,6 +7,14 @@ type IssuerOptionsRecord = import('@agoric/ertp').IssuerOptionsRecord;
  */
 type Completion = any;
 type ZCFMakeEmptySeatKit = (exit?: ExitRule | undefined) => ZcfSeatKit;
+
+type MakeInvitation = <Result>(
+  offerHandler: OfferHandler<Result>,
+  description: string,
+  customDetails?: object,
+  proposalShape?: Pattern,
+) => Promise<Invitation<R, A>>;
+
 /**
  * Zoe Contract Facet
  *
@@ -54,12 +62,7 @@ type ZCF<CT extends unknown = Record<string, unknown>> = {
    * getting in the `customDetails`. `customDetails` will be
    * placed in the details of the invitation.
    */
-  makeInvitation: <Result>(
-    offerHandler: OfferHandler<Result>,
-    description: string,
-    customDetails?: object,
-    proposalShape?: Pattern,
-  ) => Promise<Invitation<R, A>>;
+  makeInvitation: MakeInvitation;
   shutdown: (completion: Completion) => void;
   shutdownWithFailure: ShutdownWithFailure;
   getZoeService: () => ERef<ZoeService>;

package/src/contractSupport/index.js

@@ -54,6 +54,8 @@ export {
 } from './ratio.js';
 
 export * from './durability.js';
+export * from './prepare-ownable.js';
+export * from './prepare-revocable.js';
 export * from './priceAuthority.js';
 export * from './priceQuote.js';
 export * from './statistics.js';

package/src/contractSupport/prepare-ownable.js

@@ -0,0 +1,94 @@
+import { M } from '@endo/patterns';
+import { OfferHandlerI } from '../typeGuards.js';
+import { prepareRevocableKit } from './prepare-revocable.js';
+
+const TransferProposalShape = M.splitRecord({
+  give: {},
+  want: {},
+  exit: {
+    onDemand: null,
+  },
+});
+
+/**
+ * @typedef {object} OwnableOptions
+ * @property {string} [uInterfaceName]
+ *   The `interfaceName` of the underlying interface guard.
+ *   Defaults to the `uKindName`.
+ */
+
+/**
+ * @template {any} [U=any]
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {MakeInvitation} makeInvitation
+ *   A function with the same behavior as `zcf.makeInvitation`.
+ *   A contract will normally just extract it from its own zcf using the
+ *   argument expression
+ *   ```js
+ *   (...args) => zcf.makeInvitation(...args)
+ *   ```
+ *   See ownable-counter.js for the canonical example.
+ * @param {string} uKindName
+ *   The `kindName` of the underlying exo class
+ * @param {(string|symbol)[]} uMethodNames
+ *   The method names of the underlying exo class that should be represented
+ *   by transparently-forwarding methods of the wrapping ownable object.
+ * @param {OwnableOptions} [options]
+ * @returns {(underlying: U) => U}
+ */
+export const prepareOwnable = (
+  zone,
+  makeInvitation,
+  uKindName,
+  uMethodNames,
+  options = {},
+) => {
+  const { uInterfaceName = uKindName } = options;
+  const makeRevocableKit = prepareRevocableKit(zone, uKindName, uMethodNames, {
+    uInterfaceName,
+    extraMethodGuards: {
+      makeTransferInvitation: M.call().returns(M.promise()),
+    },
+    extraMethods: {
+      makeTransferInvitation() {
+        const { underlying } = this.state;
+        const { revoker } = this.facets;
+        const customDetails = underlying.getInvitationCustomDetails();
+        // eslint-disable-next-line no-use-before-define
+        const transferHandler = makeTransferHandler(underlying);
+
+        const invitation = makeInvitation(
+          transferHandler,
+          'transfer',
+          customDetails,
+          TransferProposalShape,
+        );
+        revoker.revoke();
+        return invitation;
+      },
+    },
+  });
+
+  const makeTransferHandler = zone.exoClass(
+    'TransferHandler',
+    OfferHandlerI,
+    underlying => ({
+      underlying,
+    }),
+    {
+      handle(seat) {
+        const { underlying } = this.state;
+        const { revocable } = makeRevocableKit(underlying);
+        seat.exit();
+        return revocable;
+      },
+    },
+  );
+
+  const makeOwnable = underlying => {
+    const { revocable } = makeRevocableKit(underlying);
+    return revocable;
+  };
+  return harden(makeOwnable);
+};
+harden(prepareOwnable);

package/src/contractSupport/prepare-revocable.js

@@ -0,0 +1,137 @@
+import { M } from '@endo/patterns';
+import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
+
+const { Fail, quote: q } = assert;
+
+/**
+ * @typedef {object} Revoker
+ * @property {() => boolean} revoke
+ */
+
+/**
+ * @template {any} [U=any]
+ * @typedef {object} RevocableKit
+ * @property {Revoker} revoker
+ * @property {U} revocable
+ *   Forwards to the underlying exo object, until revoked
+ */
+
+/**
+ * @template [U=any]
+ * @typedef {object} RevocableKitThis
+ * @property {RevocableKit<U>} facets
+ * @property {{ underlying: U }} state
+ */
+
+/**
+ * @template {any} [U=any]
+ * @typedef {object} RevocableKitOptions
+ * @property {string} [uInterfaceName]
+ *   The `interfaceName` of the underlying interface guard.
+ *   Defaults to the `uKindName`.
+ * @property {Record<
+ *   string|symbol,
+ *   import('@endo/patterns').MethodGuard
+ * >} [extraMethodGuards]
+ * For guarding the `extraMethods`, if you include them below. These appear
+ * only on the synthesized interface guard for the revocable caretaker, and
+ * do not necessarily correspond to any method of the underlying.
+ * @property {Record<
+ *   string|symbol,
+ *   (this: RevocableKitThis<U>, ...args: any[]) => any
+ * >} [extraMethods]
+ * Extra methods adding behavior only to the revocable caretaker, and
+ * do not necessarily correspond to any methods of the underlying.
+ */
+
+/**
+ * Make an exo class kit for wrapping an underlying exo class,
+ * where the wrapper is a revocable forwarder
+ *
+ * @template {any} [U=any]
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {string} uKindName
+ *   The `kindName` of the underlying exo class
+ * @param {(string|symbol)[]} uMethodNames
+ *   The method names of the underlying exo class that should be represented
+ *   by transparently-forwarding methods of the revocable caretaker.
+ * @param {RevocableKitOptions} [options]
+ * @returns {(underlying: U) => RevocableKit<U>}
+ */
+export const prepareRevocableKit = (
+  zone,
+  uKindName,
+  uMethodNames,
+  options = {},
+) => {
+  const {
+    uInterfaceName = uKindName,
+    extraMethodGuards = undefined,
+    extraMethods = undefined,
+  } = options;
+  const RevocableIKit = harden({
+    revoker: M.interface(`${uInterfaceName}_revoker`, {
+      revoke: M.call().returns(M.boolean()),
+    }),
+    revocable: M.interface(
+      `${uInterfaceName}_revocable`,
+      {
+        ...extraMethodGuards,
+      },
+      {
+        defaultGuards: 'raw',
+      },
+    ),
+  });
+
+  const revocableKindName = `${uKindName}_caretaker`;
+
+  const makeRevocableKit = zone.exoClassKit(
+    revocableKindName,
+    RevocableIKit,
+    underlying => ({
+      underlying,
+    }),
+    {
+      revoker: {
+        revoke() {
+          const { state } = this;
+          if (state.underlying === undefined) {
+            return false;
+          }
+          state.underlying = undefined;
+          return true;
+        },
+      },
+      revocable: {
+        ...fromUniqueEntries(
+          uMethodNames.map(name => [
+            name,
+            {
+              // Use concise method syntax for exo methods
+              [name](...args) {
+                // @ts-expect-error normal exo-this typing confusion
+                const { underlying } = this.state;
+                underlying !== undefined ||
+                  Fail`${q(revocableKindName)} revoked`;
+                return underlying[name](...args);
+              },
+              // @ts-expect-error using possible symbol as index type
+            }[name],
+          ]),
+        ),
+        ...extraMethods,
+      },
+    },
+    {
+      stateShape: {
+        underlying: M.opt(M.remotable('underlying')),
+      },
+    },
+  );
+
+  // eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error
+  // @ts-ignore parameter confusion
+  return makeRevocableKit;
+};
+harden(prepareRevocableKit);