feat(zoe): caretaker-style revocable, ownable

[erights]

closes: #XXXX
refs: #8020 #8517 #2070

Description

Alternative to #8020 and #8517

Unlike #8020 provides a caretaker-style revoker, which is a much better base for building ownables

Unlike #8517 provides ownables that are much easier to layer on top of existing implementations.

The basic idea of an "ownable object" is to provide general and lower level support for approximately the pattern that vaults implement manually in an adhoc manner: A ownable object is an object with a makeTransferInvitation method that revokes the object itself, in the sense of inactivating it — it no longer provides any authority. Instead, the exclusively transferable portion of its authority is encapsulated by the returned invitation, in an allegedly legible manner. That invitation can be redeemed, via an offer , for a new ownable object in which the transferable authority from the original ownable object is now exercisable.

We call this an "ownable object" since rights of ownership include

• the right to exercise (use)
• the right to exclusively transfer the rights of ownership
• the right to exclude others from being able to exercise and transfer
• the ability to legibly offer the exclusive transfer of ownership

Objects are about rights to exercise (use) and share, but not exclusive transfer, and not legibly.

ERTP is about legible exclusive transfer but not exercise.

The lifecycle of an ownable object, transmuting between an ephemeral ownable object and an invitation to get a new “equivalent” ownable object, combines all attributes together. But the attributes are never directly present at the same time. That’s why it is the lifecycle that combines these.

This notion of "ownable" and "ownership rights" has strong echoes in programming language notions of "ownership types", "linear types", "affine types", and "reference capabilities", in languages ranging from Rust to Pony to Move, enable mutable objects that can be exercised (use) and exclusive transfer, but not legibility.

However, none of these, as far as we are aware, has the two-phase lifecycle of our ownable objects. Thus, they do they provide for legibility of offers to transfer, which is crucial for secure exchange and offer safety. To produce a legible description of the transferable right (which we include in the invitation customDetails), we need to simultaneously stabilize the object, denying any further exercise until the invitation is redeemed. Otherwise, the "seller" could seem to be selling something whose value is invalidated by the seller's own further use.

See Necessity specifications for robustness

See https://groups.google.com/g/cap-talk/c/9OU9ZNoB3os/m/gXeu2zs4AgAJ?utm_medium=email&utm_source=footer for a useful real-world analogy for the two-phase ownership cycle.

Security Considerations

Must ensure that revocation really denies all further authority from the original ownable object, even from messages that are already in the air but not yet delivered.

Need to verify that the legibility can meet invitation legibility goals.

Scaling Considerations

The kind of intrinsic revocability of #8020 could provide scaling benefits of dropping bookkeeping for used-up objects such as payments. However, we are not currently pursuing that revocation plan. It is conceivable that we could do something similar with the caretaker-like revocability of this PR, but we do not currently plan to do so.

Documentation Considerations

Once ready to be used, not only should this be documented, we should be able to simplify several other APIs in ways that should make them more explainable.

Testing Considerations

First tests are included.

Upgrade Considerations

Given that these are used with the durable zone, as intended:

• The transfer invitations have durable handlers and so are themselves durable and should survive upgrade.
• The ownable objects themselves are defined to be durable, so they can survive upgrade if their underlying object can.

[dckc]

I don't see any important problems.

I defer to @Chris-Hibbert to approve.

[erights]

looks pretty good.

Before I approve... is this expected to be part of the developer API product? If so, I would try to generate docs and see what they look like.

@dckc
I've never done that before, but I'd love to! Where do I start?

[dckc]

For adding generated docs, an example to follow is

• more typedoc #8720

After you add stuff like that, run yarn typedoc from the top agoric-sdk directory. I think the results go in an api-doc directory.

[erights]

For adding generated docs, an example to follow is

• more typedoc #8720

After you add stuff like that, run yarn typedoc from the top agoric-sdk directory. I think the results go in an api-doc directory.

api-docs.zip

At api-docs/modules/_agoric_zoe.src_contractSupport_prepare_ownable.html
and api-docs/modules/_agoric_zoe.src_contractSupport_prepare_revocable.html

I like it!

[erights]

@dckc
I don't think I did that right. New commit coming up

[erights]

api-docs.zip

Done. Now they are just in the zoe/contractSupport module. They get kinda lost in there, bit altogether it seems like the right thing to do. Opinions?

[dckc]

... Now they are just in the zoe/contractSupport module. They get kinda lost in there, but altogether it seems like the right thing to do. Opinions?

Yeah... I think we're at the "better than nothing" stage of developing reference docs.
I don't have any better sense of what this stuff should look like.

[erights]

@dckc , do you have any remaining concerns?

[dckc]

I had some concerns about how this integrates with upcoming releases (cf. #8578) but it doesn't impact any existing on-chain bundles, and that seems to address these concerns to @mhofman 's satisfaction, which makes it fine by me.