docs(zoe): make chainmail file up-to-date with the current API

* Add note about interfaces defined in ERTP + try to make Handle a generic type

* Adding Invite interface

* add forgotten instanceHandle to InviteRecord

* Create a Keyword interface

* Add InstanceRecord

* add cancelObj and cancel

* Clarify payout type

* Document OfferHandle and add getCurrentAllocation

packages/zoe/src/zoe.chainmail

@@ -5,6 +5,41 @@
  * to the contracts.
  */
 
+/**
+ * These interfaces are defined in ERTP/src/amountMath.chainmail and ERTP/src/issuer.chainmail:
+ * Issuer, AmountMath, Payment
+ */
+
+
+/**
+ * A handle is an object which is only interesting for its (unique and unforgeable)
+ * identity. It is often used as a key on (Weak)Maps
+ */
+interface Handle(T){
+  /* a handle has no property */
+}
+
+interface Invite: Payment(InviteRecord);
+
+struct InviteRecord ( ) {
+  handle: Handle(Offer); // pending a decision on https://github.com/Agoric/agoric-sdk/issues/805
+  instanceHandle: Handle(Instance);
+}
+
+/**
+ * Keywords are strings that respect the following JavaScript Regexp: 
+ * /^[A-Z][a-zA-Z0-9_$]*$/
+ * In plain English, it means a Keyword starts with an uppercase ASCII letter
+ * and is followed by any number of letters (uppercase and lowercase), numbers, 
+ * or the "_" and "$" signs
+ */
+interface Keyword: String;
+
+interface IssuerKeywordRecord{
+  [Keyword]: Issuer;
+}
+
+
 interface ZoeService {
 
   /**
@@ -21,7 +56,7 @@ interface ZoeService {
    * Create an installation by safely evaluating the code and
    * registering it with Zoe. Returns an installationHandle. 
    */
-  install(code :String, moduleFormat :String) -> (InstallationHandle);
+  install(code :String, moduleFormat :String) -> (Handle(Installation));
 
   /** 
    * Zoe is long-lived. We can use Zoe to create smart contract
@@ -38,13 +73,13 @@ interface ZoeService {
    * Terms are up to the discretion of the smart contract. We get back
    * an invite (an ERTP payment) to participate in the contract.
    */
-  makeInstance(installationHandle :InstallationHandle, issuerKeywordRecord :IssuerKeywordRecord, terms :Object) -> (Invite);
+  makeInstance(installationHandle :Handle(Installation), issuerKeywordRecord :IssuerKeywordRecord, terms :Object) -> (Invite);
 
   /**
    * Credibly get information about the instance (such as the installation
    * and terms used).
    */
-  getInstance(instanceHandle :InstanceHandle) -> (InstanceRecord);
+  getInstance(instanceHandle :Handle(Instance)) -> (InstanceRecord);
 
   /** 
    * To redeem an invite, the user normally provides a proposal (their rules for the
@@ -74,7 +109,13 @@ interface ZoeService {
  */
 struct SeatAndPayout ( ) {
   seat :Object;
-  payout :List(Payment);
+  payout :Promise(PaymentPromiseKeywordRecord); 
+  cancelObj? :CancelObj; /* exists only when exit is 'onDemand' */
+  /* this may be renamed to complete: https://github.com/Agoric/agoric-sdk/issues/835  */
+}
+
+interface CancelObj () {
+  cancel();
 }
 
 struct Proposal ( ) {
@@ -88,8 +129,17 @@ struct Proposal ( ) {
  * { Asset: amountMath.make(5), Price: amountMath.make(9) }
  */
 struct AmountKeywordRecord ( ) {
+  [Keyword]: AmountMath;
+}
+
+struct PaymentKeywordRecord ( ){
+  [Keyword]: Payment;
 }
 
+struct PaymentPromiseKeywordRecord ( ) {
+  [Keyword]: Promise(Payment);
+} 
+
 /**
  * The possible keys are 'waived', 'onDemand', and 'afterDeadline'.
  * `timer` and `deadline` only are used for the `afterDeadline` key.
@@ -103,6 +153,14 @@ struct ExitRule ( ) {
   deadline :Deadline;
 }
 
+interface InstanceRecord{
+  installationHandle: Handle(Installation),
+  publicAPI: any,
+  terms: any,
+  issuerKeywordRecord: IssuerKeywordRecord
+}
+
+
 interface ZoeContractFacet () {
 
   /** 
@@ -113,14 +171,14 @@ interface ZoeContractFacet () {
    * index in the offerHandles array. The reallocation will only happen if
    * 'offer safety' and conservation of rights are true, as enforced by Zoe.
    */
-  reallocate (offerHandles :List(OfferHandle), reallocation :List(AmountKeywordRecord));
+  reallocate (offerHandles :List(Handle(Offer)), reallocation :List(AmountKeywordRecord));
 
   /** 
    * Eject the offer, taking the current allocation for that offer and
    * creating payments to be returned to the user. No 'offer safety' checks are
    * done here because any previous reallocation performed those checks.
    */
-  complete (offerHandles :List(OfferHandle));
+  complete (offerHandles :List(Handle(Offer)));
 
   /** Create an invite using the Zoe inviteMint */
   makeInvite (seat :Object, customProperties :Object ) -> (Invite);
@@ -129,7 +187,7 @@ interface ZoeContractFacet () {
    * Inform Zoe about new issuers. Returns a promise for acknowledging
    * when the issuer is added and ready.
    */
-  addNewIssuer (issuer :Issuer, keyword :String) -> (Promise(Undefined));
+  addNewIssuer (issuer :Issuer, keyword :Keyword) -> (Promise(Undefined));
 
   /**
    * Expose the user-facing Zoe Service API to the contracts as well.
@@ -143,33 +201,42 @@ interface ZoeContractFacet () {
 
   /** Get a list of local amountMath for each keyword in the
   sparseKeywords array */
-  getAmountMaths (sparseKeywords :List(String)) -> (AmountMathKeywordRecord));
+  getAmountMaths (sparseKeywords :List(Keyword)) -> (AmountMathKeywordRecord));
 
   /** Divide the offerHandles into 'active' and 'inactive' lists */
-  getOfferStatuses ( offerHandles :List(OfferHandle)) ->
+  getOfferStatuses ( offerHandles :List(Handle(Offer))) ->
   (OfferStatusesRecord);
 
   /** 
    * Check if the offer is still active. This method does not throw
    * if the offer is inactive.
    */
-  isOfferActive ( offerHandle :OfferHandle ) -> (Bool);
+  isOfferActive ( offerHandle :Handle(Offer) ) -> (Bool);
 
   /** Get a list of offer records */
-  getOffers ( offerHandles :List(OfferHandle)) -> (List(OfferRecord));
+  getOffers ( offerHandles :List(Handle(Offer))) -> (List(OfferRecord));
 
   /** Get the offer record */
-  getOffer ( offerHandle :OfferHandle) -> (List(OfferRecord));
+  getOffer ( offerHandle :Handle(Offer)) -> (List(OfferRecord));
+
+  /** Get the current allocation associated with the offerHandle */
+  getCurrentAllocation ( offerHandle :Handle(Offer) ) -> (AmountKeywordRecord);
 
   /** Get instance record */
   getInstanceRecord ( ) -> InstanceRecord;
 
 }
 
+struct OfferRecord ( ) {
+  handle: Handle(Offer)
+  instanceHandle: Handle(Instance);
+  proposal :Proposal;
+}
+
 /**
  * `active` and `inactive` lists of offerHandles.
  */
  struct OfferStatusesRecord ( ) {
-  active :List(OfferHandle);
-  inactive :List(OfferHandle);
+  active :List(Handle(Offer));
+  inactive :List(Handle(Offer));
 }