@agoric/cosmos 0.34.2-dev-c4a07a4.0 → 0.34.2-dev-91f5e93.0

package/git-revision.txt

@@ -1 +1 @@
-c4a07a4
+91f5e93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/cosmos",
-  "version": "0.34.2-dev-c4a07a4.0+c4a07a4",
+  "version": "0.34.2-dev-91f5e93.0+91f5e93",
   "description": "Connect JS to the Cosmos blockchain SDK",
   "parsers": {
     "js": "mjs"
@@ -35,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "c4a07a45a406c04cee1c555703bbff02d79bb2a2"
+  "gitHead": "91f5e93d5818c9c52a6035aeaec47a803a6d7363"
 }

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/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
+}