@agoric/cosmos 0.35.0-upgrade-14-dev-0169c7e.0 → 0.35.0-upgrade-16-dev-07b0130.0

package/x/vlocalchain/vlocalchain.go

@@ -0,0 +1,114 @@
+package vlocalchain
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	sdk "github.com/cosmos/cosmos-sdk/types"
+
+	"github.com/Agoric/agoric-sdk/golang/cosmos/vm"
+	"github.com/Agoric/agoric-sdk/golang/cosmos/x/vlocalchain/keeper"
+	"github.com/Agoric/agoric-sdk/golang/cosmos/x/vlocalchain/types"
+)
+
+var _ vm.PortHandler = (*portHandler)(nil)
+
+type portHandler struct {
+	keeper keeper.Keeper
+}
+
+type portMessage struct {
+	Type     string          `json:"type"`
+	Address  string          `json:"address,omitempty"`
+	Messages json.RawMessage `json:"messages,omitempty"`
+}
+
+func NewReceiver(keeper keeper.Keeper) portHandler {
+	return portHandler{keeper: keeper}
+}
+
+func (h portHandler) Receive(cctx context.Context, str string) (ret string, err error) {
+	var msg portMessage
+	err = json.Unmarshal([]byte(str), &msg)
+	if err != nil {
+		return
+	}
+
+	switch msg.Type {
+	case "VLOCALCHAIN_ALLOCATE_ADDRESS":
+		addr := h.keeper.AllocateAddress(cctx)
+		var bz []byte
+		if bz, err = json.Marshal(addr.String()); err != nil {
+			return
+		}
+		ret = string(bz)
+
+	case "VLOCALCHAIN_QUERY_MANY":
+		// Copy the JSON messages string into a CosmosTx object so we can
+		// deserialize it with just proto3 JSON.
+		cosmosTxBz := []byte(`{"messages":` + string(msg.Messages) + `}`)
+
+		var qms []types.QueryRequest
+		qms, err = h.keeper.DeserializeRequests(cosmosTxBz)
+		if err != nil {
+			return
+		}
+
+		var errs []error
+		resps := make([]interface{}, len(qms))
+		for i, qm := range qms {
+			var qr *types.QueryResponse
+			qr, err = h.keeper.Query(cctx, qm)
+			if err == nil {
+				// Only fill out the response if the query was successful.
+				resps[i] = qr
+			} else {
+				errs = append(errs, err) // Accumulate errors
+				resps[i] = &types.QueryResponse{Error: err.Error()}
+			}
+		}
+
+		bz, err := vm.ProtoJSONMarshalSlice(resps)
+		if err != nil {
+			return "", err
+		}
+
+		switch len(errs) {
+		case 0:
+			err = nil
+		case 1:
+			err = errs[0]
+		case len(resps):
+			err = fmt.Errorf("all queries in batch failed: %v", errs)
+		default:
+			// Let them inspect the individual errors manually.
+		}
+		return string(bz), err
+
+	case "VLOCALCHAIN_EXECUTE_TX":
+		origCtx := sdk.UnwrapSDKContext(cctx)
+
+		// Copy the JSON messages string into a CosmosTx object so we can
+		// deserialize it with just proto3 JSON.
+		cosmosTxBz := []byte(`{"messages":` + string(msg.Messages) + `}`)
+
+		var msgs []sdk.Msg
+		if msgs, err = h.keeper.DeserializeTxMessages(cosmosTxBz); err != nil {
+			return
+		}
+
+		var resps []interface{}
+		resps, err = h.keeper.ExecuteTx(origCtx, msg.Address, msgs)
+		if err != nil {
+			return
+		}
+
+		// Marshal the responses to proto3 JSON.
+		bz, e := vm.ProtoJSONMarshalSlice(resps)
+		return string(bz), e
+	default:
+		err = fmt.Errorf("unrecognized message type %s", msg.Type)
+	}
+	return
+}

package/x/vlocalchain/vlocalchain_test.go

