@agoric/cosmos 0.35.0-u13.0 → 0.35.0-u14.0

package/x/vstorage/capdata/capdata_test.go

@@ -0,0 +1,352 @@
+package capdata
+
+import (
+	"encoding/json"
+	"fmt"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func ptr[T any](v T) *T {
+	return &v
+}
+
+func mustJsonMarshal(val any) string {
+	jsonText, err := JsonMarshal(val)
+	if err != nil {
+		panic(err)
+	}
+	return string(jsonText)
+}
+
+func mustJsonUnmarshal(jsonText string, ptr any) {
+	if err := json.Unmarshal([]byte(jsonText), ptr); err != nil {
+		panic(err)
+	}
+}
+
+func prefixBigint(bigint *CapdataBigint) interface{} {
+	return fmt.Sprintf("bigint:%s", bigint.Normalized)
+}
+
+func remotableToString(r *CapdataRemotable) interface{} {
+	iface := ""
+	if r.Iface != nil {
+		iface = *r.Iface
+	}
+	return fmt.Sprintf("remotable:%s{%s}", iface, r.Id)
+}
+
+func Test_JsonMarshal(t *testing.T) {
+	type testCase struct {
+		input       string
+		expected    string
+		errContains *string
+	}
+	testCases := []testCase{
+		{
+			input:    "<>&\u2028\u2029",
+			expected: `"<>&\u2028\u2029"`,
+		},
+	}
+	for _, desc := range testCases {
+		label := fmt.Sprintf("%q", desc.input)
+		result, err := JsonMarshal(desc.input)
+		if desc.errContains == nil {
+			if err != nil {
+				t.Errorf("%s: got unexpected error %v", label, err)
+			} else if string(result) != desc.expected {
+				t.Errorf("%s: wrong result: %#q", label, result)
+			}
+		} else if err == nil {
+			t.Errorf("%s: got no error, want error %q", label, *desc.errContains)
+		} else if !strings.Contains(err.Error(), *desc.errContains) {
+			t.Errorf("%s: got error %v, want error %q", label, err, *desc.errContains)
+		}
+	}
+}
+
+func Test_DecodeSerializedCapdata(t *testing.T) {
+	type testCase struct {
+		format          string
+		label           string
+		body            string
+		slots           []interface{}
+		expected        string
+		errContains     *string
+		transformations CapdataValueTransformations
+	}
+	testCases := []testCase{
+		// JSON
+		// cf. https://github.com/endojs/endo/blob/209b612e0a267239f33cd607e94ccd179d3ba248/packages/marshal/test/test-marshal-capdata.js#L11
+		{body: `[1, 2]`},
+		{body: `{ "foo": 1 }`},
+		{body: `{}`},
+		{body: `{ "a": 1, "b": 2 }`},
+		{body: `{ "a": 1, "b": { "c": 3 } }`},
+		{body: `true`},
+		{body: `1`},
+		{body: `"abc"`},
+		{body: `null`},
+
+		// transformation of non-JSON values
+		{format: "smallcaps", label: "bigint",
+			body:            `"+98765432101234567890"`,
+			expected:        `"bigint:98765432101234567890"`,
+			transformations: CapdataValueTransformations{Bigint: prefixBigint},
+		},
+		{format: "legacy", label: "bigint",
+			body:            `{ "@qclass": "bigint", "digits": "98765432101234567890" }`,
+			expected:        `"bigint:98765432101234567890"`,
+			transformations: CapdataValueTransformations{Bigint: prefixBigint},
+		},
+		{format: "smallcaps", label: "remotables",
+			body:            `["$0.Foo", "$0"]`,
+			slots:           []interface{}{"a"},
+			expected:        `["remotable:Foo{a}","remotable:Foo{a}"]`,
+			transformations: CapdataValueTransformations{Remotable: remotableToString},
+		},
+		{format: "legacy", label: "remotables",
+			body:            `[{"@qclass":"slot","index":0,"iface":"Foo"}, {"@qclass":"slot","index":0}]`,
+			slots:           []interface{}{"a"},
+			expected:        `["remotable:Foo{a}","remotable:Foo{a}"]`,
+			transformations: CapdataValueTransformations{Remotable: remotableToString},
+		},
+		{format: "smallcaps", label: "escaped string",
+			body:     `"!#escaped"`,
+			expected: `"#escaped"`,
+		},
+
+		// unimplemented
+		{format: "smallcaps",
+			body:        `"#undefined"`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "legacy", label: "undefined",
+			body:        `{"@qclass":"undefined"}`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "smallcaps",
+			body:        `"#NaN"`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "legacy", label: "NaN",
+			body:        `{"@qclass":"NaN"}`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "smallcaps",
+			body:        `"#Infinity"`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "legacy", label: "Infinity",
+			body:        `{"@qclass":"Infinity"}`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "smallcaps",
+			body:        `"#-Infinity"`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "legacy", label: "-Infinity",
+			body:        `{"@qclass":"-Infinity"}`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "smallcaps", label: "symbol",
+			body:        `"%foo"`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "legacy", label: "symbol",
+			body:        `{"@qclass":"symbol"}`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "smallcaps", label: "tagged",
+			body:        `{"#tag":"foo","payload":"bar"}`,
+			errContains: ptr("not implemented: #tag"),
+		},
+		{format: "legacy", label: "tagged",
+			body:        `{"@qclass":"tagged","tag":"foo","payload":"bar"}`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "smallcaps", label: "error",
+			body:        `{"#error":"","name":"Error"}`,
+			errContains: ptr("not implemented: #error"),
+		},
+		{format: "legacy", label: "error",
+			body:        `{"@qclass":"error","message":"foo","name":"bar"}`,
+			errContains: ptr("not implemented"),
+		},
+		{format: "smallcaps", label: "promise",
+			body:        `"&0"`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("not implemented"),
+		},
+		{format: "legacy", label: "error",
+			body:        `{"@qclass":"hilbert","original":"foo"}`,
+			errContains: ptr("not implemented"),
+		},
+
+		// missing transformations
+		{format: "smallcaps", label: "untransformed bigint",
+			body:        `"+98765432101234567890"`,
+			errContains: ptr("untransformed bigint"),
+		},
+		{format: "legacy", label: "untransformed bigint",
+			body:        `{ "@qclass": "bigint", "digits": "98765432101234567890" }`,
+			errContains: ptr("untransformed bigint"),
+		},
+		{format: "smallcaps", label: "untransformed remotable",
+			body:        `["$0.Foo", "$0"]`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("untransformed remotable"),
+		},
+		{format: "legacy", label: "untransformed remotable",
+			body:        `[{"@qclass":"slot","index":0,"iface":"Foo"}, {"@qclass":"slot","index":0}]`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("untransformed remotable"),
+		},
+
+		// invalid data
+		{format: "smallcaps", label: "iface mismatch",
+			body:        `["$0.Foo", "$0."]`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("iface mismatch"),
+		},
+		{format: "legacy", label: "iface mismatch",
+			body:        `[{"@qclass":"slot","index":0,"iface":"Foo"}, {"@qclass":"slot","index":0,"iface":""}]`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("iface mismatch"),
+		},
+		{format: "smallcaps", label: "invalid slot index (out of bounds)",
+			body:        `"$0.Foo"`,
+			errContains: ptr("invalid slot index"),
+		},
+		{format: "legacy", label: "invalid slot index (out of bounds)",
+			body:        `{"@qclass":"slot","index":0}`,
+			errContains: ptr("invalid slot index"),
+		},
+		{format: "smallcaps", label: "invalid slot index (bad format)",
+			body:        `"$x.Foo"`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("invalid slot index"),
+		},
+		{format: "legacy", label: "invalid slot index (missing)",
+			body:        `{"@qclass":"slot"}`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("invalid slot index"),
+		},
+		{format: "legacy", label: "invalid slot index (null)",
+			body:        `{"@qclass":"slot","index":null}`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("invalid slot index"),
+		},
+		{format: "legacy", label: "invalid slot index (string)",
+			body:        `{"@qclass":"slot","index":"0"}`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("invalid slot index"),
+		},
+		{format: "legacy", label: "invalid slot index (non-integer)",
+			body:        `{"@qclass":"slot","index":0.1}`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("invalid slot index"),
+		},
+		{format: "legacy", label: "invalid slot index (negative)",
+			body:        `{"@qclass":"slot","index":-1}`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("invalid slot index"),
+		},
+		{format: "legacy", label: "invalid slot iface (number)",
+			body:        `{"@qclass":"slot","index":0,"iface":0}`,
+			slots:       []interface{}{"a"},
+			errContains: ptr("invalid slot iface"),
+		},
+		{format: "smallcaps", label: "unrecognized record type",
+			body:        `{"#foo":0}`,
+			errContains: ptr("unrecognized record type"),
+		},
+		{format: "legacy", label: "invalid @qclass (null)",
+			body:        `{"@qclass":null}`,
+			errContains: ptr("invalid @qclass"),
+		},
+		{format: "legacy", label: "invalid @qclass (number)",
+			body:        `{"@qclass":1}`,
+			errContains: ptr("invalid @qclass"),
+		},
+		{format: "legacy", label: "invalid @qclass (number)",
+			body:        `{"@qclass":1}`,
+			errContains: ptr("invalid @qclass"),
+		},
+		{format: "legacy", label: "unrecognized @qclass",
+			body:        `{"@qclass":"foo"}`,
+			errContains: ptr("unrecognized @qclass"),
+		},
+		{format: "smallcaps", label: "invalid copyRecord key",
+			body:        `{"+0":0}`,
+			errContains: ptr("invalid copyRecord key"),
+		},
+		{format: "smallcaps", label: "invalid bigint (`--`)",
+			body:        `"--"`,
+			errContains: ptr("invalid bigint"),
+		},
+		{format: "smallcaps", label: "invalid bigint (`+0x`)",
+			body:        `"+0x"`,
+			errContains: ptr("invalid bigint"),
+		},
+		{format: "legacy", label: "invalid bigint (no digits)",
+			body:        `{"@qclass":"bigint"}`,
+			errContains: ptr("invalid bigint"),
+		},
+		{format: "legacy", label: "invalid bigint (null digits)",
+			body:        `{"@qclass":"bigint","digits":null}`,
+			errContains: ptr("invalid bigint"),
+		},
+		{format: "legacy", label: "invalid bigint (`7up`)",
+			body:        `{"@qclass":"bigint","digits":"7up"}`,
+			errContains: ptr("invalid bigint"),
+		},
+	}
+
+	for _, desc := range testCases {
+		slots := desc.slots
+		if slots == nil {
+			slots = []interface{}{}
+		}
+		var expected interface{}
+		if desc.expected != "" {
+			mustJsonUnmarshal(desc.expected, &expected)
+		} else {
+			mustJsonUnmarshal(desc.body, &expected)
+		}
+		for _, format := range []string{"smallcaps", "legacy"} {
+			if desc.format != "" && desc.format != format {
+				continue
+			}
+			label := fmt.Sprintf("%s %s", format, desc.label)
+			if desc.label == "" {
+				label = fmt.Sprintf("%s %s", format, desc.body)
+			}
+			capdata := Capdata{desc.body, slots}
+			if format == "smallcaps" {
+				capdata.Body = "#" + capdata.Body
+			}
+			intermediate, err := DecodeSerializedCapdata(mustJsonMarshal(capdata), desc.transformations)
+			// Replace each Remotable with its representation before comparing.
+			var got interface{}
+			mustJsonUnmarshal(mustJsonMarshal(intermediate), &got)
+			if desc.errContains == nil {
+				if err != nil {
+					t.Errorf("%s: got unexpected error %v", label, err)
+				} else if !reflect.DeepEqual(got, expected) {
+					result, err := JsonMarshal(got)
+					if err != nil {
+						panic(fmt.Errorf("%s: %v", label, err))
+					}
+					t.Errorf("%s: wrong result: %s", label, result)
+				}
+			} else if err == nil {
+				t.Errorf("%s: got no error, want error %q", label, *desc.errContains)
+			} else if !strings.Contains(err.Error(), *desc.errContains) {
+				t.Errorf("%s: got error %v, want error %q", label, err, *desc.errContains)
+			}
+		}
+	}
+}

package/x/vstorage/client/cli/query.go

@@ -4,6 +4,7 @@ import (
 	"github.com/Agoric/agoric-sdk/golang/cosmos/x/vstorage/types"
 	"github.com/cosmos/cosmos-sdk/client"
 	"github.com/cosmos/cosmos-sdk/client/flags"
+	"github.com/gogo/protobuf/proto"
 	"github.com/spf13/cobra"
 )
 
@@ -18,6 +19,7 @@ func GetQueryCmd(storeKey string) *cobra.Command {
 	swingsetQueryCmd.AddCommand(
 		GetCmdGetData(storeKey),
 		GetCmdGetChildren(storeKey),
+		GetCmdGetPath(storeKey),
 	)
 
 	return swingsetQueryCmd
@@ -26,8 +28,8 @@ func GetQueryCmd(storeKey string) *cobra.Command {
 // GetCmdGetData queries information about storage
 func GetCmdGetData(queryRoute string) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "data [path]",
-		Short: "get vstorage data for path",
+		Use:   "data <path>",
+		Short: "get data for vstorage path",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			clientCtx, err := client.GetClientQueryContext(cmd)
@@ -58,8 +60,12 @@ func GetCmdGetChildren(queryRoute string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "children [path]",
 		Aliases: []string{"keys"},
-		Short:   "get vstorage subkey names for path",
-		Args:    cobra.MaximumNArgs(1),
+		Short:   "get child path segments under vstorage path",
+		Long: `get child path segments under vstorage path.
+When absent, path defaults to the empty root path.
+Path segments are dot-separated, so a child "baz" under path "foo.bar" has path
+"foo.bar.baz".`,
+		Args: cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			clientCtx, err := client.GetClientQueryContext(cmd)
 			if err != nil {
@@ -86,3 +92,44 @@ func GetCmdGetChildren(queryRoute string) *cobra.Command {
 	flags.AddQueryFlagsToCmd(cmd)
 	return cmd
 }
+
+// GetCmdGetPath queries vstorage data or children, depending on the path
+func GetCmdGetPath(queryRoute string) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "path <path>",
+		Short: "get vstorage data, or children if path ends with '.'",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			clientCtx, err := client.GetClientQueryContext(cmd)
+			if err != nil {
+				return err
+			}
+			queryClient := types.NewQueryClient(clientCtx)
+
+			path := args[0]
+
+			var res proto.Message
+
+			// if path ends with '.' then remove it and query children
+			if path[len(path)-1] == '.' {
+				path = path[:len(path)-1]
+				res, err = queryClient.Children(cmd.Context(), &types.QueryChildrenRequest{
+					Path: path,
+				})
+			} else {
+				res, err = queryClient.Data(cmd.Context(), &types.QueryDataRequest{
+					Path: path,
+				})
+			}
+
+			if err != nil {
+				return err
+			}
+
+			return clientCtx.PrintProto(res)
+		},
+	}
+
+	flags.AddQueryFlagsToCmd(cmd)
+	return cmd
+}

package/x/vstorage/keeper/grpc_query.go

@@ -2,10 +2,14 @@ package keeper
 
 import (
 	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
 
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 
+	"github.com/Agoric/agoric-sdk/golang/cosmos/x/vstorage/capdata"
 	"github.com/Agoric/agoric-sdk/golang/cosmos/x/vstorage/types"
 	sdk "github.com/cosmos/cosmos-sdk/types"
 )
@@ -17,6 +21,11 @@ type Querier struct {
 
 var _ types.QueryServer = Querier{}
 
+// ===================================================================
+// /agoric.vstorage.Query/Data
+// ===================================================================
+
+// /agoric.vstorage.Query/Data returns data for a specified path.
 func (k Querier) Data(c context.Context, req *types.QueryDataRequest) (*types.QueryDataResponse, error) {
 	if req == nil {
 		return nil, status.Error(codes.InvalidArgument, "empty request")
@@ -30,6 +39,218 @@ func (k Querier) Data(c context.Context, req *types.QueryDataRequest) (*types.Qu
 	}, nil
 }
 
+// ===================================================================
+// /agoric.vstorage.Query/CapData
+// ===================================================================
+
+const (
+	// Media types.
+	JSONLines = "JSON Lines"
+
+	// CapData transformation formats.
+	FormatCapDataFlat = "flat"
+
+	// CapData remotable value formats.
+	FormatRemotableAsObject = "object"
+	FormatRemotableAsString = "string"
+)
+
+var capDataResponseMediaTypes = map[string]string{
+	JSONLines: JSONLines,
+	// Default to JSON Lines.
+	"": JSONLines,
+}
+var capDataTransformationFormats = map[string]string{
+	FormatCapDataFlat: FormatCapDataFlat,
+	// Default to no transformation.
+	"": "",
+}
+var capDataRemotableValueFormats = map[string]string{
+	FormatRemotableAsObject: FormatRemotableAsObject,
+	FormatRemotableAsString: FormatRemotableAsString,
+	// No default because both formats are lossy.
+}
+
+// flatten converts data into a flat structure in which each deep leaf entry is replaced with
+// a top-level entry having the same value but a key generated by joining the keys on its path
+// with separating dashes.
+// For example,
+// ```
+// { "contacts": [
+//
+//	{ "name": "Alice", "email": "a@example.com" },
+//	{ "name": "Bob", "email": "b@example.com" }
+//
+// ] }
+// ```
+// becomes
+// ```
+//
+//	{
+//	  "contacts-0-name": "Alice",
+//	  "contacts-0-email": "a@example.com",
+//	  "contacts-1-name": "Bob",
+//	  "contacts-1-email": "b@example.com"
+//	}
+//
+// ```
+// cf. https://github.com/Agoric/agoric-sdk/blob/6e5b422b80e47c4dac151404f43faea5ab41e9b0/scripts/get-flattened-publication.sh
+func flatten(input interface{}, output map[string]interface{}, key string, top bool) error {
+	// Act on the raw representation of a Remotable.
+	if remotable, ok := input.(*capdata.CapdataRemotable); ok {
+		var replacement interface{}
+		repr, err := capdata.JsonMarshal(remotable)
+		if err == nil {
+			err = json.Unmarshal(repr, &replacement)
+		}
+		if err != nil {
+			return err
+		}
+		input = replacement
+	}
+
+	childKeyPrefix := key
+	if !top {
+		childKeyPrefix = childKeyPrefix + "-"
+	}
+	if arr, ok := input.([]interface{}); ok {
+		for i, v := range arr {
+			if err := flatten(v, output, childKeyPrefix+fmt.Sprintf("%d", i), false); err != nil {
+				return err
+			}
+		}
+	} else if obj, ok := input.(map[string]interface{}); ok {
+		for k, v := range obj {
+			if err := flatten(v, output, childKeyPrefix+k, false); err != nil {
+				return err
+			}
+		}
+	} else {
+		if _, has := output[key]; has {
+			return fmt.Errorf("key conflict: %q", key)
+		}
+		output[key] = input
+	}
+	return nil
+}
+
+// capdataBigintToDigits represents a bigint as a string consisting of
+// an optional "-" followed by a sequence of digits with no extraneous zeroes
+// (e.g., "0" or "-40").
+func capdataBigintToDigits(bigint *capdata.CapdataBigint) interface{} {
+	return bigint.Normalized
+}
+
+// capdataRemotableToString represents a Remotable as a bracketed string
+// containing its alleged name and id from `slots`
+// (e.g., "[Alleged: IST brand <board007>]").
+func capdataRemotableToString(r *capdata.CapdataRemotable) interface{} {
+	iface := "Remotable"
+	if r.Iface != nil || *r.Iface != "" {
+		iface = *r.Iface
+	}
+	return fmt.Sprintf("[%s <%s>]", iface, r.Id)
+}
+
+// capdataRemotableToObject represents a Remotable as an object containing
+// its id from `slots` and its alleged name minus any "Alleged:" prefix
+// (e.g., `{ "id": "board007", "allegedName": "IST brand" }`).
+func capdataRemotableToObject(r *capdata.CapdataRemotable) interface{} {
+	iface := "Remotable"
+	if r.Iface != nil || *r.Iface != "" {
+		iface = *r.Iface
+		iface, _ = strings.CutPrefix(iface, "Alleged: ")
+	}
+	return map[string]interface{}{"id": r.Id, "allegedName": iface}
+}
+
+// /agoric.vstorage.Query/CapData returns data for a specified path,
+// interpreted as CapData in a StreamCell (auto-promoting isolated CapData
+// into a single-item StreamCell) and transformed as specified.
+func (k Querier) CapData(c context.Context, req *types.QueryCapDataRequest) (*types.QueryCapDataResponse, error) {
+	if req == nil {
+		return nil, status.Error(codes.InvalidArgument, "empty request")
+	}
+	ctx := sdk.UnwrapSDKContext(c)
+
+	valueTransformations := capdata.CapdataValueTransformations{
+		Bigint: capdataBigintToDigits,
+	}
+
+	// A response Value is "<prefix><separator-joined items><suffix>".
+	prefix, separator, suffix := "", "\n", ""
+
+	// Read options.
+	mediaType, ok := capDataResponseMediaTypes[req.MediaType]
+	if !ok {
+		return nil, status.Error(codes.InvalidArgument, "invalid media_type")
+	}
+	transformation, ok := capDataTransformationFormats[req.ItemFormat]
+	if !ok {
+		return nil, status.Error(codes.InvalidArgument, "invalid item_format")
+	}
+	switch remotableFormat, ok := capDataRemotableValueFormats[req.RemotableValueFormat]; {
+	case !ok:
+		return nil, status.Error(codes.InvalidArgument, "invalid remotable_value_format")
+	case remotableFormat == FormatRemotableAsObject:
+		valueTransformations.Remotable = capdataRemotableToObject
+	case remotableFormat == FormatRemotableAsString:
+		valueTransformations.Remotable = capdataRemotableToString
+	}
+
+	// Read data, auto-upgrading a standalone value to a single-value StreamCell.
+	entry := k.GetEntry(ctx, req.Path)
+	if !entry.HasValue() {
+		return nil, status.Error(codes.FailedPrecondition, "no data")
+	}
+	value := entry.StringValue()
+	var cell StreamCell
+	_ = json.Unmarshal([]byte(value), &cell)
+	if cell.BlockHeight == "" {
+		cell = StreamCell{Values: []string{value}}
+	}
+
+	// Format each StreamCell value.
+	responseItems := make([]string, len(cell.Values))
+	for i, capDataJson := range cell.Values {
+		item, err := capdata.DecodeSerializedCapdata(capDataJson, valueTransformations)
+		if err != nil {
+			return nil, status.Error(codes.FailedPrecondition, err.Error())
+		}
+		if transformation == FormatCapDataFlat {
+			flattened := map[string]interface{}{}
+			if err := flatten(item, flattened, "", true); err != nil {
+				return nil, status.Error(codes.Internal, err.Error())
+			}
+			// Replace the item, unless it was a scalar that "flattened" to `{ "": ... }`.
+			if _, singleton := flattened[""]; !singleton {
+				item = flattened
+			}
+		}
+		switch mediaType {
+		case JSONLines:
+			jsonText, err := capdata.JsonMarshal(item)
+			if err != nil {
+				return nil, status.Error(codes.Internal, err.Error())
+			}
+			responseItems[i] = string(jsonText)
+		}
+	}
+
+	return &types.QueryCapDataResponse{
+		BlockHeight: cell.BlockHeight,
+		Value:       prefix + strings.Join(responseItems, separator) + suffix,
+	}, nil
+}
+
+// ===================================================================
+// /agoric.vstorage.Query/Children
+// ===================================================================
+
+// /agoric.vstorage.Query/Children returns the list of path segments
+// that exist immediately underneath a specified path, including
+// those corresponding with "empty non-terminals" having children
+// but no data of their own.
 func (k Querier) Children(c context.Context, req *types.QueryChildrenRequest) (*types.QueryChildrenResponse, error) {
 	if req == nil {
 		return nil, status.Error(codes.InvalidArgument, "empty request")