Document Invitation Specs

[0xpatrickdev]

As a developer, I should be able to learn about Invitation Specs and design patterns for communicating offers to and from a smart-wallet.

invitationSpec: {
  source: 'contract' | 'agoricContract' | 'purse' | 'continuing';
  instancePath: [ string ];
  callPipe: [];
  invitationMakerName:  [ string ];
  previousOffer: string;
  invitationArgs: [];
  description: string;
  publicInvitationMaker: string;
}

[0xpatrickdev]

Also see Agoric/agoric-sdk#8082

[0xpatrickdev]

See #667 for the original issue

[dckc]

@erights asked about "call pipe"

call pipe is a poor-man's expression language used to encode things like E(E(vaultFactory).getCollateralManager(atomBrand)).makeVaultInvitation()

see AgoricContractInvitationSpec https://github.com/Agoric/agoric-sdk/blob/master/packages/smart-wallet/src/invitations.js#L25

I'm struggling to find tests. I think they use this utility...

https://github.com/Agoric/agoric-sdk/blob/6e90d9640a7129584540b2028198e92a7b6e32c4/packages/inter-protocol/src/clientSupport.js#L88-L95

    invitationSpec: {
      source: 'agoricContract',
      instancePath: ['VaultFactory'],
      callPipe: [
        ['getCollateralManager', [collateralBrand]],
        ['makeVaultInvitation'],
      ],
    },

[dckc]

oops... I merged the invitation spec docs that I added to #999 on governance without review, didn't I?

@0xpatrick @turadg @sam @Hibbert showed interest at various times.

Please see InvitationSpec Usage under Specifying Offers.