feat: Add a helper for publishing iteration results to chain storage

packages/vats/decentral-core-config.json

@@ -21,6 +21,9 @@
     "board": {
       "sourceSpec": "@agoric/vats/src/vat-board.js"
     },
+    "chainStorage": {
+      "sourceSpec": "./src/vat-chainStorage.js"
+    },
     "distributeFees": {
       "sourceSpec": "@agoric/vats/src/vat-distributeFees.js"
     },

packages/vats/src/bridge-ids.js

@@ -2,5 +2,6 @@
 export const BANK = 'bank';
 export const CORE = 'core';
 export const DIBC = 'dibc';
+export const STORAGE = 'storage';
 export const PROVISION = 'provision';
 export const WALLET = 'wallet';

packages/vats/src/core/chain-behaviors.js

@@ -282,6 +282,36 @@ export const makeBridgeManager = async ({
 };
 harden(makeBridgeManager);
 
+/**
+ * @param {BootstrapPowers & {
+ *   consume: { loadVat: ERef<VatLoader<ChainStorageVat>> }
+ * }} powers
+ */
+export const makeChainStorage = async ({
+  consume: { bridgeManager: bridgeManagerP, loadVat },
+  produce: { chainStorage: chainStorageP },
+}) => {
+  const bridgeManager = await bridgeManagerP;
+  if (!bridgeManager) {
+    console.warn('Cannot support chainStorage without an actual chain.');
+    chainStorageP.resolve(undefined);
+    return;
+  }
+
+  // TODO: Formalize root key.
+  // Must not be any of {activityhash,beansOwing,egress,mailbox},
+  // and must be reserved in sites that use those keys (both Go and JS).
+  const ROOT_KEY = 'published';
+
+  const vat = E(loadVat)('chainStorage');
+  const rootNodeP = E(vat).makeBridgedChainStorageRoot(
+    bridgeManager,
+    BRIDGE_ID.STORAGE,
+    ROOT_KEY,
+  );
+  chainStorageP.resolve(rootNodeP);
+};
+
 /**
  * no free lunch on chain
  *

packages/vats/src/core/manifest.js

@@ -82,6 +82,15 @@ const SHARED_CHAIN_BOOTSTRAP_MANIFEST = harden({
     },
     home: { produce: { chainTimerService: 'timer' } },
   },
+  makeChainStorage: {
+    consume: {
+      bridgeManager: true,
+      loadVat: true,
+    },
+    produce: {
+      chainStorage: true,
+    },
+  },
   makeClientBanks: {
     consume: {
       bankManager: 'bank',

packages/vats/src/core/types.js

@@ -189,6 +189,7 @@
  *   bldIssuerKit: RemoteIssuerKit,
  *   board: Board,
  *   bridgeManager: OptionalBridgeManager,
+ *   chainStorage: unknown,
  *   chainTimerService: TimerService,
  *   client: ClientManager,
  *   clientCreator: ClientCreator,
@@ -235,6 +236,7 @@
  * @typedef {{ mint: ERef<Mint>, issuer: ERef<Issuer>, brand: Brand }} RemoteIssuerKit
  * @typedef {ReturnType<Awaited<BankVat>['makeBankManager']>} BankManager
  * @typedef {ERef<ReturnType<import('../vat-bank.js').buildRootObject>>} BankVat
+ * @typedef {ERef<ReturnType<import('../vat-chainStorage.js').buildRootObject>>} ChainStorageVat
  * @typedef {ERef<ReturnType<import('../vat-provisioning.js').buildRootObject>>} ProvisioningVat
  * @typedef {ERef<ReturnType<import('../vat-mints.js').buildRootObject>>} MintsVat
  * @typedef {ERef<ReturnType<import('../vat-priceAuthority.js').buildRootObject>>} PriceAuthorityVat

packages/vats/src/lib-chainPublish.js

@@ -0,0 +1,57 @@
+// @ts-check
+
+import { observeIteration } from '@agoric/notifier';
+import { E } from '@endo/far';
+
+/**
+ * Publish results of an async iterable into a chain storage node as an array
+ * serialized using JSON.stringify or an optionally provided function (e.g.,
+ * leveraging a serialize function from makeMarshal).
+ * Array items are possibly-duplicated [index, value] pairs, where index is a
+ * string (ascending numeric or terminal "finish" or "fail").
+ *
+ * @param {ERef<AsyncIterable>} source
+ * @param {{ setValue: (val: any) => void }} chainStorageNode
+ * @param {{ timerService: ERef<TimerService>, serialize?: (obj: any) => string }} powers
+ */
+export async function publishToChainNode(
+  source,
+  chainStorageNode,
+  { timerService, serialize = JSON.stringify },
+) {
+  let nextIndex = 0n;
+  let isNewBlock = true;
+  let oldResults = [];
+  let results = [];
+  const makeAcceptor = forceIndex => {
+    return value => {
+      if (isNewBlock) {
+        isNewBlock = false;
+        oldResults = results;
+        results = [];
+        E(timerService)
+          .delay(1n)
+          .then(() => {
+            isNewBlock = true;
+          });
+      }
+      // To avoid loss when detecting the new block *after* already consuming
+      // results produced within it, we associate each result with an index and
+      // include results of the previous batch.
+      // Downstream consumers are expected to deduplicate by index.
+      // We represent the index as a string to maintain compatibility with
+      // JSON.stringify and to avoid overly inflating the data size (e.g. with
+      // "@qclass" objects from makeMarshal serialize functions).
+      const index = forceIndex || String(nextIndex);
+      nextIndex += 1n;
+      results.push([index, value]);
+      const combined = harden(oldResults.slice().concat(results));
+      E(chainStorageNode).setValue(serialize(combined));
+    };
+  };
+  await observeIteration(source, {
+    updateState: makeAcceptor(),
+    finish: makeAcceptor('finish'),
+    fail: makeAcceptor('fail'),
+  });
+}

packages/vats/src/lib-chainStorage.js

@@ -0,0 +1,70 @@
+// @ts-check
+
+import { Far } from '@endo/far';
+
+const { details: X } = assert;
+
+// TODO: Formalize segment constraints.
+// Must be nonempty and disallow (unescaped) `.`, and for simplicity
+// (and future possibility of e.g. escaping) we currently limit to
+// ASCII alphanumeric plus underscore.
+const pathSegmentPattern = /^[a-zA-Z0-9_-]{1,100}$/;
+
+/**
+ * Create a root storage node for a given backing function and root key.
+ *
+ * @param {(message: any) => any} toStorage a function for sending a storageMessage object to the storage implementation (cf. golang/cosmos/x/swingset/storage.go)
+ * @param {string} rootKey
+ */
+export function makeChainStorageRoot(toStorage, rootKey) {
+  assert.typeof(rootKey, 'string');
+
+  function makeChainStorageNode(key) {
+    const node = {
+      getKey() {
+        return key;
+      },
+      getChildNode(name) {
+        assert.typeof(name, 'string');
+        assert(
+          pathSegmentPattern.test(name),
+          X`Path segment must be a short ASCII identifier: ${name}`,
+        );
+        return makeChainStorageNode(`${key}.${name}`);
+      },
+      setValue(value) {
+        assert.typeof(value, 'string');
+        toStorage({ key, method: 'set', value });
+      },
+      async delete() {
+        assert(key !== rootKey);
+        // A 'set' with no value deletes a key if it has no children, but
+        // otherwise sets data to the empty string and leaves all nodes intact.
+        // We want to reject silently incomplete deletes (at least for now).
+        // This check is unfortunately racy (e.g., a vat could wake up
+        // and set data for a child before _this_ vat receives an
+        // already-enqueued response claiming no children), but we can tolerate
+        // that because transforming a deletion into a set-to-empty is
+        // effectively indistinguishable from a valid reordering where a fully
+        // successful 'delete' is followed by a child-key 'set' (for which
+        // absent parent keys are automatically created with empty-string data).
+        const childCount = await toStorage({ key, method: 'size' });
+        if (childCount > 0) {
+          assert.fail(X`Refusing to delete node with children: ${key}`);
+        }
+        toStorage({ key, method: 'set' });
+      },
+      // Possible extensions:
+      // * getValue()
+      // * getChildNames() and/or getChildNodes()
+      // * getName()
+      // * recursive delete
+      // * batch operations
+      // * local buffering (with end-of-block commit)
+    };
+    return Far('chainStorageNode', node);
+  }
+
+  const rootNode = makeChainStorageNode(rootKey);
+  return rootNode;
+}

packages/vats/src/vat-chainStorage.js

@@ -0,0 +1,15 @@
+import { E, Far } from '@endo/far';
+import { makeChainStorageRoot } from './lib-chainStorage.js';
+
+export function buildRootObject(_vatPowers) {
+  function makeBridgedChainStorageRoot(bridgeManager, bridgeId, rootKey) {
+    // XXX: Should we validate uniqueness of rootKey, or is that an external concern?
+    const toStorage = message => E(bridgeManager).toBridge(bridgeId, message);
+    const rootNode = makeChainStorageRoot(toStorage, rootKey);
+    return rootNode;
+  }
+
+  return Far('root', {
+    makeBridgedChainStorageRoot,
+  });
+}