剖析Cosmos SDK(十二):构建模块(消息和查询、Msg服务)

煤油灯科技2022-07-28 10:00

消息和查询

Msgs和Queries是模块处理的两个主要对象。一个模块中定义的大多数核心组件,如Msg 服务、Keepers和Query服务,都是为了处理消息和查询而存在的。

消息

消息是最终目标是触发状态转换的对象。它们被包装在交易中,其中可能包含一个或多个。

当交易从底层共识引擎中继到Cosmos SDK应用程序时,首先由BaseApp解码。然后,提取事务中包含的每条消息,并通过BaseApp的MsgServiceRouter路由到相应的模块,以便模块的Msg服务对其进行处理。

Msg服务

请参阅x/bank模块中的Msg服务定义示例:

// Msg defines the bank Msg service.
service Msg {
  // Send defines a method for sending coins from one account to another account.
  rpc Send(MsgSend) returns (MsgSendResponse);

  // MultiSend defines a method for sending coins from some accounts to other accounts.
  rpc MultiSend(MsgMultiSend) returns (MsgMultiSendResponse);
}

每个Msg服务方法必须只有一个参数,该参数必须实现sdk.Msg接口和一个Protobuf响应。命名约定是调用RPC参数Msg<service-rpc-name>和RPC响应 Msg<service-rpc-name>Response。 例如:

  rpc Send(MsgSend) returns (MsgSendResponse);

sdk.Msg接口是下面描述的Amino LegacyMsg接口的简化版本,只有ValidateBasic()和GetSigners()方法。为了向后兼容Amino LegacyMsgs,现有的LegacyMsg类型应该用作服务RPC定义的请求参数。仅支持服务定义的较新的sdk.Msg类型应使用规范的Msg... 名称。

Cosmos SDK使用Protobuf定义来生成客户端和服务器代码:

  • MsgServer接口定义了Msg服务的服务器API,它的实现被描述为Msg服务文档的一部分。
  • 为所有RPC请求和响应类型生成结构。

还会生成一个RegisterMsgServer方法,该方法应用于在AppModule接口的RegisterServices方法中注册模块的MsgServer实现。

为了让客户端(CLI和grpc-gateway)注册这些URL,Cosmos SDK提供了函数RegisterMsgServiceDesc(registry codectypes.InterfaceRegistry, sd *grpc.ServiceDesc) 应该在模块的 RegisterInterfaces方法中调用,使用原型生成&_Msg_serviceDesc作为*grpc.ServiceDesc参数。

Legacy Amino LegacyMsgs

不推荐使用以下定义消息的方式,并且首选使用Msg服务。

Amino LegacyMsgs可以定义为protobuf消息。消息定义通常包括处理消息所需的参数列表,当最终用户想要创建包含所述消息的新事务时,这些参数将由最终用户提供。

LegacyMsg通常伴随着一个标准的构造函数,它是从模块的接口之一调用的。messages还需要实现sdk.Msg接口:

	// Msg defines the interface a transaction message must fulfill.
	Msg interface {
		proto.Message

		// ValidateBasic does a simple validation check that
		// doesn't require access to any other information.
		ValidateBasic() error

		// Signers returns the addrs of signers that must sign.
		// CONTRACT: All signatures must be present to be valid.
		// CONTRACT: Returns addrs in some deterministic order.
		GetSigners() []AccAddress
	}

它扩展了 proto.Message 并包含以下方法: 

  • Route() 字符串:此消息的路由名称。通常,模块中的所有消息都具有相同的路由,通常是模块的名称。
  • Type() 字符串:消息的类型,主要用于事件。这应该返回一个特定于消息的字符串,通常是消息本身的名称。
  • ValidateBasic() 错误。
  • GetSignBytes() []byte:返回消息的规范字节表示。 用于生成签名。
  • GetSigners() []AccAddress:返回签名者列表。Cosmos SDK将确保交易中包含的每条消息都由该方法返回的列表中列出的所有签名者签名。
// LegacyMsg defines the old interface a message must fulfill, containing
// Amino signing method and legacy router info.
// Deprecated: Please use `Msg` instead.
type LegacyMsg interface {
	sdk.Msg

	// Get the canonical byte representation of the Msg.
	GetSignBytes() []byte

	// Return the message type.
	// Must be alphanumeric or empty.
	Route() string

	// Returns a human-readable string for the message, intended for utilization
	// within tags
	Type() string
}

