[Zoe] Document the design decision around invites

[DavidBruant]

When writing the tutorial for the first smart contract in the documentation repo, i didn't understand why the ContractHost API forces the contract author and participant to go through the inviteMaker.make(desc, seat)+pass invite+redeem dance to get the seat while it could have been easier for the contract to return the seats directly and pass that over to participants

It took me a while to figure out that this process has the interesting property of being resistant against a malicious contract "installer". If the person who installed the contract handed me the seat directly, i have no way to be sure that is presence is a seat in the contract and not another arbitrary presence. On the other hand, if i get the seat myself from the contract host with the invite, i have the guarantee that 1) the invite is relevant to this contract (otherwise the contract does not give me a seat in return) 2) the seat that is handed to me by the contract directly is one that runs according to the contract

I did not see a mention of this in the ContractHost.chainmail doc (but i'm also not sure this is the right place for this)

I'm creating this issue for now to:

1. be sure i correctly understand the invite mechanism
2. find a proper place to document this

[Chris-Hibbert]

You got it. There's also 3) The redeem() can only succeed once, so if it works, you know you have the only reference to the seat.

I think it should be documented, and I don't think chainmail is the right place for it. I may even have gone overboard on how much detail I put there, but it wasn't written elsewhere, so I felt compelled. The .chainmail files should be talking about guarantees that are relevant to the API, and the calling conventions. promises about deeper behavior should be documented, but arguably, elsewhere.

[warner]

this was issue 109 in the old ERTP repo

[katelynsills]

Zoe is going to use invites extensively. Since that will be more of our focus compared to the contractHost, let's reinterpret this issue in terms of Zoe and make sure that we explain this properly