docs: drop all references to reallocate() and its helpers (#1266)

* docs: drop all references to reallocate() and its helpers

* chore: generate svg, and clean up a URL

---------

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Author: Chris-Hibbert

.wordlist.txt

@@ -226,6 +226,7 @@ daveSwapProposal
 daveSwapSeat
 declaratively
 declineOffer
+decrementBy
 defaultAcceptanceMsg
 DeFi
 delaySecs
@@ -319,6 +320,7 @@ getPurse
 getPurseIssuer
 getPurses
 getRefund
+getStagedAllocation
 getTerms
 getUpdateSince
 getUse
@@ -331,6 +333,7 @@ grabSharedMap
 HandledPromise
 HandledPromises
 hasExited
+hasStagedAllocation
 heroImage
 hookArgs
 hookMethod
@@ -347,6 +350,7 @@ idToOfferHandle
 iframe
 implementating
 importBundleSource
+incrementBy
 init
 inspectable
 inspectCode

main/guides/getting-started/assets/zoe-simp.mmd

@@ -9,6 +9,6 @@ end
     agent->>+zoe: offer(invitation, {give, want}, pmts)
     zoe-->>agent: userSeat
     zoe->>+contract: {give, want}
-    contract-->>-zoe: reallocate()
+    contract-->>-zoe: atomicRearrange()
     agent->>zoe: E(userSeat).getPayouts()
     zoe-->>-agent: payout payments

main/guides/getting-started/assets/zoe-simp.svg

@@ -21,7 +21,7 @@ Trading with a contract using Zoe typically goes through these steps:
 1. Parties call [E(zoe).offer(invitation, proposal, assets)](/reference/zoe-api/zoe#e-zoe-offer-invitation-proposal-paymentpkeywordrecord-offerargs). Zoe escrows the assets.
 2. Zoe relays the proposal to the contract identified in the invitation.
 3. The contract handles proposals using its custom business logic.
-4. The contract instructs Zoe to [reallocate](/reference/zoe-api/zoe-contract-facet#zcf-reallocate-seats) assets among the parties.
+4. The contract instructs Zoe to [reallocate](/reference/zoe-api/zoe-contract-facet#zcf-atomicrearrange-transfers) assets among the parties.
 5. The contract completes (aka [exits](/reference/zoe-api/zcfseat#azcfseat-exit-completion)) the offers.
 6. Zoe pays out assets to the parties.
 

main/guides/zoe/index.md

@@ -130,126 +130,3 @@ It checks whether **newAllocation** fully satisfies
 **proposal.give** (giving a refund) or whether it fully satisfies
 **proposal.want**. Both can be fully satisfied. See the ZoeHelper
 [**satisfies()**](./zoe-helpers#satisfies-zcf-seat-update) method for more details.
-
-::: warning DEPRECATED
-
-## aZCFSeat.getStagedAllocation()
-
-- Returns: **[Allocation](./zoe-data-types#allocation)**
-
-Gets and returns the **stagedAllocation**, which is the **Allocation** committed if the seat is
-reallocated over, if offer safety holds, and rights are conserved.
-
-**Note**: This method has been deprecated. Use **[atomicRearrange()](./zoe-helpers#atomicrearrange-zcf-transfers)** instead.
-:::
-
-::: warning DEPRECATED
-
-## aZCFSeat.hasStagedAllocation()
-
-- Returns: **Boolean**
-
-Returns **true** if there is a staged allocation, i.e., whether **ZCFSeat.incrementBy()** or
-**ZCFSeat.decrementBy()** has been called and **ZCFSeat.clear()**
-and **reallocate()** have not. Otherwise returns **false**.
-
-**Note**: This method has been deprecated. Use **[atomicRearrange()](./zoe-helpers#atomicrearrange-zcf-transfers)** instead.
-:::
-
-::: warning DEPRECATED
-
-## aZCFSeat.incrementBy(amountKeywordRecord)
-
-- **amountKeywordRecord**: **[AmountKeywordRecord](./zoe-data-types#keywordrecord)**
-- Returns: **AmountKeyRecord**
-
-Adds the **amountKeywordRecord** argument to the **ZCFseat**'s staged allocation and returns the
-same **amountKeywordRecord** so it can be reused in another call. Note that this lets
-**zcfSeat1.incrementBy(zcfSeat2.decrementBy(amountKeywordRecord))** work as a usage pattern.
-
-Note that you can add amounts to original or staged allocations which do not have the
-specified **[Keyword](./zoe-data-types#keyword)** for the amount. The result is for the **Keyword** and amount to become part
-of the allocation. For example, if we start with a new, empty, allocation:
-
-```js
-// Make an empty seat.
-const { zcfSeat: zcfSeat1 } = zcf.makeEmptySeatKit();
-// The allocation is currently empty, i.e. `{}`
-const stagedAllocation = zcfSeat1.getStagedAllocation();
-const empty = AmountMath.makeEmpty(brand, AssetKind.NAT);
-// Try to incrementBy empty. This succeeds, and the keyword is added
-// with an empty amount.
-zcfSeat1.incrementBy({ IST: empty });
-t.deepEqual(zcfSeat1.getStagedAllocation(), { IST: empty });
-```
-
-While this incremented the allocation by an empty amount, any amount would have been added to the
-allocation in the same way.
-
-**Note**: This method has been deprecated. Use **[atomicRearrange()](./zoe-helpers#atomicrearrange-zcf-transfers)** instead.
-:::
-
-::: warning DEPRECATED
-
-## aZCFSeat.decrementBy(amountKeywordRecord)
-
-- **amountKeywordRecord**: **[AmountKeywordRecord](./zoe-data-types#keywordrecord)**
-- Returns: **AmountKeywordRecord**
-
-Subtracts the **amountKeywordRecord** argument from the **ZCFseat**'s staged allocation and returns the
-same **amountKeywordRecord** so it can be used in another call. Note that this lets
-**zcfSeat1.incrementBy(zcfSeat2.decrementBy(amountKeywordRecord))** work as a usage pattern.
-
-The amounts to subtract cannot be greater than the staged allocation (i.e., negative
-results are not allowed).
-
-**decrementBy()** has different behavior from **incrementBy()** if the original or staged allocation
-does not have the **[Keyword](./zoe-data-types#keyword)** specified for an amount in the **amountKeywordRecord** argument. There are two
-cases to look at; when the corresponding amount to subtract is empty and when it isn't.
-
-```js
-// Make an empty seat.
-const { zcfSeat: zcfSeat1 } = zcf.makeEmptySeatKit();
-// The allocation is currently {}
-const stagedAllocation = zcfSeat1.getStagedAllocation();
-const empty = AmountMath.makeEmpty(brand, AssetKind.NAT);
-// decrementBy empty does not throw, and does not add a keyword
-zcfSeat1.decrementBy({ IST: empty });
-t.deepEqual(zcfSeat1.getStagedAllocation(), {});
-```
-
-The result here is **not** to add the **Keyword** to the allocation. It wasn't there to begin with, and
-the operation was to try to subtract it from the allocation. Subtracting something that's not there
-does not add it to the original value. For example, if I tell you I'm taking away the Mona Lisa from
-you and you are not the Louvre and don't have it, you still don't have it after I try to take it away.
-In the above example, trying to take away an empty amount from an empty allocation is effectively a
-null operation; the allocation is still empty, didn't add the new **Keyword**, and no error is thrown.
-
-However, decrementing a non-empty amount from an empty allocation has a different result. For example:
-
-```js
-// Make an empty seat.
-const { zcfSeat: zcfSeat1 } = zcf.makeEmptySeatKit();
-// The allocation is currently {}
-const stagedAllocation = zcfSeat1.getStagedAllocation();
-// decrementBy throws for a keyword that does not exist on the stagedAllocation and a non-empty amount
-zcfSeat1.decrementBy({ IST: runFee });
-```
-
-It throws an error because you cannot subtract something from nothing. So trying to decrement an empty
-allocation by a non-empty amount is an error, while decrementing an empty allocation by an empty amount
-is effectively a null operation with no effects.
-
-**Note**: This method has been deprecated. Use **[atomicRearrange()](./zoe-helpers#atomicrearrange-zcf-transfers)** instead.
-:::
-
-::: warning DEPRECATED
-
-## aZCFSeat.clear()
-
-- Returns: None.
-
-Deletes the **ZCFSeat**'s current staged allocation, if any,
-
-**Note**: This method has been deprecated. Use **[atomicRearrange()](./zoe-helpers#atomicrearrange-zcf-transfers)** instead.
-:::

main/reference/zoe-api/zcfseat.md

@@ -21,13 +21,6 @@ constraints. If these constraints are all met, then the reallocation happens ato
 error is thrown and none of the proposed changes has any effect. The constraints are as follows.
 
 - All the mentioned seats are still live.
-- There aren't any outstanding stagings for any of the mentioned seats.
-
-  Stagings are a reallocation mechanism that has been
-  deprecated in favor of this **atomicRearrange()** function.
-  To prevent confusion, each reallocation can only be
-  expressed in the old way or the new way, but not a mixture.
-
 - Overall conservation must be maintained. In other words, the reallocated
   **[Amounts](/reference/ertp-api/ertp-data-types#amount)** must balance out.
 - Offer Safety is preserved for each seat. That means reallocations can only take assets from a seat
@@ -392,55 +385,3 @@ Returns all the strings that have been disabled for use in invitations, if any.
 A contract's invitations may be disabled using the
 **[zcf.setOfferFilter()](#zcf-setofferfilter-strings)** method when governance determines
 that they provide a vulnerability.
-
-::: warning DEPRECATED
-
-## zcf.reallocate(seats)
-
-- **seats**: **[ZCFSeats](./zcfseat)[]** (at least two)
-- Returns: None.
-
-**zcf.reallocate()** commits the staged allocations for each of its seat arguments,
-making their staged allocations their current allocations. **zcf.reallocate()** then
-transfers the assets escrowed in Zoe from one seat to another. Importantly, the assets
-stay escrowed, with only the internal Zoe accounting of each seat's allocation changed.
-
-There must be at least two **ZCFSeats** in the array argument. Every **ZCFSeat**
-with a staged allocation must be included in the argument array or an error
-is thrown. If any seat in the argument array does not have a staged allocation,
-an error is thrown.
-
-On commit, the staged allocations become the seats' current allocations and
-the staged allocations are deleted.
-
-Note: **reallocate()** is an _atomic operation_. To enforce offer safety,
-it will never abort part way through. It will completely succeed or it will
-fail before any seats have their current allocation changed.
-
-The reallocation only succeeds if it:
-
-1. Conserves rights (the specified **[Amounts](/reference/ertp-api/ertp-data-types#amount)** have the same total value as the
-   current total amount)
-2. Is 'offer-safe' for all parties involved.
-
-The reallocation is partial, only applying to the **seats** in the
-argument array. By induction, if rights conservation and
-offer safety hold before, they hold after a safe reallocation.
-
-This is true even though we only re-validate for **seats** whose
-allocations change. A reallocation can only effect offer safety for
-those **seats**, and since rights are conserved for the change, overall
-rights are unchanged.
-
-**zcf.reallocate()** throws this error:
-
-- **reallocating must be done over two or more seats**
-
-```js
-sellerSeat.incrementBy(buyerSeat.decrementBy({ Money: providedMoney }));
-buyerSeat.incrementBy(sellerSeat.decrementBy({ Items: wantedItems }));
-zcf.reallocate(buyerSeat, sellerSeat);
-```
-
-**Note**: This method has been deprecated. Use **[atomicRearrange()](./#atomicrearrange-transfers)** instead.
-:::

main/reference/zoe-api/zoe-contract-facet.md

@@ -27,13 +27,6 @@ constraints. If these constraints are all met, then the reallocation happens ato
 error is thrown and none of the proposed changes has any effect. The constraints are as follows.
 
 - All the mentioned seats are still live.
-- There aren't any outstanding stagings for any of the mentioned seats.
-
-  Stagings are a reallocation mechanism that has been
-  deprecated in favor of this **atomicRearrange()** function.
-  To prevent confusion, each reallocation can only be
-  expressed in the old way or the new way, but not a mixture.
-
 - Overall conservation must be maintained. In other words, the reallocated
   **[Amounts](/reference/ertp-api/ertp-data-types#amount)** must balance out.
 - Offer Safety is preserved for each seat. That means reallocations can only take assets from a seat
@@ -80,13 +73,6 @@ met, then the reallocation happens atomically. Otherwise an error is thrown and
 changes has any effect. The constraints are as follows.
 
 - All the mentioned seats are still live.
-- There aren't any outstanding stagings for any of the mentioned seats.
-
-  Stagings are a reallocation mechanism that has been
-  deprecated in favor of this **atomicRearrange()** function.
-  To prevent confusion, each reallocation can only be
-  expressed in the old way or the new way, but not a mixture.
-
 - Overall conservation must be maintained. In other words, the reallocated
   **[Amounts](/reference/ertp-api/ertp-data-types#amount)** must balance out.
 - Offer Safety is preserved for each seat. That means reallocations can only take assets from a seat