@agoric/cosmic-swingset 0.40.0 → 0.40.1-dev-800c2bb.0

package/src/chain-main.js

@@ -1,30 +1,46 @@
-import path from 'path';
+// @ts-check
+
+import { resolve as pathResolve } from 'path';
 import v8 from 'node:v8';
 import process from 'node:process';
 import fs from 'node:fs';
+import fsPromises from 'node:fs/promises';
 import { performance } from 'perf_hooks';
 import { resolve as importMetaResolve } from 'import-meta-resolve';
+import tmpfs from 'tmp';
+import { fork } from 'node:child_process';
+
+import { E } from '@endo/far';
 import engineGC from '@agoric/swingset-vat/src/lib-nodejs/engine-gc.js';
 import { waitUntilQuiescent } from '@agoric/swingset-vat/src/lib-nodejs/waitUntilQuiescent.js';
 import {
   importMailbox,
   exportMailbox,
 } from '@agoric/swingset-vat/src/devices/mailbox/mailbox.js';
-import { makeBufferedStorage } from '@agoric/swingset-vat/src/lib/storageAPI.js';
 
-import { assert, details as X } from '@agoric/assert';
-import { makeSlogSender } from '@agoric/telemetry';
+import { Fail, q } from '@agoric/assert';
+import { makeSlogSender, tryFlushSlogSender } from '@agoric/telemetry';
 
-import { makeChainStorageRoot } from '@agoric/vats/src/lib-chainStorage.js';
+import {
+  makeChainStorageRoot,
+  makeSerializeToStorage,
+} from '@agoric/internal/src/lib-chainStorage.js';
 import { makeMarshal } from '@endo/marshal';
-import { makeStoredSubscriber, makePublishKit } from '@agoric/notifier';
+import { makeShutdown } from '@agoric/internal/src/node/shutdown.js';
 
-import * as STORAGE_PATH from '@agoric/vats/src/chain-storage-paths.js';
+import * as STORAGE_PATH from '@agoric/internal/src/chain-storage-paths.js';
+import * as ActionType from '@agoric/internal/src/action-types.js';
 import { BridgeId as BRIDGE_ID } from '@agoric/internal';
-import stringify from './json-stable-stringify.js';
+import {
+  makeBufferedStorage,
+  makeReadCachingStorage,
+} from './helpers/bufferedStorage.js';
+import stringify from './helpers/json-stable-stringify.js';
 import { launch } from './launch-chain.js';
 import { getTelemetryProviders } from './kernel-stats.js';
-import { makeQueue } from './make-queue.js';
+import { makeProcessValue } from './helpers/process-value.js';
+import { spawnSwingStoreExport } from './export-kernel-db.js';
+import { performStateSyncImport } from './import-kernel-db.js';
 
 // eslint-disable-next-line no-unused-vars
 let whenHellFreezesOver = null;
@@ -36,83 +52,70 @@ const TELEMETRY_SERVICE_NAME = 'agd-cosmos';
 const toNumber = specimen => {
   const number = parseInt(specimen, 10);
   String(number) === String(specimen) ||
-    assert.fail(X`Could not parse ${JSON.stringify(specimen)} as a number`);
+    Fail`Could not parse ${JSON.stringify(specimen)} as a number`;
   return number;
 };
 
