应用链插件编写

在本教程中，你将构建一个完整功能的 Plugin。过程中能学习基本的概念和具体使用细节。该示例将展示如何快速、轻松地接入自己的区块链到跨链平台中来。

如果你需要接入自己开发的区块链到BitXHub跨链平台来的话，可以根据你们自己的区块链来定制开发Plugin，通过跨链网关来加入到跨链平台。

开发要求

• 安装 go1.13+

• 设置好$GOPATH等环境

1. 重要概念

在解释具体的接口之前，先明确几个概念：

• 跨链请求：如果有两条区块链A和B，A链需要向B链发起任何操作，需要按照IBTP规则向中继链发出一个请求包，我们称之为跨链请求A->B；
• IBTP包：满足IBTP的一个package，跨链请求都需要通过IBTP包进行；
• 来源链：在跨链请求A->B中，A即为来源链服务；
• 目的链：在跨链请求A->B中，B即为目的链服务。

3. Plugin接口

为了更加便捷的开发Plugin接入到Pier中来，我们规定了下面一些必要的接口。

type Client interface {

    // 初始化Plugin服务
    Initialize(configPath string extra []byte) error

    // 启动Plugin服务的接口
    Start() error

    // 停止Plugin服务的接口
    Stop() error

    // Plugin负责将区块链上产生的跨链事件转化为标准的IBTP格式，Pier通过GetIBTP接口获取跨链请求再进行处理
    GetIBTPCh() chan *pb.IBTP

    // Plugin负责将区块链上信任根变更的信息传递给中继链
    GetUpdateMeta() chan *pb.UpdateMeta

    // Plugin 负责执行来源链过来的跨链请求，Pier调用SubmitIBTP提交收到的跨链请求。
    // from: 来源链服务ID
    // index: 跨链交易索引
    // serviceID: 目的链服务ID
    // ibtpType: 跨链交易类型<IBTP_INTERCHAIN, IBTP_RECEIPT_SUCCESS, IBTP_RECEIPT_FAILURE, IBTP_RECEIPT_ROLLBACK>
    // content: 跨链调用内容编码
    // proof: 中继链多签数据
    // isEncrypted: content.payload是否加密
    SubmitIBTP(from string, index uint64, serviceID string, ibtpType pb.IBTP_Type, content *pb.Content, proof *pb.BxhProof, isEncrypted bool) (*pb.SubmitIBTPResponse, error)

    // Plugin 负责执行来源链过来的跨链请求，Pier调用SubmitIBTP提交收到的跨链请求。
    // to: 目的链服务ID
    // index: 跨链交易索引
    // serviceID: 来源链服务ID
    // ibtpType: 跨链交易类型<IBTP_INTERCHAIN, IBTP_RECEIPT_SUCCESS, IBTP_RECEIPT_FAILURE, IBTP_RECEIPT_ROLLBACK>
    // result: 跨链调用结果编码
    // proof: 中继链多签数据
   SubmitReceipt(to string, index uint64, serviceID string, ibtpType pb.IBTP_Type, result *pb.Result, proof *pb.BxhProof) (*pb.SubmitIBTPResponse, error)


    // GetOutMessage 负责在跨链合约中查询历史跨链请求。查询键值中servicePair指定服务对，idx指定序号，查询结果为以Plugin负责的区块链作为来源链的跨链请求。
    GetOutMessage(servicePair string, idx uint64) (*pb.IBTP, error)

    // GetReceiptMessage 负责在跨链合约中查询历史跨链回执。查询键值中servicePair指定服务对，idx指定序号，查询结果为以Plugin负责的区块链作为目的链的跨链回执。
    GetReceiptMessage(servicePair string, idx uint64) (*pb.IBTP, error)

    // GetInMeta 是获取跨链回执相关的Meta信息的接口。以Plugin负责的区块链为目的链服务的一系列跨链请求的序号信息。如果Plugin负责A链服务，则A可能和多条链服务进行跨链，如A->B:3; A->C:5。返回的map中，key值为服务对（来源链服务ID+目的链服务ID），value对应已发送到该目的链的最新跨链请求的序号，如{A+B:3, A+C:5}。
    GetInMeta() (map[string]uint64, error

    // GetOutMeta 是获取跨链请求相关的Meta信息的接口。以Plugin负责的区块链为来源链服务的一系列跨链请求的序号信息。如果Plugin负责A链服务，则A可能和多条链服务进行跨链，如A->B:3; A->C:5。返回的map中，key值为服务对（来源链服务ID+目的链服务ID），value对应已发送到该目的链的最新跨链请求的序号，如{A+B:3, A+C:5}。。
    GetOutMeta() (map[string]uint64, error)


    // GetCallbackMeta 是获取跨链请求相关的Meta信息的接口。
    GetCallbackMeta() (map[string]uint64, error)

    // CommitCallback 执行完IBTP包之后进行一些回调操作。
    CommitCallback(ibtp *pb.IBTP) error

    // GetReceipt 获取一个已被执行IBTP的回执
    GetReceipt(ibtp *pb.IBTP) (*pb.IBTP, error)

    // Name 描述Plugin负责的区块链的自定义名称，一般和业务相关，如司法链等。
    Name() string

    // Type 描述Plugin负责的区块链类型，比如Fabric
    Type() string
}

3. 程序目的

本教程以开发一个简单的连接Fabric区块链网络的Plugin为例，最终的程序能够实现从负责的区块链获取Hello World信息并返回到跨链平台中。

4. 开始编写你的程序

首先选择你的工程目录，按照正常的GO程序的流程建立项目

$ go version // 确认你安装的GO版本
$ mkdir ${YOUR_PROJECT}
$ cd ${YOUR_PROJECT}
$ go mod init exmple/fabric-plugin

4.1 读取配置

Plugin的配置文件路径是通过Initialize的方法动态传入的，这意味着你可以方便的修改关于你的区块链的参数信息。我们新建文件 ./config.go 文件，负责配置读取的所有操作。

这里使用的是 github.com/spf13/viper库和TOML文件作为配置，当然你也可以使用任何你熟悉的工具来读取配置。

package main

import (
   "path/filepath"
   "strings"

   "github.com/spf13/viper"
)

const (
   ConfigName = "fabric.toml"
)

type Fabric struct {
   Addr        string `toml:"addr" json:"addr"`
   Name        string `toml:"name" json:"name"`
   EventFilter string `mapstructure:"event_filter" toml:"event_filter" json:"event_filter"`
   Username    string `toml:"username" json:"username"`
   CCID        string `toml:"ccid" json:"ccid"`
   ChannelId   string `mapstructure:"channel_id" toml:"channel_id" json:"channel_id"`
   Org         string `toml:"org" json:"org"`
}

func DefaultConfig() *Fabric {
   return &Fabric{
      Addr:        "localhost:10053",
      Name:        "fabric",
      EventFilter: "CrosschainEventName",
      Username:    "Admin",
      CCID:        "Broker-001",
      ChannelId:   "mychannel",
      Org:         "org2",
   }
}

func UnmarshalConfig(configPath string) (*Fabric, error) {
   viper.SetConfigFile(filepath.Join(configPath, ConfigName))
   viper.SetConfigType("toml")
   viper.AutomaticEnv()
   viper.SetEnvPrefix("FABRIC")
   replacer := strings.NewReplacer(".", "_")
   viper.SetEnvKeyReplacer(replacer)
   if err := viper.ReadInConfig(); err != nil {
      return nil, err
   }

   config := DefaultConfig()

   if err := viper.Unmarshal(config); err != nil {
      return nil, err
   }

   return config, nil
}

4.2 Client对象

首先创建一个client.go文件，这个文件是Plugin的核心和入口。

在该文件中，应该定义你的Plugin如何获取client 实例，以及如何启动和停止Plugin服务。

现在我们需要创建一个自定义的Client 结构，跨链网关最终拿到的应该是这个结构的一个实例，先来看看这个结构中都需要什么。

首先来看看Client自定义具体结构：

type ContractMeta struct {
    EventFilter string `json:"event_filter"`
    Username    string `json:"username"`
    CCID        string `json:"ccid"`
    ChannelID   string `json:"channel_id"`
    ORG         string `json:"org"`
}

type Client struct {
    meta       *ContractMeta
    consumer   *Consumer
    eventC     chan *pb.IBTP
    appchainID string
    name       string
    outMeta    map[string]uint64
    ticker     *time.Ticker
    done       chan bool
}

• meta：Plugin直接和跨链合约交互，需要保存你的合约的一些基础信息。由于我们需要连接一个Fabric网络，这些Meta信息包括 Fabric中跨链事件的名称、Fabric中的用户名称、Chaincode合约的名称、你的组织名称Org以及组织所在的channel；

• consumer：可以理解为Fabric上跨链事件的“监听器”，这个监听器也是一个自定义的结构，具体的结构在后面会详细介绍；

• eventC：为跨链网关提供读取监听到的跨链事件的通道；

• name：自定的区块链的名称；

• appchainID：跨链网关注册在跨链平台中后产生的唯一ID，作为应用链的标识。

然后应该提供一个Client的实例化的接口（类似于构造函数），具体代码如下：

func (c *Client) Initialize(configPath, appchainID string, extra []byte) error {
    eventC := make(chan *pb.IBTP)
    fabricConfig, err := UnmarshalConfig(configPath)
    if err != nil {
        return fmt.Errorf("unmarshal config for plugin :%w", err)
    }

    contractmeta := &ContractMeta{
        EventFilter: fabricConfig.EventFilter,
        Username:    fabricConfig.Username,
        CCID:        fabricConfig.CCID,
        ChannelID:   fabricConfig.ChannelId,
        ORG:         fabricConfig.Org,
    }

    m := make(map[string]uint64)
    if err := json.Unmarshal(extra, &m); err != nil {
        return fmt.Errorf("unmarshal extra for plugin :%w", err)
    }
    if m == nil {
        m = make(map[string]uint64)
    }

    mgh, err := newFabricHandler(contractmeta.EventFilter, eventC, appchainID)
    if err != nil {
        return err
    }

    done := make(chan bool)
    csm, err := NewConsumer(configPath, contractmeta, mgh, done)
    if err != nil {
        return err
    }

    c.consumer = csm
    c.eventC = eventC
    c.meta = contractmeta
    c.appchainID = appchainID
    c.name = fabricConfig.Name
    c.outMeta = m
    c.ticker = time.NewTicker(2 * time.Second)
    c.done = done

    return nil
}

4.3 consumer

consumer 负责监听区块链上的由跨链合约抛出的跨链事件以及和调用chaincode。

我们新建 ./consumer.go 文件

type Consumer struct {
   eventClient     *event.Client
   meta            *ContractMeta
   msgH            MessageHandler
   channelProvider context.ChannelProvider
   ChannelClient   *channel.Client
   registration    fab.Registration
   ctx             chan bool
}

• eventClient：fabric gosdk提供的事件Client；

• meta Fabric：相关的参数信息；

• msgH：事件handler，在监听到指定事件之后负责处理的函数；

• channelProvider：fabric gosdk提供的和chaincode交互；

• ChannelClient：fabric gosdk 提供的和调用chaincode的对象；

• registeration：fabric gosdk 提供的订阅特定事件的对象；

• ctx：用来结束consumer的goroutine。

4.4 Event

由于在Fabric上抛出的事件内容是可以自定义的，而跨链请求要在跨链平台上传递的话，需要使用IBTP包，所以我们需要一定的代码来执行这种转换。

我们新建 ./event.go 文件

type Event struct {
    Index     uint64   `json:"index"`
    DstFullID string   `json:"dst_full_id"`
    SrcFullID string   `json:"src_full_id"`
    Encrypt   bool     `json:"encrypt"`
    CallFunc  CallFunc `json:"call_func"`
    CallBack  CallFunc `json:"callback"`
    RollBack  CallFunc `json:"rollback"`
}

Event结构也是自定义的，需要和在你的跨链合约中抛出的事件结构一致。一个跨链交易事件，一般来说需要指定目标应用链的ID DstFullID，目标应用链上智能合约服务ID（Fabric上的chaincode没有合约地址）SrcFullID，这次跨链交易的发起方服务ID,Encrypt是否要求加密，CallFunc，跨链调用的函数及参数， 是否有跨链调用之后要执行的回调函数及参数 CallBack，是否有跨链调用之后要执行的回滚函数及参数 RollBack。

4.5 SubmitIBTP

该接口主要负责将其他链发送过来的IBTP包解析并构造成当前目的链的交易，发送到目的链的跨链合约中。 如果来源链要求将本链调用合约的结果返回的话，还需要构造相应的IBTP回执发回来源链。

func (c *Client) SubmitIBTP(from string, index uint64, serviceID string, ibtpType pb.IBTP_Type, content *pb.Content, proof *pb.BxhProof, isEncrypted bool) (*pb.SubmitIBTPResponse, error) {
    ret := &pb.SubmitIBTPResponse{Status: true}

    _, resp, err := c.InvokeInterchain(from, index, serviceID, uint64(ibtpType), content.Func, content.Args, uint64(proof.TxStatus), proof.MultiSign, isEncrypted)
    if err != nil {
        ret.Status = false
        ret.Message = fmt.Sprintf("invoke interchain foribtp to call %s: %w", content.Func, err)
        return ret, nil
    }
    ret.Status = resp.OK
    ret.Message = resp.Message

    return ret, nil
}

5. 编译你的Plugin

我们采用GO语言提供的插件模式，实现Pier对于你编写的Plugin的动态加载。

MacOS和Linux平台：

运行下面的命令，能够得到 your_plugin.so文件。

$ cd ${YOUR_PROJECT_PATH}
$ go build --buildmode=plugin -o your_plugin.so ./*.go

将你编写的动态链接文件，放到Pier配置文件夹下，配合我们提供的Pier，就能接入到跨链平台来。