查看来自gov模块的消息的示例实现:

// Route implements Msg
func (msg MsgDeposit) Route() string { return types.RouterKey }

// Type implements Msg
func (msg MsgDeposit) Type() string { return sdk.MsgTypeURL(&msg) }

// ValidateBasic implements Msg
func (msg MsgDeposit) ValidateBasic() error {
	if _, err := sdk.AccAddressFromBech32(msg.Depositor); err != nil {
		return sdkerrors.ErrInvalidAddress.Wrapf("invalid depositor address: %s", err)
	}
	amount := sdk.NewCoins(msg.Amount...)
	if !amount.IsValid() {
		return sdkerrors.Wrap(sdkerrors.ErrInvalidCoins, amount.String())
	}
	if amount.IsAnyNegative() {
		return sdkerrors.Wrap(sdkerrors.ErrInvalidCoins, amount.String())
	}

	return nil
}

// GetSignBytes implements Msg
func (msg MsgDeposit) GetSignBytes() []byte {
	bz := ModuleCdc.MustMarshalJSON(&msg)
	return sdk.MustSortJSON(bz)
}

// GetSigners implements Msg
func (msg MsgDeposit) GetSigners() []sdk.AccAddress {
	depositor, _ := sdk.AccAddressFromBech32(msg.Depositor)
	return []sdk.AccAddress{depositor}
}

查询

查询是应用程序的最终用户通过接口发出并由全节点处理的对信息的请求。全节点通过其共识引擎接收查询,并通过ABCI转发给应用程序。然后通过BaseApp的QueryRouter将其路由到适当的模块,以便模块的查询服务 (./query-services.md) 对其进行处理。

gRPC查询

应使用Protobuf服务定义查询。应在query.proto中为每个模块创建一个查询服务。此服务列出以rpc开头的端点。

以下是此类查询服务定义的示例:

// Query defines the gRPC querier service.
service Query {
  // Accounts returns all the existing accounts
  //
  // Since: cosmos-sdk 0.43
  rpc Accounts(QueryAccountsRequest) returns (QueryAccountsResponse) {
    option (google.api.http).get = "/cosmos/auth/v1beta1/accounts";
  }

  // Account returns account details based on address.
  rpc Account(QueryAccountRequest) returns (QueryAccountResponse) {
    option (google.api.http).get = "/cosmos/auth/v1beta1/accounts/{address}";
  }

  // Params queries all parameters.
  rpc Params(QueryParamsRequest) returns (QueryParamsResponse) {
    option (google.api.http).get = "/cosmos/auth/v1beta1/params";
  }

  // ModuleAccounts returns all the existing module accounts.
  //
  // Since: cosmos-sdk 0.46
  rpc ModuleAccounts(QueryModuleAccountsRequest) returns (QueryModuleAccountsResponse) {
    option (google.api.http).get = "/cosmos/auth/v1beta1/module_accounts";
  }

  // Bech32Prefix queries bech32Prefix
  //
  // Since: cosmos-sdk 0.46
  rpc Bech32Prefix(Bech32PrefixRequest) returns (Bech32PrefixResponse) {
    option (google.api.http).get = "/cosmos/auth/v1beta1/bech32";
  }

  // AddressBytesToString converts Account Address bytes to string
  //
  // Since: cosmos-sdk 0.46
  rpc AddressBytesToString(AddressBytesToStringRequest) returns (AddressBytesToStringResponse) {
    option (google.api.http).get = "/cosmos/auth/v1beta1/bech32/{address_bytes}";
  }

  // AddressStringToBytes converts Address string to bytes
  //
  // Since: cosmos-sdk 0.46
  rpc AddressStringToBytes(AddressStringToBytesRequest) returns (AddressStringToBytesResponse) {
    option (google.api.http).get = "/cosmos/auth/v1beta1/bech32/{address_string}";
  }
}

作为proto.Messages,生成的响应类型默认实现fmt.Stringer 的 String()方法。

还会生成一个RegisterQueryServer方法,该方法应用于在AppModule接口的RegisterServices方法中注册模块的查询服务器。

遗留查询

在Cosmos SDK中引入Protobuf和gRPC之前,通常没有模块开发者定义的特定查询对象,与消息相反。Cosmos SDK采用了更简单的方法,即使用简单路径来定义每个查询。路径包含查询类型和处理它所需的所有参数。对于大多数模块查询,路径应如下所示:

