@agoric/zoe 0.26.3-dev-8baf0aa.0 → 0.26.3-dev-cc54325.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/zoe",
-  "version": "0.26.3-dev-8baf0aa.0+8baf0aa",
+  "version": "0.26.3-dev-cc54325.0+cc54325",
   "description": "Zoe: the Smart Contract Framework for Offer Enforcement",
   "type": "module",
   "main": "./src/zoeService/zoe.js",
@@ -43,14 +43,14 @@
   },
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
-    "@agoric/assert": "0.6.1-dev-8baf0aa.0+8baf0aa",
-    "@agoric/ertp": "0.16.3-dev-8baf0aa.0+8baf0aa",
-    "@agoric/internal": "0.3.3-dev-8baf0aa.0+8baf0aa",
-    "@agoric/notifier": "0.6.3-dev-8baf0aa.0+8baf0aa",
-    "@agoric/store": "0.9.3-dev-8baf0aa.0+8baf0aa",
-    "@agoric/swingset-vat": "0.32.3-dev-8baf0aa.0+8baf0aa",
-    "@agoric/time": "0.3.3-dev-8baf0aa.0+8baf0aa",
-    "@agoric/vat-data": "0.5.3-dev-8baf0aa.0+8baf0aa",
+    "@agoric/assert": "0.6.1-dev-cc54325.0+cc54325",
+    "@agoric/ertp": "0.16.3-dev-cc54325.0+cc54325",
+    "@agoric/internal": "0.3.3-dev-cc54325.0+cc54325",
+    "@agoric/notifier": "0.6.3-dev-cc54325.0+cc54325",
+    "@agoric/store": "0.9.3-dev-cc54325.0+cc54325",
+    "@agoric/swingset-vat": "0.32.3-dev-cc54325.0+cc54325",
+    "@agoric/time": "0.3.3-dev-cc54325.0+cc54325",
+    "@agoric/vat-data": "0.5.3-dev-cc54325.0+cc54325",
     "@endo/bundle-source": "^2.5.2",
     "@endo/captp": "^3.1.2",
     "@endo/eventual-send": "^0.17.3",
@@ -104,6 +104,7 @@
       "test/unitTests/zcf/test-reallocate-empty.js",
       "test/unitTests/zcf/test-zoeHelpersWZcf.js",
       "test/unitTests/zcf/test-reallocateForZCFMint.js",
+      "test/unitTests/zcf/test-atomicRearrange.js",
       "test/unitTests/zcf/test-zcf.js",
       "test/unitTests/zcf/test-allStagedSeatsUsed.js",
       "# ManualTimer.setWakeup: no function",
@@ -127,5 +128,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8baf0aabe3cadeb1cd07fd30641d11baf3e68eaf"
+  "gitHead": "cc543255026eb4aa3c8e0ad97ef7b572871063cd"
 }

package/src/contractFacet/reallocate.d.ts

@@ -0,0 +1,3 @@
+export function makeAllocationMap(transfers: Array<TransferPart>): [ZCFSeat, AmountKeywordRecord][];
+export type TransactionList = Array<AmountKeywordRecord>;
+//# sourceMappingURL=reallocate.d.ts.map

package/src/contractFacet/reallocate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reallocate.d.ts","sourceRoot":"","sources":["reallocate.js"],"names":[],"mappings":"AAiBO,6CAHI,mBAAmB,GACjB,CAAC,OAAO,EAAE,mBAAmB,CAAC,EAAE,CA8E5C;8BAtFa,MAAM,mBAAmB,CAAC"}

package/src/contractFacet/reallocate.js