@@ -0,0 +1,434 @@
+package vlocalchain_test
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/Agoric/agoric-sdk/golang/cosmos/app/params"
+	"github.com/Agoric/agoric-sdk/golang/cosmos/vm"
+	"github.com/Agoric/agoric-sdk/golang/cosmos/x/vlocalchain"
+	"github.com/Agoric/agoric-sdk/golang/cosmos/x/vlocalchain/types"
+
+	"github.com/cosmos/cosmos-sdk/baseapp"
+	"github.com/cosmos/cosmos-sdk/store"
+	storetypes "github.com/cosmos/cosmos-sdk/store/types"
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	banktypes "github.com/cosmos/cosmos-sdk/x/bank/types"
+	stakingtypes "github.com/cosmos/cosmos-sdk/x/staking/types"
+	transfertypes "github.com/cosmos/ibc-go/v6/modules/apps/transfer/types"
+	"github.com/tendermint/tendermint/libs/log"
+
+	"github.com/gogo/protobuf/jsonpb"
+	"github.com/gogo/protobuf/proto"
+	tmproto "github.com/tendermint/tendermint/proto/tendermint/types"
+	dbm "github.com/tendermint/tm-db"
+)
+
+var (
+	vlocalchainStoreKey = sdk.NewKVStoreKey(types.StoreKey)
+)
+
+const (
+	firstAddr          = "cosmos1uupflqrldlpkktssnzgp3r03ff6kz4u4kzd92pjgsfddye7grrlqt9rmmt"
+	msgAllocateAddress = `{"type":"VLOCALCHAIN_ALLOCATE_ADDRESS"}`
+)
+
+type mockBank struct {
+	banktypes.UnimplementedQueryServer
+	banktypes.UnimplementedMsgServer
+	balances   map[string]sdk.Coins
+	failToSend error
+}
+
+var _ banktypes.QueryServer = (*mockBank)(nil)
+var _ banktypes.MsgServer = (*mockBank)(nil)
+
+func (b *mockBank) AllBalances(cctx context.Context, req *banktypes.QueryAllBalancesRequest) (*banktypes.QueryAllBalancesResponse, error) {
+	addr, err := sdk.AccAddressFromBech32(req.Address)
+	if err != nil {
+		return nil, err
+	}
+
+	var resp banktypes.QueryAllBalancesResponse
+	resp.Balances = sdk.Coins{}
+	if coins, ok := b.balances[addr.String()]; ok {
+		resp.Balances = coins
+	}
+	return &resp, nil
+}
+
+func (b *mockBank) Send(cctx context.Context, req *banktypes.MsgSend) (*banktypes.MsgSendResponse, error) {
+	if b.failToSend != nil {
+		return nil, b.failToSend
+	}
+	return &banktypes.MsgSendResponse{}, nil
+}
+
+type mockTransfer struct {
+	transfertypes.UnimplementedQueryServer
+	transfertypes.UnimplementedMsgServer
+}
+
+var _ transfertypes.QueryServer = (*mockTransfer)(nil)
+var _ transfertypes.MsgServer = (*mockTransfer)(nil)
+
+func (t *mockTransfer) Transfer(cctx context.Context, msg *transfertypes.MsgTransfer) (*transfertypes.MsgTransferResponse, error) {
+	return &transfertypes.MsgTransferResponse{Sequence: 1}, nil
+}
+
+type mockStaking struct {
+	stakingtypes.UnimplementedMsgServer
+	stakingtypes.UnimplementedQueryServer
+}
+
+var _ stakingtypes.MsgServer = (*mockStaking)(nil)
+var _ stakingtypes.QueryServer = (*mockStaking)(nil)
+
+func (s *mockStaking) Undelegate(cctx context.Context, msg *stakingtypes.MsgUndelegate) (*stakingtypes.MsgUndelegateResponse, error) {
+	return &stakingtypes.MsgUndelegateResponse{CompletionTime: time.Now().UTC()}, nil
+}
+
+func (s *mockStaking) UnbondingDelegation(cctx context.Context, req *stakingtypes.QueryUnbondingDelegationRequest) (*stakingtypes.QueryUnbondingDelegationResponse, error) {
+	unbondingDelegation := stakingtypes.UnbondingDelegation{
+		DelegatorAddress: req.DelegatorAddr,
+		ValidatorAddress: "cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj",
+		Entries: []stakingtypes.UnbondingDelegationEntry{
+			{
+				CreationHeight: 100,
+				CompletionTime: time.Now().UTC().Add(time.Hour * 24 * 7),
+				InitialBalance: sdk.NewInt(1000),
+				Balance:        sdk.NewInt(500),
+			},
+		},
+	}
+	return &stakingtypes.QueryUnbondingDelegationResponse{Unbond: unbondingDelegation}, nil
+}
+
+// makeTestKit creates a minimal Keeper and Context for use in testing.
+func makeTestKit(bank *mockBank, transfer *mockTransfer, staking *mockStaking) (vm.PortHandler, context.Context) {
+	encodingConfig := params.MakeEncodingConfig()
+	cdc := encodingConfig.Marshaler
+
+	txRouter := baseapp.NewMsgServiceRouter()
+	txRouter.SetInterfaceRegistry(encodingConfig.InterfaceRegistry)
+	queryRouter := baseapp.NewGRPCQueryRouter()
+	queryRouter.SetInterfaceRegistry(encodingConfig.InterfaceRegistry)
+
+	banktypes.RegisterInterfaces(encodingConfig.InterfaceRegistry)
+	banktypes.RegisterMsgServer(txRouter, bank)
+	banktypes.RegisterQueryServer(queryRouter, bank)
+	transfertypes.RegisterInterfaces(encodingConfig.InterfaceRegistry)
+	transfertypes.RegisterMsgServer(txRouter, transfer)
+	transfertypes.RegisterQueryServer(queryRouter, transfer)
+	stakingtypes.RegisterInterfaces(encodingConfig.InterfaceRegistry)
+	stakingtypes.RegisterMsgServer(txRouter, staking)
+	stakingtypes.RegisterQueryServer(queryRouter, staking)
+
+
+	// create a new Keeper
+	keeper := vlocalchain.NewKeeper(cdc, vlocalchainStoreKey, txRouter, queryRouter)
+
+	db := dbm.NewMemDB()
+	ms := store.NewCommitMultiStore(db)
+	ms.MountStoreWithDB(vlocalchainStoreKey, storetypes.StoreTypeIAVL, db)
+	err := ms.LoadLatestVersion()
+	if err != nil {
+		panic(err)
+	}
+
+	// create a new SDK Context
+	ctx := sdk.NewContext(ms, tmproto.Header{}, false, log.NewNopLogger()).WithBlockHeight(998)
+
+	handler := vm.NewProtectedPortHandler(vlocalchain.NewReceiver(keeper))
+
+	// create a new Go context
+	cctx := sdk.WrapSDKContext(ctx)
+	return handler, cctx
+}
+
+func TestAllocateAddress(t *testing.T) {
+	bank := &mockBank{}
+	transfer := &mockTransfer{}
+	staking := &mockStaking{}
+	handler, cctx := makeTestKit(bank, transfer, staking)
+
+	addrs := map[string]bool{
+		firstAddr: false,
+		"cosmos1yj40fakym8kf4wvgz9tky7k9f3v9msm3t7frscrmkjsdkxkpsfkqgeczkg": false,
+		"cosmos1s76vryj7m8k8nm9le65a4plhf5rym5sumtt2n0vwnk5l6k4cwuhsj56ujj": false,
+		"cosmos1c5hplwyxk5jr2dsygjqepzfqvfukwduq9c4660aah76krf99m6gs0k7hvl": false,
+		"cosmos1ys3a7mtna3cad0wxcs4ddukn37stexjdvns8jfdn4uerlr95y4xqnrypf6": false,
+	}
+	numToTest := len(addrs)
+	for i := 0; i < numToTest; i++ {
+		// receive the message
+		ret, err := handler.Receive(cctx, msgAllocateAddress)
+		if err != nil {
+			t.Fatalf("unexpected error[%d]: %v", i, err)
+		}
+		if ret == "" {
+			t.Fatalf("expected non-empty address[%d]", i)
+		}
+		var addr string
+		if err := json.Unmarshal([]byte(ret), &addr); err != nil {
+			t.Fatalf("unexpected error unmarshalling address string[%d]: %v: %v", i, ret, err)
+		}
+
+		already, ok := addrs[addr]
+		if !ok {
+			t.Fatalf("unexpected address[%d]: %v", i, addr)
+		}
+		if already {
+			t.Fatalf("unexpected duplicate address[%d]: %v", i, addr)
+		}
+		addrs[addr] = true
+	}
+}
+
+func TestQuery(t *testing.T) {
+	alreadyAddr := sdk.MustBech32ifyAddressBytes("cosmos", []byte("already"))
+	nonexistentAddr := sdk.MustBech32ifyAddressBytes("cosmos", []byte("nonexistent"))
+	bank := &mockBank{balances: map[string]sdk.Coins{
+		firstAddr:   []sdk.Coin{sdk.NewCoin("fresh", sdk.NewInt(123))},
+		alreadyAddr: []sdk.Coin{sdk.NewCoin("stale", sdk.NewInt(321))},
+	}}
+	transfer := &mockTransfer{}
+	staking := &mockStaking{}
+	handler, cctx := makeTestKit(bank, transfer, staking)
+
+	// get balances
+	testCases := []struct {
+		name     string
+		addr     string
+		failure  string
+		expected sdk.Coins
+	}{
+		{"nonexistent", nonexistentAddr, "", sdk.Coins{}},
+		{"already", alreadyAddr, "", bank.balances[alreadyAddr]},
+		{"first", firstAddr, "", bank.balances[firstAddr]},
+		{"badaddr", "cosmos11111111111", "decoding bech32 failed: invalid separator index 16", sdk.Coins{}},
+	}
+
+	for _, tc := range testCases {
+		tc := tc
+		ctx := sdk.UnwrapSDKContext(cctx)
+		t.Run(tc.name, func(t *testing.T) {
+			msgGetBalances := `{"type":"VLOCALCHAIN_QUERY_MANY","messages":[{"@type":"/cosmos.bank.v1beta1.QueryAllBalancesRequest","address":"` + tc.addr + `"}]}`
+			t.Logf("query request: %v", msgGetBalances)
+			ret, err := handler.Receive(cctx, msgGetBalances)
+			t.Logf("query response: %v", ret)
+			if tc.failure != "" {
+				if err == nil {
+					t.Fatalf("expected error %v, not nil with return %v", tc.failure, ret)
+				} else if err.Error() != tc.failure {
+					t.Fatalf("expected error %v, not %v", tc.failure, err)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if err == nil && ret == "" {
+				t.Fatalf("expected non-empty json")
+			}
+
+			// Unmarshal the responses.
+			s := `{"responses":` + ret + `}`
+
+			unmarshaler := jsonpb.Unmarshaler{}
+			var qrs types.QueryResponses
+			if err = unmarshaler.Unmarshal(strings.NewReader(s), &qrs); err != nil {
+				t.Fatalf("unexpected error unmarshalling reply: %v: %v", ret, err)
+			}
+
+			resps := qrs.Responses
+			if len(resps) != 1 {
+				t.Fatalf("expected responses length 1, got %v", len(resps))
+			}
+			if resps[0].Error != "" {
+				t.Fatalf("unexpected error response: %v", resps[0].Error)
+			}
+			if resps[0].Height != ctx.BlockHeight() {
+				t.Fatalf("expected height %v, got %v", ctx.BlockHeight(), resps[0].Height)
+			}
+
+			// Unmarshal the Any.
+			var pb banktypes.QueryAllBalancesResponse
+			if err = proto.Unmarshal(resps[0].Reply.Value, &pb); err != nil {
+				t.Fatalf("unexpected error unmarshalling reply: %v: %v", ret, err)
+			}
+
+			if !pb.Balances.IsEqual(tc.expected) {
+				t.Errorf("unexpected balance: expected %v, got %v", tc.expected, pb.Balances)
+			}
+		})
+	}
+
+	t.Run("UnbondingDelegation", func(t *testing.T) {
+		// create a new message
+		msg := `{"type":"VLOCALCHAIN_QUERY_MANY","messages":[{"@type":"/cosmos.staking.v1beta1.QueryUnbondingDelegationRequest","delegator_addr":"` + firstAddr + `","validator_addr":"cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj"}]}`
+		t.Logf("query request: %v", msg)
+		ret, err := handler.Receive(cctx, msg)
+		t.Logf("query response: %v", ret)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if ret == "" {
+			t.Fatalf("expected non-empty json")
+		}
+
+		// Unmarshal the JSON response
+		var respJSON []map[string]interface{}
+		if err := json.Unmarshal([]byte(ret), &respJSON); err != nil {
+			t.Fatalf("unexpected error unmarshalling JSON response: %v", err)
+		}
+
+		// Check the response fields
+		if len(respJSON) != 1 {
+			t.Fatalf("expected 1 response, got %d", len(respJSON))
+		}
+		resp := respJSON[0]
+
+		replyAny, ok := resp["reply"].(map[string]interface{})
+		if !ok {
+			t.Fatalf("expected reply field to be a map, got %v", resp["reply"])
+		}
+
+		unbond, ok := replyAny["unbond"].(map[string]interface{})
+		if !ok {
+			t.Fatalf("expected unbond field to be a map, got %v", replyAny["unbond"])
+		}
+
+		// Check the field names and values
+		if unbond["delegatorAddress"] != firstAddr {
+			t.Errorf("expected delegatorAddress %s, got %v", firstAddr, unbond["delegator_address"])
+		}
+		if unbond["validatorAddress"] != "cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj" {
+			t.Errorf("expected validatorAddress cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj, got %v", unbond["validator_address"])
+		}
+
+		entries, ok := unbond["entries"].([]interface{})
+		if !ok || len(entries) != 1 {
+			t.Fatalf("expected 1 unbonding delegation entry, got %v", entries)
+		}
+		entry, ok := entries[0].(map[string]interface{})
+		if !ok {
+			t.Fatalf("expected unbonding delegation entry to be a map, got %v", entries[0])
+		}
+		if entry["creationHeight"] != "100" {
+			t.Errorf("expected creationHeight \"100\", got %v", entry["creation_height"])
+		}
+		if entry["balance"] != "500" {
+			t.Errorf("expected balance \"500\", got %v", entry["balance"])
+		}
+		if _, ok := entry["completionTime"]; !ok {
+			t.Error("expected completionTime field in the response")
+		}
+	})
+}
+
+func TestExecuteTx(t *testing.T) {
+	alreadyAddr := sdk.MustBech32ifyAddressBytes("cosmos", []byte("already"))
+	bank := &mockBank{balances: map[string]sdk.Coins{
+		firstAddr:   []sdk.Coin{sdk.NewCoin("fresh", sdk.NewInt(123))},
+		alreadyAddr: []sdk.Coin{sdk.NewCoin("stale", sdk.NewInt(321))},
+	}}
+	transfer := &mockTransfer{}
+	staking := &mockStaking{}
+	handler, cctx := makeTestKit(bank, transfer, staking)
+
+	// create a new message
+	msg := `{"type":"VLOCALCHAIN_ALLOCATE_ADDRESS"}`
+	ret, err := handler.Receive(cctx, msg)
+	if err != nil {
+		t.Fatalf("unexpected error: %s", err)
+	}
+	if ret == "" {
+		t.Fatalf("expected non-empty json")
+	}
+	var addr string
+	if err := json.Unmarshal([]byte(ret), &addr); err != nil {
+		t.Fatalf("unexpected error unmarshalling address string: %v: %s", ret, err)
+	}
+	if addr != firstAddr {
+		t.Fatalf("expected address %v, got %v", firstAddr, addr)
+	}
+
+	testCases := []struct {
+		name          string
+		signerAddress string
+		fromAddress   string
+		toAddress     string
+		failure       string
+	}{
+		{"valid", addr, addr, alreadyAddr, ""},
+		{"parse error", `"` + addr, firstAddr, alreadyAddr, "invalid character 'c' after object key:value pair"},
+		{"invalid address", addr, alreadyAddr, alreadyAddr, "required signer cosmos1v9k8yetpv3us7src8u does not match actual signer"},
+		{"unauth", alreadyAddr, addr, alreadyAddr, "required signer cosmos1uupflqrldlpkktssnzgp3r03ff6kz4u4kzd92pjgsfddye7grrlqt9rmmt does not match actual signer"},
+	}
+	for _, tc := range testCases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+
+			// create a new message
+			msg := `{"type":"VLOCALCHAIN_EXECUTE_TX","address":"` + tc.signerAddress +
+				`","messages":[{"@type":"/cosmos.bank.v1beta1.MsgSend","from_address":"` +
+				tc.fromAddress + `","to_address":"` + tc.toAddress +
+				`","amount":[{"denom":"fresh","amount":"100"}]}]}`
+
+			ret, err = handler.Receive(cctx, msg)
+			if tc.failure != "" {
+				if err == nil {
+					t.Fatalf("expected error %v, not nil with return %v", tc.failure, ret)
+				}
+				if err.Error() != tc.failure {
+					t.Fatalf("expected error %v, not %v", tc.failure, err)
+				}
+				return
+			}
+
+			if err != nil {
+				t.Fatalf("unexpected error: %s", err)
+			}
+			if ret == "" {
+				t.Fatalf("expected non-empty json")
+			}
+			if ret != "[{}]" {
+				t.Fatalf("expected response [{}], not %v", ret)
+			}
+		})
+	}
+
+	t.Run("MsgUndelegate", func(t *testing.T) {
+		// create a new message
+		msg := `{"type":"VLOCALCHAIN_EXECUTE_TX","address":"` + addr +
+			`","messages":[{"@type":"/cosmos.staking.v1beta1.MsgUndelegate","delegatorAddress":"` +
+			addr + `","validatorAddress":"cosmosvaloper1gghjut3ccd8ay0zduzj64hwre2fxs9ldmqhffj","amount":{"denom":"stake","amount":"100"}}]}`
+
+		ret, err := handler.Receive(cctx, msg)
+		if err != nil {
+			t.Fatalf("unexpected error: %s", err)
+		}
+		if ret == "" {
+			t.Fatalf("expected non-empty json")
+		}
+
+		// Unmarshal the response
+		var resp []map[string]interface{}
+		if err := json.Unmarshal([]byte(ret), &resp); err != nil {
+			t.Fatalf("unexpected error unmarshalling response: %v", err)
+		}
+
+		// Check the response fields
+		if len(resp) != 1 {
+			t.Fatalf("expected 1 response, got %d", len(resp))
+		}
+		
+		if _, ok := resp[0]["completionTime"]; !ok {
+			t.Error("expected 'completionTime' field in response")
+		}
+	})
+}

