Authentication Modules

弃用通知

本文档已弃用，并将在未来版本中移除。

概述

认证模块承担了 ICS-30 IBC 中间件中所描述的 Base Application 角色，并使应用开发者能够在使用 Interchain Accounts controller API 时执行自定义逻辑。控制器子模块用于账户注册和数据包发送。它只执行所有 interchain accounts 控制器都需要的通用逻辑。用于管理 interchain accounts 的认证类型并未被限定。可能存在许多适用于不同使用场景的认证类型。因此，认证模块的目的是用自定义认证逻辑包装控制器子模块。在 ibc-go 中，认证模块通过中间件栈连接到控制器链。控制器子模块以中间件的形式实现，而认证模块作为中间件栈的基础应用连接到控制器子模块。要实现认证模块，必须满足 IBCModule 接口。由于控制器子模块被实现为中间件，因此可以创建任意数量的认证模块并将其连接到控制器子模块，而无需编写重复代码。认证模块必须：

对 interchain account 的所有者进行认证。
跟踪某个所有者关联的 interchain account 地址。
代表所有者发送数据包（完成认证后）。

`IBCModule` 实现

必须通过适当的自定义逻辑实现以下 IBCModule 回调：

/ OnChanOpenInit implements the IBCModule interface
func (im IBCModule)

OnChanOpenInit(
  ctx sdk.Context,
  order channeltypes.Order,
  connectionHops []string,
  portID string,
  channelID string,
  counterparty channeltypes.Counterparty,
  version string,
) (string, error) {
  / perform custom logic

  return version, nil
}

/ OnChanOpenAck implements the IBCModule interface
func (im IBCModule)

OnChanOpenAck(
  ctx sdk.Context,
  portID,
  channelID string,
  counterpartyVersion string,
)

error {
  / perform custom logic

  return nil
}

/ OnChanCloseConfirm implements the IBCModule interface
func (im IBCModule)

OnChanCloseConfirm(
  ctx sdk.Context,
  portID,
  channelID string,
)

error {
  / perform custom logic

  return nil
}

/ OnAcknowledgementPacket implements the IBCModule interface
func (im IBCModule)

OnAcknowledgementPacket(
  ctx sdk.Context,
  packet channeltypes.Packet,
  acknowledgement []byte,
  relayer sdk.AccAddress,
)

error {
  / perform custom logic

  return nil
}

/ OnTimeoutPacket implements the IBCModule interface.
func (im IBCModule)

OnTimeoutPacket(
  ctx sdk.Context,
  packet channeltypes.Packet,
  relayer sdk.AccAddress,
)

error {
  / perform custom logic

  return nil
}

为了满足 IBCModule 接口，必须定义以下函数，但控制器子模块永远不会调用它们，因此它们可以返回错误或触发 panic。这是因为在 Interchain Accounts 中，通道握手总是在控制器链上发起，数据包也总是发送到主机链，而不会发送到控制器链。

/ OnChanOpenTry implements the IBCModule interface
func (im IBCModule)

OnChanOpenTry(
  ctx sdk.Context,
  order channeltypes.Order,
  connectionHops []string,
  portID,
  channelID string,
  counterparty channeltypes.Counterparty,
  counterpartyVersion string,
) (string, error) {
    panic("UNIMPLEMENTED")
}

/ OnChanOpenConfirm implements the IBCModule interface
func (im IBCModule)

OnChanOpenConfirm(
  ctx sdk.Context,
  portID,
  channelID string,
)

error {
    panic("UNIMPLEMENTED")
}

/ OnChanCloseInit implements the IBCModule interface
func (im IBCModule)

OnChanCloseInit(
  ctx sdk.Context,
  portID,
  channelID string,
)

error {
    panic("UNIMPLEMENTED")
}

/ OnRecvPacket implements the IBCModule interface. A successful acknowledgement
/ is returned if the packet data is successfully decoded and the receive application
/ logic returns without error.
func (im IBCModule)

