Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: clean up links and improve wording
Browse files Browse the repository at this point in the history
Thanks, Dan!
Chris-Hibbert committed Dec 5, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
1 parent 5a72a8c commit 8368811
Showing 2 changed files with 25 additions and 25 deletions.
36 changes: 18 additions & 18 deletions main/guides/zoe/contract-details.md
Original file line number Diff line number Diff line change
@@ -7,26 +7,25 @@ or the ability to upgrade, while the second kind need to make use of more sophis

When a contract is intended to continue running and serving many customers over a long time, its objects and
data need to be persistent, its owners or managers may need to be able to adjust parameters or perform other
governance actions, and it needs to be upgradeable so that the code can adapt over time.
governance actions, and they may want it to be upgradeable so that the code can adapt over time.

## Durable Objects

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
that will be accessible to users have an identity that can be maintained as the behavior changes with contract
upgrades.
need. This means putting relevant state in [Baggage](/guides/zoe/contract-upgrade#baggage), and ensuring that
reachable objects that will be accessible to clients have an identity that can be maintained as the behavior
changes with contract upgrades.

We use zone.exo(), zone.exoClass(), and zone.exoClassKit() to define durable objects.

[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.
[Zone](/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](/guides/platform/#swingset) will page in or out on demand.

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).)
conventions](/guides/ertp/#method-naming-structure).)

```
zone.exoClassKit(tag, guard, init, methodKit, options)
@@ -58,24 +57,25 @@ The Exo objects (or just "Exos") defined by these functions are both persistent
knows their complete state, so it can page them out when space is tight, and page them back in when they are
referenced again.

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
each be accessed as fields of `this.state`. Our convention is to extract the fields that will be used in a
method on its first line, like `const { a, b } = this.state;` Once that has been done, those variable can be
read or written as normal javascript variables, and the values will persist. (For more details, see [the note
here](https://docs.agoric.com/guides/zoe/contract-upgrade.html#kinds)).
here](/guides/zoe/contract-upgrade.html#kinds)).

### Methods: defining behavior

The methods argument of `exoClass()` is a bag of methods, written in [concise method
The methods argument of `exoClass()` is a record of methods, written in [concise method
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
of the object. All facets of each object share access to the same state, but each facet is a separate
capability. Within the methods, other facets can be reached by name within `this.facets`. The maker you get
from `exoClassKit()` builds a new object each time it is called, and return all the facets. The caller can
decide which of the facets to pass to each recipient.
The methodKit parameter to `exoClassKit` is a record that can define multiple facets. The keys give the names
of the facets, and each value defines the methods of the corresponding facet. All facets of each object share
access to the entire state defined in `init`, but each facet is a separate capability. Within the methods,
other facets can be reached by name within `this.facets`. The maker returned by `exoClassKit()` builds a new
object each time it is called, and returns all the facets. The caller can decide which of the facets to hold
or to pass to separate recipients.

### Guards: defensive methods

14 changes: 7 additions & 7 deletions main/guides/zoe/contract-upgrade.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Contract Upgrade

The return value when starting a contract includes a capability that conveys the right to upgrade
the contract instance. A call to
The return value when starting a contract includes a capability 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
`creatorFacet` are defined by the contract. The
returns a [kit](/guides/ertp/#method-naming-structure) of [facets](/glossary#facet); that is a
record of several objects that represent different ways to access the contract instance. The
`publicFacet` and `creatorFacet` are defined by the contract. The
[`adminFacet`](/reference/zoe-api/zoe.html#adminFacet) is defined by Zoe and includes methods to
upgrade the contract.

@@ -65,8 +65,8 @@ There are a few requirements for the contract that differ from non-upgradable co
### Upgradable Declaration
The new code bundle declares that it supports upgrade by including a `meta` record in addition to
`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._)
`meta` is a record with any or all of `upgradability`, `customTermsShape`, and `privateArgsShape`
defined. The latter two are optional
@@ -97,7 +97,7 @@ if (!baggage.has('rooms')) {
}
```
The `provide` function supports a concise idiom for this get-or-create pattern:
The `provide` function supports a concise idiom for this find-or-create pattern:
```js
import { provide } from '@agoric/vat-data';

0 comments on commit 8368811

Please sign in to comment.