@@ -0,0 +1,94 @@
+import { makeScalarMapStore } from '@agoric/vat-data';
+
+import { assertRightsConserved } from './rightsConservation.js';
+import { addToAllocation, subtractFromAllocation } from './allocationMath.js';
+
+const { Fail } = assert;
+
+/** @typedef {Array<AmountKeywordRecord>} TransactionList */
+
+/**
+ * Convert from a list of transfer descriptions ([fromSeat, toSeat, fromAmount,
+ * toAmount], with many parts optional) to a list of resulting allocations for
+ * each of the seats mentioned.
+ *
+ * @param {Array<TransferPart>} transfers
+ * @returns {[ZCFSeat, AmountKeywordRecord][]}
+ */
+export const makeAllocationMap = transfers => {
+  /** @type {MapStore<ZCFSeat, [TransactionList, TransactionList]>} */
+  const allocations = makeScalarMapStore();
+
+  const getAllocations = seat => {
+    if (allocations.has(seat)) {
+      return allocations.get(seat);
+    }
+
+    /** @type {[TransactionList, TransactionList]} */
+    const pair = [[], []];
+    allocations.init(seat, pair);
+    return pair;
+  };
+
+  const decrementAllocation = (seat, decrement) => {
+    const [incr, decr] = getAllocations(seat);
+
+    const newDecr = [...decr, decrement];
+    allocations.set(seat, [incr, newDecr]);
+  };
+
+  const incrementAllocation = (seat, increment) => {
+    const [incr, decr] = getAllocations(seat);
+
+    const newIncr = [...incr, increment];
+    allocations.set(seat, [newIncr, decr]);
+  };
+
+  for (const [fromSeat, toSeat, fromAmounts, toAmounts] of transfers) {
+    if (fromSeat) {
+      if (!fromAmounts) {
+        throw Fail`Transfer from ${fromSeat} must say how much`;
+      }
+      decrementAllocation(fromSeat, fromAmounts);
+      if (toSeat) {
+        // Conserved transfer between seats
+        if (toAmounts) {
+          // distinct amounts, so we check conservation.
+          assertRightsConserved(
+            Object.values(fromAmounts),
+            Object.values(toAmounts),
+          );
+          incrementAllocation(toSeat, toAmounts);
+        } else {
+          // fromAmounts will be used for toAmounts as well
+          incrementAllocation(toSeat, fromAmounts);
+        }
+      } else {
+        // Transfer only from fromSeat
+        !toAmounts ||
+          Fail`Transfer without toSeat cannot have toAmounts ${toAmounts}`;
+      }
+    } else {
+      toSeat || Fail`Transfer must have at least one of fromSeat or toSeat`;
+      // Transfer only to toSeat
+      !fromAmounts ||
+        Fail`Transfer without fromSeat cannot have fromAmounts ${fromAmounts}`;
+      toAmounts || Fail`Transfer to ${toSeat} must say how much`;
+      incrementAllocation(toSeat, toAmounts);
+    }
+  }
+
+  /** @type {[ZCFSeat,AmountKeywordRecord][]} */
+  const resultingAllocations = [];
+  for (const [seat, [incrList, decrList]] of allocations.entries()) {
+    let newAlloc = seat.getCurrentAllocation();
+    for (const incr of incrList) {
+      newAlloc = addToAllocation(newAlloc, incr);
+    }
+    for (const decr of decrList) {
+      newAlloc = subtractFromAllocation(newAlloc, decr);
+    }
+    resultingAllocations.push([seat, newAlloc]);
+  }
+  return resultingAllocations;
+};

package/src/contractFacet/types.d.ts

