@agoric/zoe 0.26.3-u15.0 → 0.26.3-u16.1

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

@@ -0,0 +1,271 @@
+/// <reference types="@agoric/ertp/exported" />
+/// <reference types="@endo/pass-style" />
+/// <reference path="../zoeService/utils.d.ts" />
+
+/**
+ * Any passable non-thenable. Often an explanatory string.
+ */
+type Completion = import('@endo/pass-style').Passable;
+type ZCFMakeEmptySeatKit = (exit?: ExitRule | undefined) => ZcfSeatKit;
+
+type InvitationAmount = Amount<'set', InvitationDetails>;
+
+/**
+ * Zoe Contract Facet
+ *
+ * The Zoe interface specific to a contract instance. The Zoe Contract
+ * Facet is an API object used by running contract instances to access
+ * the Zoe state for that instance. The Zoe Contract Facet is accessed
+ * synchronously from within the contract, and usually is referred to
+ * 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.
+   */
+  reallocate: Reallocate;
+  /**
+   * - check
+   * whether a keyword is valid and unique and could be added in
+   * `saveIssuer`
+   */
+  assertUniqueKeyword: (keyword: Keyword) => void;
+  /**
+   * Informs Zoe about an issuer and returns a promise for acknowledging
+   * when the issuer is added and ready.
+   *
+   * @returns the AmountMath and brand synchronously accessible after
+   * saving
+   */
+  saveIssuer: <I extends Issuer>(
+    issuerP: ERef<I>,
+    keyword: Keyword,
+  ) => Promise<I extends Issuer<infer K, infer M> ? IssuerRecord<K, M> : never>;
+
+  /**
+   * Make a credible Zoe invitation for a particular smart contract
+   * indicated by the `instance` in the details of the invitation. Zoe
+   * also puts the `installation` and a unique `handle` in the details
+   * of the invitation. The contract must provide a `description` for
+   * the invitation and should include whatever information is necessary
+   * for a potential buyer of the invitation to know what they are
+   * getting in the `customDetails`. `customDetails` will be
+   * placed in the details of the invitation.
+   */
+  makeInvitation: <R, A = undefined>(
+    offerHandler: OfferHandler<ERef<R>, A>,
+    description: string,
+    customDetails?: object,
+    proposalShape?: Pattern,
+  ) => Promise<Invitation<R, A>>;
+  shutdown: (completion: Completion) => void;
+  shutdownWithFailure: import('@agoric/swingset-vat').ShutdownWithFailure;
+  getZoeService: () => ERef<ZoeService>;
+  getInvitationIssuer: () => Issuer<'set'>;
+  getTerms: () => StandardTerms & CT;
+  getBrandForIssuer: <K extends AssetKind>(issuer: Issuer<K>) => Brand<K>;
+  getIssuerForBrand: <K_1 extends AssetKind>(brand: Brand<K_1>) => Issuer<K_1>;
+  getAssetKind: GetAssetKindByBrand;
+  makeZCFMint: <K_2 extends AssetKind = 'nat'>(
+    keyword: Keyword,
+    assetKind?: K_2 | undefined,
+    displayInfo?: AdditionalDisplayInfo,
+    options?: import('@agoric/ertp').IssuerOptionsRecord,
+  ) => Promise<ZCFMint<K_2>>;
+  registerFeeMint: ZCFRegisterFeeMint;
+  makeEmptySeatKit: ZCFMakeEmptySeatKit;
+  setTestJig: SetTestJig;
+  stopAcceptingOffers: () => Promise<void>;
+  setOfferFilter: (strings: Array<string>) => Promise<void>;
+  getOfferFilter: () => Promise<Array<string>>;
+  getInstance: () => Instance;
+};
+/**
+ * The contract can reallocate over seats, which commits the staged
+ * allocation for each seat. On commit, the staged allocation becomes
+ * the current allocation and the staged allocation is deleted.
+ *
+ * The reallocation will only succeed if the reallocation 1) conserves
+ * rights (the amounts specified have the same total value as the
+ * current total amount), and 2) is 'offer-safe' for all parties
+ * involved. All seats that have staged allocations must be included
+ * as arguments to `reallocate`, or an error is thrown. Additionally,
+ * an error is thrown if any seats included in `reallocate` do not
+ * have a staged allocation.
+ *
+ * The reallocation is partial, meaning that it applies only to the
+ * seats passed in as arguments. By induction, if rights conservation
+ * and offer safety hold before, they will hold after a safe
+ * reallocation, even though we only re-validate for the seats whose
+ * allocations will change. Since rights are conserved for the change,
+ * overall rights will be unchanged, and a reallocation can only
+ * 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,
+];
+
+type ZCFRegisterFeeMint = (
+  keyword: Keyword,
+  allegedFeeMintAccess: FeeMintAccess,
+) => Promise<ZCFMint<'nat'>>;
+/**
+ * Provide a jig object for testing purposes only.
+ *
+ * The contract code provides a callback whose return result will
+ * be made available to the test that started this contract. The
+ * supplied callback will only be called in a testing context,
+ * never in production; i.e., it is only called if `testJigSetter`
+ * was supplied.
+ *
+ * If no `testFn` is supplied, then an empty jig will be used.
+ * An additional `zcf` property set to the current ContractFacet
+ * will be appended to the returned jig object (overriding any
+ * provided by the `testFn`).
+ */
+type SetTestJig = (testFn?: () => Record<string, unknown>) => void;
+type ZCFMint<K extends AssetKind = AssetKind> = {
+  getIssuerRecord: () => IssuerRecord<K>;
+  /**
+   * All the amounts in gains must be of this ZCFMint's brand.
+   * The gains' keywords are in the namespace of that seat.
+   * Add the gains to that seat's allocation.
+   * The resulting state must be offer safe. (Currently, increasing assets can
+   * never violate offer safety anyway.)
+   *
+   * Mint that amount of assets into the pooled purse.
+   * If a seat is provided, it is returned. Otherwise a new seat is
+   * returned.
+   */
+  mintGains: (gains: AmountKeywordRecord, zcfSeat?: ZCFSeat) => ZCFSeat;
+  /**
+   * All the amounts in losses must be of this ZCFMint's brand.
+   * The losses' keywords are in the namespace of that seat.
+   * Subtract losses from that seat's allocation.
+   * The resulting state must be offer safe.
+   *
+   * Burn that amount of assets from the pooled purse.
+   */
+  burnLosses: (losses: AmountKeywordRecord, zcfSeat: ZCFSeat) => void;
+};
+/**
+ * fail called with the reason for this failure, where reason is
+ * normally an instanceof Error.
+ */
+type ZCFSeatFail = (reason: unknown) => Error;
+type ZCFSeat = import('@endo/pass-style').RemotableObject & {
+  exit: (completion?: Completion) => void;
+  fail: ZCFSeatFail;
+  getSubscriber: () => Promise<Subscriber<Allocation>>;
+  hasExited: () => boolean;
+  getProposal: () => ProposalRecord;
+  /**
+   * @param brand used for filling in an empty amount if the `keyword`
+   * is not present in the allocation
+   */
+  getAmountAllocated: <B extends Brand>(
+    keyword: Keyword,
+    brand?: B,
+  ) => B extends Brand<infer K> ? Amount<K> : Amount;
+  getCurrentAllocation: () => Allocation;
+  /**
+   * @deprecated Use atomicRearrange instead
+   */
+  getStagedAllocation: () => Allocation;
+  /**
+   * @deprecated Use atomicRearrange instead
+   */
+  hasStagedAllocation: () => boolean;
+  isOfferSafe: (newAllocation: Allocation) => boolean;
+  /**
+   * @deprecated Use atomicRearrange instead
+   */
+  incrementBy: (
+    amountKeywordRecord: AmountKeywordRecord,
+  ) => AmountKeywordRecord;
+  /**
+   * @deprecated Use atomicRearrange instead
+   */
+  decrementBy: (
+    amountKeywordRecord: AmountKeywordRecord,
+  ) => AmountKeywordRecord;
+  /**
+   * @deprecated Use atomicRearrange instead
+   */
+  clear: () => void;
+};
+type ZcfSeatKit = {
+  zcfSeat: ZCFSeat;
+  userSeat: ERef<UserSeat>;
+};
+type HandleOffer<OR extends unknown, OA> = (seat: ZCFSeat, offerArgs: OA) => OR;
+type OfferHandler<OR extends unknown = unknown, OA = never> =
+  | HandleOffer<OR, OA>
+  | {
+      handle: HandleOffer<OR, OA>;
+    };
+type ContractMeta<
+  SF extends // import inline to maintain ambient mode
+    import('../zoeService/utils').ContractStartFunction = import('../zoeService/utils').ContractStartFunction,
+> = {
+  customTermsShape?: Record<
+    Parameters<SF>[0] extends ZCF<infer CT> ? keyof CT : never,
+    Pattern
+  >;
+  privateArgsShape?: { [K in keyof Parameters<SF>[1]]: Pattern };
+  /**
+   * - `none` means that the contract is not upgradable.
+   * - `canUpgrade` means this code can perform an upgrade
+   * - `canBeUpgraded` means that the contract stores kinds durably such that the next version can upgrade
+   */
+  upgradability?: 'none' | '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,
+  baggage: import('@agoric/vat-data').Baggage,
+) => ContractStartFnResult<PF, CF>;
+type ContractStartFnResult<PF, CF> = {
+  publicFacet?: PF;
+  creatorFacet?: CF;
+  creatorInvitation?: Promise<Invitation<any, any>> | undefined;
+};
+
+// XXX redef, losing documentation
+type ContractOf<S extends (...args: any) => any> =
+  import('../zoeService/utils').ContractOf<S>;
+type AdminFacet = import('../zoeService/utils').AdminFacet<any>;
+
+declare const OfferReturn: unique symbol;
+declare const OfferArgs: unique symbol;
+type Invitation<R = unknown, A = undefined> = Payment<
+  'set',
+  InvitationDetails
+> & {
+  // because TS is structural, without this the generic is ignored
+  [OfferReturn]?: R;
+  [OfferArgs]?: A;
+};

