Skip to content

应用链插件开发

Jump to bottom
jzhe edited this page Oct 26, 2020 · 1 revision

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

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

开发要求

  • 安装 go1.13+

  • 设置好 GOPATH等环境

教程章节

  1. 重要概念

  2. Plugin接口

  3. 程序目标

  4. 开始编写程序

  5. 编译你的Plugin

重要概念

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

**跨链请求：**如果有两条区块链A和B，A链需要向B链发起任何操作，需要按照IBTP规则向中继链发出一个请求包，我们称之为跨链请求A->B。

IBTP包：满足IBTP的一个package，跨链请求都需要通过IBTP包进行。

**来源链：**在跨链请求A->B中，A即为来源链。

**目的链：**在跨链请求A->B中，B即为目的链。

Plugin接口

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

type Client interface {
   // 启动Plugin服务的接口
   Start() error

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

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

   // Plugin 负责执行其他链过来的跨链请求，Pier调用SubmitIBTP提交收到的跨链请求。[][]byte 为执行跨链请求的结果。
   SubmitIBTP(*pb.IBTP) ([][]byte, error)
   
   // GetOutMessage 负责在跨链合约中查询历史跨链请求。查询键值中to指定目的链，idx指定序号，查询结果为以Plugin负责的区块链作为来源链的跨链请求。
   GetOutMessage(to string, idx uint64) (*pb.IBTP, error)

   // GetInMessage 负责在跨链合约中查询历史跨链请求。查询键值中from指定来源链，idx指定序号，查询结果为以Plugin负责的区块链作为目的链的跨链请求。
   GetInMessage(from string, idx uint64) ([][]byte, error)

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

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

   // GetCallbackMeta 是获取跨链请求相关的Meta信息的接口。以Plugin负责的区块链为来源链的一系列跨链请求的序号信息。如果Plugin负责A链，则A可能和多条链进行跨链，如A->B:3; A->C:5；同时由于跨链请求中支持回调操作，即A->B->A为一次完整的跨链操作，我们需要记录回调请求的序号信息，如A->B->:2; A->C—>A:4。返回的map中，key值为目的链ID，value对应到该目的链最新的带回调跨链请求的序号，如{B:2, C:4}。（注意 CallbackMeta序号可能和outMeta是不一致的，这是由于由A发出的跨链请求部分是没有回调的）
   GetCallbackMeta() (map[string]uint64, error)

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

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

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

程序目的

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

开始编写你的程序

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

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

Client对象

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

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

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

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

type Client struct {
   meta     *ContractMeta
   consumer *Consumer
   eventC   chan *pb.IBTP
   pierId   string
   name     string
}

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"`
}

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

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

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

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

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

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

func NewClient(configPath, pierId string, extra []byte) (client.Client, error) {
   eventC := make(chan *pb.IBTP)
   // read config from files
   fabricConfig, err := UnmarshalConfig(configPath)
   if err != nil {
      return nil, fmt.Errorf("unmarshal config for plugin :%w", err)
   }

   // some basic configs about your chaincode
   c := &ContractMeta{
      EventFilter: fabricConfig.EventFilter,
      Username:    fabricConfig.Username,
      CCID:        fabricConfig.CCID,
      ChannelID:   fabricConfig.ChannelId,
      ORG:         fabricConfig.Org,
   }

   // handler for listening on inter-chain events posted on your Fabric
   mgh, err := newFabricHandler(c.EventFilter, eventC, pierId)
   if err != nil {
      return nil, err
   }

   csm, err := NewConsumer(configPath, c, mgh)
   if err != nil {
      return nil, err
   }

   return &Client{
      consumer: csm,
      eventC:   eventC,
      meta:     c,
      pierId:   pierId,
      name:     fabricConfig.Name,
   }, nil
}

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的 gorountine

Event

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

我们新建 ./event.go 文件

type Event struct {
   Index         uint64 `json:"index"`
   DstChainID    string `json:"dst_chain_id"`
   SrcContractID string `json:"src_contract_id"`
   DstContractID string `json:"dst_contract_id"`
   Func          string `json:"func"`
   Args          string `json:"args"`
   Callback      string `json:"callback"`
   Proof         []byte `json:"proof"`
   Extra         []byte `json:"extra"`
}

Event结构也是自定义的，需要和在你的跨链合约中抛出的事件结构一致。一个跨链交易事件，一般来说需要指定目标应用的ID DstChainID，目标应用链上智能合约的地址或者ID（Fabric上的chaincode没有合约地址）DstContractID，这次跨链交易的发起者的合约地址SrcContractID，跨链调用的函数名 Func，该函数的参数 Args，是否有跨链调用之后要执行的回调函数 Callback，为了该应用链上对于该事件的证明 Proof，用户课自定义的部分 Extra。

读取配置

Plugin的配置文件路径是通过NewClient的方法动态传入的，这意味着你可以方便的修改关于你的区块链的参数信息。我们新建文件 ./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",
      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
}

编译你的Plugin

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

MacOS和Linux平台：

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

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

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

Clone this wiki locally