feat(vitepress): updates site to use vitepress

CONTRIBUTING.md

@@ -86,8 +86,7 @@ VitePress automatically builds search functionality and individual page menus fr
 You must have **only one** `h1` per `.md` file. Be careful not to have too many `h2` and `h3` level headers
 on one page and that they aren't too long. Otherwise the sidebar menu for the page will be cluttered and hard to read and use.
 
-Individual pages do not automatically display a sidebar menu for their headers (As of March 2021, VitePress
-documentation implies they do. We've filed a PR with them).
+Individual pages do not automatically display a sidebar menu for their headers without the use of a plugin.
 To force an individual page sidebar menu, add the following YAML at the top of a page's source file (this file has this YAML at the top):
 ```js
 ---
@@ -259,7 +258,7 @@ Note that the PR will automatically test and lint files. The above is for local
 
 ### Check Links
 
-To check internal VitePress links locally, run the shell command `yarn check-links` from anywhere in the
+To check internal VitePress links locally, run the shell command `yarn docs:build` from anywhere in the
 root of the local repo folder or below.
 
 Note this does **not** check either external links or router-links. Output is the text of any
@@ -281,14 +280,22 @@ agoric install
 ```shell
 yarn docs:build
 ```
+The resulting build assets can be found in `/dist` in the project root.
+
 4. **Run**: To run a local server and see your changes in real time, run:
 ```shell
 yarn docs:dev
 ```
 Most edit changes are immediately reflected in the browser, but
 applying site config changes may require stopping and restarting this program.
 
-View your local documentation site at `localhost:8080/documentation/`
+View your local documentation site at `localhost:5173`
+
+5. **Preview**: To preview a production build, run:
+```shell
+yarn docs:preview
+```
+View your local documentation site at `localhost:4173`
 
 ## Updating Zoe Version and DocsUpdated
 

main/.vitepress/config.mjs

@@ -5,6 +5,7 @@ import { rewrites } from './themeConfig/rewrites.js';
 export default defineConfig({
   /* --- FOR DEPLOYMENT TO GITHUB PAGES--- */
   base: '/', // The base URL the site will be deployed at.
+  outDir: '../dist',
   /* --- HOME PAGE --- */
   title: 'Agoric Documentation', // title for the site. prefix for all page titles and displayed in the navbar
   description: 'Build, deploy and operate dApps and DeFi markets.', // desc for the site; rendered as a <meta> tag in the page HTML
@@ -194,6 +195,7 @@ export default defineConfig({
               link: '/guides/zoe/contract-basics',
             },
             { text: 'Zoe Overview', link: '/guides/zoe/' },
+            { text: 'Contract Upgrade', link: '/guides/zoe/contract-upgrade' },
           ],
         },
         {

main/guides/integration/chain-integration.md

@@ -36,15 +36,15 @@ agd version --long
 # FAQ
 
 - How are transactions encoded?
-https://docs.cosmos.network/v0.45/core/encoding.html
+[Cosmos SDK v0.45 Docs - Encoding](https://docs.cosmos.network/v0.45/core/encoding.html)
 - What data is needed to create a transaction (last block hash, nonce, sender public key, etc.)?
-https://docs.cosmos.network/v0.45/core/transactions.html#transaction-generation
+[Cosmos SDK v0.45 Docs - Transaction Generation](https://docs.cosmos.network/v0.45/core/transactions.html#transaction-generation)
 - What data is signed and how is that data obtained (for example truncated SHA256 of transaction data)?
-https://docs.cosmos.network/v0.45/core/transactions.html#transaction-generation
+[Cosmos SDK v0.45 Docs - Transaction Generation](https://docs.cosmos.network/v0.45/core/transactions.html#transaction-generation)
 - Do transactions expire?
-Transaction do not expire unless you specify --timeout-height: https://docs.cosmos.network/v0.45/core/transactions.html#transaction-generation
+Transaction do not expire unless you specify --timeout-height: [Cosmos SDK v0.45 Docs - Transaction Generation](https://docs.cosmos.network/v0.45/core/transactions.html#transaction-generation)
 However they do have a sequence number and may be invalidated if another transaction with the same sequence number is processed by the chain
 - How are addresses generated?
-https://docs.cosmos.network/v0.45/basics/accounts.html
+[Cosmos SDK v0.45 Docs - Accounts](https://docs.cosmos.network/v0.45/basics/accounts.html)
 - How is the blockchain queried?
-JSON-RPC, gRPC, REST  https://docs.cosmos.network/v0.45/run-node/interact-node.html
+JSON-RPC, gRPC, REST  [Cosmos SDK v0.45 Docs - Interact with Node](https://docs.cosmos.network/v0.45/run-node/interact-node.html)

main/guides/zoe/contract-basics.md

@@ -44,11 +44,11 @@ A test that the `greet` method works as expected looks like:
 
 ## State
 
-Contracts can use ordinary variables for state.
+Contracts can use ordinary variables and data structures for state.
 
 <<< @/../snippets/zoe/src/02-state.js#startfn
 
-Using `set` changes the results of the following call to `get`:
+Using `makeRoom` changes the results of the following call to `getRoomCount`:
 
 <<< @/../snippets/zoe/contracts/test-zoe-hello.js#test-state
 
@@ -58,7 +58,7 @@ Ordinary heap state persists between contract invocations.
 
 We'll discuss more explicit state management for
 large numbers of objects (_virtual objects_) and
-objects that last across upgrades (_durable objects_) later.
+objects that last across upgrades ([durable objects](./contract-upgrade#durability)) later.
 
 :::
 

main/guides/zoe/contract-upgrade.md

@@ -0,0 +1,176 @@
+# Contract Upgrade
+
+The result of starting a contract includes the right to upgrade the contract. A call to [E(zoe).install(...)](/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.
+
+::: tip Upgrade Governance
+
+Governance of the right to upgrade is a complex topic that we cover only briefly here.
+
+- When [BLD staker governance](https://community.agoric.com/t/about-the-governance-category/15) makes a decision to start a contract using [swingset.CoreEval](../coreeval/),
+  to date, the `adminFacet` is stored in the bootstrap vat, allowing
+  the BLD stakers to upgrade such a contract in a later `swingset.CoreEval`.
+- The `adminFacet` reference can be discarded, so that noone can upgrade
+  the contract from within the JavaScript VM. (BLD staker governace
+  could, in theory, change the VM itself.)
+- The `adminFacet` can be managed using the [@agoric/governance](https://github.com/Agoric/agoric-sdk/tree/master/packages/governance#readme) framework; for example, using the `committee.js` contract.
+
+:::
+
+## Upgrading a Contract
+
+Upgrading a contract instance means re-starting the contract using a different [code bundle](./#bundling-a-contract). Suppose we start a contract as usual, using
+the bundle ID of a bundle we already sent to the chain:
+
+```js
+const bundleID = 'b1-1234abcd...';
+const installation = await E(zoe).installBundleID(bundleID);
+const { instance, ... facets } = await E(zoe).startInstance(installation, ...);
+
+// ... use facets.publicFacet, instance etc. as usual
+```
+
+If we have the `adminFacet` and the bundle ID of a new version,
+we can use the `upgradeContract` method to upgrade the contract instance:
+
+```js
+const v2BundleId = 'b1-feed1234...`; // hash of bundle with new feature
+const { incarnationNumber } = await E(facets.adminFacet).upgradeContract(v2BundleId);
+```
+
+The `incarnationNumber` is 1 after the 1st upgrade, 2 after the 2nd, and so on.
+
+::: details re-using the same bundle
+
+Note that a "null upgrade" that re-uses the original bundle is valid, and a legitimate approach to deleting accumulated heap state.
+
+See also `E(adminFacet).restartContract()`.
+
+:::
+
+## Upgradable Contracts
+
+There are a few requirements for the contract that differ from non-upgradable contracts:
+
+1. [Upgradable Declaration](#upgradable-declaration)
+2. [Durability](#durability)
+3. [Kinds](#kinds)
+4. [Crank](#crank)
+
+### Upgradable Declaration
+
+The new code bundle declares that it supports upgrade by exporting a `prepare` function in place of `start`.
+
+<<< @/../snippets/zoe/src/02b-state-durable.js#export-prepare
+
+### Durability
+
+The 3rd argument, `baggage`, of the `prepare` function is a `MapStore`
+that provides a way to preserve state and behavior of objects
+between incarnations in a way that preserves identity of objects
+as seen from other vats:
+
+```js
+let rooms;
+if (!baggage.has('rooms')) {
+  // initial incarnation: create the object
+  rooms = makeScalarBigMapStore('rooms', { durable: true });
+  baggage.init('rooms', rooms);
+} else {
+  // subsequent incarnation: use the object from the initial incarnation
+  rooms = baggage.get('rooms');
+}
+```
+
+The `provide` function supports a concise idiom for this find-or-create pattern:
+
+```js
+import { provide } from '@agoric/vat-data';
+
+const rooms = provide(baggage, 'rooms', () =>
+  makeScalarBigMapStore('rooms', { durable: true }),
+);
+```
+
+The `zone` API is a convenient way to manage durability. Its store methods integrate the `provide` pattern:
+
+::: details import { makeDurableZone } ...
+
+<<< @/../snippets/zoe/src/02b-state-durable.js#import-zone
+
+:::
+
+<<< @/../snippets/zoe/src/02b-state-durable.js#zone1
+
+::: details What happens if we don't use baggage?
+
+When the contract instance is restarted, its [vat](../js-programming/#vats-the-unit-of-synchrony) gets a fresh heap, so [ordinary heap state](./contract-basics.md#state) does not survive upgrade. This implementation does not persist the rooms nor their counts between incarnations:
+
+<<< @/../snippets/zoe/src/02-state.js#heap-state{2}
+
+:::
+
+### Kinds
+
+Use `zone.exoClass()` to define state and methods of kinds of durable objects such as `Room`:
+
+<<< @/../snippets/zoe/src/02b-state-durable.js#exoclass
+
+Defining `publicFacet` as a singleton `exo` allows clients to
+continue to use it after an upgrade:
+
+<<< @/../snippets/zoe/src/02b-state-durable.js#exo
+
+Now we have all the parts of an upgradable contract.
+
+::: details full contract listing
+
+<<< @/../snippets/zoe/src/02b-state-durable.js#contract
+
+:::
+
+We can then upgrade it to have another method:
+
+```js
+  const makeRoom = zone.exoClass('Room', RoomI, (id) => ({ id, value: 0 }), {
+    ...
+    clear(delta) {
+      this.state.value = 0;
+    },
+  });
+```
+
+The interface guard also needs updating.
+<small>_See [@endo/patterns](https://endojs.github.io/endo/modules/_endo_patterns.html) for more on interface guards._</small>
+
+```js
+const RoomI = M.interface('Room', {
+  ...
+  clear: M.call().returns(),
+});
+```
+
+::: tip Notes
+
+- Once the state is defined by the `init` function (3rd arg), properties cannot be added or removed.
+- Values of state properties must be serializable.
+- Values of state properties are hardened on assignment.
+- You can replace the value of a state property (e.g. `state.zot = [...state.zot, 'last']`), and you can update stores (`state.players.set(1, player1)`), but you cannot do things like `state.zot.push('last')`, and if jot is part of state (`state.jot = { x: 1 };`), then you can't do `state.jot.x = 2;`
+- The tag (1st arg) is used to form a key in `baggage`, so take care to avoid collisions. `zone.subZone()` may be used to partition namespaces.
+- See also [defineExoClass](https://endojs.github.io/endo/functions/_endo_exo.defineExoClass.html) for further detail `zone.exoClass`.
+- To define multiple objects that share state, use `zone.exoClassKit`.
+  - See also [defineExoClassKit](https://endojs.github.io/endo/functions/_endo_exo.defineExoClassKit.html)
+- For an extended test / example, see [test-coveredCall-service-upgrade.js](https://github.com/Agoric/agoric-sdk/blob/master/packages/zoe/test/swingsetTests/upgradeCoveredCall/test-coveredCall-service-upgrade.js).
+
+:::
+
+### Crank
+
+Define all exo classes/kits before any incoming method calls from other vats -- in the first "crank".
+
+::: tip Note
+
+- For more on crank constraints, see [Virtual and Durable Objects](https://github.com/Agoric/agoric-sdk/blob/master/packages/SwingSet/docs/virtual-objects.md#virtual-and-durable-objects) in [SwingSet docs](https://github.com/Agoric/agoric-sdk/tree/master/packages/SwingSet/docs)
+
+:::

main/guides/zoe/index.md

@@ -159,6 +159,8 @@ t.is(typeof instance, 'object');
 
 _`makeIssuerKit` and `AmountMath.make` are covered in the [ERTP](../ertp/) section, along with `makeEmptyPurse`, `mintPayment`, and `getAmountOf` below._
 
+_See also [E(zoe).startInstance(...)](/reference/zoe-api/zoe.md#e-zoe-startinstance-installation-issuerkeywordrecord-terms-privateargs)._
+
 Let's take a look at what happens in the contract when it starts. A _facet_ of Zoe, the _Zoe Contract Facet_, is passed to the contract `start` function.
 The contract uses this `zcf` to get its terms. Likewise it uses `zcf` to
 make a `gameSeat` where it can store assets that it receives in trade

package.json

@@ -7,9 +7,7 @@
     "docs:dev": "NODE_OPTIONS=--openssl-legacy-provider vitepress dev main",
     "docs:build": "NODE_OPTIONS=--openssl-legacy-provider vitepress build main",
     "docs:preview": "NODE_OPTIONS=--openssl-legacy-provider vitepress preview main",
-    "docs:build-cf": "NODE_OPTIONS=--openssl-legacy-provider vitepress build main && cp _redirects main/.vitepress/dist/",
-    "docs:build-root": "NODE_OPTIONS=--openssl-legacy-provider yarn docs:build && yarn docs:re-root && cp _redirects main/.vitepress/dist-root/",
-    "docs:re-root": "cd main && mkdir -p .vitepress/dist-root/ && cp -rp .vitepress/dist/ .vitepress/dist-root/documentation/",
+    "docs:build-cf": "NODE_OPTIONS=--openssl-legacy-provider vitepress build main && cp _redirects dist/",
     "test": "ava",
     "lint-fix": "yarn lint --fix",
     "lint": "eslint 'snippets/**/*.js'",
@@ -35,6 +33,7 @@
   "dependencies": {
     "@agoric/ertp": "community-dev",
     "@agoric/zoe": "community-dev",
+    "@agoric/zone": "0.2.3-u13.0",
     "@endo/far": "^0.2.19",
     "@endo/marshal": "^0.8.6",
     "@endo/pass-style": "^0.1.6",
@@ -140,6 +139,7 @@
   ],
   "prettier": {
     "trailingComma": "all",
+    "arrowParens": "avoid",
     "singleQuote": true
   }
 }

snippets/zoe/contracts/test-zoe-hello.js

@@ -19,9 +19,10 @@ test('contract greets by name', async t => {
 // #region test-state
 test('state', async t => {
   const { publicFacet } = state.start();
-  t.is(await E(publicFacet).get(), 'Hello, World!');
-  await E(publicFacet).set(2);
-  t.is(await E(publicFacet).get(), 2);
+  const actual = await E(publicFacet).getRoomCount();
+  t.is(actual, 0);
+  await E(publicFacet).makeRoom(2);
+  t.is(await E(publicFacet).getRoomCount(), 1);
 });
 // #endregion test-state
 

snippets/zoe/src/02-state.js

@@ -1,13 +1,25 @@
 import { Far } from '@endo/far';
 
 // #region startfn
+// #region heap-state
 export const start = () => {
-  let value = 'Hello, World!';
-  const get = () => value;
-  const set = v => (value = v);
+  const rooms = new Map();
+
+  const getRoomCount = () => rooms.size;
+  const makeRoom = id => {
+    let count = 0;
+    const room = Far('Room', {
+      getId: () => id,
+      incr: () => (count += 1),
+      decr: () => (count -= 1),
+    });
+    rooms.set(id, room);
+    return room;
+  };
+  // #endregion heap-state
 
   return {
-    publicFacet: Far('ValueCell', { get, set }),
+    publicFacet: Far('RoomMaker', { getRoomCount, makeRoom }),
   };
 };
 // #endregion startfn