[Zoe] Zoe Release v0.3.0

[katelynsills]

This is the release PR for "Zoe Keywords" (Release v0.3.0).

"OfferRules", or the declarative statement portion of an offer, have
been renamed to "proposal". The structure of a proposal has changed to:

{
  give: { Asset: moola(4 )},
  want: { Price: simoleans(15) },
  exit: { afterDeadline: {
    timer,
    deadline: 100,
  }}
}

(* moola is an alias for moolaAmountMath.make, and likewise for
simoleans.)

There are no longer any keys such as 'payoutRules' or 'exitRule'. Most
importantly, we no longer rely on the specific order of payoutRules
arrays and payment/payout arrays to be the same. In fact, we can even
make a partial proposal that will be filled in.

Asset and Price in the above example are called "keywords". Each
contract has its own specific keywords. For instance, an auction
might have "Asset" and "Bid". Keywords are unique identifiers per
contract, that tie together the proposal, payments to be escrowed, and
payouts to the user.

Users should submit their payments using keywords:

const payments = { Asset: moolaPayment };

And, users will receive their payouts with keywords as the keys of a
payout object:

moolaPurse.deposit(payout.Asset);

In summary, the arrays that were part of the previous API have been
replaced with records keyed by keywords.

Below is a summary of the changes:

Changes to the Zoe Service (User-facing) API:

• makeInstance now takes in three arguments: installationHandle,
  issuerKeywordRecord, and terms. issuerKeywordRecord should have strings
  as keys (called keywords), and issuers as values (called args).
  For instance, {Asset: moolaIssuer, Price: simoleanIssuer }. Terms
  no longer needs an issuers property. Instead, terms should be used for
  any contract-specific parameters, such as the number of bids an
  auction should wait for before closing.
• OfferRules (now proposal) have the new structure mentioned above
• Payments to be escrowed must be an object keyed by keywords rather
  than an array
• Payouts from Zoe will be in the form of a promise that resolves to a
  object keyed by keywords where the values are promises for
  payments
• We have added three new methods to the Zoe Service API: getOffer,
  getOffers, and isOfferActive. Note that getOffer and
  getOffers will throw if the offer is not found, whereas
  isOfferActive is safe to check whether an offer is still active or
  not.

Changes to the Contract Facet API and contract helpers:

• The userFlow helpers have been renamed to zoeHelpers
• hasValidPayoutRules is no longer a helper function due to the
  change in the proposal structure
• Instead, we have three new helpers: assertKeywords which can be
  used to make sure that the keywords on instantiation match what
  the contract expects, rejectIfNotProposal which rejects an
  offer if the proposal have the wrong structure, and
  checkIfProposal which checks if the proposal match the
  expected structure and returns true or false.
• getAmountMathForIssuers and getBrandsForIssuers no longer exist
• getAmountMaths is added. It takes in a issuerKeywordRecord
  record that maps keywords to issuers.
• getInstanceRecord is added. It allows the contracts to get access
  to their keywords, issuers and other "instanceRecord" information from
  Zoe.
• The instanceRecord now has properties: issuerKeywordRecord (a record with
  keyword keys and issuer values) and keywords (an array of
  strings). The keywords in issuerKeywordRecord and the keywords array
  are the same.
• In the offerRecord, amounts are no longer an array. Instead they are
  an amountKeywordRecord, an object with keywords as keys and amount
  values.
• Reallocate now takes an array of offerHandles/inviteHandles and an
  array of the above amountKeywordRecords keyed on keywords.
• AddNewIssuer now requires a keyword to be provided alongside the issuer.

Closes #97
Closes #392
Closes #469
Closes #564
Closes #677
Closes #686

[Chris-Hibbert]

Some early comments to give Kate a head start on anything that needs to be added. More comments coming. Most of my requests are about documentation or testing, which shouldn't be too surprising.

[erights]

Most suggestions at #700

[erights]

The difference LGTM so you can now squash as you wish.

[erights]

Note that my review skips

chainmail file
most tests
the wrong myFirstDapp that should be deleted anyway

The review is not yet done. But zoe.js is done, which is the most important part. More soon.

[erights]

Both differential commits LGTM. Squash when you wish.

I'm glad you deleted myFirstDapp despite my misunderstanding. If we can, please leave it deleted.

[erights]

(I don't know why, once I've started a review, I can't comment in place on review comments like #685 (comment) )

At #685 (comment) @katelynsills writes:

Sure, I think we can coerce each amount by the corresponding amountMath. What kind of validation can we do of the exit condition structure for afterDeadline? For onDemand and waived we can check the value is null.

Well, at least that the timer and deadline properties exist. Yeah, when I wrote my review comment I hadn't realized how little we can say in general about timer and deadline being well formed. This makes sense though, because the well formedness of a given deadline is only wrt the timer that would understand that deadline.

[erights]

Everything reviewed except for the exclusions already mentioned + autoswap and bondingCurves. I'm done for the night, busy a whole day tomorrow, and autoSwap is hard. @dtribble what's your feeling about merging this before I review those two, and then doing post-merge review and fixing-if-needed?

[erights]

Still looking at autoswap. All else reviewed.

As of your tenth commit, I've also done all the differential review, so squash at will.

[erights]

Review done.

[erights]

LGTM

[Chris-Hibbert]

I'm okay with the merge/refactoring of redeem. Now to look at the tests...

[katelynsills]

We decided I'm going to add back in any t.plan that existed in Chris's earlier PR that got merged into master.

[erights]

That was scary!

I did happen to have in my local git the last zoe.js that I approved. Comparing it with the current merged one was easy. Took less than a minute. Reviewing the diff below would have taken hours more.

LGTM