From 3f7f19ee1955c86c438a29d492074c748b583073 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Wed, 2 Aug 2023 10:52:34 -0400
Subject: [PATCH 1/2] docs(cosmos/x/vstorage): Add README section for "REST"
 API interface

---
 golang/cosmos/x/vstorage/README.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/golang/cosmos/x/vstorage/README.md b/golang/cosmos/x/vstorage/README.md
index af6dfc6079a..cea572ba878 100644
--- a/golang/cosmos/x/vstorage/README.md
+++ b/golang/cosmos/x/vstorage/README.md
@@ -46,6 +46,24 @@ and `data` \<serialized protobuf per [vstorage/query.proto](../../proto/agoric/v
 * /agoric.vstorage.Query/Children
 * /agoric.vstorage.Query/Data
 
+## 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)

From 72556d1f424d4c54111cc04f723333d4ce8e78d1 Mon Sep 17 00:00:00 2001
From: Richard Gibson <richard.gibson@gmail.com>
Date: Wed, 2 Aug 2023 11:29:21 -0400
Subject: [PATCH 2/2] docs(cosmos/x/vstorage): Add README section for CLI

---
 golang/cosmos/x/vstorage/README.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/golang/cosmos/x/vstorage/README.md b/golang/cosmos/x/vstorage/README.md
index cea572ba878..32dfefc7eb7 100644
--- a/golang/cosmos/x/vstorage/README.md
+++ b/golang/cosmos/x/vstorage/README.md
@@ -34,6 +34,28 @@ This is used by the SwingSet "bridge".
   * 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 $command` via [client/cli](./client/cli/query.go).
+* `children [--height $blockHeight] [-o {text,json}] [$path]`
+* `data [--height $blockHeight] [-o {text,json}] $path`
+
+Examples:
+```sh
+$ agd --node https://main.rpc.agoric.net:443/ query vstorage children published.reserve
+children:
+- governance
+- metrics
+pagination: null
+
+$ agd --node https://main.rpc.agoric.net:443/ query vstorage children -o json published.reserve
+{"children":["governance","metrics"],"pagination":null}
+
+$ agd --node https://main.rpc.agoric.net:443/ query vstorage data 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