queryCategory/queryRoute/queryType/arg1/arg2/...

其中: 

  • queryCategory是查询的类别,通常为模块查询自定义。它用于区分BaseApp的Query方法中的不同类型的查询。
  • BaseApp的queryRouter使用queryRoute将查询映射到其模块。通常,queryRoute应该是模块的名称。
  • 模块的查询器使用queryType将查询映射到模块内的适当查询器函数。
  • args是处理查询所需的实际参数。它们由最终用户填写。请注意,对于更大的查询,可能更喜欢在请求req的Data字段中传递参数,而不是路径。

每个查询的路径必须由模块开发人员在模块的命令行接口文件中定义。总体而言,模块开发人员需要实现3个主要组件,以使其模块定义的状态子集可查询:

  • 查询器 , 在查询被路由到模块后处理查询。
  • 在模块的CLI文件中查询命令,其中指定了每个查询的路径。
  • 查询返回类型。通常在文件 types/querier.go 中定义,它们指定每个模块查询的结果类型。这些自定义类型必须实现 fmt.Stringer 的 String() 方法。

存储查询

存储查询直接查询存储键。他们使用clientCtx.QueryABCI(req abci.RequestQuery) 返回包含Merkle证明的完整abci.ResponseQuery。

请参阅以下示例:

func handleQueryStore(app *BaseApp, path []string, req abci.RequestQuery) abci.ResponseQuery {
	// "/store" prefix for store queries
	queryable, ok := app.cms.(sdk.Queryable)
	if !ok {
		return sdkerrors.QueryResult(sdkerrors.Wrap(sdkerrors.ErrUnknownRequest, "multistore doesn't support queries"), app.trace)
	}

	req.Path = "/" + strings.Join(path[1:], "/")

	if req.Height <= 1 && req.Prove {
		return sdkerrors.QueryResult(
			sdkerrors.Wrap(
				sdkerrors.ErrInvalidRequest,
				"cannot query with proof when height <= 1; please provide a valid height",
			), app.trace)
	}

	resp := queryable.Query(req)
	resp.Height = req.Height

	return resp
}


Msg服务

Protobuf Msg服务处理消息。Protobuf消息服务特定于定义它们的模块,并且只处理在所述模块中定义的消息。它们在DeliverTx期间从BaseApp调用。

模块Msg服务的实现

每个模块都应该定义一个Protobuf Msg服务,它将负责处理请求(实现sdk.Msg)并返回响应。

正如在ADR 031中进一步描述的那样,这种方法的优点是可以清楚地指定返回类型并生成服务器和客户端代码。

Protobuf根据Msg服务的定义生成一个MsgServer接口。模块开发者的作用是通过实现每个sdk.Msg接收时应该发生的状态转换逻辑来实现这个接口。例如,这里是为x/bank生成的MsgServer接口,它公开了两个sdk.Msgs:

// MsgServer is the server API for Msg service.
type MsgServer interface {
	// Send defines a method for sending coins from one account to another account.
	Send(context.Context, *MsgSend) (*MsgSendResponse, error)
	// MultiSend defines a method for sending coins from some accounts to other accounts.
	MultiSend(context.Context, *MsgMultiSend) (*MsgMultiSendResponse, error)
}

如果可能,现有模块的Keeper应该实现MsgServer,否则可以创建嵌入Keeper的msgServer结构,通常在 ./keeper/msg_server.go 中:

type msgServer struct {
	Keeper
}

msgServer方法可以使用sdk.UnwrapSDKContext从context.Context参数方法中检索sdk.Context:

	ctx := sdk.UnwrapSDKContext(goCtx)

sdk.Msg处理通常遵循以下3个步骤:

验证

在执行msgServer方法之前,消息的ValidateBasic()方法已经被调用。由于msg.ValidateBasic()只执行最基本的检查,这个阶段必须执行所有其他验证(包括有状态和无状态)以确保消息有效。在msgServer方法中执行的检查可能更昂贵,签名者要为这些操作收取气体。例如,一个转账信息的msgServer方法可能会检查发送账户是否有足够的资金来实际执行转账。

建议在将状态值作为参数传递的单独函数中实现所有验证检查。此实现简化了测试,正如预期的那样,昂贵的验证功能会收取额外的费用。例子:

