Agoric / documentation

User documentation
https://agoric.com/documentation/
Apache License 2.0
15 stars 39 forks source link

Invitations should not be considered Payments #887

Open gibson042 opened 11 months ago

gibson042 commented 11 months ago

_Originally posted by @erights in https://github.com/Agoric/documentation/pull/876#discussion_r1411215368_

There is however a genuine terminology problem here. A purse or payment of the invitation issuers can have an amount with any number of invitation details, including none. Perhaps we need to switch to using "invitation" to describe the abstract non-fungible assets, which can move between purses and payments. In the same way that we wouldn't say that a dollar "is" a payment with a 1 dollar amount, we should probably stop saying that an invitation "is" a payment with 1 invitations detail amount.

What a mess. Would be a lot of work to clean up, but probably needed. Just do some adequate stopgap in this PR and file an issue? In any case, the above pair of sentences still need to be fixed because they contradict each other.

dckc commented 11 months ago

The title presumes the conclusion. I would prefer something like:

I'll stand by for a bit before changing it, though.

erights commented 11 months ago

New slogan (though not for the title): Assets are not objects. (Or closer to our own history: ERights are not objects.)

The title presumes the conclusion.

Fine with me if we make the title more of a problem statement rather than a conclusion. But I just wanna say that since I wrote the above comment and slept on it, I'm feeling rather confident. We already must and do explain:

Amounts describe assets. Purses hold assets. Payments hold and convey assets. But there is no object which is the asset itself. The asset itself is a concept that appears only at a higher level of abstraction that emerges from the interplay of these other objects.

Given that, using the term "invitation" to refer to the asset seems exactly right. Actually making this fix is indeed a lot of work, but I think we need to find a way to navigate to fixing this.