docs: vstorage reference; chainStorage publishing guide

main/guides/coreeval/permissions.md

@@ -34,9 +34,10 @@ export const main = startSellConcertTicketsContract;
 
 In the top level promise space, we have:
 
-- **agoricNames**: read-only access to the [agoricNames](../integration/name-services.md#agoricnames-agoricnamesadmin-well-known-names) name service.
+- **agoricNames**: read-only access to the [agoricNames](../integration/name-services#agoricnames-agoricnamesadmin-well-known-names) name service.
 
-- **agoricNamesAdmin**: admin / update access to **agoricNames** and the name hubs it contains.
+- **agoricNamesAdmin**: admin / update access to [agoricNames](../integration/name-services#agoricnames-agoricnamesadmin-well-known-names) and the name hubs it contains.
+  **Warning: this includes access to over-write existing bindings to instances, brands, etc.**
   **Warning: this includes the right to over-write existing bindings to instances, brands, etc.**
 
 - **bankManager**: to manage reflection of cosmos
@@ -45,14 +46,14 @@ In the top level promise space, we have:
 - **board**: the [board](../integration/name-services.md#the-board-publishing-under-arbitrary-names) name service.
   **Note: the board only grows; no mechanism to reclaim storage has been established.**
 
-- **chainStorage**: to make storage nodes to write to vstorage.
-  **Warning: this includes the right to over-write previously allocated storage nodes.**
+- **chainStorage**: to make storage nodes to [write to vstorage](../zoe/pub-to-storage).
+  **Warning: this includes access to over-write previously allocated storage nodes.**
 
-- **chainTimerService**: for getting the current timer and setting timer wake-ups; for example, at the conclusion of a governance vote.
-  **Note: this includes the right to schedule infinitely repeating events.**
+- **chainTimerService**: for getting the current [timer](../../reference/repl/timerServices) and setting timer wake-ups; for example, at the conclusion of a governance vote.
+  **Note: this includes access to schedule infinitely repeating events.**
 
 - **priceAuthority**: access to get price quotes and triggers; see [Price Authority Guide](../zoe/price-authority).
 
 - **priceAuthorityAdmin**: access to add and replace sources of price quotes using [E(priceAuthorityAdmin).registerPriceAuthority()](../../reference/zoe-api/price-authority-admin#e-priceauthorityregistryadmin-registerpriceauthority-priceauthority-brandin-brandout-force)
 
-- **zoe**: the Zoe service
+- **zoe**: the [Zoe service](../../reference/zoe-api//zoe)

main/guides/governance/index.md

@@ -46,7 +46,7 @@ Adding parameter governance to a contract consists mainly of using `handleParamG
 We pass it `zcf` so that it can `getTerms()` for initial parameter values, and we
 pass `paramTypes` to specify governed parameters and their types. `initialPoserInvitation`
 is necessary to set up replacing the electorate. `storageNode` and `marshaller` are used
-to publish values of the parameters to vstorage.
+to [publish values of the parameters to vstorage](../zoe/pub-to-storage).
 
 ```js
 import { handleParamGovernance } from '@agoric/governance/src/contractHelper.js';

main/guides/zoe/pub-to-storage.md

@@ -0,0 +1,159 @@
+# Publishing to chainStorage
+
+Contracts can use [notifiers and subscriptions](../js-programming/notifiers)
+to publish to clients. To publish data visible to [vstorage queries](../getting-started/contract-rpc#querying-vstorage), contracts should connect
+a subscriber to a `chainStorage` node.
+
+## Deployment Capabilities for Publishing to chainStorage
+
+In [Adding Parameter Governance to a Contract](../governance/#adding-parameter-governance-to-a-contract), 
+`storageNode` and `marshaller` are passed to the contract in its `privateArgs` so it can publish to chainStorage.
+
+In [dapp-agoric-basics](https://github.com/Agoric/dapp-agoric-basics), the `startSwapContract` uses 2 [permitted deployment capabilities](../coreeval/permissions), `chainStorage` and `board` and uses them to make the `privateArgs`:
+
+```js
+const marshaller = await E(board).getPublishingMarshaller();
+const storageNode = await E(chainStorage).makeChildNode(contractName);
+```
+
+A `Marshaller` is parameterized by functions for mapping unforgeable object identities to plain data slot references and back. Using the [board](../integration/name-services#the-board-publishing-under-arbitrary-names) name service gives consistent slot references across contracts.
+As discussed in [Marshalling Amounts and Instances](../getting-started/contract-rpc#marshalling-amounts-and-instances), this lets
+off-chain clients use the same `@endo/marshal` API.
+
+The `chainStorage` node corresponds to the `published` key in the
+[vstorage hierarchy](/reference/vstorage-ref).
+Using `E(chainStorage).makeChildNode(contractName)` gives the contract
+access to write to the `published.swaparoo` key and all keys under it.
+
+The `swaparoo` contract delegates the rest of publishing governance parameters to the `@agoric/governance` package.
+
+## Publishing structured data to chainStorage
+
+Let's look at the Inter Protocol [assetReserve.js](https://github.com/Agoric/agoric-sdk/blob/agoric-upgrade-13/packages/inter-protocol/src/reserve/assetReserve.js) contract to get more of the details. It publishes to [published.reserve.metrics](https://github.com/Agoric/agoric-sdk/blob/agoric-upgrade-13/packages/inter-protocol/test/reserve/snapshots/test-reserve.js.md) data of the form
+
+```js
+/**
+ * @typedef {object} MetricsNotification
+ * @property {AmountKeywordRecord} allocations
+ * @property {Amount<'nat'>} shortfallBalance shortfall from liquidation that
+ *   has not yet been compensated.
+ * @property {Amount<'nat'>} totalFeeMinted total Fee tokens minted to date
+ * @property {Amount<'nat'>} totalFeeBurned total Fee tokens burned to date
+ */
+```
+
+For example:
+
+```js
+    {
+      allocations: {
+        Fee: {
+          brand: Object @Alleged: IST brand {},
+          value: 64561373455n,
+        },
+        ATOM: {
+          brand: Object @Alleged: ATOM brand {},
+          value: 6587020n
+        },
+      },
+      shortfallBalance: {
+        brand: Object @Alleged: IST brand {},
+        value: 5747205025n,
+      },
+      totalFeeBurned: {
+        brand: Object @Alleged: IST brand {},
+        value: n,
+      },
+      totalFeeMinted: {
+        brand: Object @Alleged: IST brand {},
+        value: 0n,
+      },
+    },
+```
+
+The method that writes this data is:
+
+```js
+        writeMetrics() {
+          const { state } = this;
+          const metrics = harden({
+            allocations: state.collateralSeat.getCurrentAllocation(),
+            shortfallBalance: state.shortfallBalance,
+            totalFeeMinted: state.totalFeeMinted,
+            totalFeeBurned: state.totalFeeBurned,
+          });
+          void state.metricsKit.recorder.write(metrics);
+        },
+```
+
+The `metricsKit` is made with a `makeRecorderKit` function:
+
+```js
+        metricsKit: makeRecorderKit(
+          metricsNode,
+          /** @type {import('@agoric/zoe/src/contractSupport/recorder.js').TypedMatcher<MetricsNotification>} */ (
+            M.any()
+          ),
+        ),
+```
+
+We "prepare" (in the [exo](https://endojs.github.io/endo/modules/_endo_exo.html) sense) that function for making
+a `RecorderKit` using [prepareRecorderKitMakers](/reference/zoe-api/zoe-helpers#preparerecorderkitmakers-baggage-marshaller).
+
+```js
+const { makeRecorderKit } = prepareRecorderKitMakers(
+  baggage,
+  privateArgs.marshaller,
+);
+```
+
+The contract gets `baggage`, along with `privateArgs` when it starts in
+[the usual way for upgradable contracts](./contract-upgrade.html#upgradable-declaration):
+
+```js
+/**
+ * Asset Reserve holds onto assets for the Inter Protocol, and ...
+ *
+ * @param {{
+ *   ...
+ *   marshaller: ERef<Marshaller>,
+ *   storageNode: ERef<StorageNode>,
+ * }} privateArgs
+ * @param {Baggage} baggage
+ */
+export const prepare = async (zcf, privateArgs, baggage) => {
+    ...
+};
+```
+
+The reserve uses its `StorageNode` and makes a child to get `metricsNode`:
+
+```js
+const metricsNode = await E(storageNode).makeChildNode('metrics');
+```
+
+The `marshaller` is used to serialize data structures such as `MetricsNotification` above.
+
+### Deployment Capabilities for the reserve
+
+To start `assetReserve`, the [setupReserve](https://github.com/Agoric/agoric-sdk/blob/agoric-upgrade-13/packages/inter-protocol/src/proposals/econ-behaviors.js#L76) function again supplies
+the two relevant `privateArgs`, `marshaller` and `storageNode`:
+
+```js
+const STORAGE_PATH = 'reserve';
+const storageNode = await E(storageNode).makeChildNode(STORAGE_PATH);
+const marshaller = await E(board).getReadonlyMarshaller();
+```
+
+The `setupReserve` function gets `chainStorage` and `board` deployment capabilities passed in:
+
+```js
+export const setupReserve = async ({
+  consume: {
+    board,
+    chainStorage,
+    ...
+  },
+...
+}) => { ... };
+```