docs: add VStorage documentation #1110
Conversation
Deploying documentation with
|
| Latest commit: |
93c3d02
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://0dcdec0d.documentation-7tp.pages.dev |
| Branch Preview URL: | https://awg-add-vstorage-documentati.documentation-7tp.pages.dev |
|
Cloudflare deployment logs are available here |
main/reference/vstorage-ref.md
Outdated
| ## VStorage with CLI | ||
| VStorage can be accessed via CLI using: | ||
|
|
||
| ```sh | ||
| $ agd /[--node {url}] query vstorage {path} | ||
| ``` | ||
|
|
||
| For example: | ||
| ```sh | ||
| $ agd query vstorage path published.agoricNames | ||
| children: | ||
| - brand | ||
| - installation | ||
| - instance | ||
| ... |
There was a problem hiding this comment.
Ah. yes. this is the sort of material that I'd like to see in https://docs.agoric.com/guides/agoric-cli/agd-query-tx.html
The --node flag is discussed more thoroughly there. I don't see any reference to it here, so you might as well drop it here.
What's the / in /[--node {url}] by the way?
There was a problem hiding this comment.
/ was a typo. Fixing it in a commit.
The query goes to a local node at tcp://localhost:26657 by default. To use another node:
$ agd status --node https://devnet.rpc.agoric.net:443
Can you confirm this is same for query as well? I am not sure about it. There is no mention about --node parameter there. Maybe I can add information there and then refer it to that.
There was a problem hiding this comment.
yes, --node applies to all agd query and agd tx sub-commands, IME.
The help text is oddly inconsistent, though: agd query --help | grep node is empty, as is agd query vstorage --help | grep node but:
$ agd query tx --help | grep node
--node string <host>:<port> to Tendermint RPC interface for this chain (default "tcp://localhost:26657")@gibson042 Do you know of some reason why the help text is inconsistent? If not, I suppose we owe an issue?
There was a problem hiding this comment.
Yes, an issue would be good. I'm pretty sure this is because the Cobra library responsible for CLI option definition shows help for applicable options defined higher in the command hierarchy (so-called "persistent flags") only at an invocable command (which agd query tx is but e.g. agd query vstorage is not because it must be followed by "children" or "data" or "path" and agd query params is not because it must be followed by "subspace").
But there should be a way to do it, because "--chain-id" seems to work that way (e.g., it shows in both e.g. agd tx --help and [as a Global Flag] in agd tx gov --help).
ansabgillani
changed the title
There was a problem hiding this comment.
re technical correctness: this change is mostly neutral. I don't think it introduces any new material. The "Common VStorage Examples" heading suggests that it's no longer exhaustive, but the content is just as exhaustive as it was, and the top-level heading still says "Reference".
I don't see any errors.
So the impact is mainly organizational / editorial. I defer to others on that.
| ## DApp UI and VStorage | ||
| As mentioned above, VStorage offers clients an access to data from contracts, including dApp UI. For detail tutorial on tools and libraries available for this connection is available [here](https://docs.agoric.com/guides/getting-started/ui-tutorial/querying-vstorage.html#querying-vstorage). | ||
|
|
||
| ## Common VStorage Examples |
| ## vstorage: published.\* keys | ||
| ### vstorage: published.\* keys |
There was a problem hiding this comment.
Demoting these from h2 to h3 means they don't show up in the page TOC. Is that on purpose?
| `published.agoricNames.instance` contains _instances_ of important contracts. | ||
| The data at this key are the entries of the NameHub. Here we show the object comprised of those entries. | ||
|
|
There was a problem hiding this comment.
I don't think you meant to repeat this.
| ## VStorage Protobuf Service Definition | ||
| The protobuf definition of vstorage is [agoric.vstorage.Query](https://github.com/Agoric/agoric-sdk/blob/mainnet1B/golang/cosmos/proto/agoric/vstorage/query.proto#L11) package. | ||
| ``` | ||
| service Query { |
There was a problem hiding this comment.
good idea to put the proto here
| }) | ||
| ) | ||
| ``` | ||
| The `chainStorage` node corresponds to the `published` key in the [vstorage hierarchy](https://docs.agoric.com/reference/vstorage-ref.html#vstorage-hierarchy). Using `E(chainStorage).makeChildNode(contractName)` gives the contract access to write to the `published.{contractName}` key and all keys under it. |
There was a problem hiding this comment.
maybe put a security warning here to ensure contracts aren't passed the top most storage node, because then they can write to any key under it. I made this mistake in the past.
could be something like
Note: Always ensure to only pass the storage node to your contract that you explicitly intend for it to use. This will avoid giving a contract too much write powers to write to unintended storage nodes.
What do you think @ansabgillani ?
Adding VStorage documentation
Attempt to improve the documentation in terms of VStorage from just reference to a centralized documentation for the feature.