@agoric/internal 0.2.2-pismo-dev-0d5327f.0 → 0.3.1-dev-bf4b59f.0

package/src/config.js

@@ -1,9 +1,12 @@
 // @ts-check
-/** @file
+// @jessie-check
+
+/**
+ * @file
  *
  * Some of this config info may make more sense in a particular package. However
- * due to the maxNodeModuleJsDepth hack and our general lax dependency graph,
- * sometimes rational placements cause type resolution errors.
+ * due to https://github.com/Agoric/agoric-sdk/issues/4620 and our lax package
+ * dependency graph, sometimes rational placements cause type resolution errors.
  *
  * So as a work-around some constants that need access from more than one package are placed here.
  */
@@ -17,6 +20,7 @@ export const BridgeId = {
   DIBC: 'dibc',
   STORAGE: 'storage',
   PROVISION: 'provision',
+  PROVISION_SMART_WALLET: 'provisionWallet',
   WALLET: 'wallet',
 };
 harden(BridgeId);
@@ -25,3 +29,16 @@ export const WalletName = {
   depositFacet: 'depositFacet',
 };
 harden(WalletName);
+
+// defined in golang/cosmos/x/vbank
+export const VBankAccount = {
+  reserve: {
+    module: 'vbank/reserve',
+    address: 'agoric1ae0lmtzlgrcnla9xjkpaarq5d5dfez63h3nucl',
+  },
+  provision: {
+    module: 'vbank/provision',
+    address: 'agoric1megzytg65cyrgzs6fvzxgrcqvwwl7ugpt62346',
+  },
+};
+harden(VBankAccount);

package/src/debug.d.ts

@@ -0,0 +1,2 @@
+export function makeTracer(name: string, enable?: boolean | 'verbose'): (..._args: any[]) => void;
+//# sourceMappingURL=debug.d.ts.map

package/src/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["debug.js"],"names":[],"mappings":"AAQO,iCAHI,MAAM,WACN,OAAO,GAAG,SAAS,6BAiC7B"}

package/src/debug.js

@@ -0,0 +1,41 @@
+// @jessie-check
+
+let debugInstance = 1;
+
+/**
+ * @param {string} name
+ * @param {boolean | 'verbose'} enable
+ */
+export const makeTracer = (name, enable = true) => {
+  debugInstance += 1;
+  let debugCount = 1;
+  const key = `----- ${name}.${debugInstance} `;
+  // the cases below define a named variable to provide better debug info
+  switch (enable) {
+    case false: {
+      const logDisabled = (..._args) => {};
+      return logDisabled;
+    }
+    case 'verbose': {
+      const infoTick = (optLog, ...args) => {
+        if (optLog.log) {
+          console.info(key, (debugCount += 1), ...args);
+        } else {
+          console.info(key, (debugCount += 1), optLog, ...args);
+        }
+      };
+      return infoTick;
+    }
+    default: {
+      const debugTick = (optLog, ...args) => {
+        if (optLog.log) {
+          optLog.log(key, (debugCount += 1), ...args);
+        } else {
+          console.info(key, (debugCount += 1), optLog, ...args);
+        }
+      };
+      return debugTick;
+    }
+  }
+};
+harden(makeTracer);

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./config.js";
+export * from "./debug.js";
+export * from "./utils.js";
+export * from "./method-tools.js";
+export * from "./typeGuards.js";
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":""}

package/src/index.js

@@ -1,4 +1,9 @@
-// @ts-check
+// @jessie-check
+
+/// <reference types="ses"/>
 
-export * from './utils.js';
 export * from './config.js';
+export * from './debug.js';
+export * from './utils.js';
+export * from './method-tools.js';
+export * from './typeGuards.js';