OnRecvPacket(
  ctx sdk.Context,
  packet channeltypes.Packet,
  relayer sdk.AccAddress,
)

ibcexported.Acknowledgement {
    panic("UNIMPLEMENTED")
}

`OnAcknowledgementPacket`

一旦中继者中继确认，控制器链就能够访问写入主机链状态中的确认。确认字节中包含主机链上消息执行的响应或错误信息。它们会通过 OnAcknowledgementPacket 回调传递给认证模块。认证模块应当知道如何解码该确认。如果控制器链通过 ibc-go 上的主机模块连接到主机链，则它可以按如下方式解释确认字节：首先将确认反序列化为 sdk.TxMsgData：

var ack channeltypes.Acknowledgement
    if err := channeltypes.SubModuleCdc.UnmarshalJSON(acknowledgement, &ack); err != nil {
    return err
}
    txMsgData := &sdk.TxMsgData{
}
    if err := proto.Unmarshal(ack.GetResult(), txMsgData); err != nil {
    return err
}

如果 txMsgData.Data 字段非 nil，则主机链使用的是 <= v0.45 的 SDK 版本。认证模块应按如下方式解释 txMsgData.Data：

switch len(txMsgData.Data) {
    case 0:
    / see documentation below for SDK 0.46.x or greater
default:
    for _, msgData := range txMsgData.Data {
    if err := handler(msgData); err != nil {
    return err
}

}
...
}

需要一个处理器，根据发送的消息类型决定执行哪些操作。可以使用路由器，或者更简单地使用 switch 语句。

func handler(msgData sdk.MsgData)

error {
    switch msgData.MsgType {
    case sdk.MsgTypeURL(&banktypes.MsgSend{
}):
    msgResponse := &banktypes.MsgSendResponse{
}
    if err := proto.Unmarshal(msgData.Data, msgResponse
}; err != nil {
    return err
}

handleBankSendMsg(msgResponse)
    case sdk.MsgTypeURL(&stakingtypes.MsgDelegate{
}):
    msgResponse := &stakingtypes.MsgDelegateResponse{
}
    if err := proto.Unmarshal(msgData.Data, msgResponse
}; err != nil {
    return err
}

handleStakingDelegateMsg(msgResponse)
    case sdk.MsgTypeURL(&transfertypes.MsgTransfer{
}):
    msgResponse := &transfertypes.MsgTransferResponse{
}
    if err := proto.Unmarshal(msgData.Data, msgResponse
}; err != nil {
    return err
}

handleIBCTransferMsg(msgResponse)

default:
  return
}

如果 txMsgData.Data 为空，则主机链使用的是 > v0.45 的 SDK 版本。认证模块应按如下方式解释 txMsgData.Responses：

...
/ switch statement from above
    case 0:
    for _, any := range txMsgData.MsgResponses {
    if err := handleAny(any); err != nil {
    return err
}

}
}

需要一个处理器，根据 Any 的 type URL 决定执行哪些操作。可以使用路由器，或者更简单地使用 switch 语句。 handler 与 handleAny 之间的逻辑可能可以去重。

func handleAny(any *codectypes.Any)

