@agoric/cosmos 0.34.2-dev-eb7e9eb.0 → 0.35.0-u11.0

package/CHANGELOG.md

@@ -3,6 +3,51 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.35.0-u11.0](https://github.com/Agoric/agoric-sdk/compare/@agoric/cosmos@0.34.1...@agoric/cosmos@0.35.0-u11.0) (2023-08-24)
+
+
+### ⚠ BREAKING CHANGES
+
+* **cosmos:** add required export-dir export cmd option
+* remove deprecated `ag-cosmos-helper`
+
+### Features
+
+* **agd:** try harder to find cosmic-swingset ([a1d1666](https://github.com/Agoric/agoric-sdk/commit/a1d1666997c2f5b9c7bf14748f6d9603c0b3c5f9))
+* **cosmic-swingset:** add repair-metadata snapshot restore option ([ebbb982](https://github.com/Agoric/agoric-sdk/commit/ebbb9829f1f845c0932ae92b23d0d43be9a0e196))
+* **cosmic-swingset:** replace import/export options ([393b91b](https://github.com/Agoric/agoric-sdk/commit/393b91baaa25c61364955102e8cfcdcaec90870d))
+* **cosmic-swingset:** use x/swingset for swing-store export data ([3336b62](https://github.com/Agoric/agoric-sdk/commit/3336b62fbb10bd2293a832f8c30e590530d14213))
+* **cosmos:** add required export-dir export cmd option ([8d2571c](https://github.com/Agoric/agoric-sdk/commit/8d2571c51c2fe08d630dd2897d7e5e1b45ab45c9))
+* **cosmos:** fix and migrate swing-store ([6ba1957](https://github.com/Agoric/agoric-sdk/commit/6ba19571688518dcfdc4553a0c822695a61908b1))
+* **cosmos:** KVEntry implements json Marshaler and Unmarshaller ([6d2fe11](https://github.com/Agoric/agoric-sdk/commit/6d2fe11d144c5bbdc1611b59c84b6842e8084cb9))
+* **cosmos:** spawn JS on export command ([fe4eb56](https://github.com/Agoric/agoric-sdk/commit/fe4eb56facf83569aa343f098e97c6229556afa9))
+* **cosmos:** wire new swingset port handler ([3361b25](https://github.com/Agoric/agoric-sdk/commit/3361b25ddaa00116476d3de1107e800499ab5c21))
+* **x/swingset:** add store data to genesis ([df72903](https://github.com/Agoric/agoric-sdk/commit/df729030643a097262ad1393503d380e243107eb))
+* **x/swingset:** add WaitUntilSwingStoreExportDone ([f8acd22](https://github.com/Agoric/agoric-sdk/commit/f8acd22381ff3da4682bcb0cdcf71665095506a4))
+* **x/swingset:** allow taking snapshot latest height ([0c0e742](https://github.com/Agoric/agoric-sdk/commit/0c0e74227d34d49ac7ce76ce8e92715816d5ea6a))
+* **x/swingset:** export swing store in genesis ([e5f9425](https://github.com/Agoric/agoric-sdk/commit/e5f9425e74c7235323cd6b1b88540b73b57a69a6))
+* **x/swingset:** import swing store from genesis state ([2446cf4](https://github.com/Agoric/agoric-sdk/commit/2446cf43bb13aad7de0805cd7e33c966d2e31016))
+* Cosmos upgrade handler calls swingset ([66f7bcc](https://github.com/Agoric/agoric-sdk/commit/66f7bccce7ce30cf5b9e1e5321710567c05723cb))
+
+
+### Bug Fixes
+
+* **cosmos:** don't init controller before upgrade ([e567c21](https://github.com/Agoric/agoric-sdk/commit/e567c21a224d239c467f740bb937f84b18db9dd7))
+* **cosmos:** module order independent init and bootstrap ([3ce4012](https://github.com/Agoric/agoric-sdk/commit/3ce4012ea99b39b2d6bfd422b1d7ea7a7e904568))
+* **cosmos:** prevent Golang error wrapping stack frame divergence ([1d8acf6](https://github.com/Agoric/agoric-sdk/commit/1d8acf6270cadfbcdafb1081360155260d031ac1))
+* **cosmos:** Support building on Linux aarch64 ([475708e](https://github.com/Agoric/agoric-sdk/commit/475708e63bb95d75184072547ca92586a978c5a0))
+* **x/swingset:** enforce snapshot restore before init ([c946d58](https://github.com/Agoric/agoric-sdk/commit/c946d5866ef956c198d7ea14936eb9904aa272ae))
+* **x/swingset:** guard snapshot restore for concurrency ([5320a30](https://github.com/Agoric/agoric-sdk/commit/5320a30a873455764104e13d89131e30a93a238c))
+* **x/swingset:** switch export/import to replay artifact level ([c037ea3](https://github.com/Agoric/agoric-sdk/commit/c037ea3931877fe4d56df5b82cc7c3eb77a84a53))
+* **x/vstorage:** value can be empty in genesis data ([9a51df5](https://github.com/Agoric/agoric-sdk/commit/9a51df515b87638b869564ab08445a0ce0d55707))
+
+
+### Build System
+
+* remove deprecated `ag-cosmos-helper` ([ee43112](https://github.com/Agoric/agoric-sdk/commit/ee431121e3f93406896f8a9e7d949fbf1427c44e))
+
+
+
 ### [0.34.1](https://github.com/Agoric/agoric-sdk/compare/@agoric/cosmos@0.34.0...@agoric/cosmos@0.34.1) (2023-06-09)
 
 **Note:** Version bump only for package @agoric/cosmos

package/app/app.go

@@ -126,6 +126,14 @@ import (
 
 const appName = "agoric"
 
+// FlagSwingStoreExportDir defines the config flag used to specify where a
+// genesis swing-store export is expected. For start from genesis, the default
+// value is config/swing-store in the home directory. For genesis export, the
+// value is always a "swing-store" directory sibling to the exported
+// genesis.json file.
+// TODO: document this flag in config, likely alongside the genesis path
+const FlagSwingStoreExportDir = "swing-store-export-dir"
+
 var (
 	// DefaultNodeHome default home directories for the application daemon
 	DefaultNodeHome string
@@ -588,6 +596,7 @@ func NewAgoricApp(
 	app.EvidenceKeeper = *evidenceKeeper
 
 	skipGenesisInvariants := cast.ToBool(appOpts.Get(crisis.FlagSkipGenesisInvariants))
+	swingStoreExportDir := cast.ToString(appOpts.Get(FlagSwingStoreExportDir))
 
 	// NOTE: Any module instantiated in the module manager that is later modified
 	// must be passed by reference here.
@@ -617,7 +626,7 @@ func NewAgoricApp(
 		transferModule,
 		icaModule,
 		vstorage.NewAppModule(app.VstorageKeeper),
-		swingset.NewAppModule(app.SwingSetKeeper, setBootstrapNeeded, app.ensureControllerInited),
+		swingset.NewAppModule(app.SwingSetKeeper, &app.SwingStoreExportsHandler, setBootstrapNeeded, app.ensureControllerInited, swingStoreExportDir),
 		vibcModule,
 		vbankModule,
 		lienModule,

package/cmd/agd/main.go

@@ -13,7 +13,7 @@ import (
 
 func main() {
 	// We need to delegate to our default app for running the actual chain.
-	daemoncmd.OnStartHook = func(logger log.Logger) {
+	launchVM := func(logger log.Logger) {
 		args := []string{"ag-chain-cosmos", "--home", gaia.DefaultNodeHome}
 		args = append(args, os.Args[1:]...)
 
@@ -22,12 +22,15 @@ func main() {
 			panic(lookErr)
 		}
 
-		logger.Info("Start chain delegating to JS executable", "binary", binary, "args", args)
+		logger.Info("agd delegating to JS executable", "binary", binary, "args", args)
 		execErr := syscall.Exec(binary, args, os.Environ())
 		if execErr != nil {
 			panic(execErr)
 		}
 	}
 
+	daemoncmd.OnStartHook = launchVM
+	daemoncmd.OnExportHook = launchVM
+
 	daemon.RunWithController(nil)
 }

package/daemon/cmd/root.go

@@ -28,6 +28,7 @@ import (
 	genutilcli "github.com/cosmos/cosmos-sdk/x/genutil/client/cli"
 	"github.com/spf13/cast"
 	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
 	tmcli "github.com/tendermint/tendermint/libs/cli"
 	"github.com/tendermint/tendermint/libs/log"
 	dbm "github.com/tendermint/tm-db"
@@ -40,7 +41,8 @@ import (
 type Sender func(needReply bool, str string) (string, error)
 
 var AppName = "agd"
-var OnStartHook func(log.Logger)
+var OnStartHook func(logger log.Logger)
+var OnExportHook func(logger log.Logger)
 
 // NewRootCmd creates a new root command for simd. It is called once in the
 // main function.
@@ -133,6 +135,14 @@ func initRootCmd(sender Sender, rootCmd *cobra.Command, encodingConfig params.En
 	}
 	server.AddCommands(rootCmd, gaia.DefaultNodeHome, ac.newApp, ac.appExport, addModuleInitFlags)
 
+	hasVMController := sender != nil
+	for _, command := range rootCmd.Commands() {
+		if command.Name() == "export" {
+			extendCosmosExportCommand(command, hasVMController)
+			break
+		}
+	}
+
 	// add keybase, auxiliary RPC, query, and tx child commands
 	rootCmd.AddCommand(
 		rpc.StatusCommand(),
@@ -232,7 +242,16 @@ func (ac appCreator) newApp(
 		panic(err)
 	}
 
-	snapshotDir := filepath.Join(cast.ToString(appOpts.Get(flags.FlagHome)), "data", "snapshots")
+	homePath := cast.ToString(appOpts.Get(flags.FlagHome))
+
+	// Set a default value for FlagSwingStoreExportDir based on the homePath
+	// in case we need to InitGenesis with swing-store data
+	viper, ok := appOpts.(*viper.Viper)
+	if ok && cast.ToString(appOpts.Get(gaia.FlagSwingStoreExportDir)) == "" {
+		viper.Set(gaia.FlagSwingStoreExportDir, filepath.Join(homePath, "config", ExportedSwingStoreDirectoryName))
+	}
+
+	snapshotDir := filepath.Join(homePath, "data", "snapshots")
 	snapshotDB, err := sdk.NewLevelDB("metadata", snapshotDir)
 	if err != nil {
 		panic(err)
@@ -245,7 +264,7 @@ func (ac appCreator) newApp(
 	return gaia.NewAgoricApp(
 		ac.sender,
 		logger, db, traceStore, true, skipUpgradeHeights,
-		cast.ToString(appOpts.Get(flags.FlagHome)),
+		homePath,
 		cast.ToUint(appOpts.Get(server.FlagInvCheckPeriod)),
 		ac.encCfg,
 		appOpts,
@@ -263,6 +282,74 @@ func (ac appCreator) newApp(
 	)
 }
 
+const (
+	// FlagExportDir is the command-line flag for the "export" command specifying
+	// where the output of the export should be placed. It contains both the
+	// items names below: the genesis file, and a directory containing the
+	// exported swing-store artifacts
+	FlagExportDir = "export-dir"
+	// ExportedGenesisFileName is the file name used to save the genesis in the export-dir
+	ExportedGenesisFileName = "genesis.json"
+	// ExportedSwingStoreDirectoryName is the directory name used to save the swing-store
+	// export (artifacts only) in the export-dir
+	ExportedSwingStoreDirectoryName = "swing-store"
+)
+
+// extendCosmosExportCommand monkey-patches the "export" command added by
+// cosmos-sdk to add a required "export-dir" command-line flag, and create the
+// genesis export in the specified directory.
+func extendCosmosExportCommand(cmd *cobra.Command, hasVMController bool) {
+	cmd.Flags().String(FlagExportDir, "", "The directory where to create the genesis export")
+	err := cmd.MarkFlagRequired(FlagExportDir)
+	if err != nil {
+		panic(err)
+	}
+
+	originalRunE := cmd.RunE
+
+	extendedRunE := func(cmd *cobra.Command, args []string) error {
+		serverCtx := server.GetServerContextFromCmd(cmd)
+
+		exportDir, _ := cmd.Flags().GetString(FlagExportDir)
+		err := os.MkdirAll(exportDir, os.ModePerm)
+		if err != nil {
+			return err
+		}
+
+		genesisPath := filepath.Join(exportDir, ExportedGenesisFileName)
+		swingStoreExportPath := filepath.Join(exportDir, ExportedSwingStoreDirectoryName)
+
+		err = os.MkdirAll(swingStoreExportPath, os.ModePerm)
+		if err != nil {
+			return err
+		}
+		// We unconditionally set FlagSwingStoreExportDir as for export, it makes
+		// little sense for users to control this location separately, and we don't
+		// want to override any swing-store artifacts that may be associated to the
+		// current genesis.
+		serverCtx.Viper.Set(gaia.FlagSwingStoreExportDir, swingStoreExportPath)
+
+		// This will fail is a genesis.json already exists in the export-dir
+		genesisFile, err := os.OpenFile(genesisPath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, os.ModePerm)
+		if err != nil {
+			return err
+		}
+		defer genesisFile.Close()
+
+		cmd.SetOut(genesisFile)
+
+		return originalRunE(cmd, args)
+	}
+
+	// Only modify the command handler when we have a VM controller to handle
+	// the full export logic. Otherwise, appExport will just exec the VM program
+	// (OnExportHook), which will result in re-entering this flow with the VM
+	// controller set.
+	if hasVMController {
+		cmd.RunE = extendedRunE
+	}
+}
+
 func (ac appCreator) appExport(
 	logger log.Logger,
 	db dbm.DB,
@@ -272,6 +359,9 @@ func (ac appCreator) appExport(
 	jailAllowedAddrs []string,
 	appOpts servertypes.AppOptions,
 ) (servertypes.ExportedApp, error) {
+	if OnExportHook != nil {
+		OnExportHook(logger)
+	}
 
 	homePath, ok := appOpts.Get(flags.FlagHome).(string)
 	if !ok || homePath == "" {

package/git-revision.txt

@@ -1 +1 @@
-eb7e9eb
+92b6cd724

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/cosmos",
-  "version": "0.34.2-dev-eb7e9eb.0+eb7e9eb",
+  "version": "0.35.0-u11.0",
   "description": "Connect JS to the Cosmos blockchain SDK",
   "parsers": {
     "js": "mjs"
@@ -19,7 +19,7 @@
     "postpack": "git clean -f git-revision.txt",
     "build": "exit 0",
     "lint-fix": "yarn lint:eslint --fix",
-    "lint": "exit 0"
+    "lint": "eslint '**/*.{cjs,js}'"
   },
   "dependencies": {
     "bindings": "^1.2.1",
@@ -35,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "eb7e9ebe52e78052e5ded601b6658896d257cab4"
+  "gitHead": "92b6cd72484079b0349d8ccfa4510aeb820e8d67"
 }

package/proto/agoric/vstorage/query.proto

@@ -9,18 +9,11 @@ option go_package = "github.com/Agoric/agoric-sdk/golang/cosmos/x/vstorage/types
 
 // Query defines the gRPC querier service
 service Query {
-  // Return the raw string value of an arbitrary vstorage datum.
+  // Return an arbitrary vstorage datum.
   rpc Data(QueryDataRequest) returns (QueryDataResponse) {
     option (google.api.http).get = "/agoric/vstorage/data/{path}";
   }
 
-  // Return a formatted representation of a vstorage datum that must be
-  // a valid StreamCell with CapData values, or standalone CapData.
-  rpc CapData(QueryCapDataRequest)
-    returns (QueryCapDataResponse) {
-      option (google.api.http).get = "/agoric/vstorage/capdata/{path}";
-  }
-
   // Return the children of a given vstorage path.
   rpc Children(QueryChildrenRequest)
     returns (QueryChildrenResponse) {
@@ -44,51 +37,6 @@ message QueryDataResponse {
   ];
 }
 
-// QueryCapDataRequest contains a path and formatting configuration.
-message QueryCapDataRequest {
-  string path = 1 [
-    (gogoproto.jsontag)    = "path",
-    (gogoproto.moretags)   = "yaml:\"path\""
-  ];
-  // mediaType must be an actual media type in the registry at
-  // https://www.iana.org/assignments/media-types/media-types.xhtml
-  // or a special value that does not conflict with the media type syntax.
-  // The only valid value is "JSON Lines", which is also the default.
-  string media_type = 2 [
-    (gogoproto.jsontag)    = "mediaType",
-    (gogoproto.moretags)   = "yaml:\"mediaType\""
-  ];
-  // itemFormat, if present, must be the special value "flat" to indicate that
-  // the deep structure of each item should be flattened into a single level
-  // with kebab-case keys (e.g., `{ "metrics": { "min": 0, "max": 88 } }` as
-  // `{ "metrics-min": 0, "metrics-max": 88 }`).
-  string item_format = 3 [
-    (gogoproto.jsontag)    = "itemFormat",
-    (gogoproto.moretags)   = "yaml:\"itemFormat\""
-  ];
-  // remotableValueFormat indicates how to transform references to opaque but
-  // distinguishable Remotables into readable embedded representations.
-  // * "object" represents each Remotable as an `{ id, allegedName }` object, e.g. `{ "id": "board007", "allegedName": "IST brand" }`.
-  // * "string" represents each Remotable as a string with bracket-wrapped contents including its alleged name and id, e.g. "[Alleged: IST brand <board007>]".
-  string remotable_value_format = 10 [
-    (gogoproto.jsontag)    = "remotableValueFormat",
-    (gogoproto.moretags)   = "yaml:\"remotableValueFormat\""
-  ];
-}
-
-// QueryCapDataResponse represents the result with the requested formatting,
-// reserving space for future metadata such as media type.
-message QueryCapDataResponse {
-  string block_height = 1 [
-    (gogoproto.jsontag)    = "blockHeight",
-    (gogoproto.moretags)   = "yaml:\"blockHeight\""
-  ];
-  string value = 10 [
-    (gogoproto.jsontag)    = "value",
-    (gogoproto.moretags)   = "yaml:\"value\""
-  ];
-}
-
 // QueryChildrenRequest is the vstorage path children query.
 message QueryChildrenRequest {
   string path = 1 [

package/x/swingset/genesis.go

@@ -4,6 +4,8 @@ import (
 	// "os"
 	"fmt"
 
+	agoric "github.com/Agoric/agoric-sdk/golang/cosmos/types"
+	"github.com/Agoric/agoric-sdk/golang/cosmos/x/swingset/keeper"
 	"github.com/Agoric/agoric-sdk/golang/cosmos/x/swingset/types"
 	sdk "github.com/cosmos/cosmos-sdk/types"
 )
@@ -28,33 +30,58 @@ func DefaultGenesisState() *types.GenesisState {
 
 // InitGenesis initializes the (Cosmos-side) SwingSet state from the GenesisState.
 // Returns whether the app should send a bootstrap action to the controller.
-func InitGenesis(ctx sdk.Context, keeper Keeper, data *types.GenesisState) bool {
-	keeper.SetParams(ctx, data.GetParams())
-	keeper.SetState(ctx, data.GetState())
+func InitGenesis(ctx sdk.Context, k Keeper, swingStoreExportsHandler *SwingStoreExportsHandler, swingStoreExportDir string, data *types.GenesisState) bool {
+	k.SetParams(ctx, data.GetParams())
+	k.SetState(ctx, data.GetState())
 
 	swingStoreExportData := data.GetSwingStoreExportData()
-	if len(swingStoreExportData) > 0 {
-		// See https://github.com/Agoric/agoric-sdk/issues/6527
-		panic("genesis with swing-store state not implemented")
+	if len(swingStoreExportData) == 0 {
+		return true
 	}
 
-	// TODO: bootstrap only if not restoring swing-store from genesis state
-	return true
+	artifactProvider, err := keeper.OpenSwingStoreExportDirectory(swingStoreExportDir)
+	if err != nil {
+		panic(err)
+	}
+
+	swingStore := k.GetSwingStore(ctx)
+
+	for _, entry := range swingStoreExportData {
+		swingStore.Set([]byte(entry.Key), []byte(entry.Value))
+	}
+
+	snapshotHeight := uint64(ctx.BlockHeight())
+
+	getExportDataReader := func() (agoric.KVEntryReader, error) {
+		exportDataIterator := swingStore.Iterator(nil, nil)
+		return agoric.NewKVIteratorReader(exportDataIterator), nil
+	}
+
+	err = swingStoreExportsHandler.RestoreExport(
+		keeper.SwingStoreExportProvider{
+			BlockHeight:         snapshotHeight,
+			GetExportDataReader: getExportDataReader,
+			ReadNextArtifact:    artifactProvider.ReadNextArtifact,
+		},
+		keeper.SwingStoreRestoreOptions{
+			ArtifactMode:   keeper.SwingStoreArtifactModeReplay,
+			ExportDataMode: keeper.SwingStoreExportDataModeAll,
+		},
+	)
+	if err != nil {
+		panic(err)
+	}
+
+	return false
 }
 
-func ExportGenesis(ctx sdk.Context, k Keeper) *types.GenesisState {
+func ExportGenesis(ctx sdk.Context, k Keeper, swingStoreExportsHandler *SwingStoreExportsHandler, swingStoreExportDir string) *types.GenesisState {
 	gs := &types.GenesisState{
 		Params:               k.GetParams(ctx),
 		State:                k.GetState(ctx),
 		SwingStoreExportData: []*types.SwingStoreExportDataEntry{},
 	}
 
-	// Only export the swing-store shadow copy for now
-	// TODO:
-	// - perform state-sync export with check blockHeight (figure out how to
-	//   handle export of historical height),
-	// - include swing-store artifacts in genesis state
-	// See https://github.com/Agoric/agoric-sdk/issues/6527
 	exportDataIterator := k.GetSwingStore(ctx).Iterator(nil, nil)
 	defer exportDataIterator.Close()
 	for ; exportDataIterator.Valid(); exportDataIterator.Next() {
@@ -64,5 +91,51 @@ func ExportGenesis(ctx sdk.Context, k Keeper) *types.GenesisState {
 		}
 		gs.SwingStoreExportData = append(gs.SwingStoreExportData, &entry)
 	}
+
+	snapshotHeight := uint64(ctx.BlockHeight())
+
+	err := swingStoreExportsHandler.InitiateExport(
+		// The export will fail if the export of a historical height was requested
+		snapshotHeight,
+		swingStoreGenesisEventHandler{exportDir: swingStoreExportDir, snapshotHeight: snapshotHeight},
+		// The export will fail if the swing-store does not contain all replay artifacts
+		keeper.SwingStoreExportOptions{
+			ArtifactMode:   keeper.SwingStoreArtifactModeReplay,
+			ExportDataMode: keeper.SwingStoreExportDataModeSkip,
+		},
+	)
+	if err != nil {
+		panic(err)
+	}
+
+	err = keeper.WaitUntilSwingStoreExportDone()
+	if err != nil {
+		panic(err)
+	}
+
 	return gs
 }
+
+type swingStoreGenesisEventHandler struct {
+	exportDir      string
+	snapshotHeight uint64
+}
+
+func (eventHandler swingStoreGenesisEventHandler) OnExportStarted(height uint64, retrieveSwingStoreExport func() error) error {
+	return retrieveSwingStoreExport()
+}
+
+func (eventHandler swingStoreGenesisEventHandler) OnExportRetrieved(provider keeper.SwingStoreExportProvider) error {
+	if eventHandler.snapshotHeight != provider.BlockHeight {
+		return fmt.Errorf("snapshot block height (%d) doesn't match requested height (%d)", provider.BlockHeight, eventHandler.snapshotHeight)
+	}
+
+	artifactsProvider := keeper.SwingStoreExportProvider{
+		GetExportDataReader: func() (agoric.KVEntryReader, error) {
+			return nil, nil
+		},
+		ReadNextArtifact: provider.ReadNextArtifact,
+	}
+
+	return keeper.WriteSwingStoreExportToDirectory(artifactsProvider, eventHandler.exportDir)
+}

package/x/swingset/keeper/swing_store_exports_handler.go

@@ -638,19 +638,42 @@ func (exportsHandler SwingStoreExportsHandler) retrieveExport(onExportRetrieved
 
 	defer os.RemoveAll(exportDir)
 
-	rawManifest, err := os.ReadFile(filepath.Join(exportDir, ExportManifestFilename))
+	provider, err := OpenSwingStoreExportDirectory(exportDir)
 	if err != nil {
 		return err
 	}
 
-	var manifest exportManifest
-	err = json.Unmarshal(rawManifest, &manifest)
+	if blockHeight != 0 && provider.BlockHeight != blockHeight {
+		return fmt.Errorf("export manifest blockHeight (%d) doesn't match (%d)", provider.BlockHeight, blockHeight)
+	}
+
+	err = onExportRetrieved(provider)
 	if err != nil {
 		return err
 	}
 
-	if blockHeight != 0 && manifest.BlockHeight != blockHeight {
-		return fmt.Errorf("export manifest blockHeight (%d) doesn't match (%d)", manifest.BlockHeight, blockHeight)
+	operationDetails.logger.Info("retrieved swing-store export", "exportDir", exportDir)
+
+	return nil
+}
+
+// OpenSwingStoreExportDirectory creates an export provider from a swing-store
+// export saved on disk in the provided directory. It expects the export manifest
+// to be present in that directory. The provider's function will read the
+// export's data and artifacts from disk on demand. Each artifact is using a
+// dedicated file, and the export data is read from a jsonl-like file, if any.
+// The export manifest filename and overall export format is common with the JS
+// swing-store import/export logic.
+func OpenSwingStoreExportDirectory(exportDir string) (SwingStoreExportProvider, error) {
+	rawManifest, err := os.ReadFile(filepath.Join(exportDir, ExportManifestFilename))
+	if err != nil {
+		return SwingStoreExportProvider{}, err
+	}
+
+	var manifest exportManifest
+	err = json.Unmarshal(rawManifest, &manifest)
+	if err != nil {
+		return SwingStoreExportProvider{}, err
 	}
 
 	getExportDataReader := func() (agoric.KVEntryReader, error) {
@@ -689,18 +712,7 @@ func (exportsHandler SwingStoreExportsHandler) retrieveExport(onExportRetrieved
 		return artifact, err
 	}
 
-	err = onExportRetrieved(SwingStoreExportProvider{BlockHeight: manifest.BlockHeight, GetExportDataReader: getExportDataReader, ReadNextArtifact: readNextArtifact})
-	if err != nil {
-		return err
-	}
-
-	// if nextArtifact != len(manifest.Artifacts) {
-	// 	return errors.New("not all export artifacts were retrieved")
-	// }
-
-	operationDetails.logger.Info("retrieved swing-store export", "exportDir", exportDir)
-
-	return nil
+	return SwingStoreExportProvider{BlockHeight: manifest.BlockHeight, GetExportDataReader: getExportDataReader, ReadNextArtifact: readNextArtifact}, nil
 }
 
 // RestoreExport restores the JS swing-store using previously exported data and artifacts.
@@ -739,8 +751,41 @@ func (exportsHandler SwingStoreExportsHandler) RestoreExport(provider SwingStore
 	}
 	defer os.RemoveAll(exportDir)
 
-	manifest := exportManifest{
+	err = WriteSwingStoreExportToDirectory(provider, exportDir)
+	if err != nil {
+		return err
+	}
+
+	action := &swingStoreRestoreExportAction{
+		Type:        swingStoreExportActionType,
 		BlockHeight: blockHeight,
+		Request:     restoreRequest,
+		Args: [1]swingStoreImportOptions{{
+			ExportDir:      exportDir,
+			ArtifactMode:   restoreOptions.ArtifactMode,
+			ExportDataMode: restoreOptions.ExportDataMode,
+		}},
+	}
+
+	_, err = exportsHandler.blockingSend(action, true)
+	if err != nil {
+		return err
+	}
+
+	exportsHandler.logger.Info("restored swing-store export", "exportDir", exportDir, "height", blockHeight)
+
+	return nil
+}
+
+// WriteSwingStoreExportToDirectory consumes a provider and saves a swing-store
+// export to disk in the provided directory. It creates files for each artifact
+// deriving a filename from the artifact name, and stores any "export data" in
+// a jsonl-like file, before saving the export manifest linking these together.
+// The export manifest filename and overall export format is common with the JS
+// swing-store import/export logic.
+func WriteSwingStoreExportToDirectory(provider SwingStoreExportProvider, exportDir string) error {
+	manifest := exportManifest{
+		BlockHeight: provider.BlockHeight,
 	}
 
 	exportDataReader, err := provider.GetExportDataReader()
@@ -808,28 +853,5 @@ func (exportsHandler SwingStoreExportsHandler) RestoreExport(provider SwingStore
 	if err != nil {
 		return err
 	}
-	err = writeExportFile(ExportManifestFilename, manifestBytes)
-	if err != nil {
-		return err
-	}
-
-	action := &swingStoreRestoreExportAction{
-		Type:        swingStoreExportActionType,
-		BlockHeight: blockHeight,
-		Request:     restoreRequest,
-		Args: [1]swingStoreImportOptions{{
-			ExportDir:      exportDir,
-			ArtifactMode:   restoreOptions.ArtifactMode,
-			ExportDataMode: restoreOptions.ExportDataMode,
-		}},
-	}
-
-	_, err = exportsHandler.blockingSend(action, true)
-	if err != nil {
-		return err
-	}
-
-	exportsHandler.logger.Info("restored swing-store export", "exportDir", exportDir, "height", blockHeight)
-
-	return nil
+	return writeExportFile(ExportManifestFilename, manifestBytes)
 }