package/x/vstorage/README.md

@@ -0,0 +1,138 @@
+# 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?], ...]
+ 
+## CLI
+
+A blockchain node may be interrogated by RPC using `agd [--node $url] query vstorage path` via [client/cli](./client/cli/query.go). (See command help for options and variants `data` and `children`.)
+
+Examples:
+```sh
+$ agd --node https://main.rpc.agoric.net:443/ query vstorage path published.reserve.
+children:
+- governance
+- metrics
+pagination: null
+
+$ agd --node https://main.rpc.agoric.net:443/ query vstorage path -o json published.reserve.
+{"children":["governance","metrics"],"pagination":null}
+
+$ agd --node https://main.rpc.agoric.net:443/ query vstorage path published.reserve.metrics
+value: '{"blockHeight":"11030240","values":["{\"body\":\"#{\\\"allocations\\\":{\\\"Fee\\\":{\\\"brand\\\":\\\"$0.Alleged:
+  IST brand\\\",\\\"value\\\":\\\"+20053582387\\\"}},\\\"shortfallBalance\\\":{\\\"brand\\\":\\\"$0\\\",\\\"value\\\":\\\"+0\\\"},\\\"totalFeeBurned\\\":{\\\"brand\\\":\\\"$0\\\",\\\"value\\\":\\\"+0\\\"},\\\"totalFeeMinted\\\":{\\\"brand\\\":\\\"$0\\\",\\\"value\\\":\\\"+0\\\"}}\",\"slots\":[\"board0257\"]}"]}'
+```
+
+## External protobuf interface
+
+RPC via [Querier](./keeper/grpc_query.go),
+and [CometBFT method "abci_query"](https://docs.cometbft.com/main/rpc/#/ABCI/abci_query)
+with params `path` "/agoric.vstorage.Query/..."
+and `data` \<serialized protobuf per [vstorage/query.proto](../../proto/agoric/vstorage/query.proto)>
+(also via [Querier](./keeper/grpc_query.go))
+* /agoric.vstorage.Query/CapData
+* /agoric.vstorage.Query/Children
+* /agoric.vstorage.Query/Data
+
+Example:
+```sh
+$ curl -sS 'https://main.rpc.agoric.net/' -H 'Content-Type: application/json' -X POST --data "$(
+    jq -n --arg queryChildrenRequestHex 0a147075626c69736865642e636f6d6d697474656573 '{
+      id: 1,
+      method: "abci_query",
+      params: { path: "/agoric.vstorage.Query/Children", data: $queryChildrenRequestHex }
+    }' | \
+    tee /dev/stderr \
+  )" | \
+  jq . | \
+  tee /dev/stderr | \
+  jq -r '.result.response.value' | \
+  base64 -d | \
+  protoc -I golang/cosmos/proto/agoric/vstorage/ -I golang/cosmos/third_party/proto/ \
+    --decode=agoric.vstorage.QueryChildrenResponse golang/cosmos/proto/agoric/vstorage/query.proto 
+{
+  "id": 1,
+  "method": "abci_query",
+  "params": {
+    "path": "/agoric.vstorage.Query/Children",
+    "data": "0a147075626c69736865642e636f6d6d697474656573"
+  }
+}
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "response": {
+      "code": 0,
+      "log": "",
+      "info": "",
+      "index": "0",
+      "key": null,
+      "value": "ChJFY29ub21pY19Db21taXR0ZWUKCWtyZWFkLWdvdg==",
+      "proofOps": null,
+      "height": "12222836",
+      "codespace": ""
+    }
+  }
+}
+children: "Economic_Committee"
+children: "kread-gov"
+```
+
+## External JSON interface
+
+As described at [Cosmos SDK: Using the REST Endpoints](https://docs.cosmos.network/main/run-node/interact-node#using-the-rest-endpoints), a blockchain node whose [`app.toml` configuration](https://docs.cosmos.network/main/run-node/run-node#configuring-the-node-using-apptoml-and-configtoml) enables the "REST" API server uses [gRPC-Gateway](https://grpc-ecosystem.github.io/grpc-gateway/) and `google.api.http` annotations in [vstorage/query.proto](../../proto/agoric/vstorage/query.proto) to automatically translate the protobuf-based RPC endpoints into URL paths that accept query parameters and emit JSON.
+* /agoric/vstorage/capdata/$path?remotableValueFormat={object,string}[&mediaType=JSON%20Lines][&itemFormat=flat]
+* /agoric/vstorage/children/$path
+* /agoric/vstorage/data/$path
+
+Example:
+```sh
+$ curl -sS 'https://main.api.agoric.net/agoric/vstorage/children/published.committees'
+{
+  "children": [
+    "Economic_Committee"
+  ],
+  "pagination": null
+}
+```
+
+## 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