@agoric/cosmos 0.35.0-u12.0 → 0.35.0-u14.0

package/x/vibc/ibc.go

@@ -1,17 +1,18 @@
 package vibc
 
 import (
+	"context"
 	"encoding/json"
 	"fmt"
 
 	"github.com/Agoric/agoric-sdk/golang/cosmos/vm"
 	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
 	capability "github.com/cosmos/cosmos-sdk/x/capability/types"
-	channeltypes "github.com/cosmos/ibc-go/v3/modules/core/04-channel/types"
-	porttypes "github.com/cosmos/ibc-go/v3/modules/core/05-port/types"
-	host "github.com/cosmos/ibc-go/v3/modules/core/24-host"
+	channeltypes "github.com/cosmos/ibc-go/v6/modules/core/04-channel/types"
+	porttypes "github.com/cosmos/ibc-go/v6/modules/core/05-port/types"
+	host "github.com/cosmos/ibc-go/v6/modules/core/24-host"
 
-	"github.com/cosmos/ibc-go/v3/modules/core/exported"
+	"github.com/cosmos/ibc-go/v6/modules/core/exported"
 
 	sdk "github.com/cosmos/cosmos-sdk/types"
 )
@@ -63,8 +64,9 @@ func NewIBCModule(keeper Keeper) IBCModule {
 	}
 }
 