-const makeChainStorage = (call, prefix = '', options = {}) => {
-  prefix === '' ||
-    prefix.endsWith('.') ||
-    assert.fail(X`prefix ${prefix} must end with a dot`);
-
-  const { fromChainShape, toChainShape } = options;
-
-  // In addition to the wrapping write buffer, keep a simple cache of
-  // read values for has and get.
-  let cache;
-  function resetCache() {
-    cache = new Map();
-  }
-  resetCache();
-  const storage = {
-    has(key) {
-      return storage.get(key) !== undefined;
+/**
+ * @template {unknown} [T=unknown]
+ * @param {(req: string) => string} call
+ * @param {string} prefix
+ * @param {"set" | "legacySet" | "setWithoutNotify"} setterMethod
+ * @param {(value: string) => T} fromBridgeStringValue
+ * @param {(value: T) => string} toBridgeStringValue
+ * @returns {import("./helpers/bufferedStorage.js").KVStore<T>}
+ */
+const makePrefixedBridgeStorage = (
+  call,
+  prefix,
+  setterMethod,
+  fromBridgeStringValue = x => JSON.parse(x),
+  toBridgeStringValue = x => stringify(x),
+) => {
+  prefix.endsWith('.') || Fail`prefix ${prefix} must end with a dot`;
+
+  return harden({
+    has: key => {
+      const retStr = call(
+        stringify({ method: 'has', args: [`${prefix}${key}`] }),
+      );
+      const ret = JSON.parse(retStr);
+      return ret;
     },
-    get(key) {
-      if (cache.has(key)) return cache.get(key);
-
-      // Fetch the value and cache it until the next commit or abort.
-      const retStr = call(stringify({ method: 'get', key: `${prefix}${key}` }));
+    get: key => {
+      const retStr = call(
+        stringify({ method: 'get', args: [`${prefix}${key}`] }),
+      );
       const ret = JSON.parse(retStr);
-      const chainShapeValue = ret ? JSON.parse(ret) : undefined;
-      const value =
-        chainShapeValue === undefined || !fromChainShape
-          ? chainShapeValue
-          : fromChainShape(chainShapeValue);
-      cache.set(key, value);
-      return value;
+      if (ret == null) {
+        return undefined;
+      }
+      return fromBridgeStringValue(ret);
     },
-    set(key, value) {
-      // Set the value and cache it until the next commit or abort (which is
-      // expected immediately, since the buffered wrapper only calls set
-      // *during* a commit).
-      cache.set(key, value);
-      const chainShapeValue =
-        value === undefined || !toChainShape ? value : toChainShape(value);
-      const valueStr = value === undefined ? '' : stringify(chainShapeValue);
+    set: (key, value) => {
+      const path = `${prefix}${key}`;
+      const entry = [path, toBridgeStringValue(value)];
       call(
         stringify({
-          method: 'set',
-          key: `${prefix}${key}`,
-          value: valueStr,
+          method: setterMethod,
+          args: [entry],
         }),
       );
     },
-    delete(key) {
-      // Deletion in chain storage manifests as set-to-undefined.
-      storage.set(key, undefined);
-    },
-    // eslint-disable-next-line require-yield
-    *getKeys(_start, _end) {
-      throw new Error('not implemented');
+    delete: key => {
+      const path = `${prefix}${key}`;
+      const entry = [path];
+      call(
+        stringify({
+          method: setterMethod,
+          args: [entry],
+        }),
+      );
     },
-  };
-  const {
-    kvStore: buffered,
-    commit,
-    abort,
-  } = makeBufferedStorage(storage, {
-    // Enqueue a write of any retrieved value, to handle callers like mailbox.js
-    // that expect local mutations to be automatically written back.
-    onGet(key, value) {
-      buffered.set(key, value);
+    getNextKey(_previousKey) {
+      throw Error('not implemented');
     },
-
-    // Reset the read cache upon commit or abort.
-    onCommit: resetCache,
-    onAbort: resetCache,
   });
-  return { ...buffered, commit, abort };
 };
 
 export default async function main(progname, args, { env, homedir, agcc }) {
@@ -120,32 +123,16 @@ export default async function main(progname, args, { env, homedir, agcc }) {
 
   // TODO: use the 'basedir' pattern
 
-  // Try to determine the cosmos chain home.
-  function getFlagValue(flagName, deflt) {
-    let flagValue = deflt;
-    const envValue =
-      env[`AG_CHAIN_COSMOS_${flagName.toUpperCase().replace(/-/g, '_')}`];
-    if (envValue !== undefined) {
-      flagValue = envValue;
-    }
-    const flag = `--${flagName}`;
-    const flagEquals = `--${flagName}=`;
-    for (let i = 0; i < args.length; i += 1) {
-      const arg = args[i];
-      if (arg === flag) {
-        i += 1;
-        flagValue = args[i];
-      } else if (arg.startsWith(flagEquals)) {
-        flagValue = arg.substr(flagEquals.length);
-      }
-    }
-    return flagValue;
-  }
+  const processValue = makeProcessValue({ env, args });
 
   // We try to find the actual cosmos state directory (default=~/.ag-chain-cosmos), which
   // is better than scribbling into the current directory.
-  const cosmosHome = getFlagValue('home', `${homedir}/.ag-chain-cosmos`);
-  const stateDBDir = `${cosmosHome}/data/ag-cosmos-chain-state`;
+  const cosmosHome = processValue.getFlag(
+    'home',
+    `${homedir}/.ag-chain-cosmos`,
+  );
+  const stateDBDir = `${cosmosHome}/data/agoric`;
+  fs.mkdirSync(stateDBDir, { recursive: true });
 
   // console.log('Have AG_COSMOS', agcc);
 
@@ -154,14 +141,11 @@ export default async function main(progname, args, { env, homedir, agcc }) {
   function registerPortHandler(portHandler) {
     lastPort += 1;
     const port = lastPort;
-    portHandlers[port] = async (...phArgs) => {
-      try {
-        return await portHandler(...phArgs);
-      } catch (e) {
+    portHandlers[port] = async (...phArgs) =>
+      E.resolve(portHandler(...phArgs)).catch(e => {
         console.error('portHandler threw', e);
         throw e;
-      }
-    };
+      });
     return port;
   }
 
@@ -174,7 +158,8 @@ export default async function main(progname, args, { env, homedir, agcc }) {
     }
     const action = JSON.parse(str);
     const p = Promise.resolve(handler(action));
-    p.then(
+    void E.when(
+      p,
       res => {
         // console.error(`Replying in Node to ${str} with`, res);
         replier.resolve(stringify(res !== undefined ? res : null));
@@ -195,6 +180,23 @@ export default async function main(progname, args, { env, homedir, agcc }) {
   whenHellFreezesOver = new Promise(() => {});
   agcc.runAgCosmosDaemon(nodePort, fromGo, [progname, ...args]);
 
+  /**
+   * @type {undefined | {
+   *   blockHeight: number,
+   *   exporter?: import('./export-kernel-db.js').StateSyncExporter,
+   *   exportDir?: string,
+   *   cleanup?: () => Promise<void>,
+   * }}
+   */
+  let stateSyncExport;
+
+  async function discardStateSyncExport() {
+    const exportData = stateSyncExport;
+    stateSyncExport = undefined;
+    await exportData?.exporter?.stop();
+    await exportData?.cleanup?.();
+  }
+
   let savedChainSends = [];
 
   // Send a chain downcall, recording what we sent and received.
@@ -204,7 +206,10 @@ export default async function main(progname, args, { env, homedir, agcc }) {
     return ret;
   }
 
-  const clearChainSends = () => {
+  const clearChainSends = async () => {
+    // Cosmos should have blocked before calling commit, but wait just in case
+    await stateSyncExport?.exporter?.onStarted().catch(() => {});
+
     const chainSends = savedChainSends;
     savedChainSends = [];
     return chainSends;
@@ -232,37 +237,81 @@ export default async function main(progname, args, { env, homedir, agcc }) {
     }
   }
 
+  /** @type {((obj: object) => void) | undefined} */
+  let writeSlogObject;
+
   // this storagePort changes for every single message. We define it out here
   // so the 'externalStorage' object can close over the single mutable
   // instance, and we update the 'portNums.storage' value each time toSwingSet is called
   async function launchAndInitializeSwingSet(bootMsg) {
+    const sendToChain = msg => chainSend(portNums.storage, msg);
     // this object is used to store the mailbox state.
-    const mailboxStorage = makeChainStorage(
-      msg => chainSend(portNums.storage, msg),
-      `${STORAGE_PATH.MAILBOX}.`,
-      {
-        fromChainShape: data => {
-          const ack = toNumber(data.ack);
-          const outbox = data.outbox.map(([seq, msg]) => [toNumber(seq), msg]);
-          return importMailbox({ outbox, ack });
-        },
-        toChainShape: exportMailbox,
-      },
-    );
-    const actionQueue = makeQueue(
-      makeChainStorage(
-        msg => chainSend(portNums.storage, msg),
-        `${STORAGE_PATH.ACTION_QUEUE}.`,
+    const fromBridgeMailbox = data => {
+      const ack = toNumber(data.ack);
+      const outbox = data.outbox.map(([seq, msg]) => [toNumber(seq), msg]);
+      return importMailbox({ outbox, ack });
+    };
+    const mailboxStorage = makeReadCachingStorage(
+      makePrefixedBridgeStorage(
+        sendToChain,
+        `${STORAGE_PATH.MAILBOX}.`,
+        'legacySet',
+        val => fromBridgeMailbox(JSON.parse(val)),
+        val => stringify(exportMailbox(val)),
       ),
     );
-    function setActivityhash(activityhash) {
-      const msg = stringify({
-        method: 'set',
-        key: STORAGE_PATH.ACTIVITYHASH,
-        value: activityhash,
+    const makeQueueStorage = queuePath => {
+      const { kvStore, commit, abort } = makeBufferedStorage(
+        makePrefixedBridgeStorage(
+          sendToChain,
+          `${queuePath}.`,
+          'setWithoutNotify',
+          x => x,
+          x => x,
+        ),
+      );
+      return harden({ ...kvStore, commit, abort });
+    };
+    const actionQueueStorage = makeQueueStorage(STORAGE_PATH.ACTION_QUEUE);
+    const highPriorityQueueStorage = makeQueueStorage(
+      STORAGE_PATH.HIGH_PRIORITY_QUEUE,
+    );
+    /**
+     * Callback invoked during SwingSet execution when new "export data" is
+     * generated by swingStore to be saved in the host's verified DB. In our
+     * case, we publish these entries in vstorage under a dedicated prefix.
+     * This effectively shadows the "export data" of the swingStore so that
+     * processes like state-sync can generate a verified "root of trust" to
+     * restore SwingSet state.
+     *
+     * @param {ReadonlyArray<[path: string, value?: string | null]>} updates
+     */
+    const swingStoreExportCallback = async updates => {
+      // Allow I/O to proceed first
+      await waitUntilQuiescent();
+
+      const entries = updates.map(([key, value]) => {
+        if (typeof key !== 'string') {
+          throw Fail`Unexpected swingStore exported key ${q(key)}`;
+        }
+        const path = `${STORAGE_PATH.SWING_STORE}.${key}`;
+        if (value == null) {
+          return [path];
+        }
+        if (typeof value !== 'string') {
+          throw Fail`Unexpected ${typeof value} value for swingStore exported key ${q(
+            key,
+          )}`;
+        }
+        return [path, value];
       });
-      chainSend(portNums.storage, msg);
-    }
+      sendToChain(
+        stringify({
+          method: 'setWithoutNotify',
+          args: entries,
+        }),
+      );
+    };
     function doOutboundBridge(dstID, msg) {
       const portNum = portNums[dstID];
       if (portNum === undefined) {
@@ -278,7 +327,7 @@ export default async function main(progname, args, { env, homedir, agcc }) {
       try {
         return JSON.parse(respStr);
       } catch (e) {
-        assert.fail(X`cannot JSON.parse(${JSON.stringify(respStr)}): ${e}`);
+        throw Fail`cannot JSON.parse(${JSON.stringify(respStr)}): ${e}`;
       }
     }
 
@@ -289,27 +338,32 @@ export default async function main(progname, args, { env, homedir, agcc }) {
     const makeInstallationPublisher = () => {
       const installationStorageNode = makeChainStorageRoot(
         toStorage,
-        'swingset',
         STORAGE_PATH.BUNDLES,
         { sequence: true },
       );
-      const marshaller = makeMarshal();
-      const { publisher, subscriber } = makePublishKit();
-      makeStoredSubscriber(subscriber, installationStorageNode, marshaller);
+      const marshaller = makeMarshal(undefined, undefined, {
+        serializeBodyFormat: 'smallcaps',
+      });
+      const publish = makeSerializeToStorage(
+        installationStorageNode,
+        marshaller,
+      );
+      const publisher = harden({ publish });
       return publisher;
     };
 
     const argv = {
-      ROLE: 'chain',
       bootMsg,
     };
-    const vatconfig = new URL(
-      await importMetaResolve(
-        env.CHAIN_BOOTSTRAP_VAT_CONFIG ||
-          argv.bootMsg.params.bootstrap_vat_config,
-        import.meta.url,
-      ),
-    ).pathname;
+    const vatHref = await importMetaResolve(
+      env.CHAIN_BOOTSTRAP_VAT_CONFIG ||
+        argv.bootMsg.params.bootstrap_vat_config,
+      import.meta.url,
+    );
+    const vatconfig = new URL(vatHref).pathname;
+
+    // Delay makeShutdown to override the golang interrupts
+    const { registerShutdown } = makeShutdown();
 
     const { metricsProvider } = getTelemetryProviders({
       console,
@@ -317,37 +371,18 @@ export default async function main(progname, args, { env, homedir, agcc }) {
       serviceName: TELEMETRY_SERVICE_NAME,
     });
 
-    const {
-      LMDB_MAP_SIZE,
-      SWING_STORE_TRACE,
-      XSNAP_KEEP_SNAPSHOTS,
-      NODE_HEAP_SNAPSHOTS = -1,
-    } = env;
+    const { XSNAP_KEEP_SNAPSHOTS, NODE_HEAP_SNAPSHOTS = -1 } = env;
     const slogSender = await makeSlogSender({
       stateDir: stateDBDir,
       env,
       serviceName: TELEMETRY_SERVICE_NAME,
     });
 
-    const mapSize = (LMDB_MAP_SIZE && parseInt(LMDB_MAP_SIZE, 10)) || undefined;
-
-    const defaultTraceFile = path.resolve(stateDBDir, 'store-trace.log');
-    let swingStoreTraceFile;
-    switch (SWING_STORE_TRACE) {
-      case '0':
-      case 'false':
-        break;
-      case '1':
-      case 'true':
-        swingStoreTraceFile = defaultTraceFile;
-        break;
-      default:
-        if (SWING_STORE_TRACE) {
-          swingStoreTraceFile = path.resolve(SWING_STORE_TRACE);
-        } else if (getFlagValue('trace-store')) {
-          swingStoreTraceFile = defaultTraceFile;
-        }
-    }
+    const swingStoreTraceFile = processValue.getPath({
+      envName: 'SWING_STORE_TRACE',
+      flagName: 'trace-store',
+      trueValue: pathResolve(stateDBDir, 'store-trace.log'),
+    });
 
     const keepSnapshots =
       XSNAP_KEEP_SNAPSHOTS === '1' || XSNAP_KEEP_SNAPSHOTS === 'true';
@@ -356,67 +391,73 @@ export default async function main(progname, args, { env, homedir, agcc }) {
 
     let lastCommitTime = 0;
     let commitCallsSinceLastSnapshot = NaN;
-    const snapshotBaseDir = path.resolve(stateDBDir, 'node-heap-snapshots');
+    const snapshotBaseDir = pathResolve(stateDBDir, 'node-heap-snapshots');
 
     if (nodeHeapSnapshots >= 0) {
       fs.mkdirSync(snapshotBaseDir, { recursive: true });
     }
 
     const afterCommitCallback = async () => {
+      const slogSenderFlushed = tryFlushSlogSender(slogSender, {
+        env,
+        log: console.warn,
+      });
+
       // delay until all current promise reactions are drained so we can be sure
       // that the commit-block reply has been sent to agcc through replier.resolve
-      await waitUntilQuiescent();
+      await Promise.all([slogSenderFlushed, waitUntilQuiescent()]);
 
-      let heapSnapshot;
-      let heapSnapshotTime;
-
-      const t0 = performance.now();
-      engineGC();
-      const t1 = performance.now();
-      const memoryUsage = process.memoryUsage();
-      const t2 = performance.now();
-      const heapStats = v8.getHeapStatistics();
-      const t3 = performance.now();
-
-      commitCallsSinceLastSnapshot += 1;
-      if (
-        (nodeHeapSnapshots >= 0 && t0 - lastCommitTime > 30 * 1000) ||
-        (nodeHeapSnapshots > 0 &&
-          !(nodeHeapSnapshots > commitCallsSinceLastSnapshot))
-      ) {
-        commitCallsSinceLastSnapshot = 0;
-        heapSnapshot = `Heap-${process.pid}-${Date.now()}.heapsnapshot`;
-        const snapshotPath = path.resolve(snapshotBaseDir, heapSnapshot);
-        v8.writeHeapSnapshot(snapshotPath);
-        heapSnapshotTime = performance.now() - t3;
+      try {
+        let heapSnapshot;
+        let heapSnapshotTime;
+
+        const t0 = performance.now();
+        engineGC();
+        const t1 = performance.now();
+        const memoryUsage = process.memoryUsage();
+        const t2 = performance.now();
+        const heapStats = v8.getHeapStatistics();
+        const t3 = performance.now();
+
+        commitCallsSinceLastSnapshot += 1;
+        if (
+          (nodeHeapSnapshots >= 0 && t0 - lastCommitTime > 30 * 1000) ||
+          (nodeHeapSnapshots > 0 &&
+            !(nodeHeapSnapshots > commitCallsSinceLastSnapshot))
+        ) {
+          commitCallsSinceLastSnapshot = 0;
+          heapSnapshot = `Heap-${process.pid}-${Date.now()}.heapsnapshot`;
+          const snapshotPath = pathResolve(snapshotBaseDir, heapSnapshot);
+          v8.writeHeapSnapshot(snapshotPath);
+          heapSnapshotTime = performance.now() - t3;
+        }
+        lastCommitTime = t0;
+
+        return {
+          memoryUsage,
+          heapStats,
+          heapSnapshot,
+          statsTime: {
+            forcedGc: t1 - t0,
+            memoryUsage: t2 - t1,
+            heapStats: t3 - t2,
+            heapSnapshot: heapSnapshotTime,
+          },
+        };
+      } catch (err) {
+        console.warn('Failed to gather memory stats', err);
+        return {};
       }
-      lastCommitTime = t0;
-
-      await Promise.resolve(slogSender?.forceFlush?.()).catch(err => {
-        console.warn('Failed to flush slog sender', err);
-      });
-
-      return {
-        memoryUsage,
-        heapStats,
-        heapSnapshot,
-        statsTime: {
-          forcedGc: t1 - t0,
-          memoryUsage: t2 - t1,
-          heapStats: t3 - t2,
-          heapSnapshot: heapSnapshotTime,
-        },
-      };
     };
 
     const s = await launch({
-      actionQueue,
+      actionQueueStorage,
+      highPriorityQueueStorage,
       kernelStateDBDir: stateDBDir,
       makeInstallationPublisher,
       mailboxStorage,
       clearChainSends,
       replayChainSends,
-      setActivityhash,
       bridgeOutbound: doOutboundBridge,
       vatconfig,
       argv,
@@ -424,18 +465,151 @@ export default async function main(progname, args, { env, homedir, agcc }) {
       verboseBlocks: true,
       metricsProvider,
       slogSender,
-      mapSize,
+      swingStoreExportCallback,
       swingStoreTraceFile,
       keepSnapshots,
       afterCommitCallback,
     });
 
-    savedChainSends = s.savedChainSends;
+    const { blockingSend, shutdown } = s;
+    ({ writeSlogObject, savedChainSends } = s);
+
+    let pendingBlockingSend = Promise.resolve();
 
-    return s.blockingSend;
+    registerShutdown(async interrupted =>
+      Promise.all([
+        interrupted && pendingBlockingSend.then(shutdown),
+        discardStateSyncExport(),
+      ]).then(() => {}),
+    );
+
+    return async action => {
+      const result = blockingSend(action);
+      pendingBlockingSend = Promise.resolve(result).then(
+        () => {},
+        () => {},
+      );
+      return result;
+    };
   }
 
+  async function handleCosmosSnapshot(blockHeight, request, requestArgs) {
+    switch (request) {
+      case 'restore': {
+        const exportDir = requestArgs[0];
+        if (typeof exportDir !== 'string') {
+          throw Fail`Invalid exportDir argument ${q(exportDir)}`;
+        }
+        console.info(
+          'Restoring SwingSet state from snapshot at block height',
+          blockHeight,
+        );
+        return performStateSyncImport(
+          { exportDir, stateDir: stateDBDir, blockHeight },
+          { fs: { ...fs, ...fsPromises }, pathResolve, log: null },
+        );
+      }
+      case 'initiate': {
+        !stateSyncExport ||
+          Fail`Snapshot already in progress for ${stateSyncExport.blockHeight}`;
+
+        const exportData =
+          /** @type {Required<NonNullable<typeof stateSyncExport>>} */ ({
+            blockHeight,
+          });
+        stateSyncExport = exportData;
+
+        // eslint-disable-next-line @jessie.js/no-nested-await
+        await new Promise((resolve, reject) => {
+          tmpfs.dir(
+            {
+              prefix: `agd-state-sync-${blockHeight}-`,
+              unsafeCleanup: true,
+            },
+            (err, exportDir, cleanup) => {
+              if (err) {
+                reject(err);
+                return;
+              }
+              exportData.exportDir = exportDir;
+              /** @type {Promise<void> | undefined} */
+              let cleanupResult;
+              exportData.cleanup = async () => {
+                cleanupResult ||= new Promise(cleanupDone => {
+                  // If the exporter is still the same, then the retriever
+                  // is in charge of cleanups
+                  if (stateSyncExport !== exportData) {
+                    // @ts-expect-error wrong type definitions
+                    cleanup(cleanupDone);
+                  } else {
+                    console.warn('unexpected call of state-sync cleanup');
+                    cleanupDone();
+                  }
+                });
+                await cleanupResult;
+              };
+              resolve(null);
+            },
+          );
+        });
+
+        console.info(
+          'Initiating SwingSet state snapshot at block height',
+          blockHeight,
+        );
+        exportData.exporter = spawnSwingStoreExport(
+          {
+            stateDir: stateDBDir,
+            exportDir: exportData.exportDir,
+            blockHeight,
+          },
+          {
+            fork,
+          },
+        );
+
+        exportData.exporter.onDone().catch(() => {
+          if (exportData === stateSyncExport) {
+            stateSyncExport = undefined;
+          }
+          return exportData.cleanup();
+        });
+
+        return exportData.exporter.onStarted().catch(err => {
+          console.warn(
+            `State-sync export failed for block ${blockHeight}`,
+            err,
+          );
+          throw err;
+        });
+      }
+      case 'discard': {
+        return discardStateSyncExport();
+      }
+      case 'retrieve': {
+        const exportData = stateSyncExport;
+        if (!exportData || !exportData.exporter) {
+          throw Fail`No snapshot in progress`;
+        }
+
+        return exportData.exporter.onDone().then(() => {
+          if (exportData === stateSyncExport) {
+            // Don't cleanup, cosmos is now in charge
+            stateSyncExport = undefined;
+            return exportData.exportDir;
+          } else {
+            throw Fail`Snapshot was discarded`;
+          }
+        });
+      }
+      default:
+        throw Fail`Unknown cosmos snapshot request ${request}`;
+    }
+  }
+
+  /** @type {Awaited<ReturnType<typeof launch>>['blockingSend'] | undefined} */
   let blockingSend;
+
   async function toSwingSet(action, _replier) {
     // console.log(`toSwingSet`, action);
     if (action.vibcPort) {
@@ -456,16 +630,51 @@ export default async function main(progname, args, { env, homedir, agcc }) {
       portNums.lien = action.lienPort;
     }
 
-    // Ensure that initialization has completed.
-    if (!blockingSend) {
-      blockingSend = await launchAndInitializeSwingSet(action);
+    // Snapshot actions are specific to cosmos chains and handled here
+    if (action.type === ActionType.COSMOS_SNAPSHOT) {
+      const { blockHeight, request, args: requestArgs } = action;
+      writeSlogObject?.({
+        type: 'cosmic-swingset-snapshot-start',
+        blockHeight,
+        request,
+        args: requestArgs,
+      });
+
+      const resultP = handleCosmosSnapshot(blockHeight, request, requestArgs);
+
+      resultP.then(
+        result => {
+          writeSlogObject?.({
+            type: 'cosmic-swingset-snapshot-finish',
+            blockHeight,
+            request,
+            args: requestArgs,
+            result,
+          });
+        },
+        error => {
+          writeSlogObject?.({
+            type: 'cosmic-swingset-snapshot-finish',
+            blockHeight,
+            request,
+            args: requestArgs,
+            error,
+          });
+        },
+      );
+
+      return resultP;
     }
 
+    // Ensure that initialization has completed.
+    blockingSend = await (blockingSend || launchAndInitializeSwingSet(action));
+
     if (action.type === AG_COSMOS_INIT) {
       // console.error('got AG_COSMOS_INIT', action);
       return true;
     }
 
+    // Block related actions are processed by `blockingSend`
     return blockingSend(action);
   }
 }