confusion around checking proposal shapes (featuring M)

[tgrecojs]

It's unclear how to properly check an offer's proposal shape, so I'm opening this issue to get clarity around the matter.

vscode informed me of assertProposalShape being deprecated, which led me to find this issue. In that issue, @erights informs us that zcf.makeInvitation takes an optional proposalSeat parameter which, if supplied, will be used by Zoe to verify an offer proposal. He also mentions that users can request information about the shape of an invitations proposalSeat from Zoe.

I understood this to mean that the proposalShape parameter would mirror the parameters used in assertProposalShape, but after several attempts, it was clear that this wasn't the case. I investigated a bit and couldn't find any instances in which this new approach was used. I found fitProposalShape inside the zoeHelpers.js file so I made an attempt to use that directly in my contract, but again, I had no luck.

Among the things I discovered while investigating was the use of agoric/store's M being used to construct what looks as though it may be a valid proposalShape.

In addition to my confusion around understanding proposalShapes, this also led me to realize I lacked any knowledge of the aforementioned M API.

Is the agoric documentation a suitable place for this information? It looks fairly robust and seems to be used quite a bit throughout the agoric-sdk, so I imagine that users of the SDK would benefit to have knowledge of it.

[erights]

Hi @tgrecojs , indeed, the makeInvitation proposalShape takes a Pattern. By contrast, assertProposalShape took an ad-hoc one-off encoding of something pattern-like for this one usage. Patterns are more general, expressive, and reusable for a range of different purposes.

Patterns are explained at
https://github.com/Agoric/agoric-sdk/blob/65d3f14c8102993168d2568eed5e6acbcba0c48a/packages/store/src/types.js#L31 .
Methods of M are indeed the main way to express patterns. These methods are explained at https://github.com/Agoric/agoric-sdk/blob/65d3f14c8102993168d2568eed5e6acbcba0c48a/packages/store/src/types.js#L483 .
There are plenty of examples of such use of M patterns for various purposes. I suggest you start with the ones in ERTP.

We have not yet converted most old calls to assertProposalShape into patterns to be passed as proposalShape arguments. Thus, there are not yet many examples of use of the proposalShape argument, but two good ones are at
https://github.com/Agoric/agoric-sdk/blob/65d3f14c8102993168d2568eed5e6acbcba0c48a/packages/inter-protocol/src/psm/psm.js#L255 . This shows off how much better general patterns are at doing a first rejections of proposals the contract doesn't want to handle: In this case, even requiring that the amount brands be the expected brands.

At Agoric/agoric-sdk#6475 I have started on expressing more proposalShape arguments, but I haven't gotten very far yet.

[erights]

Attn @Chris-Hibbert @gibson042 @Tyrosine22

[erights]

See also https://github.com/Agoric/agoric-sdk/wiki/Interfaces for the main current use of patterns. Has nothing to do with proposalShape, but it is most of the pattern examples you'll encounter.

[tgrecojs]

@erights thanks so much for the information!

Initially, I was having a difficult time grasping the use of M's pattern matcher, but after viewing the psm example you referenced, things have started to click!

I've successfully used the proposalShape parameter to validate an invitation's offer using Zoe.

Again, I've only begun using these patterns, but their flexibility is already becoming apparent. In my use case, Zoe needs to be able to accept offers that use different values for want and give, and I was able to implement this fairly quickly using M.or.

In regards to patterns not being specific to proposalShape, I understand, and I'm looking forward to seeing where else in my code it comes in hand. 🙂