error {
    switch any.TypeURL {
    case banktypes.MsgSend:
  msgResponse, err := unpackBankMsgSendResponse(any)
    if err != nil {
    return err
}

handleBankSendMsg(msgResponse)
    case stakingtypes.MsgDelegate:
  msgResponse, err := unpackStakingDelegateResponse(any)
    if err != nil {
    return err
}

handleStakingDelegateMsg(msgResponse)
    case transfertypes.MsgTransfer:
  msgResponse, err := unpackIBCTransferMsgResponse(any)
    if err != nil {
    return err
}

handleIBCTransferMsg(msgResponse)

default:
    return
}

集成到 `app.go` 文件

要将认证模块集成到你的链中，请按照 app.go 集成中列出的步骤操作。

Deprecation Notice

This document is deprecated and will be removed in future releases.

Synopsis

Authentication modules play the role of the Base Application as described in ICS-30 IBC Middleware, and enable application developers to perform custom logic when working with the Interchain Accounts controller API. The controller submodule is used for account registration and packet sending. It executes only logic required of all controllers of interchain accounts. The type of authentication used to manage the interchain accounts remains unspecified. There may exist many different types of authentication which are desirable for different use cases. Thus the purpose of the authentication module is to wrap the controller submodule with custom authentication logic. In ibc-go, authentication modules are connected to the controller chain via a middleware stack. The controller submodule is implemented as middleware and the authentication module is connected to the controller submodule as the base application of the middleware stack. To implement an authentication module, the IBCModule interface must be fulfilled. By implementing the controller submodule as middleware, any amount of authentication modules can be created and connected to the controller submodule without writing redundant code. The authentication module must:

Authenticate interchain account owners.
Track the associated interchain account address for an owner.
Send packets on behalf of an owner (after authentication).

`IBCModule` implementation

The following IBCModule callbacks must be implemented with appropriate custom logic:

/ OnChanOpenInit implements the IBCModule interface
func (im IBCModule)

OnChanOpenInit(
  ctx sdk.Context,
  order channeltypes.Order,
  connectionHops []string,
  portID string,
  channelID string,
  counterparty channeltypes.Counterparty,
  version string,
) (string, error) {
  / perform custom logic

  return version, nil
}

/ OnChanOpenAck implements the IBCModule interface
func (im IBCModule)

OnChanOpenAck(
  ctx sdk.Context,
  portID,
  channelID string,
  counterpartyVersion string,
)

error {
  / perform custom logic

  return nil
}

/ OnChanCloseConfirm implements the IBCModule interface
func (im IBCModule)

OnChanCloseConfirm(
  ctx sdk.Context,
  portID,
  channelID string,
)

error {
  / perform custom logic

  return nil
}

/ OnAcknowledgementPacket implements the IBCModule interface
func (im IBCModule)

OnAcknowledgementPacket(
  ctx sdk.Context,
  packet channeltypes.Packet,
  acknowledgement []byte,
  relayer sdk.AccAddress,
)

error {
  / perform custom logic

  return nil
}

/ OnTimeoutPacket implements the IBCModule interface.
func (im IBCModule)

OnTimeoutPacket(
  ctx sdk.Context,
  packet channeltypes.Packet,
  relayer sdk.AccAddress,
)

error {
  / perform custom logic

  return nil
}

The following functions must be defined to fulfill the IBCModule interface, but they will never be called by the controller submodule so they may error or panic. That is because in Interchain Accounts, the channel handshake is always initiated on the controller chain and packets are always sent to the host chain and never to the controller chain.

/ OnChanOpenTry implements the IBCModule interface
func (im IBCModule)

OnChanOpenTry(
  ctx sdk.Context,
  order channeltypes.Order,
  connectionHops []string,
  portID,
  channelID string,
  counterparty channeltypes.Counterparty,
  counterpartyVersion string,
) (string, error) {
    panic("UNIMPLEMENTED")
}

/ OnChanOpenConfirm implements the IBCModule interface
func (im IBCModule)

OnChanOpenConfirm(
  ctx sdk.Context,
  portID,
  channelID string,
)

error {
    panic("UNIMPLEMENTED")
}

/ OnChanCloseInit implements the IBCModule interface
func (im IBCModule)

OnChanCloseInit(
  ctx sdk.Context,
  portID,
  channelID string,
)

error {
    panic("UNIMPLEMENTED")
}

/ OnRecvPacket implements the IBCModule interface. A successful acknowledgement
/ is returned if the packet data is successfully decoded and the receive application
/ logic returns without error.
func (im IBCModule)

OnRecvPacket(
  ctx sdk.Context,
  packet channeltypes.Packet,
  relayer sdk.AccAddress,
)

ibcexported.Acknowledgement {
    panic("UNIMPLEMENTED")
}

`OnAcknowledgementPacket`

Controller chains will be able to access the acknowledgement written into the host chain state once a relayer relays the acknowledgement. The acknowledgement bytes contain either the response of the execution of the message(s) on the host chain or an error. They will be passed to the auth module via the OnAcknowledgementPacket callback. Auth modules are expected to know how to decode the acknowledgement. If the controller chain is connected to a host chain using the host module on ibc-go, it may interpret the acknowledgement bytes as follows: Begin by unmarshaling the acknowledgement into sdk.TxMsgData:

var ack channeltypes.Acknowledgement
    if err := channeltypes.SubModuleCdc.UnmarshalJSON(acknowledgement, &ack); err != nil {
    return err
}
    txMsgData := &sdk.TxMsgData{
}
    if err := proto.Unmarshal(ack.GetResult(), txMsgData); err != nil {
    return err
}

If the txMsgData.Data field is non nil, the host chain is using SDK version <= v0.45. The auth module should interpret the txMsgData.Data as follows:

switch len(txMsgData.Data) {
    case 0:
    / see documentation below for SDK 0.46.x or greater
default:
    for _, msgData := range txMsgData.Data {
    if err := handler(msgData); err != nil {
    return err
}

}
...
}

A handler will be needed to interpret what actions to perform based on the message type sent. A router could be used, or more simply a switch statement.

func handler(msgData sdk.MsgData)

error {
    switch msgData.MsgType {
    case sdk.MsgTypeURL(&banktypes.MsgSend{
}):
    msgResponse := &banktypes.MsgSendResponse{
}
    if err := proto.Unmarshal(msgData.Data, msgResponse
}; err != nil {
    return err
}

handleBankSendMsg(msgResponse)
    case sdk.MsgTypeURL(&stakingtypes.MsgDelegate{
}):
    msgResponse := &stakingtypes.MsgDelegateResponse{
}
    if err := proto.Unmarshal(msgData.Data, msgResponse
}; err != nil {
    return err
}

handleStakingDelegateMsg(msgResponse)
    case sdk.MsgTypeURL(&transfertypes.MsgTransfer{
}):
    msgResponse := &transfertypes.MsgTransferResponse{
}
    if err := proto.Unmarshal(msgData.Data, msgResponse
}; err != nil {
    return err
}

handleIBCTransferMsg(msgResponse)

default:
  return
}

If the txMsgData.Data is empty, the host chain is using SDK version > v0.45. The auth module should interpret the txMsgData.Responses as follows:

...
/ switch statement from above
    case 0:
    for _, any := range txMsgData.MsgResponses {
    if err := handleAny(any); err != nil {
    return err
}

}
}

A handler will be needed to interpret what actions to perform based on the type URL of the Any. A router could be used, or more simply a switch statement. It may be possible to deduplicate logic between handler and handleAny.

func handleAny(any *codectypes.Any)

error {
    switch any.TypeURL {
    case banktypes.MsgSend:
  msgResponse, err := unpackBankMsgSendResponse(any)
    if err != nil {
    return err
}

handleBankSendMsg(msgResponse)
    case stakingtypes.MsgDelegate:
  msgResponse, err := unpackStakingDelegateResponse(any)
    if err != nil {
    return err
}

handleStakingDelegateMsg(msgResponse)
    case transfertypes.MsgTransfer:
  msgResponse, err := unpackIBCTransferMsgResponse(any)
    if err != nil {
    return err
}

handleIBCTransferMsg(msgResponse)

default:
    return
}

Integration into `app.go` file

To integrate the authentication module into your chain, please follow the steps outlined in app.go integration.

​弃用通知

​概述

​IBCModule 实现

​OnAcknowledgementPacket

​集成到 app.go 文件

​Deprecation Notice

​Synopsis

​IBCModule implementation

​OnAcknowledgementPacket

​Integration into app.go file

弃用通知

概述

`IBCModule` 实现

`OnAcknowledgementPacket`

集成到 `app.go` 文件

Deprecation Notice

Synopsis

`IBCModule` implementation

`OnAcknowledgementPacket`

Integration into `app.go` file