vstorage

package
v0.0.0-...-6678205 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 20, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

README

Virtual Storage

This module manages "IAVL" chain storage data with a hierarchical keyspace in which each key is a "path" 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

  • 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 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. (See command help for options and variants data and children.)

Examples:

$ 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, and CometBFT method "abci_query" with params path "/agoric.vstorage.Query/..." and data <serialized protobuf per vstorage/query.proto> (also via Querier)

  • /agoric.vstorage.Query/CapData
  • /agoric.vstorage.Query/Children
  • /agoric.vstorage.Query/Data

Example:

$ 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, a blockchain node whose app.toml configuration enables the "REST" API server uses gRPC-Gateway and google.api.http annotations in 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:

$ curl -sS 'https://main.api.agoric.net/agoric/vstorage/children/published.committees'
{
  "children": [
    "Economic_Committee"
  ],
  "pagination": null
}

Documentation

Index

Constants

View Source 
const (
	ModuleName = types.ModuleName
	StoreKey   = types.StoreKey
)

Variables

View Source 
var (
	NewKeeper   = keeper.NewKeeper
	NewStorage  = types.NewData
	NewChildren = types.NewChildren
)

Functions

func DefaultGenesisState 

func DefaultGenesisState() *types.GenesisState

func ExportGenesis 

func ExportGenesis(ctx sdk.Context, keeper Keeper) (*types.GenesisState, error)

func InitGenesis 

func InitGenesis(ctx sdk.Context, keeper Keeper, data *types.GenesisState) error

func NewGenesisState 

func NewGenesisState() *types.GenesisState

func NewHandler 

func NewHandler(k Keeper) baseapp.MsgServiceHandler

NewHandler returns a handler for "vstorage" type messages.

func NewStorageHandler 

func NewStorageHandler(keeper Keeper) vstorageHandler

func ValidateGenesis 

func ValidateGenesis(data *types.GenesisState) error

Types

type AppModule 

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

func NewAppModule 

func NewAppModule(k Keeper) AppModule

NewAppModule creates a new AppModule Object

func (AppModule) BeginBlock 

func (am AppModule) BeginBlock(ctx context.Context) error

func (AppModule) ConsensusVersion 

func (AppModule) ConsensusVersion() uint64

func (AppModule) EndBlock 

func (am AppModule) EndBlock(ctx context.Context) error

func (AppModule) ExportGenesis 

func (am AppModule) ExportGenesis(ctx sdk.Context, cdc codec.JSONCodec) json.RawMessage

func (AppModule) InitGenesis 

func (am AppModule) InitGenesis(ctx sdk.Context, cdc codec.JSONCodec, data json.RawMessage)

func (AppModule) IsAppModule 

func (am AppModule) IsAppModule()

IsAppModule implements the appmodule.AppModule interface.

func (AppModule) IsOnePerModuleType 

func (am AppModule) IsOnePerModuleType()

IsOnePerModuleType is a marker function just indicates that this is a one-per-module type.

func (AppModule) Name 

func (AppModule) Name() string

func (AppModule) RegisterInvariants 

func (am AppModule) RegisterInvariants(ir sdk.InvariantRegistry)

func (AppModule) RegisterServices 

func (am AppModule) RegisterServices(cfg module.Configurator)

type AppModuleBasic 

type AppModuleBasic struct {
}

app module Basics object

func (AppModuleBasic) DefaultGenesis 

func (AppModuleBasic) DefaultGenesis(cdc codec.JSONCodec) json.RawMessage

DefaultGenesis returns default genesis state as raw bytes for the deployment

func (AppModuleBasic) GetQueryCmd 

func (AppModuleBasic) GetQueryCmd() *cobra.Command

Get the root query command of this module

func (AppModuleBasic) GetTxCmd 

func (AppModuleBasic) GetTxCmd() *cobra.Command

Get the root tx command of this module

func (AppModuleBasic) Name 

func (AppModuleBasic) Name() string

func (AppModuleBasic) RegisterGRPCGatewayRoutes 

func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux)

func (AppModuleBasic) RegisterInterfaces 

func (b AppModuleBasic) RegisterInterfaces(registry cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types

func (AppModuleBasic) RegisterLegacyAminoCodec 

func (AppModuleBasic) RegisterLegacyAminoCodec(cdc *codec.LegacyAmino)

func (AppModuleBasic) ValidateGenesis 

func (AppModuleBasic) ValidateGenesis(cdc codec.JSONCodec, config client.TxEncodingConfig, bz json.RawMessage) error

Validation check of the Genesis

type Data 

type Data = types.Data

type Keeper 

type Keeper = keeper.Keeper

Source Files

View all Source files

Directories

Path Synopsis
client
cli
Package types is a reverse proxy.
 Package types is a reverse proxy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.