package/src/contractFacet/types-ambient.js

@@ -0,0 +1 @@
+// Dummy file for .d.ts twin to declare ambients

package/src/contractFacet/vatRoot.d.ts

@@ -3,12 +3,12 @@
  * @param {{contractBundleCap: BundleCap, zoeService: ZoeService, invitationIssuer: Issuer<'set'>, privateArgs?: any}} vatParameters
  * @param {import('@agoric/vat-data').Baggage} baggage
  */
-export function buildRootObject(powers: import("@agoric/swingset-vat").TerminationVatPowers & {
+export function buildRootObject(powers: VatPowers & {
     testJigSetter: TestJigSetter;
 }, vatParameters: {
     contractBundleCap: BundleCap;
     zoeService: ZoeService;
-    invitationIssuer: Issuer<'set'>;
+    invitationIssuer: Issuer<"set">;
     privateArgs?: any;
-}, baggage: MapStore<string, unknown>): Promise<import("@endo/eventual-send").RemotableBrand<{}, {}>>;
+}, baggage: import("@agoric/vat-data").Baggage): Promise<import("@endo/marshal").RemotableObject<`Alleged: ${string}`> & import("@endo/eventual-send").RemotableBrand<{}, {}>>;
 //# sourceMappingURL=vatRoot.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vatRoot.d.ts","sourceRoot":"","sources":["vatRoot.js"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH;mBAJwC,aAAa;;uBACtB,SAAS;gBAAc,UAAU;sBAAoB,OAAO,KAAK,CAAC;kBAAgB,GAAG;sGAgEnH"}