package/src/lib-chainStorage.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Create a heap-based root storage node for a given backing function and root path.
+ *
+ * @param {(message: StorageMessage) => any} handleStorageMessage a function for
+ * sending a storageMessage object to the storage implementation
+ * (cf. golang/cosmos/x/vstorage/vstorage.go)
+ * @param {string} rootPath
+ * @param {object} [rootOptions]
+ * @param {boolean} [rootOptions.sequence] employ a wrapping structure that
+ * preserves each value set within a single block, and default child nodes
+ * to do the same
+ */
+export function makeChainStorageRoot(handleStorageMessage: (message: StorageMessage) => any, rootPath: string, rootOptions?: {
+    sequence?: boolean | undefined;
+} | undefined): {
+    getPath(): string;
+    /**
+     * @deprecated use getPath
+     * @type {() => Promise<VStorageKey>}
+     */
+    getStoreKey(): Promise<VStorageKey>;
+    /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
+    makeChildNode(name: string, childNodeOptions?: {
+        sequence?: boolean | undefined;
+    } | undefined): StorageNode;
+    /** @type {(value: string) => Promise<void>} */
+    setValue(value: string): Promise<void>;
+} & import("@endo/eventual-send").RemotableBrand<{}, {
+    getPath(): string;
+    /**
+     * @deprecated use getPath
+     * @type {() => Promise<VStorageKey>}
+     */
+    getStoreKey(): Promise<VStorageKey>;
+    /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
+    makeChildNode(name: string, childNodeOptions?: {
+        sequence?: boolean | undefined;
+    } | undefined): StorageNode;
+    /** @type {(value: string) => Promise<void>} */
+    setValue(value: string): Promise<void>;
+}>;
+/**
+ * Convenience function for returning a storage node at or under its input,
+ * falling back to an inert object with the correct interface (but incomplete
+ * behavior) when that is unavailable.
+ *
+ * @param {import('@endo/far').ERef<StorageNode?>} storageNodeRef
+ * @param {string} childName
+ * @returns {Promise<StorageNode>}
+ */
+export function makeStorageNodeChild(storageNodeRef: import('@endo/far').ERef<StorageNode | null>, childName: string): Promise<StorageNode>;
+export function isStreamCell(cell: any): cell is StreamCell<unknown>;
+export function assertCapData(data: unknown): asserts data is import("@endo/marshal").CapData<string>;
+export function unmarshalFromVstorage(data: Map<string, string>, key: string, fromCapData: ReturnType<typeof import('@endo/marshal').makeMarshal>['fromCapData'], index?: number | undefined): any;
+/** @type {(name: string) => void} */
+export const assertPathSegment: (name: string) => void;
+export function prepareChainStorageNode(zone: import('@agoric/zone').Zone): (args_0: import("./types.js").Callback<(message: StorageMessage) => any>, args_1: string, args_2?: {
+    sequence?: boolean | undefined;
+} | undefined) => {
+    getPath(): string;
+    /**
+     * @deprecated use getPath
+     * @type {() => Promise<VStorageKey>}
+     */
+    getStoreKey(): Promise<VStorageKey>;
+    /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
+    makeChildNode(name: string, childNodeOptions?: {
+        sequence?: boolean | undefined;
+    } | undefined): StorageNode;
+    /** @type {(value: string) => Promise<void>} */
+    setValue(value: string): Promise<void>;
+} & import("@endo/eventual-send").RemotableBrand<{}, {
+    getPath(): string;
+    /**
+     * @deprecated use getPath
+     * @type {() => Promise<VStorageKey>}
+     */
+    getStoreKey(): Promise<VStorageKey>;
+    /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
+    makeChildNode(name: string, childNodeOptions?: {
+        sequence?: boolean | undefined;
+    } | undefined): StorageNode;
+    /** @type {(value: string) => Promise<void>} */
+    setValue(value: string): Promise<void>;
+}>;
+export function makeSerializeToStorage(storageNode: import('@endo/far').ERef<StorageNode>, marshaller: import('@endo/far').ERef<Marshaller>): (value: unknown) => Promise<void>;
+export type Marshaller = ReturnType<typeof import('@endo/marshal').makeMarshal>;
+export type Unserializer = Pick<Marshaller, 'fromCapData'>;
+/**
+ * Defined by vstorageStoreKey in vstorage.go
+ */
+export type VStorageKey = {
+    storeName: string;
+    storeSubkey: string;
+    dataPrefixBytes: string;
+    noDataValue?: string | undefined;
+};
+export type StreamCell<T = unknown> = {
+    /**
+     * decimal representation of a natural number
+     */
+    blockHeight: string;
+    values: T[];
+};
+/**
+ * This represents a node in an IAVL tree.
+ *
+ * The active implementation is x/vstorage, an Agoric extension of the Cosmos SDK.
+ *
+ * Vstorage is a hierarchical externally-reachable storage structure that
+ * identifies children by restricted ASCII name and is associated with arbitrary
+ * string-valued data for each node, defaulting to the empty string.
+ */
+export type StorageNode = {
+    /**
+     * publishes some data
+     */
+    setValue: (data: string) => Promise<void>;
+    /**
+     * the chain storage path at which the node was constructed
+     */
+    getPath: () => string;
+    /**
+     * DEPRECATED use getPath
+     */
+    getStoreKey: () => Promise<VStorageKey>;
+    makeChildNode: (subPath: string, options?: {
+        sequence?: boolean;
+    }) => StorageNode;
+};
+export type StoredFacet = {
+    /**
+     * the chain storage path at which the node was constructed
+     */
+    getPath: () => Promise<string>;
+    /**
+     * DEPRECATED use getPath
+     */
+    getStoreKey: StorageNode['getStoreKey'];
+    /**
+     * get the unserializer for the stored data
+     */
+    getUnserializer: () => Unserializer;
+};
+/**
+ * Must match the switch in vstorage.go using `vstorageMessage` type
+ */
+export type StorageGetByPathMessageMethod = 'get' | 'getStoreKey' | 'has' | 'children' | 'entries' | 'values' | 'size';
+/**
+ * Must match the switch in vstorage.go using `vstorageMessage` type
+ */
+export type StorageUpdateEntriesMessageMethod = 'set' | 'setWithoutNotify' | 'append';
+/**
+ * Must match the switch in vstorage.go using `vstorageMessage` type
+ */
+export type StorageMessageMethod = StorageGetByPathMessageMethod | StorageUpdateEntriesMessageMethod;
+/**
+ * Must match the switch in vstorage.go using `vstorageMessage` type
+ */
+export type StorageGetByPathMessageArgs = [path: string];
+/**
+ * Must match the switch in vstorage.go using `vstorageMessage` type
+ */
+export type StorageEntry = [path: string, value?: string | null];
+/**
+ * Must match the switch in vstorage.go using `vstorageMessage` type
+ */
+export type StorageUpdateEntriesMessageArgs = [path: string, value?: string | null | undefined][];
+/**
+ * Must match the switch in vstorage.go using `vstorageMessage` type
+ */
+export type StorageMessage = {
+    method: StorageGetByPathMessageMethod;
+    args: [path: string];
+} | {
+    method: StorageUpdateEntriesMessageMethod;
+    args: StorageUpdateEntriesMessageArgs;
+};
+//# sourceMappingURL=lib-chainStorage.d.ts.map

