Reallocate api patch #519
Reallocate api patch #519
Conversation
Added new Reallocate API methods to ZCF.Seat: incrementBy() decrementBy() clear() getStagedAllocation() hasStagedAllocation()
main/zoe/api/zoe-contract-facet.md
Outdated
| Note that ZoeHelpers [`trade()`](./zoe-helpers.md#trade-zcf-left-right-lefthasexitedmsg-righthasexitedmsg) | ||
| and [`swap()`](./zoe-helpers.md#swap-zcf-leftseat-rightseat-lefthasexitedmsg-righthasexitedmsg) might | ||
| be easier to use for simple cases. | ||
| ### `ZCFSeat.stage(newAllocation)`**DEPRECATED 22-06-01** |
There was a problem hiding this comment.
I think it's going to be gone, not deprecated
There was a problem hiding this comment.
That's a good point. We should probably distinguish between methods that exist and are deprecated, and methods that are gone. I think at this point, we should remove anything from documentation that is removed in the code.
There was a problem hiding this comment.
Although at some point, we do want to start leaving indicators in the docs for a while when we drop something, since someone will probably have been using it.
There was a problem hiding this comment.
Yup, agreed. I think we should start that after we finish this string of known breaking changes for Zoe and ERTP.
main/zoe/api/zoe-contract-facet.md
Outdated
| The reallocation is partial, only applying to `seats` associated | ||
| with the `seatStagings`. By induction, if rights conservation and | ||
| offer safety hold before, they hold after a safe reallocation. |
There was a problem hiding this comment.
We need to say something new about offer safety. The existing versions verify offer safety as each staging is created, but the new approach is unable to do that, so offer safety is checked on reallocate, and can cause the transaction to fail.
There was a problem hiding this comment.
I don't think we need to say anything new about offer safety. We just need to remove anything that says "offer safety is checked at staging". Checking offer safety at the reallocation step is the model we had originally, and I don't think any contracts will have problems moving back to that model (nor will they notice).
|
Commenting here because this file wasn't yet included in this PR, but we'll need to remove the "SeatStagings" entry on line 429 of glossary/README.md |
There was a problem hiding this comment.
I think we're pretty close on the reallocate API changes, but let's move working_with_ZCFSeats.md to a separate PR, as I think that will take a lot longer than our timeline for the reallocate change landing. I only reviewed to line 84 or so of working_with_ZCFSeats.md.
main/zoe/api/zoe-contract-facet.md
Outdated
| - Adds the `amountKeywordRecord` argument to the `ZCFseat`'s staged allocation and returns the | ||
| resulting new staged allocation value. |
There was a problem hiding this comment.
| - Adds the `amountKeywordRecord` argument to the `ZCFseat`'s staged allocation and returns the | |
| resulting new staged allocation value. | |
| - Adds the `amountKeywordRecord` argument to the `ZCFseat`'s staged allocation and returns the | |
| same `amountKeywordRecord` so it can be reused in another call. |
incrementBy returns the same exact amountKeywordRecord that was passed to it, which is why incrementBy(decrementBy()) works as a pattern of use. Maybe we should explain this pattern of use here?
main/zoe/api/zoe-contract-facet.md
Outdated
| Note that ZoeHelpers [`trade()`](./zoe-helpers.md#trade-zcf-left-right-lefthasexitedmsg-righthasexitedmsg) | ||
| and [`swap()`](./zoe-helpers.md#swap-zcf-leftseat-rightseat-lefthasexitedmsg-righthasexitedmsg) might | ||
| be easier to use for simple cases. | ||
| ### `ZCFSeat.stage(newAllocation)`**DEPRECATED 22-06-01** |
There was a problem hiding this comment.
Yup, agreed. I think we should start that after we finish this string of known breaking changes for Zoe and ERTP.
|
We can merge this, as Agoric/agoric-sdk#3184 is pretty much settled apart from an optional final review. |
Updated documentation to reflect Reallocate API changes and enhance coverage of ZCFSeats.