+{"version":3,"file":"vatRoot.d.ts","sourceRoot":"","sources":["vatRoot.js"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,wCAJW,SAAS,GAAG;IAAE,aAAa,EAAE,aAAa,CAAA;CAAE,iBAC5C;IAAC,iBAAiB,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,UAAU,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAAC,WAAW,CAAC,EAAE,GAAG,CAAA;CAAC,WAC1G,OAAO,kBAAkB,EAAE,OAAO,iIA+D5C"}

package/src/contractFacet/zcfMint.d.ts

@@ -1,5 +1,7 @@
-export function sumAmountKeywordRecord<K extends AssetKind>(amr: AmountKeywordRecord, issuerRecord: IssuerRecord<K>): Amount<K>;
-export function prepareZcMint(zcfBaggage: MapStore<string, unknown>, recordIssuer: (keyword: string, issuerRecord: IssuerRecord) => void, getAssetKindByBrand: GetAssetKindByBrand, makeEmptySeatKit: (exit?: undefined) => {
+export function sumAmountKeywordRecord(amr: AmountKeywordRecord, issuerRecord: IssuerRecord): Amount;
+export function prepareZcMint(zcfBaggage: import("@agoric/vat-data").Baggage, recordIssuer: {
+    (keyword: string, issuerRecord: IssuerRecord): void;
+}, getAssetKindByBrand: GetAssetKindByBrand, makeEmptySeatKit: (exit?: undefined) => {
     zcfSeat: any;
     userSeat: Promise<UserSeat>;
 }, reallocator: ZcfMintReallocator): <K extends AssetKind>(keyword: string, zoeMintP: ERef<ZoeMint<K>>) => Promise<ZCFMint<K>>;

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

@@ -1 +1 @@
-{"version":3,"file":"zcfMint.d.ts","sourceRoot":"","sources":["zcfMint.js"],"names":[],"mappings":"AAqBO,iEAJI,mBAAmB,4CAc7B;AASM,6FALgB,MAAM,gBAAgB,YAAY,KAAG,IAAI,uBACrD,mBAAmB,4BACX,SAAS,KAAK;IAAE,OAAO,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,QAAQ,QAAQ,CAAC,CAAA;CAAE,eACnE,kBAAkB,kCAkHhB,MAAM,qDAalB"}
+{"version":3,"file":"zcfMint.d.ts","sourceRoot":"","sources":["zcfMint.js"],"names":[],"mappings":"AAqBO,4CAJI,mBAAmB,gBACnB,YAAY,GACV,MAAM,CAYlB;AASM,0CANI,OAAO,kBAAkB,EAAE,OAAO,gBAClC;IAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,IAAI,CAAA;CAAE,uBACvD,mBAAmB,oBACnB,CAAC,IAAI,CAAC,EAAE,SAAS,KAAK;IAAE,OAAO,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;CAAE,eACnE,kBAAkB,IAiHF,CAAC,SAAZ,SAAU,WACb,MAAM,YACN,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KACd,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAWjC"}

package/src/contractFacet/zcfMint.js

@@ -1,3 +1,4 @@
+/* eslint @typescript-eslint/no-floating-promises: "warn" */
 import { AmountMath } from '@agoric/ertp';
 import { prepareExoClass } from '@agoric/vat-data';
 import { E } from '@endo/eventual-send';
@@ -9,15 +10,14 @@ import { addToAllocation, subtractFromAllocation } from './allocationMath.js';
 import '../internal-types.js';
 import { ZcfMintI } from '../typeGuards.js';
 import './internal-types.js';
-import './types.js';
+import './types-ambient.js';
 
 const { Fail } = assert;
 
 /**
- * @template {AssetKind} K
  * @param {AmountKeywordRecord} amr
- * @param {IssuerRecord<K>} issuerRecord
- * @returns {Amount<K>}
+ * @param {IssuerRecord} issuerRecord
+ * @returns {Amount}
  */
 export const sumAmountKeywordRecord = (amr, issuerRecord) => {
   const empty = AmountMath.makeEmpty(
@@ -106,7 +106,7 @@ export const prepareZcMint = (
         // committed atomically, but it is not a disaster if they are
         // not. If we minted only, no one would ever get those
         // invisibly-minted assets.
-        E(zoeMint).mintAndEscrow(totalToMint);
+        void E(zoeMint).mintAndEscrow(totalToMint);
         reallocator.reallocate(zcfSeat, allocationPlusGains);
         return zcfSeat;
       },
@@ -143,7 +143,7 @@ export const prepareZcMint = (
         // not. If we only commit the allocationMinusLosses no one would
         // ever get the unburned assets.
         reallocator.reallocate(zcfSeat, allocationMinusLosses);
-        E(zoeMint).withdrawAndBurn(totalToBurn);
+        void E(zoeMint).withdrawAndBurn(totalToBurn);
       },
     },
   );

package/src/contractFacet/zcfSeat.d.ts

@@ -1,3 +1,5 @@
-/** @type {CreateSeatManager} */
-export const createSeatManager: CreateSeatManager;
+export function createSeatManager(zoeInstanceAdmin: ERef<ZoeInstanceAdmin>, getAssetKindByBrand: GetAssetKindByBrand, shutdownWithFailure: import("@agoric/swingset-vat").ShutdownWithFailure, zcfBaggage: import("@agoric/vat-data").Baggage): {
+    seatManager: ZcfSeatManager;
+    zcfMintReallocator: ZcfMintReallocator;
+};
 //# sourceMappingURL=zcfSeat.d.ts.map

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":"AAqCO,oDANI,IAAI,CAAC,gBAAgB,CAAC,uBACtB,mBAAmB,uBACnB,OAAO,sBAAsB,EAAE,mBAAmB,cAClD,OAAO,kBAAkB,EAAE,OAAO,GAChC;IAAE,WAAW,EAAE,cAAc,CAAC;IAAC,kBAAkB,EAAE,kBAAkB,CAAA;CAAE,CAsenF"}

package/src/contractFacet/zcfSeat.js

@@ -1,10 +1,11 @@
+/* eslint @typescript-eslint/no-floating-promises: "warn" */
 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,10 +20,21 @@ import {
   SeatDataShape,
   SeatShape,
 } from '../typeGuards.js';
+import { makeAllocationMap } from './reallocate.js';
+import { TransferPartShape } from '../contractSupport/atomicTransfer.js';
 
 const { Fail } = assert;
 
-/** @type {CreateSeatManager} */
+/**
+ * The SeatManager holds the active zcfSeats and can reallocate and
+ * make new zcfSeats.
+ *
+ * @param {ERef<ZoeInstanceAdmin>} zoeInstanceAdmin
+ * @param {GetAssetKindByBrand} getAssetKindByBrand
+ * @param {import('@agoric/swingset-vat').ShutdownWithFailure} shutdownWithFailure
+ * @param {import('@agoric/vat-data').Baggage} zcfBaggage
+ * @returns {{ seatManager: ZcfSeatManager, zcfMintReallocator: ZcfMintReallocator }}
+ */
 export const createSeatManager = (
   zoeInstanceAdmin,
   getAssetKindByBrand,
@@ -155,7 +167,11 @@ export const createSeatManager = (
         assertActive(self);
         assertNoStagedAllocation(self);
         doExitSeat(self);
-        E(zoeInstanceAdmin).exitSeat(zcfSeatToSeatHandle.get(self), completion);
+        void E(zoeInstanceAdmin).exitSeat(
+          zcfSeatToSeatHandle.get(self),
+          completion,
+        );
+        zcfSeatToSeatHandle.delete(self);
       },
       fail(
         reason = Error(
@@ -172,10 +188,11 @@ export const createSeatManager = (
         }
         if (!hasExited(self)) {
           doExitSeat(self);
-          E(zoeInstanceAdmin).failSeat(
+          void E(zoeInstanceAdmin).failSeat(
             zcfSeatToSeatHandle.get(self),
             harden(reason),
           );
+          zcfSeatToSeatHandle.delete(self);
         }
         return reason;
       },
@@ -184,15 +201,22 @@ export const createSeatManager = (
         return hasExited(self);
       },
 
+      /**
+       * @type {ZCFSeat['getAmountAllocated']}
+       */
       getAmountAllocated(keyword, brand) {
         const { self } = this;
         assertActive(self);
         const currentAllocation = getCurrentAllocation(self);
         if (currentAllocation[keyword] !== undefined) {
+          // @ts-expect-error never checks brand
           return currentAllocation[keyword];
         }
-        brand || Fail`A brand must be supplied when the keyword is not defined`;
+        if (!brand) {
+          throw Fail`A brand must be supplied when the keyword is not defined`;
+        }
         const assetKind = getAssetKindByBrand(brand);
+        // @ts-expect-error cast
         return AmountMath.makeEmpty(brand, assetKind);
       },
       getCurrentAllocation() {
@@ -214,6 +238,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 +255,10 @@ export const createSeatManager = (
         );
         return amountKeywordRecord;
       },
+      /**
+       * @deprecated switch to zcf.atomicRearrange()
+       * @param {AmountKeywordRecord} amountKeywordRecord
+       */
       decrementBy(amountKeywordRecord) {
         const { self } = this;
         assertActive(self);
@@ -265,6 +297,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 +322,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

@@ -1,3 +1,2 @@
-export function makeZCFZygote(powers: VatPowers, zoeService: ERef<ZoeService>, invitationIssuer: Issuer<'set'>, testJigSetter: TestJigSetter, contractBundleCap: BundleCap, zcfBaggage?: MapStore<string, unknown>): Promise<ZCFZygote>;
-export type IssuerOptionsRecord = import('@agoric/ertp').IssuerOptionsRecord;
+export function makeZCFZygote(powers: VatPowers, zoeService: ERef<ZoeService>, invitationIssuer: Issuer<"set">, testJigSetter: TestJigSetter, contractBundleCap: BundleCap, zcfBaggage?: import("@agoric/vat-data").Baggage): Promise<ZCFZygote>;
 //# sourceMappingURL=zcfZygote.d.ts.map

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,CAia9B;kCAhba,OAAO,cAAc,EAAE,mBAAmB"}
+{"version":3,"file":"zcfZygote.d.ts","sourceRoot":"","sources":["zcfZygote.js"],"names":[],"mappings":"AAiDO,sCARI,SAAS,cACT,IAAI,CAAC,UAAU,CAAC,oBAChB,MAAM,CAAC,KAAK,CAAC,iBACb,aAAa,qBACb,SAAS,eACT,OAAO,kBAAkB,EAAE,OAAO,GAChC,OAAO,CAAC,SAAS,CAAC,CAkd9B"}