@@ -14,6 +14,10 @@ type ZCFMakeEmptySeatKit = (exit?: ExitRule | undefined) => ZcfSeatKit;
  * in code as zcf.
  */
 type ZCF<CT extends unknown = Record<string, unknown>> = {
+    /**
+     * - atomically reallocate amounts among seats.
+     */
+    atomicRearrange: (transfers: TransferPart[]) => void;
     /**
      * - reallocate amounts among seats.
      * Deprecated: Use atomicRearrange instead.
@@ -71,6 +75,12 @@ type ZCF<CT extends unknown = Record<string, unknown>> = {
  * effect offer safety for seats whose allocations change.
  */
 type Reallocate = (seat1: ZCFSeat, seat2: ZCFSeat, ...seatRest: Array<ZCFSeat>) => void;
+type TransferPart = [
+    fromSeat?: ZCFSeat,
+    toSeat?: ZCFSeat,
+    fromAmounts?: AmountKeywordRecord,
+    toAmounts?: AmountKeywordRecord
+];
 /**
  * Informs Zoe about an issuer and returns a promise for acknowledging
  * when the issuer is added and ready.
@@ -175,12 +185,17 @@ type HandleOffer<OR extends unknown> = (seat: ZCFSeat, offerArgs?: object) => OR
 type OfferHandler<OR extends unknown = unknown> = HandleOffer<OR> | {
     handle: HandleOffer<OR>;
 };
+type ContractMeta = {
+    customTermsShape?: CopyRecord<any> | undefined;
+    privateArgsShape?: CopyRecord<any> | undefined;
+    upgradability?: "canBeUpgraded" | "canUpgrade" | undefined;
+};
 /**
  * API for a contract start function.
  *
  * CAVEAT: assumes synchronous
  */
-type ContractStartFn<PF extends unknown = any, CF extends unknown = any, CT extends unknown = any, PA extends unknown = any> = (zcf: ZCF<CT>, privateArgs: PA) => ContractStartFnResult<PF, CF>;
+type ContractStartFn<PF extends unknown = any, CF extends unknown = any, CT extends unknown = any, PA extends unknown = any> = (zcf: ZCF<CT>, privateArgs: PA, baggage?: MapStore<any, any> | undefined) => ContractStartFnResult<PF, CF>;
 type ContractStartFnResult<PF, CF> = {
     publicFacet: PF;
     creatorFacet: CF;

package/src/contractFacet/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"2BAIc,OAAO,cAAc,EAAE,mBAAmB;;;;kBAI3C,GAAG;4DAOH,UAAU;;;;;;;;;;;;;;;gBAaT,UAAU;;;;;;mCAEA,OAAO,KAAK,IAAI;;;;;;gBAG1B,UAAU;oBAGV,cAAc;2BACD,UAAU,KAAK,IAAI;yBAChC,mBAAmB;mBACnB,MAAM,KAAK,UAAU,CAAC;yBACtB,MAAM,OAAO,KAAK,CAAC;cACnB,MAAM,aAAa,GAAG,EAAE;;;kBAGxB,mBAAmB;0DAEnB,OAAO,6CAEF,qBAAqB,YACzB,mBAAmB;qBAEpB,kBAAkB;sBAClB,mBAAmB;gBACnB,UAAU;yBACV,MAAM,QAAQ,IAAI,CAAC;8BACT,MAAM,MAAM,CAAC,KAAK,QAAQ,IAAI,CAAC;oBACzC,MAAM,QAAQ,MAAM,MAAM,CAAC,CAAC;iBAC5B,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;0BAIP,OAAO,SAAS,OAAO,eAC3C,MAAQ,OAAO,CAAC,KAAK,IAAI;;;;;4BA6Bf,KAAK,MAAM,CAAC,WACZ,OAAO,KACL,QAAQ,iBAAe,CAAC;;;;;;;;;;;gFAMnB,MAAM,kBACH,MAAM,kBACN,OAAO;oCAgBjB,OAAO,wBACP,aAAa,KAEX,QAAQ,QAAQ,KAAK,CAAC,CAAC;;;;;;;;;;;;;;;2BAkBzB,MAAM,OAAO,MAAM,EAAE,OAAO,CAAC,KAC3B,IAAI;;qBAMH,MAAM,aAAa,CAAC,CAAC;;;;;;;;;;;;uBACb,mBAAmB,YAAY,OAAO,KAAK,OAAO;;;;;;;;;yBAWjD,mBAAmB,WAClB,OAAO,KACZ,IAAI;;;;;;4BAcZ,OAAO,KACL,KAAK;;;;;uCAOP,OAAO,2CAEL,OAAO,GAAG,CAAC;;wBAKI,UAAU,KAAK,IAAI;UACjC,WAAW;mBACX,MAAM,QAAQ,WAAW,UAAU,CAAC,CAAC;eACrC,MAAM,OAAO;iBACb,MAAM,cAAc;wBACpB,qBAAqB;0BACrB,MAAM,UAAU;;;;yBAChB,MAAM,UAAU;;;;yBAEhB,MAAM,OAAO;iCAEG,UAAU,KAAK,OAAO;;;;uCAChB,mBAAmB,KAAK,mBAAmB;;;;uCAE3C,mBAAmB,KAAK,mBAAmB;;;;WAEjE,MAAM,IAAI;;kBAKX;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,KAAK,QAAQ,CAAC,CAAA;CAAC;8CAKtC,OAAO,cAAc,MAAM,KAAK,EAAE;kDAKzC,YAAY,EAAE,CAAC,GAAG;IAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAA;CAAE;;;;;;qIAe/C,IAAI,EAAE,CAAC,eACP,EAAE,KACA,sBAAsB,EAAE,EAAE,EAAE,CAAC;;iBAO5B,EAAE;kBACF,EAAE;;;qBAMH,OAAO,qBAAqB,EAAE,UAAU,CAAC,CAAC,CAAC;kBAI3C,OAAO,qBAAqB,EAAE,UAAU"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"2BAIc,OAAO,cAAc,EAAE,mBAAmB;;;;kBAI3C,GAAG;4DAOH,UAAU;;;;;;;;;;;;;;iCAaG,cAAc,KAAK,IAAI;;;;;gBACnC,UAAU;;;;;;mCAEA,OAAO,KAAK,IAAI;;;;;;gBAG1B,UAAU;oBAGV,cAAc;2BACD,UAAU,KAAK,IAAI;yBAChC,mBAAmB;mBACnB,MAAM,KAAK,UAAU,CAAC;yBACtB,MAAM,OAAO,KAAK,CAAC;cACnB,MAAM,aAAa,GAAG,EAAE;;;kBAGxB,mBAAmB;0DAEnB,OAAO,6CAEF,qBAAqB,YACzB,mBAAmB;qBAEpB,kBAAkB;sBAClB,mBAAmB;gBACnB,UAAU;yBACV,MAAM,QAAQ,IAAI,CAAC;8BACT,MAAM,MAAM,CAAC,KAAK,QAAQ,IAAI,CAAC;oBACzC,MAAM,QAAQ,MAAM,MAAM,CAAC,CAAC;iBAC5B,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;0BAMP,OAAO,SAAS,OAAO,eAC3C,MAAQ,OAAO,CAAC,KAAK,IAAI;oBAwBb;IACZ,QAAY,CAAC,EAAE,OAAO;IACtB,MAAU,CAAC,EAAE,OAAO;IACpB,WAAe,CAAC,EAAE,mBAAmB;IACrC,SAAa,CAAC,EAAE,mBAAmB;CAChC;;;;;4BASO,KAAK,MAAM,CAAC,WACZ,OAAO,KACL,QAAQ,iBAAe,CAAC;;;;;;;;;;;gFAMnB,MAAM,kBACH,MAAM,kBACN,OAAO;oCAgBjB,OAAO,wBACP,aAAa,KAEX,QAAQ,QAAQ,KAAK,CAAC,CAAC;;;;;;;;;;;;;;;2BAkBzB,MAAM,OAAO,MAAM,EAAE,OAAO,CAAC,KAC3B,IAAI;;qBAMH,MAAM,aAAa,CAAC,CAAC;;;;;;;;;;;;uBACb,mBAAmB,YAAY,OAAO,KAAK,OAAO;;;;;;;;;yBAWjD,mBAAmB,WAClB,OAAO,KACZ,IAAI;;;;;;4BAcZ,OAAO,KACL,KAAK;;;;;uCAOP,OAAO,2CAEL,OAAO,GAAG,CAAC;;wBAKI,UAAU,KAAK,IAAI;UACjC,WAAW;mBACX,MAAM,QAAQ,WAAW,UAAU,CAAC,CAAC;eACrC,MAAM,OAAO;iBACb,MAAM,cAAc;wBACpB,qBAAqB;0BACrB,MAAM,UAAU;;;;yBAChB,MAAM,UAAU;;;;yBAEhB,MAAM,OAAO;iCAEG,UAAU,KAAK,OAAO;;;;uCAChB,mBAAmB,KAAK,mBAAmB;;;;uCAE3C,mBAAmB,KAAK,mBAAmB;;;;WAEjE,MAAM,IAAI;;kBAKX;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,KAAK,QAAQ,CAAC,CAAA;CAAC;8CAKtC,OAAO,cAAc,MAAM,KAAK,EAAE;kDAKzC,YAAY,EAAE,CAAC,GAAG;IAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAA;CAAE;;;;;;;;;;;qIAsB/C,IAAI,EAAE,CAAC,eACP,EAAE,+CAEA,sBAAsB,EAAE,EAAE,EAAE,CAAC;;iBAO5B,EAAE;kBACF,EAAE;;;qBAMH,OAAO,qBAAqB,EAAE,UAAU,CAAC,CAAC,CAAC;kBAI3C,OAAO,qBAAqB,EAAE,UAAU"}

package/src/contractFacet/types.js

@@ -26,6 +26,7 @@
  * synchronously from within the contract, and usually is referred to
  * in code as zcf.
  *
+ * @property {(transfers: TransferPart[]) => void} atomicRearrange - atomically reallocate amounts among seats.
  * @property {Reallocate} reallocate - reallocate amounts among seats.
  * Deprecated: Use atomicRearrange instead.
  * @property {(keyword: Keyword) => void} assertUniqueKeyword - check
@@ -59,6 +60,8 @@
  */
 
 /**
+ * @deprecated reallocate(). Use zcf.atomicRearrange() instead
+ *
  * @typedef {(seat1: ZCFSeat, seat2: ZCFSeat, ...seatRest:
  * Array<ZCFSeat>) => void} Reallocate
  *
@@ -83,6 +86,15 @@
  * effect offer safety for seats whose allocations change.
  */
 
+/**
+ * @typedef {[
+ *   fromSeat?: ZCFSeat,
+ *   toSeat?: ZCFSeat,
+ *   fromAmounts?: AmountKeywordRecord,
+ *   toAmounts?: AmountKeywordRecord
+ * ]} TransferPart
+ */
+
 /**
  * @callback SaveIssuer
  *
@@ -220,6 +232,13 @@
  * @typedef {HandleOffer<OR> | { handle: HandleOffer<OR> }} OfferHandler
  */
 
+/**
+ * @typedef ContractMeta
+ * @property {CopyRecord<Pattern>} [customTermsShape]
+ * @property {CopyRecord<Pattern>} [privateArgsShape]
+ * @property {'canBeUpgraded' | 'canUpgrade'} [upgradability]
+ */
+
 /**
  * API for a contract start function.
  *
@@ -234,6 +253,7 @@
  * @callback ContractStartFn
  * @param {ZCF<CT>} zcf
  * @param {PA} privateArgs
+ * @param {MapStore} [baggage]
  * @returns {ContractStartFnResult<PF, CF>}
  */
 

package/src/contractFacet/zcfSeat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zcfSeat.d.ts","sourceRoot":"","sources":["zcfSeat.js"],"names":[],"mappings":"AAwBA,gCAAgC;AAChC,gCADW,iBAAiB,CAsX1B"}
+{"version":3,"file":"zcfSeat.d.ts","sourceRoot":"","sources":["zcfSeat.js"],"names":[],"mappings":"AA0BA,gCAAgC;AAChC,gCADW,iBAAiB,CAyd1B"}

package/src/contractFacet/zcfSeat.js

@@ -1,10 +1,10 @@
 import {
   makeScalarBigWeakMapStore,
-  provideDurableMapStore,
-  provideDurableWeakMapStore,
+  prepareExoClass,
   prepareExoClassKit,
   provide,
-  prepareExoClass,
+  provideDurableMapStore,
+  provideDurableWeakMapStore,
 } from '@agoric/vat-data';
 import { E } from '@endo/eventual-send';
 import { AmountMath } from '@agoric/ertp';
@@ -19,6 +19,8 @@ import {
   SeatDataShape,
   SeatShape,
 } from '../typeGuards.js';
+import { makeAllocationMap } from './reallocate.js';
+import { TransferPartShape } from '../contractSupport/atomicTransfer.js';
 
 const { Fail } = assert;
 
@@ -214,6 +216,10 @@ export const createSeatManager = (
 
         return isOfferSafe(state.proposal, reallocation);
       },
+      /**
+       * @deprecated switch to zcf.atomicRearrange()
+       * @param {AmountKeywordRecord} amountKeywordRecord
+       */
       incrementBy(amountKeywordRecord) {
         const { self } = this;
         assertActive(self);
@@ -227,6 +233,10 @@ export const createSeatManager = (
         );
         return amountKeywordRecord;
       },
+      /**
+       * @deprecated switch to zcf.atomicRearrange()
+       * @param {AmountKeywordRecord} amountKeywordRecord
+       */
       decrementBy(amountKeywordRecord) {
         const { self } = this;
         assertActive(self);
@@ -265,6 +275,7 @@ export const createSeatManager = (
   const ZcfSeatManagerIKit = harden({
     seatManager: M.interface('ZcfSeatManager', {
       makeZCFSeat: M.call(SeatDataShape).returns(M.remotable('zcfSeat')),
+      atomicRearrange: M.call(M.arrayOf(TransferPartShape)).returns(),
       reallocate: M.call(M.remotable('zcfSeat'), M.remotable('zcfSeat'))
         .rest(M.arrayOf(M.remotable('zcfSeat')))
         .returns(),
@@ -289,6 +300,96 @@ export const createSeatManager = (
           return zcfSeat;
         },
 
+        /**
+         * Rearrange the allocations according to the transfer descriptions.
+         * This is a set of changes to allocations that must satisfy several
+         * constraints. If these constraints are all met, then the reallocation
+         * happens atomically. Otherwise, it does not happen at all.
+         *
+         * The conditions
+         *    * All the mentioned seats are still live,
+         *    * No outstanding stagings for any of the mentioned seats. Stagings
+         *      have been deprecated in favor or atomicRearrange. To prevent
+         *      confusion, for each reallocation, it can only be expressed in
+         *      the old way or the new way, but not a mixture.
+         *    * Offer safety
+         *    * Overall conservation
+         *
+         * The overall transfer is expressed as an array of `TransferPart`. Each
+         * individual `TransferPart` is one of
+         * - A transfer from a `fromSeat` to a `toSeat`. Specify both toAmount
+         *     and fromAmount to change keywords, otherwise only fromAmount is required.
+         * - A taking from a `fromSeat`'s allocation. See the `fromOnly` helper.
+         * - A giving into a `toSeat`'s allocation. See the `toOnly` helper.
+         *
+         * @param {TransferPart[]} transfers
+         */
+        atomicRearrange(transfers) {
+          const newAllocations = makeAllocationMap(transfers);
+
+          // ////// All Seats are active /////////////////////////////////
+          for (const [seat] of newAllocations) {
+            assertActive(seat);
+            !seat.hasStagedAllocation() ||
+              Fail`Cannot mix atomicRearrange with seat stagings: ${seat}`;
+            zcfSeatToSeatHandle.has(seat) ||
+              Fail`The seat ${seat} was not recognized`;
+          }
+
+          // ////// Ensure that rights are conserved overall /////////////
+
+          // convert array of keywordAmountRecords to 1-level array of Amounts
+          const flattenAmounts = allocations =>
+            allocations.flatMap(Object.values);
+          const previousAmounts = flattenAmounts(
+            newAllocations.map(([seat]) => seat.getCurrentAllocation()),
+          );
+          const newAmounts = flattenAmounts(
+            newAllocations.map(([_, allocation]) => allocation),
+          );
+          assertRightsConserved(previousAmounts, newAmounts);
+
+          // ////// Ensure that offer safety holds ///////////////////////
+          for (const [seat, allocation] of newAllocations) {
+            isOfferSafe(seat.getProposal(), allocation) ||
+              Fail`Offer safety was violated by the proposed allocation: ${allocation}. Proposal was ${seat.getProposal()}`;
+          }
+
+          const seatHandleAllocations = newAllocations.map(
+            ([seat, allocation]) => {
+              const seatHandle = zcfSeatToSeatHandle.get(seat);
+              return { allocation, seatHandle };
+            },
+          );
+          try {
+            // No side effects above. All conditions checked which could have
+            // caused us to reject this reallocation. Notice that the current
+            // allocations are captured in seatHandleAllocations, so there must
+            // be no awaits between that assignment and here.
+            //
+            // COMMIT POINT
+            //
+            // The effects must succeed atomically. The call to
+            // replaceAllocations() will be processed in the order of updates
+            // from ZCF to Zoe. Its effects must occur immediately in Zoe on
+            // reception, and must not fail.
+            //
+            // Commit the new allocations (currentAllocation is replaced
+            // for each of the seats) and inform Zoe of the new allocation.
+
+            for (const [seat, allocation] of newAllocations) {
+              activeZCFSeats.set(seat, allocation);
+            }
+
+            // we don't wait for the results here. As described in
+            // docs/zoe-zcf.md, The initial allocation to a seat originates with
+            // Zoe, but *all subsequent updates come from ZCF to Zoe*.
+            void E(zoeInstanceAdmin).replaceAllocations(seatHandleAllocations);
+          } catch (err) {
+            shutdownWithFailure(err);
+            throw err;
+          }
+        },
         reallocate(/** @type {ZCFSeat[]} */ ...seats) {
           seats.forEach(assertActive);
           seats.forEach(assertStagedAllocation);

package/src/contractFacet/zcfZygote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zcfZygote.d.ts","sourceRoot":"","sources":["zcfZygote.js"],"names":[],"mappings":"AAiDO,sCARI,SAAS,cACT,KAAK,UAAU,CAAC,oBAChB,OAAO,KAAK,CAAC,iBACb,aAAa,qBACb,SAAS,2CAEP,QAAQ,SAAS,CAAC,CAyZ9B;kCAxaa,OAAO,cAAc,EAAE,mBAAmB"}
+{"version":3,"file":"zcfZygote.d.ts","sourceRoot":"","sources":["zcfZygote.js"],"names":[],"mappings":"AAiDO,sCARI,SAAS,cACT,KAAK,UAAU,CAAC,oBAChB,OAAO,KAAK,CAAC,iBACb,aAAa,qBACb,SAAS,2CAEP,QAAQ,SAAS,CAAC,CAka9B;kCAjba,OAAO,cAAc,EAAE,mBAAmB"}

package/src/contractFacet/zcfZygote.js

@@ -210,6 +210,16 @@ export const makeZCFZygote = async (
   });
   const handleOfferObj = makeHandleOfferObj(taker);
 
+  /**
+   * @type {() => Promise< {
+   * buildRootObject: any,
+   * start: undefined,
+   * meta: undefined,
+   * } | {
+   * buildRootObject: undefined,
+   * start: ContractStartFn,
+   * meta?: ContractMeta,
+}>} */
   const evaluateContract = () => {
     let bundle;
     if (passStyleOf(contractBundleCap) === 'remotable') {
@@ -222,22 +232,18 @@ export const makeZCFZygote = async (
     return evalContractBundle(bundle);
   };
   // evaluate the contract (either the first version, or an upgrade)
-  const {
-    start,
-    buildRootObject,
-    privateArgsShape,
-    customTermsShape,
-    prepare,
-  } = await evaluateContract();
-
-  if (start === undefined && prepare === undefined) {
+  const { start, buildRootObject, meta = {} } = await evaluateContract();
+
+  if (start === undefined) {
     buildRootObject === undefined ||
       Fail`Did you provide a vat bundle instead of a contract bundle?`;
-    Fail`contract exports missing start/prepare`;
+    throw Fail`contract exports missing start`;
   }
-  !start ||
-    !prepare ||
-    Fail`contract must provide exactly one of "start" and "prepare"`;
+
+  start.length <= 3 || Fail`invalid start parameters`;
+  const durabilityRequired = meta.upgradability
+    ? ['canBeUpgraded', 'canUpgrade'].includes(meta.upgradability)
+    : false;
 
   /** @type {ZCF} */
   // Using Remotable rather than Far because there are too many complications
@@ -245,6 +251,7 @@ export const makeZCFZygote = async (
   // accept raw functions. assert cannot be a valid passable! (It's a function
   // and has members.)
   const zcf = Remotable('Alleged: zcf', undefined, {
+    atomicRearrange: transfers => seatManager.atomicRearrange(transfers),
     reallocate: (...seats) => seatManager.reallocate(...seats),
     assertUniqueKeyword: kwd => getInstanceRecHolder().assertUniqueKeyword(kwd),
     saveIssuer: async (issuerP, keyword) => {
@@ -300,6 +307,7 @@ export const makeZCFZygote = async (
       const terms = getInstanceRecHolder().getTerms();
 
       // If the contract provided customTermsShape, validate the customTerms.
+      const { customTermsShape } = meta;
       if (customTermsShape) {
         const { brands: _b, issuers: _i, ...customTerms } = terms;
         mustMatch(harden(customTerms), customTermsShape, 'customTerms');
@@ -372,13 +380,13 @@ export const makeZCFZygote = async (
       instantiateIssuerStorage(issuerStorageFromZoe);
       zcfBaggage.init('instanceRecHolder', instanceRecHolder);
 
-      const startFn = start || prepare;
+      const { privateArgsShape } = meta;
       if (privateArgsShape) {
         mustMatch(privateArgs, privateArgsShape, 'privateArgs');
       }
       // start a contract for the first time
       return E.when(
-        startFn(zcf, privateArgs, contractBaggage),
+        start(zcf, privateArgs, contractBaggage),
         ({
           creatorFacet = undefined,
           publicFacet = undefined,
@@ -387,18 +395,16 @@ export const makeZCFZygote = async (
         }) => {
           const unexpectedKeys = Object.keys(unexpected);
           unexpectedKeys.length === 0 ||
-            Fail`contract ${
-              prepare ? 'prepare' : 'start'
-            } returned unrecognized properties ${unexpectedKeys}`;
+            Fail`contract "start" returned unrecognized properties ${unexpectedKeys}`;
 
           const areDurable = objectMap(
             { creatorFacet, publicFacet, creatorInvitation },
             canBeDurable,
           );
           const allDurable = Object.values(areDurable).every(Boolean);
-          if (prepare) {
+          if (durabilityRequired) {
             allDurable ||
-              Fail`values from prepare() must be durable ${areDurable}`;
+              Fail`with ${meta.upgradability}, values from start() must be durable ${areDurable}`;
           }
 
           if (allDurable) {
@@ -418,18 +424,21 @@ export const makeZCFZygote = async (
     },
 
     restartContract: async (privateArgs = undefined) => {
-      prepare || Fail`prepare must be defined to upgrade a contract`;
+      if (meta.upgradability) {
+        meta.upgradability === 'canUpgrade' || Fail`contract cannot upgrade`;
+      }
       zoeInstanceAdmin = zcfBaggage.get('zcfInstanceAdmin');
       instanceRecHolder = zcfBaggage.get('instanceRecHolder');
       initSeatMgrAndMintKind();
 
+      const { privateArgsShape } = meta;
       if (privateArgsShape) {
         mustMatch(privateArgs, privateArgsShape, 'privateArgs');
       }
 
       // restart an upgradeable contract
       return E.when(
-        prepare(zcf, privateArgs, contractBaggage),
+        start(zcf, privateArgs, contractBaggage),
         ({
           creatorFacet = undefined,
           publicFacet = undefined,

package/src/contractSupport/atomicTransfer.d.ts

@@ -3,10 +3,4 @@ export function atomicRearrange(zcf: ZCF, transfers: TransferPart[]): void;
 export function fromOnly(fromSeat: ZCFSeat, fromAmounts: AmountKeywordRecord): TransferPart;
 export function toOnly(toSeat: ZCFSeat, toAmounts: AmountKeywordRecord): TransferPart;
 export function atomicTransfer(zcf: ZCF, fromSeat?: ZCFSeat | undefined, toSeat?: ZCFSeat | undefined, fromAmounts?: AmountKeywordRecord | undefined, toAmounts?: AmountKeywordRecord | undefined): void;
-export type TransferPart = [
-    fromSeat?: ZCFSeat,
-    toSeat?: ZCFSeat,
-    fromAmounts?: AmountKeywordRecord,
-    toAmounts?: AmountKeywordRecord
-];
 //# sourceMappingURL=atomicTransfer.d.ts.map

package/src/contractSupport/atomicTransfer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomicTransfer.d.ts","sourceRoot":"","sources":["atomicTransfer.js"],"names":[],"mappings":"AAMA,iEAGE;AAgDK,qCAHI,GAAG,aACH,cAAc,QA+ExB;AAcM,mCAJI,OAAO,eACP,mBAAmB,gBAIc;AAcrC,+BAJI,OAAO,aACP,mBAAmB,gBAIqB;AAW5C,oCANI,GAAG,kKAYiE;2BAzKlE;IACZ,QAAY,CAAC,EAAE,OAAO;IACtB,MAAU,CAAC,EAAE,OAAO;IACpB,WAAe,CAAC,EAAE,mBAAmB;IACrC,SAAa,CAAC,EAAE,mBAAmB;CAChC"}
+{"version":3,"file":"atomicTransfer.d.ts","sourceRoot":"","sources":["atomicTransfer.js"],"names":[],"mappings":"AAGA,iEAGE;AAyCK,qCAHI,GAAG,aACH,cAAc,QAIxB;AAcM,mCAJI,OAAO,eACP,mBAAmB,gBAIc;AAcrC,+BAJI,OAAO,aACP,mBAAmB,gBAIqB;AAW5C,oCANI,GAAG,kKAYgE"}