-func (ch IBCModule) Receive(ctx *vm.ControllerContext, str string) (ret string, err error) {
+func (ch IBCModule) Receive(cctx context.Context, str string) (ret string, err error) {
 	// fmt.Println("ibc.go downcall", str)
+	ctx := sdk.UnwrapSDKContext(cctx)
 	keeper := ch.keeper
 
 	msg := new(portMessage)
@@ -79,29 +81,28 @@ func (ch IBCModule) Receive(ctx *vm.ControllerContext, str string) (ret string,
 
 	switch msg.Method {
 	case "sendPacket":
-		seq, ok := keeper.GetNextSequenceSend(
-			ctx.Context,
-			msg.Packet.SourcePort,
-			msg.Packet.SourceChannel,
-		)
-		if !ok {
-			return "", fmt.Errorf("unknown sequence number")
-		}
-
 		timeoutTimestamp := msg.Packet.TimeoutTimestamp
 		if msg.Packet.TimeoutHeight.IsZero() && msg.Packet.TimeoutTimestamp == 0 {
 			// Use the relative timeout if no absolute timeout is specifiied.
-			timeoutTimestamp = uint64(ctx.Context.BlockTime().UnixNano()) + msg.RelativeTimeoutNs
+			timeoutTimestamp = uint64(ctx.BlockTime().UnixNano()) + msg.RelativeTimeoutNs
 		}
 
-		packet := channeltypes.NewPacket(
-			msg.Packet.Data, seq,
-			msg.Packet.SourcePort, msg.Packet.SourceChannel,
-			msg.Packet.DestinationPort, msg.Packet.DestinationChannel,
-			msg.Packet.TimeoutHeight, timeoutTimestamp,
+		seq, err := keeper.SendPacket(
+			ctx,
+			msg.Packet.SourcePort,
+			msg.Packet.SourceChannel,
+			msg.Packet.TimeoutHeight,
+			timeoutTimestamp,
+			msg.Packet.Data,
 		)
-		err = keeper.SendPacket(ctx.Context, packet)
 		if err == nil {
+			// synthesize the sent packet
+			packet := channeltypes.NewPacket(
+				msg.Packet.Data, seq,
+				msg.Packet.SourcePort, msg.Packet.SourceChannel,
+				msg.Packet.DestinationPort, msg.Packet.DestinationChannel,
+				msg.Packet.TimeoutHeight, timeoutTimestamp,
+			)
 			bytes, err := json.Marshal(&packet)
 			if err == nil {
 				ret = string(bytes)
@@ -109,14 +110,14 @@ func (ch IBCModule) Receive(ctx *vm.ControllerContext, str string) (ret string,
 		}
 
 	case "receiveExecuted":
-		err = keeper.WriteAcknowledgement(ctx.Context, msg.Packet, msg.Ack)
+		err = keeper.WriteAcknowledgement(ctx, msg.Packet, msg.Ack)
 		if err == nil {
 			ret = "true"
 		}
 
 	case "startChannelOpenInit":
 		err = keeper.ChanOpenInit(
-			ctx.Context, stringToOrder(msg.Order), msg.Hops,
+			ctx, stringToOrder(msg.Order), msg.Hops,
 			msg.Packet.SourcePort,
 			msg.Packet.DestinationPort,
 			msg.Version,
@@ -126,19 +127,19 @@ func (ch IBCModule) Receive(ctx *vm.ControllerContext, str string) (ret string,
 		}
 
 	case "startChannelCloseInit":
-		err = keeper.ChanCloseInit(ctx.Context, msg.Packet.SourcePort, msg.Packet.SourceChannel)
+		err = keeper.ChanCloseInit(ctx, msg.Packet.SourcePort, msg.Packet.SourceChannel)
 		if err == nil {
 			ret = "true"
 		}
 
 	case "bindPort":
-		err = keeper.BindPort(ctx.Context, msg.Packet.SourcePort)
+		err = keeper.BindPort(ctx, msg.Packet.SourcePort)
 		if err == nil {
 			ret = "true"
 		}
 
 	case "timeoutExecuted":
-		err = keeper.TimeoutExecuted(ctx.Context, msg.Packet)
+		err = keeper.TimeoutExecuted(ctx, msg.Packet)
 		if err == nil {
 			ret = "true"
 		}
@@ -151,7 +152,7 @@ func (ch IBCModule) Receive(ctx *vm.ControllerContext, str string) (ret string,
 	return
 }
 
-func (im IBCModule) PushAction(ctx sdk.Context, action vm.Jsonable) error {
+func (im IBCModule) PushAction(ctx sdk.Context, action vm.Action) error {
 	// fmt.Println("ibc.go upcall", send)
 	return im.keeper.PushAction(ctx, action)
 	// fmt.Println("ibc.go upcall reply", reply, err)
@@ -167,24 +168,22 @@ func (im IBCModule) OnChanOpenInit(
 	channelCap *capability.Capability,
 	counterparty channeltypes.Counterparty,
 	version string,
-) error {
-	return sdkerrors.Wrap(
+) (string, error) {
+	return "", sdkerrors.Wrap(
 		channeltypes.ErrChannelNotFound,
 		fmt.Sprintf("vibc does not allow synthetic channelOpenInit for port %s", portID),
 	)
 }
 
 type channelOpenTryEvent struct {
-	Type           string                    `json:"type"`  // IBC
-	Event          string                    `json:"event"` // channelOpenTry
-	Order          string                    `json:"order"`
-	ConnectionHops []string                  `json:"connectionHops"`
-	PortID         string                    `json:"portID"`
-	ChannelID      string                    `json:"channelID"`
-	Counterparty   channeltypes.Counterparty `json:"counterparty"`
-	Version        string                    `json:"version"`
-	BlockHeight    int64                     `json:"blockHeight"`
-	BlockTime      int64                     `json:"blockTime"`
+	vm.ActionHeader `actionType:"IBC_EVENT"`
+	Event           string                    `json:"event" default:"channelOpenTry"`
+	Order           string                    `json:"order"`
+	ConnectionHops  []string                  `json:"connectionHops"`
+	PortID          string                    `json:"portID"`
+	ChannelID       string                    `json:"channelID"`
+	Counterparty    channeltypes.Counterparty `json:"counterparty"`
+	Version         string                    `json:"version"`
 }
 
 func (im IBCModule) OnChanOpenTry(
@@ -198,16 +197,12 @@ func (im IBCModule) OnChanOpenTry(
 	counterpartyVersion string,
 ) (string, error) {
 	event := channelOpenTryEvent{
-		Type:           "IBC_EVENT",
-		Event:          "channelOpenTry",
 		Order:          orderToString(order),
 		ConnectionHops: connectionHops,
 		PortID:         portID,
 		ChannelID:      channelID,
 		Counterparty:   counterparty,
 		Version:        counterpartyVersion, // TODO: don't just use the counterparty version
-		BlockHeight:    ctx.BlockHeight(),
-		BlockTime:      ctx.BlockTime().Unix(),
 	}
 
 	err := im.PushAction(ctx, event)
@@ -224,15 +219,13 @@ func (im IBCModule) OnChanOpenTry(
 }
 
 type channelOpenAckEvent struct {
-	Type                  string                    `json:"type"`  // IBC
-	Event                 string                    `json:"event"` // channelOpenAck
-	PortID                string                    `json:"portID"`
-	ChannelID             string                    `json:"channelID"`
-	CounterpartyVersion   string                    `json:"counterpartyVersion"`
-	Counterparty          channeltypes.Counterparty `json:"counterparty"`
-	ConnectionHops        []string                  `json:"connectionHops"`
-	BlockHeight           int64                     `json:"blockHeight"`
-	BlockTime             int64                     `json:"blockTime"`
+	vm.ActionHeader     `actionType:"IBC_EVENT"`
+	Event               string                    `json:"event" default:"channelOpenAck"`
+	PortID              string                    `json:"portID"`
+	ChannelID           string                    `json:"channelID"`
+	CounterpartyVersion string                    `json:"counterpartyVersion"`
+	Counterparty        channeltypes.Counterparty `json:"counterparty"`
+	ConnectionHops      []string                  `json:"connectionHops"`
 }
 
 func (im IBCModule) OnChanOpenAck(
@@ -248,27 +241,21 @@ func (im IBCModule) OnChanOpenAck(
 
 	channel.Counterparty.ChannelId = counterpartyChannelID
 	event := channelOpenAckEvent{
-		Type:                  "IBC_EVENT",
-		Event:                 "channelOpenAck",
-		PortID:                portID,
-		ChannelID:             channelID,
-		CounterpartyVersion:   counterpartyVersion,
-		Counterparty:          channel.Counterparty,
-		ConnectionHops:        channel.ConnectionHops,
-		BlockHeight:           ctx.BlockHeight(),
-		BlockTime:             ctx.BlockTime().Unix(),
+		PortID:              portID,
+		ChannelID:           channelID,
+		CounterpartyVersion: counterpartyVersion,
+		Counterparty:        channel.Counterparty,
+		ConnectionHops:      channel.ConnectionHops,
 	}
 
 	return im.PushAction(ctx, event)
 }
 
 type channelOpenConfirmEvent struct {
-	Type        string `json:"type"`  // IBC
-	Event       string `json:"event"` // channelOpenConfirm
-	PortID      string `json:"portID"`
-	ChannelID   string `json:"channelID"`
-	BlockHeight int64  `json:"blockHeight"`
-	BlockTime   int64  `json:"blockTime"`
+	vm.ActionHeader `actionType:"IBC_EVENT"`
+	Event           string `json:"event" default:"channelOpenConfirm"`
+	PortID          string `json:"portID"`
+	ChannelID       string `json:"channelID"`
 }
 
 func (im IBCModule) OnChanOpenConfirm(
@@ -277,24 +264,18 @@ func (im IBCModule) OnChanOpenConfirm(
 	channelID string,
 ) error {
 	event := channelOpenConfirmEvent{
-		Type:        "IBC_EVENT",
-		Event:       "channelOpenConfirm",
-		PortID:      portID,
-		ChannelID:   channelID,
-		BlockHeight: ctx.BlockHeight(),
-		BlockTime:   ctx.BlockTime().Unix(),
+		PortID:    portID,
+		ChannelID: channelID,
 	}
 
 	return im.PushAction(ctx, event)
 }
 
 type channelCloseInitEvent struct {
-	Type        string `json:"type"`  // IBC
-	Event       string `json:"event"` // channelCloseInit
-	PortID      string `json:"portID"`
-	ChannelID   string `json:"channelID"`
-	BlockHeight int64  `json:"blockHeight"`
-	BlockTime   int64  `json:"blockTime"`
+	vm.ActionHeader `actionType:"IBC_EVENT"`
+	Event           string `json:"event" default:"channelCloseInit"`
+	PortID          string `json:"portID"`
+	ChannelID       string `json:"channelID"`
 }
 
 func (im IBCModule) OnChanCloseInit(
@@ -303,12 +284,8 @@ func (im IBCModule) OnChanCloseInit(
 	channelID string,
 ) error {
 	event := channelCloseInitEvent{
-		Type:        "IBC_EVENT",
-		Event:       "channelCloseInit",
-		PortID:      portID,
-		ChannelID:   channelID,
-		BlockHeight: ctx.BlockHeight(),
-		BlockTime:   ctx.BlockTime().Unix(),
+		PortID:    portID,
+		ChannelID: channelID,
 	}
 
 	err := im.PushAction(ctx, event)
@@ -316,12 +293,10 @@ func (im IBCModule) OnChanCloseInit(
 }
 
 type channelCloseConfirmEvent struct {
-	Type        string `json:"type"`  // IBC
-	Event       string `json:"event"` // channelCloseConfirm
-	PortID      string `json:"portID"`
-	ChannelID   string `json:"channelID"`
-	BlockHeight int64  `json:"blockHeight"`
-	BlockTime   int64  `json:"blockTime"`
+	vm.ActionHeader `actionType:"IBC_EVENT"`
+	Event           string `json:"event" default:"channelCloseConfirm"`
+	PortID          string `json:"portID"`
+	ChannelID       string `json:"channelID"`
 }
 
 func (im IBCModule) OnChanCloseConfirm(
@@ -330,12 +305,8 @@ func (im IBCModule) OnChanCloseConfirm(
 	channelID string,
 ) error {
 	event := channelCloseConfirmEvent{
-		Type:        "IBC_EVENT",
-		Event:       "channelCloseConfirm",
-		PortID:      portID,
-		ChannelID:   channelID,
-		BlockHeight: ctx.BlockHeight(),
-		BlockTime:   ctx.BlockTime().Unix(),
+		PortID:    portID,
+		ChannelID: channelID,
 	}
 
 	err := im.PushAction(ctx, event)
@@ -343,11 +314,9 @@ func (im IBCModule) OnChanCloseConfirm(
 }
 
 type receivePacketEvent struct {
-	Type        string              `json:"type"`  // IBC
-	Event       string              `json:"event"` // receivePacket
-	Packet      channeltypes.Packet `json:"packet"`
-	BlockHeight int64               `json:"blockHeight"`
-	BlockTime   int64               `json:"blockTime"`
+	vm.ActionHeader `actionType:"IBC_EVENT"`
+	Event           string              `json:"event" default:"receivePacket"`
+	Packet          channeltypes.Packet `json:"packet"`
 }
 
 func (im IBCModule) OnRecvPacket(
@@ -364,28 +333,22 @@ func (im IBCModule) OnRecvPacket(
 	// the same packets.
 
 	event := receivePacketEvent{
-		Type:        "IBC_EVENT",
-		Event:       "receivePacket",
-		Packet:      packet,
-		BlockHeight: ctx.BlockHeight(),
-		BlockTime:   ctx.BlockTime().Unix(),
+		Packet: packet,
 	}
 
 	err := im.PushAction(ctx, event)
 	if err != nil {
-		return channeltypes.NewErrorAcknowledgement(err.Error())
+		return channeltypes.NewErrorAcknowledgement(err)
 	}
 
 	return nil
 }
 
 type acknowledgementPacketEvent struct {
-	Type            string              `json:"type"`  // IBC
-	Event           string              `json:"event"` // acknowledgementPacket
+	vm.ActionHeader `actionType:"IBC_EVENT"`
+	Event           string              `json:"event" default:"acknowledgementPacket"`
 	Packet          channeltypes.Packet `json:"packet"`
 	Acknowledgement []byte              `json:"acknowledgement"`
-	BlockHeight     int64               `json:"blockHeight"`
-	BlockTime       int64               `json:"blockTime"`
 }
 
 func (im IBCModule) OnAcknowledgementPacket(
@@ -395,12 +358,8 @@ func (im IBCModule) OnAcknowledgementPacket(
 	relayer sdk.AccAddress,
 ) error {
 	event := acknowledgementPacketEvent{
-		Type:            "IBC_EVENT",
-		Event:           "acknowledgementPacket",
 		Packet:          packet,
 		Acknowledgement: acknowledgement,
-		BlockHeight:     ctx.BlockHeight(),
-		BlockTime:       ctx.BlockTime().Unix(),
 	}
 
 	err := im.PushAction(ctx, event)
@@ -412,11 +371,9 @@ func (im IBCModule) OnAcknowledgementPacket(
 }
 
 type timeoutPacketEvent struct {
-	Type        string              `json:"type"`  // IBC
-	Event       string              `json:"event"` // timeoutPacket
-	Packet      channeltypes.Packet `json:"packet"`
-	BlockHeight int64               `json:"blockHeight"`
-	BlockTime   int64               `json:"blockTime"`
+	vm.ActionHeader `actionType:"IBC_EVENT"`
+	Event           string              `json:"event" default:"timeoutPacket"`
+	Packet          channeltypes.Packet `json:"packet"`
 }
 
 func (im IBCModule) OnTimeoutPacket(
@@ -425,11 +382,7 @@ func (im IBCModule) OnTimeoutPacket(
 	relayer sdk.AccAddress,
 ) error {
 	event := timeoutPacketEvent{
-		Type:        "IBC_EVENT",
-		Event:       "timeoutPacket",
-		Packet:      packet,
-		BlockHeight: ctx.BlockHeight(),
-		BlockTime:   ctx.BlockTime().Unix(),
+		Packet: packet,
 	}
 
 	err := im.PushAction(ctx, event)

package/x/vibc/keeper/keeper.go

@@ -4,15 +4,17 @@ import (
 	"fmt"
 
 	"github.com/cosmos/cosmos-sdk/codec"
+	storetypes "github.com/cosmos/cosmos-sdk/store/types"
 	sdk "github.com/cosmos/cosmos-sdk/types"
 
 	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
 	capabilitykeeper "github.com/cosmos/cosmos-sdk/x/capability/keeper"
 	capability "github.com/cosmos/cosmos-sdk/x/capability/types"
-	channeltypes "github.com/cosmos/ibc-go/v3/modules/core/04-channel/types"
-	porttypes "github.com/cosmos/ibc-go/v3/modules/core/05-port/types"
-	host "github.com/cosmos/ibc-go/v3/modules/core/24-host"
-	ibcexported "github.com/cosmos/ibc-go/v3/modules/core/exported"
+	clienttypes "github.com/cosmos/ibc-go/v6/modules/core/02-client/types"
+	channeltypes "github.com/cosmos/ibc-go/v6/modules/core/04-channel/types"
+	porttypes "github.com/cosmos/ibc-go/v6/modules/core/05-port/types"
+	host "github.com/cosmos/ibc-go/v6/modules/core/24-host"
+	ibcexported "github.com/cosmos/ibc-go/v6/modules/core/exported"
 
 	bankkeeper "github.com/cosmos/cosmos-sdk/x/bank/keeper"
 
@@ -22,7 +24,7 @@ import (
 
 // Keeper maintains the link to data storage and exposes getter/setter methods for the various parts of the state machine
 type Keeper struct {
-	storeKey sdk.StoreKey
+	storeKey storetypes.StoreKey
 	cdc      codec.Codec
 
 	channelKeeper types.ChannelKeeper
@@ -35,7 +37,7 @@ type Keeper struct {
 
 // NewKeeper creates a new dIBC Keeper instance
 func NewKeeper(
-	cdc codec.Codec, key sdk.StoreKey,
+	cdc codec.Codec, key storetypes.StoreKey,
 	channelKeeper types.ChannelKeeper, portKeeper types.PortKeeper,
 	bankKeeper bankkeeper.Keeper,
 	scopedKeeper capabilitykeeper.ScopedKeeper,
@@ -57,12 +59,6 @@ func (k Keeper) GetBalance(ctx sdk.Context, addr sdk.AccAddress, denom string) s
 	return k.bankKeeper.GetBalance(ctx, addr, denom)
 }
 
-// GetNextSequenceSend defines a wrapper function for the channel Keeper's function
-// in order to expose it to the vibc IBC handler.
-func (k Keeper) GetNextSequenceSend(ctx sdk.Context, portID, channelID string) (uint64, bool) {
-	return k.channelKeeper.GetNextSequenceSend(ctx, portID, channelID)
-}
-
 // GetChannel defines a wrapper function for the channel Keeper's function
 // in order to expose it to the vibc IBC handler.
 func (k Keeper) GetChannel(ctx sdk.Context, portID, channelID string) (channeltypes.Channel, bool) {
@@ -98,15 +94,20 @@ func (k Keeper) ChanOpenInit(ctx sdk.Context, order channeltypes.Order, connecti
 
 // SendPacket defines a wrapper function for the channel Keeper's function
 // in order to expose it to the vibc IBC handler.
-func (k Keeper) SendPacket(ctx sdk.Context, packet ibcexported.PacketI) error {
-	portID := packet.GetSourcePort()
-	channelID := packet.GetSourceChannel()
-	capName := host.ChannelCapabilityPath(portID, channelID)
+func (k Keeper) SendPacket(
+	ctx sdk.Context,
+	sourcePort string,
+	sourceChannel string,
+	timeoutHeight clienttypes.Height,
+	timeoutTimestamp uint64,
+	data []byte,
+) (uint64, error) {
+	capName := host.ChannelCapabilityPath(sourcePort, sourceChannel)
 	chanCap, ok := k.GetCapability(ctx, capName)
 	if !ok {
-		return sdkerrors.Wrapf(channeltypes.ErrChannelCapabilityNotFound, "could not retrieve channel capability at: %s", capName)
+		return 0, sdkerrors.Wrapf(channeltypes.ErrChannelCapabilityNotFound, "could not retrieve channel capability at: %s", capName)
 	}
-	return k.channelKeeper.SendPacket(ctx, chanCap, packet)
+	return k.channelKeeper.SendPacket(ctx, chanCap, sourcePort, sourceChannel, timeoutHeight, timeoutTimestamp, data)
 }
 
 var _ ibcexported.Acknowledgement = (*rawAcknowledgement)(nil)

package/x/vibc/types/expected_keepers.go

@@ -3,16 +3,24 @@ package types
 import (
 	sdk "github.com/cosmos/cosmos-sdk/types"
 	capability "github.com/cosmos/cosmos-sdk/x/capability/types"
-	connection "github.com/cosmos/ibc-go/v3/modules/core/03-connection/types"
-	channel "github.com/cosmos/ibc-go/v3/modules/core/04-channel/types"
-	ibcexported "github.com/cosmos/ibc-go/v3/modules/core/exported"
+	clienttypes "github.com/cosmos/ibc-go/v6/modules/core/02-client/types"
+	connection "github.com/cosmos/ibc-go/v6/modules/core/03-connection/types"
+	channel "github.com/cosmos/ibc-go/v6/modules/core/04-channel/types"
+	ibcexported "github.com/cosmos/ibc-go/v6/modules/core/exported"
 )
 
 // ChannelKeeper defines the expected IBC channel keeper
 type ChannelKeeper interface {
 	GetChannel(ctx sdk.Context, srcPort, srcChan string) (channel channel.Channel, found bool)
-	GetNextSequenceSend(ctx sdk.Context, portID, channelID string) (uint64, bool)
-	SendPacket(ctx sdk.Context, channelCap *capability.Capability, packet ibcexported.PacketI) error
+	SendPacket(
+		ctx sdk.Context,
+		channelCap *capability.Capability,
+		sourcePort string,
+		sourceChannel string,
+		timeoutHeight clienttypes.Height,
+		timeoutTimestamp uint64,
+		data []byte,
+	) (uint64, error)
 	WriteAcknowledgement(ctx sdk.Context, channelCap *capability.Capability, packet ibcexported.PacketI, acknowledgement ibcexported.Acknowledgement) error
 	ChanOpenInit(ctx sdk.Context, order channel.Order, connectionHops []string, portID string,
 		portCap *capability.Capability, counterparty channel.Counterparty, version string) (string, *capability.Capability, error)

package/x/vibc/types/msgs.go

@@ -4,7 +4,7 @@ import (
 	sdk "github.com/cosmos/cosmos-sdk/types"
 	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
 
-	chanTypes "github.com/cosmos/ibc-go/v3/modules/core/04-channel/types"
+	chanTypes "github.com/cosmos/ibc-go/v6/modules/core/04-channel/types"
 )
 
 const RouterKey = ModuleName // this was defined in your key.go file

package/x/vibc/types/msgs.pb.go

@@ -7,7 +7,7 @@ import (
 	context "context"
 	fmt "fmt"
 	github_com_cosmos_cosmos_sdk_types "github.com/cosmos/cosmos-sdk/types"
-	types "github.com/cosmos/ibc-go/v3/modules/core/04-channel/types"
+	types "github.com/cosmos/ibc-go/v6/modules/core/04-channel/types"
 	_ "github.com/gogo/protobuf/gogoproto"
 	grpc1 "github.com/gogo/protobuf/grpc"
 	proto "github.com/gogo/protobuf/proto"

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