package/src/lib-chainStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib-chainStorage.d.ts","sourceRoot":"","sources":["lib-chainStorage.js"],"names":[],"mappings":"AAmPA;;;;;;;;;;;GAWG;AACH,qEATqB,cAAc,KAAK,GAAG,YAGhC,MAAM;;;;IA1DX;;;OAGG;mBADa,QAAQ,WAAW,CAAC;IASpC,qFAAqF;wBAAnE,MAAM;;oBAA8C,WAAW;IAWjF,+CAA+C;oBAA5B,MAAM,GAAK,QAAQ,IAAI,CAAC;;;IAtB3C;;;OAGG;mBADa,QAAQ,WAAW,CAAC;IASpC,qFAAqF;wBAAnE,MAAM;;oBAA8C,WAAW;IAWjF,+CAA+C;oBAA5B,MAAM,GAAK,QAAQ,IAAI,CAAC;GAoDhD;AAUD;;;;;;;;GAQG;AACH,qDAJW,OAAO,WAAW,EAAE,IAAI,CAAC,WAAW,QAAE,aACtC,MAAM,GACJ,QAAQ,WAAW,CAAC,CAMhC;AAlOM,mCAHI,GAAG,+BAQ8B;AASrC,oCAHI,OAAO,2DASjB;AAWM,4CALI,IAAI,MAAM,EAAE,MAAM,CAAC,OACnB,MAAM,eACN,WAAW,cAAc,eAAe,EAAE,WAAW,CAAC,CAAC,aAAa,CAAC,mCAwB/E;AAgBD,qCAAqC;AACrC,uCADkB,MAAM,KAAK,IAAI,CAI/B;AAwBK,8CAFI,OAAO,cAAc,EAAE,IAAI,oDAqBiB,cAAc,KAAK,GAAG;;;;IAcvE;;;OAGG;mBADa,QAAQ,WAAW,CAAC;IASpC,qFAAqF;wBAAnE,MAAM;;oBAA8C,WAAW;IAWjF,+CAA+C;oBAA5B,MAAM,GAAK,QAAQ,IAAI,CAAC;;;IAtB3C;;;OAGG;mBADa,QAAQ,WAAW,CAAC;IASpC,qFAAqF;wBAAnE,MAAM;;oBAA8C,WAAW;IAWjF,+CAA+C;oBAA5B,MAAM,GAAK,QAAQ,IAAI,CAAC;GA0BhD;AA0DM,oDAJI,OAAO,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,cACrC,OAAO,WAAW,EAAE,IAAI,CAAC,UAAU,CAAC,WAC1B,OAAO,KAAK,QAAQ,IAAI,CAAC,CAQ7C;yBAvSa,WAAW,cAAc,eAAe,EAAE,WAAW,CAAC;2BACtD,KAAK,UAAU,EAAE,aAAa,CAAC;;;;;eAM/B,MAAM;iBACN,MAAM;qBACN,MAAM;;;;;;;iBAON,MAAM;YACN,CAAC,EAAE;;;;;;;;;;;;;;;qBAaI,MAAM,KAAK,QAAQ,IAAI,CAAC;;;;aAC/B,MAAM,MAAM;;;;iBACZ,MAAM,QAAQ,WAAW,CAAC;6BAChB,MAAM,YAAY;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAC,KAAK,WAAW;;;;;;aA8EhE,MAAM,QAAQ,MAAM,CAAC;;;;iBACrB,WAAW,CAAC,aAAa,CAAC;;;;qBAC1B,MAAM,YAAY;;;;;4CAmBlB,KAAK,GAAG,aAAa,GAAG,KAAK,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAE,MAAM;;;;gDACzE,KAAK,GAAG,kBAAkB,GAAG,QAAQ;;;;mCACtC,6BAA6B,GAAG,iCAAiC;;;;0CAChE,CAAC,IAAI,EAAE,MAAM,CAAC;;;;2BACd,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;;;;8CACrC,mDAAc;;;;6BACf;IACZ,MAAU,EAAE,6BAA6B,CAAC;IAC1C,IAAQ,iBAA8B;CAClC,GAAG;IACP,MAAU,EAAE,iCAAiC,CAAC;IAC9C,IAAQ,kCAAkC;CACvC"}