ValidateMsgA(msg MsgA, now Time, gm GasMeter) error {
	if now.Before(msg.Expire) {
		return sdkerrrors.ErrInvalidRequest.Wrap("msg expired")
	}
	gm.ConsumeGas(1000, "signature verification")
	return signatureVerificaton(msg.Prover, msg.Data)
}

状态转换

验证成功后,msgServer方法使用keeper函数访问状态,进行状态转换。

事件

在返回之前,msgServer方法一般会使用ctx中持有的EventManager发出一个或多个事件。 使用使用基于protobuf的事件类型的新EmitTypedEvent函数:

ctx.EventManager().EmitTypedEvent(
	&group.EventABC{Key1: Value1,  Key2, Value2})

或较旧的EmitEvent函数:

ctx.EventManager().EmitEvent(
	sdk.NewEvent(
		eventType,  // e.g. sdk.EventTypeMessage for a message, types.CustomEventType for a custom event defined in the module
		sdk.NewAttribute(key1, value1),
		sdk.NewAttribute(key2, value2),
	),
)

这些事件被转发回底层共识引擎,服务提供商可以使用这些事件围绕应用程序实现服务。

调用的msgServer方法返回一个proto.Message响应和一个错误。然后使用sdk.WrapServiceResult(ctx sdk.Context, res proto.Message, err error) 将这些返回值包装到*sdk.Result或错误中:

package baseapp

import (
	"context"
	"fmt"

	gogogrpc "github.com/gogo/protobuf/grpc"
	"github.com/gogo/protobuf/proto"
	"google.golang.org/grpc"

	codectypes "github.com/cosmos/cosmos-sdk/codec/types"
	sdk "github.com/cosmos/cosmos-sdk/types"
	sdkerrors "github.com/cosmos/cosmos-sdk/types/errors"
)

// MsgServiceRouter routes fully-qualified Msg service methods to their handler.
type MsgServiceRouter struct {
	interfaceRegistry codectypes.InterfaceRegistry
	routes            map[string]MsgServiceHandler
}

var _ gogogrpc.Server = &MsgServiceRouter{}

// NewMsgServiceRouter creates a new MsgServiceRouter.
func NewMsgServiceRouter() *MsgServiceRouter {
	return &MsgServiceRouter{
		routes: map[string]MsgServiceHandler{},
	}
}

// MsgServiceHandler defines a function type which handles Msg service message.
type MsgServiceHandler = func(ctx sdk.Context, req sdk.Msg) (*sdk.Result, error)

// Handler returns the MsgServiceHandler for a given msg or nil if not found.
func (msr *MsgServiceRouter) Handler(msg sdk.Msg) MsgServiceHandler {
	return msr.routes[sdk.MsgTypeURL(msg)]
}

// HandlerByTypeURL returns the MsgServiceHandler for a given query route path or nil
// if not found.
func (msr *MsgServiceRouter) HandlerByTypeURL(typeURL string) MsgServiceHandler {
	return msr.routes[typeURL]
}

