@agoric/cosmos 0.34.2-dev-29ef60f.0 → 0.34.2-dev-f84ea2e.0

package/app/app.go

@@ -598,7 +598,7 @@ func NewAgoricApp(
 		transferModule,
 		icaModule,
 		vstorage.NewAppModule(app.VstorageKeeper),
-		swingset.NewAppModule(app.SwingSetKeeper, setBootstrapNeeded),
+		swingset.NewAppModule(app.SwingSetKeeper, setBootstrapNeeded, app.ensureControllerInited),
 		vibcModule,
 		vbankModule,
 		lienModule,
@@ -631,6 +631,8 @@ func NewAgoricApp(
 		paramstypes.ModuleName,
 		vestingtypes.ModuleName,
 		vstorage.ModuleName,
+		// This will cause the swingset controller to init if it hadn't yet, passing
+		// any upgrade plan or bootstrap flag when starting at an upgrade height
 		swingset.ModuleName,
 		vibc.ModuleName,
 		vbank.ModuleName,
@@ -792,6 +794,7 @@ func NewAgoricApp(
 // upgrade11Handler performs standard upgrade actions plus custom actions for upgrade-11.
 func upgrade11Handler(app *GaiaApp, targetUpgrade string) func(sdk.Context, upgradetypes.Plan, module.VersionMap) (module.VersionMap, error) {
 	return func(ctx sdk.Context, plan upgradetypes.Plan, fromVm module.VersionMap) (module.VersionMap, error) {
+		app.CheckControllerInited(false)
 		// Record the plan to send to SwingSet
 		app.upgradePlan = &plan
 
@@ -825,6 +828,7 @@ func normalizeModuleAccount(ctx sdk.Context, ak authkeeper.AccountKeeper, name s
 type cosmosInitAction struct {
 	Type        string             `json:"type"`
 	ChainID     string             `json:"chainID"`
+	BlockTime   int64              `json:"blockTime,omitempty"`
 	IsBootstrap bool               `json:"isBootstrap"`
 	Params      swingset.Params    `json:"params"`
 	SupplyCoins sdk.Coins          `json:"supplyCoins"`
@@ -849,13 +853,22 @@ func (app *GaiaApp) CheckControllerInited(expected bool) {
 
 // initController sends the initialization message to the VM.
 // Exits if the controller has already been initialized.
+// The init message will contain any upgrade plan if we're starting after an
+// upgrade, and a flag indicating whether this is a bootstrap of the controller.
 func (app *GaiaApp) initController(ctx sdk.Context, bootstrap bool) {
 	app.CheckControllerInited(false)
 	app.controllerInited = true
+
+	var blockTime int64 = 0
+	if bootstrap || app.upgradePlan != nil {
+		blockTime = ctx.BlockTime().Unix()
+	}
+
 	// Begin initializing the controller here.
 	action := &cosmosInitAction{
 		Type:        "AG_COSMOS_INIT",
 		ChainID:     ctx.ChainID(),
+		BlockTime:   blockTime,
 		IsBootstrap: bootstrap,
 		Params:      app.SwingSetKeeper.GetParams(ctx),
 		SupplyCoins: sdk.NewCoins(app.BankKeeper.GetSupply(ctx, "uist")),
@@ -883,33 +896,24 @@ func (app *GaiaApp) initController(ctx sdk.Context, bootstrap bool) {
 	}
 }
 
-type bootstrapBlockAction struct {
-	Type      string `json:"type"`
-	BlockTime int64  `json:"blockTime"`
-}
-
-// BootstrapController initializes the controller (with the bootstrap flag) and sends a bootstrap action.
-func (app *GaiaApp) BootstrapController(ctx sdk.Context) error {
-	app.initController(ctx, true)
-
-	stdlog.Println("Running SwingSet until bootstrap is ready")
-	// Just run the SwingSet kernel to finish bootstrap and get ready to open for
-	// business.
-	action := &bootstrapBlockAction{
-		Type:      "BOOTSTRAP_BLOCK",
-		BlockTime: ctx.BlockTime().Unix(),
+// ensureControllerInited inits the controller if needed. It's used by the
+// x/swingset module's BeginBlock to lazily start the JS controller.
+// We cannot init early as we don't know when starting the software if this
+// might be a simple restart, or a chain init from genesis or upgrade which
+// require the controller to not be inited yet.
+func (app *GaiaApp) ensureControllerInited(ctx sdk.Context) {
+	if app.controllerInited {
+		return
 	}
 
-	_, err := app.SwingSetKeeper.BlockingSend(ctx, action)
-	return err
+	// While we don't expect it anymore, some upgrade may want to throw away
+	// the current JS state and bootstrap again (bulldozer). In that case the
+	// upgrade handler can just set the bootstrapNeeded flag.
+	app.initController(ctx, app.bootstrapNeeded)
 }
 
 // BeginBlocker application updates every begin block
 func (app *GaiaApp) BeginBlocker(ctx sdk.Context, req abci.RequestBeginBlock) abci.ResponseBeginBlock {
-	if !app.controllerInited {
-		app.initController(ctx, false)
-	}
-
 	return app.mm.BeginBlock(ctx, req)
 }
 
@@ -933,14 +937,9 @@ func (app *GaiaApp) InitChainer(ctx sdk.Context, req abci.RequestInitChain) abci
 	normalizeModuleAccount(ctx, app.AccountKeeper, vbanktypes.ProvisionPoolName)
 	normalizeModuleAccount(ctx, app.AccountKeeper, vbanktypes.ReservePoolName)
 
+	// Init early (before first BeginBlock) to run the potentially lengthy bootstrap
 	if app.bootstrapNeeded {
-		err := app.BootstrapController(ctx)
-		// fmt.Fprintf(os.Stderr, "BOOTSTRAP_BLOCK Returned from swingset: %s, %v\n", out, err)
-		if err != nil {
-			// NOTE: A failed BOOTSTRAP_BLOCK means that the SwingSet state is inconsistent.
-			// Panic here, in the hopes that a replay from scratch will fix the problem.
-			panic(err)
-		}
+		app.initController(ctx, true)
 	}
 
 	// Agoric: report the genesis time explicitly.

package/git-revision.txt

@@ -1 +1 @@
-29ef60f
+f84ea2e

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/cosmos",
-  "version": "0.34.2-dev-29ef60f.0+29ef60f",
+  "version": "0.34.2-dev-f84ea2e.0+f84ea2e",
   "description": "Connect JS to the Cosmos blockchain SDK",
   "parsers": {
     "js": "mjs"
@@ -35,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "29ef60f589cf63d033b5d0e3e2cc060c087781ad"
+  "gitHead": "f84ea2e166856351f9d080a3edc0721aea63d1f9"
 }

package/proto/agoric/vstorage/query.proto

@@ -9,11 +9,18 @@ option go_package = "github.com/Agoric/agoric-sdk/golang/cosmos/x/vstorage/types
 
 // Query defines the gRPC querier service
 service Query {
-  // Return an arbitrary vstorage datum.
+  // Return the raw string value of 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) {
@@ -37,6 +44,51 @@ 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.
+  // * "string" represents each Remotable as a bracketed string such as `[Alleged: IST brand {}]`.
+  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/module.go

@@ -80,16 +80,18 @@ func (AppModuleBasic) GetTxCmd() *cobra.Command {
 
 type AppModule struct {
 	AppModuleBasic
-	keeper             Keeper
-	setBootstrapNeeded func()
+	keeper                 Keeper
+	setBootstrapNeeded     func()
+	ensureControllerInited func(sdk.Context)
 }
 
 // NewAppModule creates a new AppModule Object
-func NewAppModule(k Keeper, setBootstrapNeeded func()) AppModule {
+func NewAppModule(k Keeper, setBootstrapNeeded func(), ensureControllerInited func(sdk.Context)) AppModule {
 	am := AppModule{
-		AppModuleBasic:     AppModuleBasic{},
-		keeper:             k,
-		setBootstrapNeeded: setBootstrapNeeded,
+		AppModuleBasic:         AppModuleBasic{},
+		keeper:                 k,
+		setBootstrapNeeded:     setBootstrapNeeded,
+		ensureControllerInited: ensureControllerInited,
 	}
 	return am
 }
@@ -127,6 +129,8 @@ func (am AppModule) RegisterServices(cfg module.Configurator) {
 func (AppModule) ConsensusVersion() uint64 { return 2 }
 
 func (am AppModule) BeginBlock(ctx sdk.Context, req abci.RequestBeginBlock) {
+	am.ensureControllerInited(ctx)
+
 	err := BeginBlock(ctx, req, am.keeper)
 	if err != nil {
 		fmt.Println("BeginBlock error:", err)

package/x/swingset/types/msgs.pb.go

@@ -433,7 +433,7 @@ type MsgInstallBundle struct {
 	Submitter github_com_cosmos_cosmos_sdk_types.AccAddress `protobuf:"bytes,2,opt,name=submitter,proto3,casttype=github.com/cosmos/cosmos-sdk/types.AccAddress" json:"submitter" yaml:"submitter"`
 	// Either bundle or compressed_bundle will be set.
 	// Default compression algorithm is gzip.
-	CompressedBundle []byte `protobuf:"bytes,3,opt,name=compressed_bundle,json=compressedBundle,proto3" json:"compressedBundle" yaml:"bcompressedBndle"`
+	CompressedBundle []byte `protobuf:"bytes,3,opt,name=compressed_bundle,json=compressedBundle,proto3" json:"compressedBundle" yaml:"compressedBundle"`
 	// Size in bytes of uncompression of compressed_bundle.
 	UncompressedSize int64 `protobuf:"varint,4,opt,name=uncompressed_size,json=uncompressedSize,proto3" json:"uncompressedSize"`
 }
@@ -553,7 +553,7 @@ func init() {
 func init() { proto.RegisterFile("agoric/swingset/msgs.proto", fileDescriptor_788baa062b181a57) }
 
 var fileDescriptor_788baa062b181a57 = []byte{
-	// 789 bytes of a gzipped FileDescriptorProto
+	// 788 bytes of a gzipped FileDescriptorProto
 	0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xff, 0xc4, 0x56, 0xcf, 0x6f, 0xe3, 0x44,
 	0x14, 0x8e, 0xe3, 0x50, 0x36, 0xaf, 0xd9, 0x6d, 0x63, 0x95, 0xad, 0xd7, 0x0b, 0x99, 0xac, 0xa5,
 	0x15, 0x01, 0xd4, 0x44, 0xb0, 0xb7, 0xed, 0x29, 0x16, 0x42, 0x5a, 0xa4, 0xa0, 0xc5, 0x2b, 0x84,
@@ -590,20 +590,20 @@ var fileDescriptor_788baa062b181a57 = []byte{
 	0x01, 0x8d, 0x2d, 0xcf, 0x33, 0x66, 0xc1, 0xc4, 0xc3, 0xca, 0x0b, 0xd8, 0x1a, 0xf3, 0x7f, 0xf9,
 	0xe9, 0x3c, 0x4d, 0x18, 0xca, 0x91, 0x94, 0xa1, 0x87, 0xc2, 0x9e, 0x88, 0x75, 0x33, 0x27, 0x96,
 	0x57, 0x56, 0xbf, 0x87, 0x95, 0x29, 0xdf, 0x40, 0xdb, 0x26, 0x7e, 0x98, 0xc1, 0x78, 0x72, 0x9c,
-	0x3b, 0x96, 0x79, 0xe7, 0x41, 0xc2, 0xd0, 0x6e, 0x45, 0x1a, 0x85, 0xf7, 0xfd, 0xdc, 0xfb, 0x02,
-	0x25, 0x56, 0xb1, 0x26, 0x56, 0x86, 0xd0, 0x9e, 0x05, 0x0b, 0xf5, 0xa9, 0x7b, 0x89, 0xf9, 0x89,
-	0xc9, 0xc6, 0x5e, 0x56, 0x7d, 0x91, 0x7c, 0xe3, 0x5e, 0x62, 0x73, 0x0d, 0xd1, 0x35, 0x50, 0x57,
-	0xf7, 0xb6, 0xd8, 0xf8, 0x4f, 0xae, 0x65, 0x90, 0x47, 0xd4, 0x51, 0xbe, 0x85, 0x87, 0xcb, 0x9b,
-	0xff, 0xac, 0xbf, 0xf2, 0x1a, 0xe8, 0xaf, 0xd6, 0xd0, 0x3e, 0xb8, 0x55, 0x52, 0xb4, 0x51, 0x4e,
-	0xe0, 0xd1, 0xca, 0x8b, 0x42, 0xdf, 0x94, 0xbc, 0xac, 0xd1, 0x3e, 0xbc, 0x5d, 0x53, 0x76, 0x38,
-	0x82, 0xd6, 0xd2, 0xc3, 0xb4, 0xbb, 0x29, 0x77, 0x51, 0xa1, 0xf5, 0x6e, 0x53, 0x94, 0xb5, 0x5d,
-	0x68, 0xaf, 0x3f, 0xf9, 0x9e, 0xff, 0x73, 0xfa, 0x82, 0x4c, 0x3b, 0xf8, 0x4f, 0xb2, 0xb2, 0xd5,
-	0x97, 0xd0, 0xac, 0x1e, 0x50, 0xef, 0x6d, 0xca, 0x2d, 0x69, 0xed, 0xf9, 0xbf, 0xd2, 0x45, 0x49,
-	0xe3, 0xab, 0xdf, 0xe6, 0x1d, 0xe9, 0x6a, 0xde, 0x91, 0xae, 0xe7, 0x1d, 0xe9, 0xc7, 0x9b, 0x4e,
-	0xed, 0xea, 0xa6, 0x53, 0xfb, 0xfd, 0xa6, 0x53, 0x3b, 0x3a, 0x5c, 0x98, 0xf9, 0xa1, 0xf8, 0x20,
-	0x10, 0x15, 0xf9, 0xcc, 0x3b, 0xc4, 0xb3, 0x02, 0xa7, 0xb8, 0x0c, 0xdf, 0x57, 0xdf, 0x0a, 0xfc,
-	0x32, 0x8c, 0xb7, 0xf8, 0x67, 0xc0, 0x8b, 0xbf, 0x03, 0x00, 0x00, 0xff, 0xff, 0x99, 0x11, 0x18,
-	0xbe, 0x4b, 0x08, 0x00, 0x00,
+	0x3b, 0x96, 0x79, 0xe7, 0x41, 0xc2, 0xd0, 0x6e, 0x45, 0x1a, 0x85, 0xf7, 0x7d, 0x61, 0x60, 0x95,
+	0xd1, 0xcd, 0x35, 0xb1, 0x32, 0x84, 0xf6, 0x2c, 0x58, 0xa8, 0x4f, 0xdd, 0x4b, 0xcc, 0x4f, 0x4c,
+	0x36, 0xf6, 0xb2, 0xea, 0x8b, 0xe4, 0x1b, 0xf7, 0x12, 0x9b, 0x6b, 0x88, 0xae, 0x81, 0xba, 0xba,
+	0xb7, 0xc5, 0xc6, 0x7f, 0x72, 0x2d, 0x83, 0x3c, 0xa2, 0x8e, 0xf2, 0x2d, 0x3c, 0x5c, 0xde, 0xfc,
+	0x67, 0xfd, 0x95, 0xd7, 0x40, 0x7f, 0xb5, 0x86, 0xf6, 0xc1, 0xad, 0x92, 0xa2, 0x8d, 0x72, 0x02,
+	0x8f, 0x56, 0x5e, 0x14, 0xfa, 0xa6, 0xe4, 0x65, 0x8d, 0xf6, 0xe1, 0xed, 0x9a, 0xb2, 0xc3, 0x11,
+	0xb4, 0x96, 0x1e, 0xa6, 0xdd, 0x4d, 0xb9, 0x8b, 0x0a, 0xad, 0x77, 0x9b, 0xa2, 0xac, 0xed, 0x42,
+	0x7b, 0xfd, 0xc9, 0xf7, 0xfc, 0x9f, 0xd3, 0x17, 0x64, 0xda, 0xc1, 0x7f, 0x92, 0x95, 0xad, 0xbe,
+	0x84, 0x66, 0xf5, 0x80, 0x7a, 0x6f, 0x53, 0x6e, 0x49, 0x6b, 0xcf, 0xff, 0x95, 0x2e, 0x4a, 0x1a,
+	0x5f, 0xfd, 0x36, 0xef, 0x48, 0x57, 0xf3, 0x8e, 0x74, 0x3d, 0xef, 0x48, 0x3f, 0xde, 0x74, 0x6a,
+	0x57, 0x37, 0x9d, 0xda, 0xef, 0x37, 0x9d, 0xda, 0xd1, 0xe1, 0xc2, 0xcc, 0x0f, 0xc5, 0x07, 0x81,
+	0xa8, 0xc8, 0x67, 0xde, 0x21, 0x9e, 0x15, 0x38, 0xc5, 0x65, 0xf8, 0xbe, 0xfa, 0x56, 0xe0, 0x97,
+	0x61, 0xbc, 0xc5, 0x3f, 0x03, 0x5e, 0xfc, 0x1d, 0x00, 0x00, 0xff, 0xff, 0x51, 0x66, 0x1b, 0xd5,
+	0x4b, 0x08, 0x00, 0x00,
 }
 
 // Reference imports to suppress errors if they are not otherwise used.

package/x/vstorage/README.md

@@ -0,0 +1,52 @@
+# Virtual Storage
+
+This module manages "[IAVL](https://github.com/cosmos/iavl)" chain storage data with a hierarchical keyspace in which each key is a "[path](./types/path_keys.go)" composed of zero or more dot-separated nonempty segments in a restricted alphabet. It exposes gRPC endpoints to arbitrary external clients for reading data, and internal read/write interfaces for use by SwingSet (which itself manages further subtree-scoped attenuation).
+
+## Internal Go interface
+
+[Keeper](./keeper/keeper.go)
+* generic
+  * GetChildren
+  * GetEntry
+  * HasEntry
+  * HasStorage
+  * SetStorage[AndNotify]
+* StreamCell-oriented (a StreamCell captures a block height and an array of values)
+  * AppendStorageValue[AndNotify]
+* queue-oriented (a queue stores items at paths like "$prefix.$n", documenting
+  the n for the next item to be consumed at "$prefix.head" and the n for the next
+  next item to be pushed at "$prefix.tail" such that the queue is empty when both
+  head and tail store the same n)
+  * GetQueueLength
+  * PushQueueItem
+
+## Internal JSON interface
+
+This is used by the SwingSet "bridge".
+
+[Receive](./vstorage.go) with input `{ "method": "...", "args": [...] }`
+* generic
+  * method "entries", args path
+  * method "get"/"has", args path
+  * method "set"/"setWithoutNotify", args [[path, value?], ...]
+  * method "children", args path
+  * method "values", args path (returns values for children in the same order as method "children")
+  * method "size", args path (returns the count of children)
+* StreamCell-oriented
+  * method "append", args [[path, value?], ...]
+
+## External protobuf interface
+
+gRPC via [Querier](./keeper/keeper.go)
+and CometBFT method "abci_query" with params `{ "path": "/agoric.vstorage.Query/...", "data": "<hexadecimal representation of serialized protobuf>" }` via the same
+* /agoric.vstorage.Query/CapData
+* /agoric.vstorage.Query/Children
+* /agoric.vstorage.Query/Data
+
+## Arbitrary-response HTTP interface
+
+This depends upon appModule `LegacyQuerierHandler` functionality that is [removed from cosmos-sdk as of v0.47](https://github.com/cosmos/cosmos-sdk/blob/fa4d87ef7e6d87aaccc94c337ffd2fe90fcb7a9d/CHANGELOG.md#api-breaking-changes-3)
+
+[legacy querier](./keeper/querier.go)
+* /custom/vstorage/children/$path
+* /custom/vstorage/data/$path

package/x/vstorage/capdata/capdata.go

@@ -0,0 +1,298 @@
+package capdata
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+// JsonMarshal returns JSON text representing its input,
+// without special replacement of "<", ">", "&", U+2028, or U+2029.
+func JsonMarshal(val any) ([]byte, error) {
+	buf := &bytes.Buffer{}
+	encoder := json.NewEncoder(buf)
+	encoder.SetEscapeHTML(false)
+	if err := encoder.Encode(val); err != nil {
+		return nil, err
+	}
+	// Return without a trailing line feed.
+	lineTerminatedJson := buf.Bytes()
+	return bytes.TrimSuffix(lineTerminatedJson, []byte("\n")), nil
+}
+
+// cf. https://github.com/endojs/endo/tree/master/packages/marshal
+
+type Capdata struct {
+	Body  string        `json:"body"`
+	Slots []interface{} `json:"slots"`
+}
+
+var validBigint = regexp.MustCompile(`^-?(?:0|[1-9][0-9]*)$`)
+
+type CapdataBigint struct {
+	Normalized string
+}
+
+type CapdataRemotable struct {
+	Id             interface{}
+	Iface          *string
+	Representation interface{}
+}
+
+func NewCapdataBigint(str string) *CapdataBigint {
+	if !validBigint.MatchString(str) {
+		return nil
+	}
+	bigint := CapdataBigint{str}
+	return &bigint
+}
+
+func (r *CapdataRemotable) MarshalJSON() ([]byte, error) {
+	return JsonMarshal(r.Representation)
+}
+
+type CapdataValueTransformations struct {
+	Bigint    func(*CapdataBigint) interface{}
+	Remotable func(*CapdataRemotable) interface{}
+}
+
+// upsertCapdataRemotable either adds a new CapdataRemotable to `remotables` at the specified
+// slot index or updates the iface of the value that is already there, ensuring lack of iface name
+// inconsistency (iteration order is not guaranteed to correspond with JSON text like it does in
+// JavaScript, so we must accept encountering the "first" reference to a slot late
+// and must therefore also defer transformations).
+func upsertCapdataRemotable(remotables map[uint64]*CapdataRemotable, slotIndex uint64, id interface{}, iface *string) (*CapdataRemotable, error) {
+	r := remotables[slotIndex]
+	if r == nil {
+		r = new(CapdataRemotable)
+		r.Id = id
+		r.Iface = iface
+		remotables[slotIndex] = r
+	} else if iface != nil {
+		if r.Iface != nil && *iface != *r.Iface {
+			return nil, fmt.Errorf("slot iface mismatch: %q", *iface)
+		}
+		r.Iface = iface
+	}
+	return r, nil
+}
+
+// decodeCapdataLegacyValue decodes the non-smallcaps encoding of
+// https://github.com/endojs/endo/blob/master/packages/marshal/src/encodeToCapData.js
+func decodeCapdataLegacyValue(
+	encoded interface{},
+	slots []interface{},
+	remotables map[uint64]*CapdataRemotable,
+	transformations CapdataValueTransformations,
+) (interface{}, error) {
+	if arr, ok := encoded.([]interface{}); ok {
+		for i, v := range arr {
+			decoded, err := decodeCapdataLegacyValue(v, slots, remotables, transformations)
+			if err != nil {
+				return nil, err
+			}
+			arr[i] = decoded
+		}
+		return arr, nil
+	} else if obj, ok := encoded.(map[string]interface{}); ok {
+		if qclassVal, ok := obj["@qclass"]; ok {
+			qclass, ok := qclassVal.(string)
+			if !ok {
+				return nil, fmt.Errorf("invalid @qclass: %q", qclassVal)
+			}
+			switch qclass {
+			case "bigint":
+				var bigint *CapdataBigint
+				digitsVal := obj["digits"]
+				if digitsStr, ok := digitsVal.(string); ok {
+					bigint = NewCapdataBigint(digitsStr)
+				}
+				if bigint == nil {
+					return nil, fmt.Errorf("invalid bigint: %q", digitsVal)
+				}
+				if transformations.Bigint == nil {
+					return nil, fmt.Errorf("untransformed bigint")
+				}
+				return transformations.Bigint(bigint), nil
+			case "slot":
+				var iface *string
+				slotIndexVal, ifaceVal := obj["index"], obj["iface"]
+				slotIndexNum, ok := slotIndexVal.(float64)
+				slotIndex := uint64(slotIndexNum)
+				if !ok || float64(slotIndex) != slotIndexNum || slotIndex >= uint64(len(slots)) {
+					return nil, fmt.Errorf("invalid slot index: %q", slotIndexVal)
+				}
+				if ifaceStr, ok := ifaceVal.(string); ok {
+					iface = &ifaceStr
+				} else if ifaceVal != nil {
+					return nil, fmt.Errorf("invalid slot iface: %q", ifaceVal)
+				}
+				return upsertCapdataRemotable(remotables, slotIndex, slots[slotIndex], iface)
+			case "hilbert":
+				fallthrough
+			case "undefined":
+				fallthrough
+			case "NaN":
+				fallthrough
+			case "Infinity":
+				fallthrough
+			case "symbol":
+				fallthrough
+			case "tagged":
+				fallthrough
+			case "error":
+				fallthrough
+			case "-Infinity":
+				return nil, fmt.Errorf("not implemented: @qclass %q", qclass)
+			default:
+				return nil, fmt.Errorf("unrecognized @qclass: %q", qclass)
+			}
+		}
+		for k, v := range obj {
+			decoded, err := decodeCapdataLegacyValue(v, slots, remotables, transformations)
+			if err != nil {
+				return nil, err
+			}
+			obj[k] = decoded
+		}
+		return obj, nil
+	} else {
+		return encoded, nil
+	}
+}
+
+// decodeCapdataSmallcapsValue decodes the "smallcaps" encoding from
+// https://github.com/endojs/endo/blob/master/packages/marshal/src/encodeToSmallcaps.js
+func decodeCapdataSmallcapsValue(
+	encoded interface{},
+	slots []interface{},
+	remotables map[uint64]*CapdataRemotable,
+	transformations CapdataValueTransformations,
+) (interface{}, error) {
+	if arr, ok := encoded.([]interface{}); ok {
+		for i, v := range arr {
+			decoded, err := decodeCapdataSmallcapsValue(v, slots, remotables, transformations)
+			if err != nil {
+				return nil, err
+			}
+			arr[i] = decoded
+		}
+		return arr, nil
+	} else if encodedObj, ok := encoded.(map[string]interface{}); ok {
+		if _, ok := encodedObj["#tag"]; ok {
+			return nil, fmt.Errorf("not implemented: #tag")
+		}
+		if _, ok := encodedObj["#error"]; ok {
+			return nil, fmt.Errorf("not implemented: #error")
+		}
+		// We need a distinct output map to avoid reprocessing already-decoded keys.
+		decodedObj := make(map[string]interface{}, len(encodedObj))
+		for encodedK, v := range encodedObj {
+			if strings.HasPrefix(encodedK, "#") {
+				return nil, fmt.Errorf("unrecognized record type: %q", encodedK)
+			}
+			decodedK, err := decodeCapdataSmallcapsValue(encodedK, slots, remotables, CapdataValueTransformations{})
+			k, ok := decodedK.(string)
+			if err != nil || !ok {
+				return nil, fmt.Errorf("invalid copyRecord key: %q", encodedK)
+			}
+			decoded, err := decodeCapdataSmallcapsValue(v, slots, remotables, transformations)
+			if err != nil {
+				return nil, err
+			}
+			decodedObj[k] = decoded
+		}
+		return decodedObj, nil
+	} else if str, ok := encoded.(string); ok {
+		if len(str) == 0 {
+			return str, nil
+		}
+		switch str[0] {
+		case '!':
+			return str[1:], nil
+		case '+':
+			// Normalize to no leading "+".
+			str = str[1:]
+			fallthrough
+		case '-':
+			bigint := NewCapdataBigint(str)
+			if bigint == nil {
+				return nil, fmt.Errorf("invalid bigint: %q", encoded.(string))
+			}
+			if transformations.Bigint == nil {
+				return nil, fmt.Errorf("untransformed bigint")
+			}
+			return transformations.Bigint(bigint), nil
+		case '$':
+			var slotIndexStr string
+			var iface *string
+			if dotIndex := strings.IndexByte(str, '.'); dotIndex >= 0 {
+				slotIndexStr = str[1:dotIndex]
+				ifaceStr := str[dotIndex+1:]
+				iface = &ifaceStr
+			} else {
+				slotIndexStr = str[1:]
+			}
+			slotIndex, err := strconv.ParseUint(slotIndexStr, 10, 0)
+			if err != nil || slotIndex >= uint64(len(slots)) {
+				return nil, fmt.Errorf("invalid slot index: %q", str)
+			}
+			r, err := upsertCapdataRemotable(remotables, slotIndex, slots[slotIndex], iface)
+			if err != nil {
+				return nil, fmt.Errorf("slot iface mismatch: %q", str)
+			}
+			return r, nil
+		case '#':
+			fallthrough
+		case '%':
+			fallthrough
+		case '&':
+			return nil, fmt.Errorf("not implemented: %q", str)
+		default:
+			if str[0] >= '!' && str[0] <= '-' {
+				return nil, fmt.Errorf("invalid smallcaps encoding prefix: %q", str[:1])
+			}
+		}
+		return str, nil
+	} else {
+		return encoded, nil
+	}
+}
+
+// DecodeSerializedCapdata accepts JSON text representing encoded CapData and
+// decodes it, applying specified transformations for values that otherwise
+// hinder interchange.
+func DecodeSerializedCapdata(
+	serializedCapdata string,
+	transformations CapdataValueTransformations,
+) (interface{}, error) {
+	var capdata Capdata
+	if err := json.Unmarshal([]byte(serializedCapdata), &capdata); err != nil {
+		return nil, err
+	}
+	if capdata.Body == "" || capdata.Slots == nil {
+		return nil, fmt.Errorf("invalid CapData")
+	}
+	serializedBody, decodeValue := capdata.Body, decodeCapdataLegacyValue
+	if strings.HasPrefix(serializedBody, "#") {
+		serializedBody, decodeValue = serializedBody[1:], decodeCapdataSmallcapsValue
+	}
+	var encoded interface{}
+	if err := json.Unmarshal([]byte(serializedBody), &encoded); err != nil {
+		return nil, err
+	}
+	remotables := map[uint64]*CapdataRemotable{}
+	decoded, err := decodeValue(encoded, capdata.Slots, remotables, transformations)
+	if err == nil && len(remotables) > 0 {
+		if transformations.Remotable == nil {
+			return nil, fmt.Errorf("untransformed remotable")
+		}
+		for _, r := range remotables {
+			r.Representation = transformations.Remotable(r)
+		}
+	}
+	return decoded, err
+}