[Zoe] Sparse Keywords Spec

[katelynsills]

Zoe currently has the concept of keywords which are used as indexes in place of the array indexes that we had previously. The keywords are used to match proposal elements, payments, amounts in the offerRecord within Zoe, and payouts to the user. Keywords are per contract, and are currently objective: they are the same for all users of a contract.

We expect that future contracts (specifically multipool Autoswap #391) will have many keywords, potentially hundreds. Therefore, we want to ensure that the keywordRecords (records using keywords as keys) throughout Zoe are sparse, much sparser than all the keywords for a contract.

The question is where a subset of these keywords should be used, and how this subset is derived at different points.

Below are key points in Zoe where keywords are used:

User

1. The proposal sent in by the user
2. The offer payments sent in by the user
3. The payouts to the user

Zoe

1. offer.proposal (the user's offer proposal)
2. offer.amounts (the current allocation)

Contract

1. offer.proposal (the user's offer proposal, possibly altered in the query)
2. offer.amounts (the current allocation, possibly altered in the query)
3. newAmountKeywordRecord arguments to zcf.reallocate

The current Zoe makes this easy by filling all the keywords that the contract has at the time that the user escrows with Zoe, so at no point after that step do any partial keywords exist. However, that strategy will not work for contracts with hundreds of keywords.

We decided March 27th that the solution, the "sparse keywords" PR, should include the following:

• All of the keywords for the contract should be called allKeywords*
• Any particular subset is sparseKeywords*
• offerRecord will still include proposal and amounts. However, the Zoe Contract Facet (zcf) API will change.
• zcf.getOffers and zcf.getOffer will only return proposal, handle, and instanceHandle, not amounts
• Two new methods will be added: zcf.getAmounts and zcf.getAmountsForOffer, which will take as arguments offerHandles, and sparseKeywords. The representation of amounts that is returned should have filled in empty values for all the sparseKeywords and anything not listed in sparseKeywords is dropped. Note that nothing changes in Zoe's offerRecord table. This is merely changing what the contract gets as a response to the query.
• The user can use sparse keywords (whichever they want) in their proposal. Zoe will not fill these in, but will store the proposal as is, after cleaning it.
• The user's offer payments must match the user's proposal.give. Zoe will check that these match, but will not do any additional filling.
• When Zoe creates offerRecord.amounts after depositing the user's payments, Zoe will fill in the wants of the user's offer with empty. Zoe will not fill in all keywords, just the ones mentioned by the user.
• zcf.reallocate will have a similar signature to zcf.getAmounts: offerHandles, sparseKeywords and newAmountKeywordRecords will be the arguments. zcf.reallocate will throw an error if any of the newAmountKeywordRecords do not have a value for all the keywords in sparseKeywords. An error will also be thrown if any newAmountKeywordRecords have keywords that are not in sparseKeywords. We expect that contracts will be using zcf.getAmounts and then calling zcf.reallocate, so these requirements should not be burdensome if the same sparseKeywords is used in both calls, since zcf.getAmounts fills in the values appropriately.
• The reallocation done in zcf.reallocate will change the keywords in offerRecord.amounts
• The keywords in the payouts to users will be the same as the current offerRecord.amounts for that user, because that is what our offer safety and rights conservation checks were made over.
• Note that the keywords in the payouts might be different than the keywords original mentioned by the user in their offer

Asterisk: Kate's late addition

[katelynsills]

One consequence of this change - users should look at what keywords are expected by the contracts for each position, since Zoe no longer fills in all keywords for the users. For instance, in Autoswap, when Alice removed liquidity, she didn't specify what she wanted in return, because in this test, she supposedly didn't care. However, now the Autoswap contract does expect a user to specify the two tokens they want, because it will not be filled in by Zoe.

[katelynsills]

Additionally, we can get rid of the keywords array in the instanceRecord with this change.

[katelynsills]

@DavidBruant suggested calling getAmounts: getCurrentAllocation. I like that a lot