// RegisterService implements the gRPC Server.RegisterService method. sd is a gRPC
// service description, handler is an object which implements that gRPC service.
//
// This function PANICs:
// - if it is called before the service `Msg`s have been registered using
//   RegisterInterfaces,
// - or if a service is being registered twice.
func (msr *MsgServiceRouter) RegisterService(sd *grpc.ServiceDesc, handler interface{}) {
	// Adds a top-level query handler based on the gRPC service name.
	for _, method := range sd.Methods {
		fqMethod := fmt.Sprintf("/%s/%s", sd.ServiceName, method.MethodName)
		methodHandler := method.Handler

		var requestTypeName string

		// NOTE: This is how we pull the concrete request type for each handler for registering in the InterfaceRegistry.
		// This approach is maybe a bit hacky, but less hacky than reflecting on the handler object itself.
		// We use a no-op interceptor to avoid actually calling into the handler itself.
		_, _ = methodHandler(nil, context.Background(), func(i interface{}) error {
			msg, ok := i.(sdk.Msg)
			if !ok {
				// We panic here because there is no other alternative and the app cannot be initialized correctly
				// this should only happen if there is a problem with code generation in which case the app won't
				// work correctly anyway.
				panic(fmt.Errorf("unable to register service method %s: %T does not implement sdk.Msg", fqMethod, i))
			}

			requestTypeName = sdk.MsgTypeURL(msg)
			return nil
		}, noopInterceptor)

		// Check that the service Msg fully-qualified method name has already
		// been registered (via RegisterInterfaces). If the user registers a
		// service without registering according service Msg type, there might be
		// some unexpected behavior down the road. Since we can't return an error
		// (`Server.RegisterService` interface restriction) we panic (at startup).
		reqType, err := msr.interfaceRegistry.Resolve(requestTypeName)
		if err != nil || reqType == nil {
			panic(
				fmt.Errorf(
					"type_url %s has not been registered yet. "+
						"Before calling RegisterService, you must register all interfaces by calling the `RegisterInterfaces` "+
						"method on module.BasicManager. Each module should call `msgservice.RegisterMsgServiceDesc` inside its "+
						"`RegisterInterfaces` method with the `_Msg_serviceDesc` generated by proto-gen",
					requestTypeName,
				),
			)
		}

		// Check that each service is only registered once. If a service is
		// registered more than once, then we should error. Since we can't
		// return an error (`Server.RegisterService` interface restriction) we
		// panic (at startup).
		_, found := msr.routes[requestTypeName]
		if found {
			panic(
				fmt.Errorf(
					"msg service %s has already been registered. Please make sure to only register each service once. "+
						"This usually means that there are conflicting modules registering the same msg service",
					fqMethod,
				),
			)
		}

		msr.routes[requestTypeName] = func(ctx sdk.Context, req sdk.Msg) (*sdk.Result, error) {
			ctx = ctx.WithEventManager(sdk.NewEventManager())
			interceptor := func(goCtx context.Context, _ interface{}, _ *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
				goCtx = context.WithValue(goCtx, sdk.SdkContextKey, ctx)
				return handler(goCtx, req)
			}
			// Call the method handler from the service description with the handler object.
			// We don't do any decoding here because the decoding was already done.
			res, err := methodHandler(handler, sdk.WrapSDKContext(ctx), noopDecoder, interceptor)
			if err != nil {
				return nil, err
			}

			resMsg, ok := res.(proto.Message)
			if !ok {
				return nil, sdkerrors.Wrapf(sdkerrors.ErrInvalidType, "Expecting proto.Message, got %T", resMsg)
			}

			return sdk.WrapServiceResult(ctx, resMsg, err)
		}
	}
}

// SetInterfaceRegistry sets the interface registry for the router.
func (msr *MsgServiceRouter) SetInterfaceRegistry(interfaceRegistry codectypes.InterfaceRegistry) {
	msr.interfaceRegistry = interfaceRegistry
}

func noopDecoder(_ interface{}) error { return nil }
func noopInterceptor(_ context.Context, _ interface{}, _ *grpc.UnaryServerInfo, _ grpc.UnaryHandler) (interface{}, error) {
	return nil, nil
}

此方法负责将res参数编组到protobuf并将ctx.EventManager()上的任何事件附加到sdk.Result。

// Result is the union of ResponseFormat and ResponseCheckTx.
message Result {
  option (gogoproto.goproto_getters) = false;

  // Data is any data returned from message or handler execution. It MUST be
  // length prefixed in order to separate data from multiple message executions.
  // Deprecated. This field is still populated, but prefer msg_response instead
  // because it also contains the Msg response typeURL.
  bytes data = 1 [deprecated = true];

  // Log contains the log information from message or handler execution.
  string log = 2;

  // Events contains a slice of Event objects that were emitted during message
  // or handler execution.
  repeated tendermint.abci.Event events = 3 [(gogoproto.nullable) = false];

  // msg_responses contains the Msg handler responses type packed in Anys.
  //
  // Since: cosmos-sdk 0.46
  repeated google.protobuf.Any msg_responses = 4;
}

此图显示了Protobuf Msg服务的典型结构,以及消息如何通过模块传播。

遥测

处理消息时,可以从msgServer方法创建新的遥测指标。

这是来自x/auth/vesting模块的示例:

defer func() {
		telemetry.IncrCounter(1, "new", "account")

		for _, a := range msg.Amount {
			if a.Amount.IsInt64() {
				telemetry.SetGaugeWithLabels(
					[]string{"tx", "msg", "create_vesting_account"},
					float32(a.Amount.Int64()),
					[]metrics.Label{telemetry.NewLabel("denom", a.Denom)},
				)
			}
		}
	}()


原文链接:https://docs.cosmos.network/main/building-modules/messages-and-queries.html

https://docs.cosmos.network/main/building-modules/msg-services.html


---煤油灯科技victorlamp.com翻译整理---

你可能也喜欢这些文章