Durable contracts by Chris-Hibbert · Pull Request #1255 · Agoric/documentation

Chris-Hibbert · 2024-12-03T22:38:04Z

closes: #1126

Description

Collect the details on creating durable contracts in one place. Update to cover use of meta with start and stop recommending prepare for this.

Also provide some cross-linking between various descriptions of the approach.

cloudflare-workers-and-pages · 2024-12-03T23:00:27Z

Deploying documentation with Cloudflare Pages

Latest commit:	`0335f86`
Status:	✅ Deploy successful!
Preview URL:	https://8944fae8.documentation-7tp.pages.dev
Branch Preview URL:	https://durablecontracts.documentation-7tp.pages.dev

View logs

Chris-Hibbert · 2024-12-04T18:55:51Z

Lint is failing and claiming there are warnings for two files. When I run yarn prettier locally, it doesn't find any issues.

dckc

Fixing the links is important.

The rest of the comments are just suggestions.

dckc · 2024-12-04T19:19:01Z

+
+The first step toward contracts that can be upgraded is storing all the data that a later incarnation will
+need. This means putting relevant state in
+[Baggage](http://localhost:5173/guides/zoe/contract-upgrade.html#baggage), and ensuring that reachable objects


some localhost links crept in. And "links should ... exclude the file extension" per contributing docs on writing links

Suggested change

[Baggage](http://localhost:5173/guides/zoe/contract-upgrade.html#baggage), and ensuring that reachable objects

[Baggage](/guides/zoe/contract-upgrade#baggage), and ensuring that reachable objects

dckc · 2024-12-04T19:22:23Z

+Our persistent objects are designed to encapsulate their state, and can present different facets to different
+clients to distinguish different aspects of authority. `zone.exoClass()` defines a kind with a single facet,
+while `zone.exoClassKit()` defines a kind with multiple facets. (Here are some relevant [naming
+conventions](https://docs.agoric.com/guides/ertp/#method-naming-structure).)


use relative links to facilitate local preview:

Suggested change

conventions](https://docs.agoric.com/guides/ertp/#method-naming-structure).)

conventions](/guides/ertp/#method-naming-structure).)

dckc · 2024-12-04T19:24:06Z

-The result of starting a contract includes the right to upgrade the contract instance. A call to [E(zoe).startInstance(...)](/reference/zoe-api/zoe.md#e-zoe-startinstance-installation-issuerkeywordrecord-terms-privateargs) returns a record of several objects that represent different levels of access.
-The `publicFacet` and `creatorFacet` are defined by the contract.
-The `adminFacet` is defined by Zoe and includes methods to upgrade the contract.
+The return value when starting a contract includes a capability that conveys the right to upgrade


"a capability that conveys the right" seems wordy; how about...

Suggested change

The return value when starting a contract includes a capability that conveys the right to upgrade

The return value when starting a contract includes a capability to upgrade

dckc · 2024-12-04T19:35:12Z

+The return value when starting a contract includes a capability that conveys the right to upgrade
+the contract instance. A call to
+[E(zoe).startInstance(...)](/reference/zoe-api/zoe.md#e-zoe-startinstance-installation-issuerkeywordrecord-terms-privateargs)
+returns a record of several objects that carry different powers. The `publicFacet` and


The change from "represent different levels of access" to "carry different powers" seems to make things more obscure. I think typical readers are much more likely to be familiar with levels access than "powers".

Perhaps "... returns a kit of facets; that is: a record of several objects that represent different ways to access the contract instance" with kit and facets linked to glossary entries.

Another option would be to leave most of that to the startInstance docs: "Recall that E(zoe).startInstance(...) returns a record including an adminFacet property. This adminFacet includes methods to upgrade the contract instance."

I don't like "levels of access". "kit of facets" (with links) works for me.

dckc · 2024-12-04T19:35:56Z

+`start`. (We used to indicate upgradability by using `prepare` instead of `start`, but that
+approach is deprecated.)`


Suggested change

`start`. (We used to indicate upgradability by using `prepare` instead of `start`, but that

approach is deprecated.)`

`start`. (_We used to indicate upgradability by using `prepare` instead of `start`, but that

approach is deprecated._)`

dckc · 2024-12-04T20:15:29Z

+Fields of the object returned by the `init` function become fields of the persistent state. (These cannot
+currently be changed on upgrade, though we're considering relaxing that restriction.) Within methods they can


Suggested change

Fields of the object returned by the `init` function become fields of the persistent state. (These cannot

currently be changed on upgrade, though we're considering relaxing that restriction.) Within methods they can

Fields of the object returned by the `init` function become fields of the persistent state. (_These cannot

currently be changed on upgrade, though we're considering relaxing that restriction._) Within methods they can

dckc · 2024-12-04T20:18:19Z

+
+### Methods: defining behavior
+
+The methods argument of `exoClass()` is a bag of methods, written in [concise method


Suggested change

The methods argument of `exoClass()` is a bag of methods, written in [concise method

The methods argument of `exoClass()` is a collection of methods, written in [concise method

or "... record of methods ..."

done. I like "record" here.

dckc · 2024-12-04T20:19:41Z

+syntax](https://github.com/Agoric/agoric-sdk/wiki/Arrow-Function-Style#far-classes-do-not-use-arrow-function-style).
+`exoClass()` defines a single facet.
+
+The methodKit parameter to `exoClassKit` is a record of labelled bags of methods. Each label defines a facet


Suggested change

The methodKit parameter to `exoClassKit` is a record of labelled bags of methods. Each label defines a facet

The methodKit parameter to `exoClassKit` is a record where each value is a collection of methods. Each property defines a facet

dckc · 2024-12-04T20:21:04Z

+
+[Zone](http://localhost:5173/glossary/#zone) provides an interface for defining objects and classes that
+supports both ephemeral objects (allocated on the heap), and durable objects that can persist and that
+SwingSet will page in or out on demand.


Is "SwingSet" in the reader's vocabulary at this point? Link to glossary entry?

dckc · 2024-12-04T20:25:23Z

+result matches before invoking the method. When a guard is written this latter way, the method doesn't have to
+be `async`. In both cases, the method doesn't have to check for compliance with the guard.
+
+[Shapes can specify](https://endojs.github.io/endo/interfaces/_endo_patterns.PatternMatchers.html) simple


I made a patterns cheat-sheet at https://docs.agoric.com/reference/zoe-api/zoe-contract-facet.html#proposal-shapes, but that context is specialized to proposal shapes. hm.

Perhaps using glossary entries for Pattern and Shape would help. Perhaps I should do that in a follow-up PR.

Thanks, Dan!

Chris-Hibbert added 2 commits December 3, 2024 09:32

docs: durable contract details collected in one place

159b0a4

docs: more detail and more cross links

f47fd29

Chris-Hibbert added documentation devex labels Dec 3, 2024

Chris-Hibbert self-assigned this Dec 3, 2024

chore: prettier's suggestions

5a72a8c

Chris-Hibbert force-pushed the durableContracts branch from 7a91dde to 5a72a8c Compare December 4, 2024 00:57

Chris-Hibbert requested a review from dckc December 4, 2024 18:54

dckc requested changes Dec 4, 2024

View reviewed changes

chore: clean up links and improve wording

8368811

Thanks, Dan!

Chris-Hibbert requested a review from dckc December 5, 2024 00:56

dckc approved these changes Dec 5, 2024

View reviewed changes

Chris-Hibbert added 2 commits December 5, 2024 09:16

chore: cleanup with yarn format

c80699b

chore: better format for glossary link

0335f86

Chris-Hibbert merged commit 537427b into main Dec 5, 2024

Chris-Hibbert deleted the durableContracts branch December 5, 2024 21:28

dckc mentioned this pull request Dec 7, 2024

docs(ertp): ERTP walk-thru: Alice buys a ticket from Bob #1257

Draft

2 tasks

	[Baggage](http://localhost:5173/guides/zoe/contract-upgrade.html#baggage), and ensuring that reachable objects
	[Baggage](/guides/zoe/contract-upgrade#baggage), and ensuring that reachable objects

	conventions](https://docs.agoric.com/guides/ertp/#method-naming-structure).)
	conventions](/guides/ertp/#method-naming-structure).)

	The return value when starting a contract includes a capability that conveys the right to upgrade
	The return value when starting a contract includes a capability to upgrade

		`start`. (We used to indicate upgradability by using `prepare` instead of `start`, but that
		approach is deprecated.)`

		Fields of the object returned by the `init` function become fields of the persistent state. (These cannot
		currently be changed on upgrade, though we're considering relaxing that restriction.) Within methods they can


		### Methods: defining behavior

		The methods argument of `exoClass()` is a bag of methods, written in [concise method

	The methodKit parameter to `exoClassKit` is a record of labelled bags of methods. Each label defines a facet
	The methodKit parameter to `exoClassKit` is a record where each value is a collection of methods. Each property defines a facet

Conversation

Chris-Hibbert commented Dec 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

cloudflare-workers-and-pages Bot commented Dec 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying documentation with Cloudflare Pages

Uh oh!

Chris-Hibbert commented Dec 4, 2024

Uh oh!

dckc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Chris-Hibbert commented Dec 3, 2024 •

edited

Loading

cloudflare-workers-and-pages Bot commented Dec 3, 2024 •

edited

Loading