Agoric / documentation

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

teach exo's from the start? #1033

Open dckc opened 6 months ago

dckc commented 6 months ago

our hello world contract currently uses Far, as does dapp-offer-up and dapp-agoric-basics.

Then we teach contract upgrade later, with a brief example exoClass.

Some have suggested teaching exo's from the start (@dtribble , @ivanlei , @erights ? @mhofman ?)

Should we?

The decision should probably be informed by trying it out first.

cc @sufyaankhan @kriskowal

erights commented 6 months ago

I certainly agree we should learn from trying it. I am hopeful that it'll turn out well, but we'll see ;)

erights commented 6 months ago

See https://github.com/endojs/endo/pull/2118

dckc commented 6 months ago

The exo docs presume an understanding of Far:

An Exo is a Far object protected by an interface guard.

If we're going to avoid teaching Far, that seems like an important place to start.

dckc commented 6 months ago

@kriskowal has an interesting suggestion:

If it serves a purpose in the docs, I think it provides a gentle step up to Exo. You write a Far function, write all the necessary validation to make it safe, then convert it to an Exo. Shows the user that it’s a net savings once the object is made safe to share.

Part of me likes that idea, but part of me is trying to avoid documenting how the sausage is made and just hand over the dang sausage. So... hm. I'm not sure.

LuqiPan commented 6 months ago

Do we expect developers to use exo exclusively?

erights commented 6 months ago

Do we expect developers to use exo exclusively?

As opposed to Far? Yes.

mhofman commented 6 months ago

The exo docs presume an understanding of Far:

An Exo is a Far object protected by an interface guard.

The fact that all exos are Far objects is also something that we may want to revisit. Right now we miss the ability to create high cardinality or simply objects with interface guards that are not exportable.