Skip to content

Commit

Permalink
Merge pull request #8056 from Agoric/gibson-7581-rpc-capdata-formatting
Browse files Browse the repository at this point in the history
feat(cosmos): Add a "CapData" vstorage RPC endpoint
  • Loading branch information
gibson042 authored and mhofman committed Aug 7, 2023
2 parents 29a25c3 + 47defd4 commit 360924c
Show file tree
Hide file tree
Showing 9 changed files with 2,056 additions and 53 deletions.
54 changes: 53 additions & 1 deletion golang/cosmos/proto/agoric/vstorage/query.proto
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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 [
Expand Down
32 changes: 16 additions & 16 deletions golang/cosmos/x/swingset/types/msgs.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

52 changes: 52 additions & 0 deletions golang/cosmos/x/vstorage/README.md
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 360924c

Please sign in to comment.