package/src/lib-chainStorage.js

@@ -0,0 +1,304 @@
+// @ts-check
+
+import { E } from '@endo/far';
+import { M, heapZone } from '@agoric/zone';
+import * as cb from './callback.js';
+
+const { Fail } = assert;
+
+/** @typedef {ReturnType<typeof import('@endo/marshal').makeMarshal>} Marshaller */
+/** @typedef {Pick<Marshaller, 'fromCapData'>} Unserializer */
+
+/**
+ * Defined by vstorageStoreKey in vstorage.go
+ *
+ * @typedef VStorageKey
+ * @property {string} storeName
+ * @property {string} storeSubkey
+ * @property {string} dataPrefixBytes
+ * @property {string} [noDataValue]
+ */
+
+/**
+ * @template [T=unknown]
+ * @typedef StreamCell
+ * @property {string} blockHeight decimal representation of a natural number
+ * @property {T[]} values
+ */
+
+/**
+ * This represents a node in an IAVL tree.
+ *
+ * The active implementation is x/vstorage, an Agoric extension of the Cosmos SDK.
+ *
+ * Vstorage is a hierarchical externally-reachable storage structure that
+ * identifies children by restricted ASCII name and is associated with arbitrary
+ * string-valued data for each node, defaulting to the empty string.
+ *
+ * @typedef {object} StorageNode
+ * @property {(data: string) => Promise<void>} setValue publishes some data
+ * @property {() => string} getPath the chain storage path at which the node was constructed
+ * @property {() => Promise<VStorageKey>} getStoreKey DEPRECATED use getPath
+ * @property {(subPath: string, options?: {sequence?: boolean}) => StorageNode} makeChildNode
+ */
+
+const ChainStorageNodeI = M.interface('StorageNode', {
+  setValue: M.callWhen(M.string()).returns(),
+  getPath: M.call().returns(M.string()),
+  getStoreKey: M.callWhen().returns(M.record()),
+  makeChildNode: M.call(M.string())
+    .optional(M.splitRecord({}, { sequence: M.boolean() }, {}))
+    .returns(M.remotable('StorageNode')),
+});
+
+/**
+ * This is an imperfect heuristic to navigate the migration from value cells to
+ * stream cells.
+ * At time of writing, no legacy cells have the same shape as a stream cell,
+ * and we do not intend to create any more legacy value cells.
+ *
+ * @param {any} cell
+ * @returns {cell is StreamCell}
+ */
+export const isStreamCell = cell =>
+  cell &&
+  typeof cell === 'object' &&
+  Array.isArray(cell.values) &&
+  typeof cell.blockHeight === 'string' &&
+  /^0$|^[1-9][0-9]*$/.test(cell.blockHeight);
+harden(isStreamCell);
+
+// TODO: Consolidate with `insistCapData` functions from swingset-liveslots,
+// swingset-xsnap-supervisor, etc.
+/**
+ * @param {unknown} data
+ * @returns {asserts data is import('@endo/marshal').CapData<string>}
+ */
+export const assertCapData = data => {
+  assert.typeof(data, 'object');
+  assert(data);
+  assert.typeof(data.body, 'string');
+  assert(Array.isArray(data.slots));
+  // XXX check that the .slots array elements are actually strings
+};
+harden(assertCapData);
+
+/**
+ * Read and unmarshal a value from a map representation of vstorage data
+ *
+ * @param {Map<string, string>} data
+ * @param {string} key
+ * @param {ReturnType<typeof import('@endo/marshal').makeMarshal>['fromCapData']} fromCapData
+ * @param {number} [index=-1] index of the desired value in a deserialized stream cell
+ */
+export const unmarshalFromVstorage = (data, key, fromCapData, index = -1) => {
+  const serialized = data.get(key) || Fail`no data for ${key}`;
+  assert.typeof(serialized, 'string');
+
+  const streamCell = JSON.parse(serialized);
+  if (!isStreamCell(streamCell)) {
+    throw Fail`not a StreamCell: ${streamCell}`;
+  }
+
+  const { values } = streamCell;
+  values.length > 0 || Fail`no StreamCell values: ${streamCell}`;
+
+  const marshalled = values.at(index);
+  assert.typeof(marshalled, 'string');
+
+  /** @type {import("@endo/marshal").CapData<string>} */
+  const capData = harden(JSON.parse(marshalled));
+  assertCapData(capData);
+
+  const unmarshalled = fromCapData(capData);
+  return unmarshalled;
+};
+harden(unmarshalFromVstorage);
+
+/**
+ * @typedef {object} StoredFacet
+ * @property {() => Promise<string>} getPath the chain storage path at which the node was constructed
+ * @property {StorageNode['getStoreKey']} getStoreKey DEPRECATED use getPath
+ * @property {() => Unserializer} getUnserializer get the unserializer for the stored data
+ */
+
+// 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 and dash.
+const pathSegmentPattern = /^[a-zA-Z0-9_-]{1,100}$/;
+
+/** @type {(name: string) => void} */
+export const assertPathSegment = name => {
+  pathSegmentPattern.test(name) ||
+    Fail`Path segment names must consist of 1 to 100 characters limited to ASCII alphanumerics, underscores, and/or dashes: ${name}`;
+};
+harden(assertPathSegment);
+
+/**
+ * Must match the switch in vstorage.go using `vstorageMessage` type
+ *
+ * @typedef { 'get' | 'getStoreKey' | 'has' | 'children' | 'entries' | 'values' |'size' } StorageGetByPathMessageMethod
+ * @typedef { 'set' | 'setWithoutNotify' | 'append' } StorageUpdateEntriesMessageMethod
+ * @typedef {StorageGetByPathMessageMethod | StorageUpdateEntriesMessageMethod } StorageMessageMethod
+ * @typedef { [path: string] } StorageGetByPathMessageArgs
+ * @typedef { [path: string, value?: string | null] } StorageEntry
+ * @typedef { StorageEntry[] } StorageUpdateEntriesMessageArgs
+ * @typedef {{
+ *   method: StorageGetByPathMessageMethod;
+ *   args: StorageGetByPathMessageArgs;
+ *  } | {
+ *   method: StorageUpdateEntriesMessageMethod;
+ *   args: StorageUpdateEntriesMessageArgs;
+ * }} StorageMessage
+ */
+
+/**
+ * @param {import('@agoric/zone').Zone} zone
+ */
+export const prepareChainStorageNode = zone => {
+  /**
+   * Create a storage node for a given backing storage interface and path.
+   *
+   * @param {import('./callback').Callback<(message: StorageMessage) => any>} messenger a callback
+   * for sending a storageMessage object to the storage implementation
+   * (cf. golang/cosmos/x/vstorage/vstorage.go)
+   * @param {string} path
+   * @param {object} [options]
+   * @param {boolean} [options.sequence] set values with `append` messages rather than `set` messages
+   * so the backing implementation employs a wrapping structure that
+   * preserves each value set within a single block.
+   * Child nodes default to inheriting this option from their parent.
+   * @returns {StorageNode}
+   */
+  const makeChainStorageNode = zone.exoClass(
+    'ChainStorageNode',
+    ChainStorageNodeI,
+    /**
+     * @param {import('./callback').Callback<(message: StorageMessage) => any>} messenger
+     * @param {string} path
+     * @param {object} [options]
+     * @param {boolean} [options.sequence]
+     */
+    (messenger, path, { sequence = false } = {}) => {
+      assert.typeof(path, 'string');
+      assert.typeof(sequence, 'boolean');
+      return harden({ path, messenger, sequence });
+    },
+    {
+      getPath() {
+        return this.state.path;
+      },
+      /**
+       * @deprecated use getPath
+       * @type {() => Promise<VStorageKey>}
+       */
+      async getStoreKey() {
+        const { path, messenger } = this.state;
+        return cb.callE(messenger, {
+          method: 'getStoreKey',
+          args: [path],
+        });
+      },
+      /** @type {(name: string, childNodeOptions?: {sequence?: boolean}) => StorageNode} */
+      makeChildNode(name, childNodeOptions = {}) {
+        const { sequence, path, messenger } = this.state;
+        assertPathSegment(name);
+        const mergedOptions = { sequence, ...childNodeOptions };
+        return makeChainStorageNode(
+          messenger,
+          `${path}.${name}`,
+          mergedOptions,
+        );
+      },
+      /** @type {(value: string) => Promise<void>} */
+      async setValue(value) {
+        const { sequence, path, messenger } = this.state;
+        assert.typeof(value, 'string');
+        /** @type {StorageEntry} */
+        let entry;
+        if (!sequence && !value) {
+          entry = [path];
+        } else {
+          entry = [path, value];
+        }
+        await cb.callE(messenger, {
+          method: sequence ? 'append' : 'set',
+          args: [entry],
+        });
+      },
+      // Possible extensions:
+      // * getValue()
+      // * getChildNames() and/or makeChildNodes()
+      // * getName()
+      // * recursive delete
+      // * batch operations
+      // * local buffering (with end-of-block commit)
+    },
+  );
+  return makeChainStorageNode;
+};
+
+const makeHeapChainStorageNode = prepareChainStorageNode(heapZone);
+
+/**
+ * Create a heap-based root storage node for a given backing function and root path.
+ *
+ * @param {(message: StorageMessage) => any} handleStorageMessage a function for
+ * sending a storageMessage object to the storage implementation
+ * (cf. golang/cosmos/x/vstorage/vstorage.go)
+ * @param {string} rootPath
+ * @param {object} [rootOptions]
+ * @param {boolean} [rootOptions.sequence] employ a wrapping structure that
+ * preserves each value set within a single block, and default child nodes
+ * to do the same
+ */
+export function makeChainStorageRoot(
+  handleStorageMessage,
+  rootPath,
+  rootOptions = {},
+) {
+  const messenger = cb.makeFunctionCallback(handleStorageMessage);
+
+  // Use the heapZone directly.
+  const rootNode = makeHeapChainStorageNode(messenger, rootPath, rootOptions);
+  return rootNode;
+}
+
+/**
+ * @returns {StorageNode} an object that confirms to StorageNode API but does not store anywhere.
+ */
+const makeNullStorageNode = () => {
+  // XXX re-use "ChainStorage" methods above which don't actually depend on chains
+  return makeChainStorageRoot(() => null, 'null');
+};
+
+/**
+ * Convenience function for returning a storage node at or under its input,
+ * falling back to an inert object with the correct interface (but incomplete
+ * behavior) when that is unavailable.
+ *
+ * @param {import('@endo/far').ERef<StorageNode?>} storageNodeRef
+ * @param {string} childName
+ * @returns {Promise<StorageNode>}
+ */
+export async function makeStorageNodeChild(storageNodeRef, childName) {
+  const existingStorageNode = await storageNodeRef;
+  const storageNode = existingStorageNode || makeNullStorageNode();
+  return E(storageNode).makeChildNode(childName);
+}
+harden(makeStorageNodeChild);
+
+// TODO find a better module for this
+/**
+ * @param {import('@endo/far').ERef<StorageNode>} storageNode
+ * @param {import('@endo/far').ERef<Marshaller>} marshaller
+ * @returns {(value: unknown) => Promise<void>}
+ */
+export const makeSerializeToStorage = (storageNode, marshaller) => {
+  return async value => {
+    const marshalled = await E(marshaller).toCapData(value);
+    const serialized = JSON.stringify(marshalled);
+    return E(storageNode).setValue(serialized);
+  };
+};

package/src/magic-cookie-test-only.d.ts

@@ -0,0 +1,2 @@
+export function notForProductionUse(): {};
+//# sourceMappingURL=magic-cookie-test-only.d.ts.map

package/src/magic-cookie-test-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-cookie-test-only.d.ts","sourceRoot":"","sources":["magic-cookie-test-only.js"],"names":[],"mappings":"AAQO,0CAEN"}

package/src/magic-cookie-test-only.js

@@ -0,0 +1,11 @@
+// @jessie-check
+
+const cookie = harden({});
+
+/**
+ * Facilitate static analysis to prevent
+ * demo/test facilities from being bundled in production.
+ */
+export const notForProductionUse = () => {
+  return cookie;
+};

package/src/method-tools.d.ts

@@ -0,0 +1,3 @@
+export function getMethodNames<K extends PropertyKey>(val: Record<K, any>): K[];
+export function bindAllMethods<T extends Record<PropertyKey, any>>(obj: T): T;
+//# sourceMappingURL=method-tools.d.ts.map

package/src/method-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-tools.d.ts","sourceRoot":"","sources":["method-tools.js"],"names":[],"mappings":"AAyCO,gFAoBN;AAgCM,8EAeJ"}