【无标题】

# 多异构链互操作架构集成方案和集成支持-部署手册

注：最好将源码放置在同一目录下，例如`Cross-chain`，否则可能涉及到路径修改问题；`CrossChainTest`目录可拷贝至`CrossChainHub/hubPeer/CrossChainListener`下

## 一、系统环境搭建

### 1.1 更新系统环境

```shell
sudo apt-get update
sudo apt-get upgrade
```

### 1.2 安装Go语言环境

+ 下载go语言安装包

```shell
wget https://dl.google.com/go/go1.18.1.linux-amd64.tar.gz
sudo tar -xvf go1.18.1.linux-amd64.tar.gz
sudo mv go /usr/local
mkdir go
mkdir go/src
```

+ 配置go语言环境变量

```shell
vim ~/.bashrc
# 添加如下内容
export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export PATH=$GOPATH/bin:$GOROOT/bin:$PATH
export HUBPATH=path/to/CrossChainHub
# 保存更改
source ~/.bashrc
# 确认是否配置成功
go version
```

### 1.3 安装docker与docker-compose

```shell
# 卸载旧版本
sudo apt-get remove docker docker-engine docker.io containerd runc
# 更新apt软件包索引
sudo apt-get update
# 安装软件包以允许apt通过HTTPS使⽤存储库
sudo apt-get install \
apt-transport-https \
ca-certificates \
curl \
gnupg-agent \
software-properties-common
# 添加Docker的官⽅GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
# 验证密钥
sudo apt-key fingerprint 0EBFCD88
# X86_64/amd64平台下设置存储库
sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) \
stable"
# 安装docker
sudo apt-get install docker-ce docker-ce-cli containerd.io
# 安装docker-compose
# 下载运⾏⽂件
# https://github.com/docker/compose/releases/download/1.28.6/docker-compose-Linux-x86_64
sudo curl -L "https://github.com/docker/compose/releases/download/1.28.6/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# 配置权限
sudo chmod +x /usr/local/bin/docker-compose
# 查看版本信息
docker version
docker-compose version
```

### 1.4 配置代理

```shell
# 设置go代理
go env -w GO111MODULE="on"
go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/
# 设置docker代理
vim /etc/docker/daemon.json
# 添加如下内容
{
  "registry-mirrors": ["https://registry.docker-cn.com","https://6kx4zyno.mirror.aliyuncs.com","http://hub-mirror.c.163.com","https://docker.mirrors.ustc.edu.cn"]
}
# 重启生效
systemctl daemon-reload 
systemctl restart docker
```

## 二、中继链搭建

通过GitHub或者拷贝的方式拷贝项目文件到服务器，根据不同需要部署不同的跨链服务

### 2.1 中继链部署

在根目录`/root`下执行

#### 2.1.1 拷贝文件至GOPATH

```shell
cp -r go/src/PeerApp/ $GOPATH
```

#### 2.1.2 拉取所需镜像

```shell
cd go/src/PeerApp/fixtures/
./pull_images.sh
```

执行`pull_images.sh`拉取镜像，最终在控制台打印所有镜像如下：

```shell
===> List out hyperledger docker images
hyperledger/fabric-tools    1.4.3   18ed4db0cd57  2 years ago  1.55GB
hyperledger/fabric-tools    latest   18ed4db0cd57  2 years ago  1.55GB
hyperledger/fabric-ca      1.4.3   c18a0d3cc958  2 years ago  253MB
hyperledger/fabric-ca      latest   c18a0d3cc958  2 years ago  253MB
hyperledger/fabric-ccenv    1.4.3   3d31661a812a  2 years ago  1.45GB
hyperledger/fabric-ccenv    latest   3d31661a812a  2 years ago  1.45GB
hyperledger/fabric-orderer   1.4.3   b666a6ebbe09  2 years ago  173MB
hyperledger/fabric-orderer   latest   b666a6ebbe09  2 years ago  173MB
hyperledger/fabric-peer     1.4.3   fa87ccaed0ef  2 years ago  179MB
hyperledger/fabric-peer     latest   fa87ccaed0ef  2 years ago  179MB
hyperledger/fabric-zookeeper  0.4.15   20c6045930c8  3 years ago  1.43GB
hyperledger/fabric-zookeeper  latest   20c6045930c8  3 years ago  1.43GB
hyperledger/fabric-kafka    0.4.15   b4ab82bbaf2f  3 years ago  1.44GB
hyperledger/fabric-kafka    latest   b4ab82bbaf2f  3 years ago  1.44GB
hyperledger/fabric-couchdb   0.4.15   8de128a55539  3 years ago  1.5GB
hyperledger/fabric-couchdb   latest   8de128a55539  3 years ago  1.5GB
```

#### 2.1.3 编译Hub-CA镜像

本地编译镜像

```shell
cd go/src/PeerApp/Superchain/myCA
docker build -t hub-fabric-ca .
```

#### 2.1.4 启动Hyperledger Fabric中继链

+ 进入`go/src/PeerApp/Superchain/myCA/SuperListener`目录，编译中继链所需的两个监听器程序，分别执行`go build -o superListener main.go`以及`go build credit.go`
+ 修改`bypn.sh`中的相对路径
+ 启动中继链

```shell
cd go/src/PeerApp/Superchain
./bypn.sh up
```

通过脚本`bypn.sh`自动容器化部署Hyperledger Fabric中继链及其链码

+ 中继链启动完成
  + 两个监听器程序启动，产生相应日志
  + `CrossChainHub`目录下得到中继链`mychannel.block`

#### 2.1.5 配置跨链网络

+ 修改`go/src/PeerApp/FabricSDK/superchainConfig.yaml`，将其中的IP地址换为部署中继链的服务器IP地址

#### 2.1.6 初始化跨链节点信息

+ 生成跨链节点证书：默认业务链各自持有10个跨链节点，例如Fabric节点序号为3-12，Fisco BCOS节点序号为13-22

  + 目录`CrossChainHub\hubPeer\super-crypto-config\peerOrganizations\org1.superchain.com\users`下存放了证书，如果数量不满足要求可以通过`cryptogen`工具补充

    + 证书数量可以修改`crypto-config.yaml`定义

    ```yaml
    Template:
        Count: 140 # peer节点数量
        # Start: 5
        # Hostname: {{.Prefix}}{{.Index}} # default
        # ---------------------------------------------------------------------------
        # "Users"
        # ---------------------------------------------------------------------------
        # Count: The number of user accounts _in addition_ to Admin
        # cryptogen extend --config=./crypto-config.yaml
        # ---------------------------------------------------------------------------
        Users:
        Count: 12000 # 用户数量，至少大于节点数量
    ```

    + 通过`cryptogen`补充

    ```shell
    # 按照crypto-config.yaml补充证书
    cd go\src\PeerApp\Superchain
    ./cryptogen extend --config=./crypto-config.yaml
    ```

  + 补充后的证书会保存在`go\src\PeerApp\Superchain\crypto-config`目录下，拷贝该目录替换`CrossChainHub\hubPeer\super-crypto-config`

+ 初始化节点路由：手动预先配置
  + 执行节点路由初始化脚本`go run CrossChainHub/hubPeer/CrossChainListener/CrossChainTest/ctl-manualInitRoute.go`
  + 按需配置业务链ID和IP地址、跨链路由

+ 在`~/CrossChainHub/hubPeer`目录下检查是否存在如下文件：`chainID`,`nodeBhv`,`nodeMode`,`root.pem`
  + chainID是上一步对应业务链的链ID
  + root.pem是中继链根证书
  + nodeBhv和nodeMode可以控制节点行为，默认填入`normal`即可，无需修改


### 2.2 Hyperledger Fabric部署

#### 2.2.1 拷贝文件至GOPATH

```shell
cp -r Cross-chain/go/src/PeerApp/ $GOPATH
```

#### 2.2.2 拉取所需镜像

```shell
cd go/src/PeerApp/fixtures/
./pull_images.sh
```

执行`pull_images.sh`拉取镜像，最终在控制台打印所有镜像如下：

```shell
===> List out hyperledger docker images
hyperledger/fabric-tools    1.4.3   18ed4db0cd57  2 years ago  1.55GB
hyperledger/fabric-tools    latest   18ed4db0cd57  2 years ago  1.55GB
hyperledger/fabric-ca      1.4.3   c18a0d3cc958  2 years ago  253MB
hyperledger/fabric-ca      latest   c18a0d3cc958  2 years ago  253MB
hyperledger/fabric-ccenv    1.4.3   3d31661a812a  2 years ago  1.45GB
hyperledger/fabric-ccenv    latest   3d31661a812a  2 years ago  1.45GB
hyperledger/fabric-orderer   1.4.3   b666a6ebbe09  2 years ago  173MB
hyperledger/fabric-orderer   latest   b666a6ebbe09  2 years ago  173MB
hyperledger/fabric-peer     1.4.3   fa87ccaed0ef  2 years ago  179MB
hyperledger/fabric-peer     latest   fa87ccaed0ef  2 years ago  179MB
hyperledger/fabric-zookeeper  0.4.15   20c6045930c8  3 years ago  1.43GB
hyperledger/fabric-zookeeper  latest   20c6045930c8  3 years ago  1.43GB
hyperledger/fabric-kafka    0.4.15   b4ab82bbaf2f  3 years ago  1.44GB
hyperledger/fabric-kafka    latest   b4ab82bbaf2f  3 years ago  1.44GB
hyperledger/fabric-couchdb   0.4.15   8de128a55539  3 years ago  1.5GB
hyperledger/fabric-couchdb   latest   8de128a55539  3 years ago  1.5GB
```

#### 2.2.3 配置跨链网络

+ 修改`CrossChainHub/hubPeer/CrossChainListener/CCListener/CrossChainConfig/FabricHub-template.json`，将`MY_IP`替换为部署Fabric的服务器IP地址，`SUPER_IP`替换为部署中继链的IP地址
+ 修改`CrossChainHub/hubPeer/CrossChainListener/CCListener/CrossChainConfig/FabricHub-template.json`，将`myIP替换为部署Fabric的服务器IP地址`

#### 2.2.4 启动Hyperledger Fabric

```shell
cd go/src/PeerApp/fixtrues
./bypn.sh up
```

通过脚本`bypn.sh`自动容器化部署Hyperledger Fabric及其链码

#### 2.2.5 初始化Hyperledger Fabric链码数据

+ `fabricTestInit.go`会初始化链ID，并从中继链下载根证书，根据配置的链ID对应修改脚本中参数
+ 脚本还会初始化一些业务合约，可按需修改

````go
go run fabricTestInit.go 0/1
````

### 2.3 Fisco BCOS部署

#### 2.3.1 环境准备

```shell
# 安装依赖
sudo apt install -y openssl curl
# 创建操作目录
cd ~ && mkdir -p fisco && cd fisco
# 下载脚本
curl -#LO https://github.com/FISCO-BCOS/FISCO-BCOS/releases/download/v2.9.1/build_chain.sh && chmod u+x build_chain.sh
# 如果上述下载过慢，使用如下指令
curl -#LO https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/FISCO-BCOS/FISCO-BCOS/releases/v2.9.1/build_chain.sh && chmod u+x build_chain.sh
```

#### 2.3.2 Fisco BCOS链部署

在`~/fisco`目录下执行如下命令，其中`[服务器IP]`需要替换为部署机器IP

```shell
bash build_chain.sh -l [服务器IP]:4 -p 30300,20200,8545
```

#### 2.3.3 Fisco BCOS链启动

```shell
# 进入链节点目录
cd ~/fisco/nodes/[服务器IP]
# 执行启动脚本
./start_all.sh
```

#### 2.3.4 配置跨链网络

+ 修改`CrossChainHub/hubPeer/CrossChainListener/CCListener/CrossChainConfig/FiscoHub-template.json`，将`MY_IP`替换为部署FiscoBCOS的服务器IP地址，`SUPER_IP`替换为部署中继链的IP地址
+ 修改`CrossChainHub/hubPeer/CrossChainListener/CCListener/CrossChainConfig/FiscoHub-template.json`，将`myIP替换为部署FiscoBCOS的服务器IP地址`

#### 2.3.5 Fisco BCOS智能合约部署

首先获取Fisco BCOS go-sdk，并拷贝sdk所需证书文件，配置go-sdk

```shell
# 克隆仓库
cd ~/fisco
git clone -b master-FISCO-BCOS-v2 git@github.com:FISCO-BCOS/go-sdk.git
# 拷贝证书
cp nodes/[服务器IP]/sdk/* go-sdk
# 拷贝config.toml至Interface/FiscoInterface/serverResource目录
# 为证书和密钥文件路径添加前缀../../Interfaces/FiscoInterface/serverResource
# 配置go-sdk
cd go-sdk
go mod tidy
```

完成后`FiscoInterface/serverResource`目录应当呈现如下结构：

```shell
.
├── ca.crt
├── config.toml
├── sdk.crt
├── sdk.key
└── tomlop.go
```

`config.toml`配置了FiscoBCOS的网络信息，一般情况只需配置`CAFile,Cert,Key,NodeURL,KeyFile`这几项

```toml

[Network]
#type rpc or channel
Type="channel"
CAFile="../../Interfaces/FiscoInterface/serverResource/ca.crt"
Cert="../../Interfaces/FiscoInterface/serverResource/sdk.crt"
Key="../../Interfaces/FiscoInterface/serverResource/sdk.key"
# if the certificate context is not empty, use it, otherwise read from the certificate file
# multi lines use triple quotes
CAContext=''''''
KeyContext=''''''
CertContext=''''''

[[Network.Connection]]
NodeURL="172.16.65.156:20200"
GroupID=1
# [[Network.Connection]]
# NodeURL="172.16.65.1516:20200"
# GroupID=2

[Account]
# only support PEM format for now
KeyFile="../../Interfaces/FiscoInterface/serverResource/.ci/0x1c27b94554f70b375129a7ef6857a2af73c8dfa1.pem"

[Chain]
ChainID=1
SMCrypto=false

[log]
Path="./"
```

之后运行`Cross-chain/fisco`文件夹下的`initFiscoBCOS.sh`脚本，指定Fisco BCOS链安装位置和服务器IP，如不成功可参考[FiscoBCOS合约开发样例](https://fisco-bcos-documentation.readthedocs.io/zh-cn/latest/docs/sdk/go_sdk/contractExamples.html)，利用已有的合约源码进行部署

```shell
cd /fisco
./initFiscoBCOS.sh ~/fisco [服务器IP] # 可能需要编译每个合约的deploy.go
```

#### 2.3.6 初始化Fisco BCOS智能合约数据

+ `fiscoTestInit.go`会初始化链ID，并从中继链下载根证书，根据配置的链ID对应修改脚本中参数
+ 脚本还会初始化一些业务合约，可按需修改

````go
go run fiscoTestInit.go 0/1
````

# 多异构链互操作架构集成方案和集成支持-使用手册

以某一条业务链为例，启动跨链节点服务

## 一、CrossChainHub启动

1. 编译跨链节点程序，执行编译脚本`CrossChainHub\hubPeer\CrossChainListener\CCListener\buildCCNode.sh`
1. 编译跨链节点镜像

```shell
# 本地编译
cd $HUBPATH/hubPeer
docker build -t hub-fabric-peer .
```

3. 配置跨链节点文件（部署链时如已配置可忽略）

通过`[链名][序号]`的方式区分不同业务链的不同跨链节点

以Fabric为例，跨链节点的配置文件如下，例如`$HUBPATH/hubConfig-Fabric.json`

```json
{
    "PEER_NUM": "peer3",
    "PEER_ADDR_PORT": "11051",
    "PEER_CC_PORT": "11052",
    "PEER_OPEN_PORT": "11053",
    "MY_IP": "172.16.65.157",
    "SUPER_IP": "172.16.65.152",
    "OUT_PORT": "8083",
    "REDIS_PORT": "6379",
    "CERT_HTTP": "9093",
    "CERT_HTTPS": "8443"
}
```

其中`PEER_NUM`代表本链所部署的10个Hub的起始节点在中继链中的序号，格式为`peer[number]`；`PEER_ADDR_PORT`,`PEER_CC_PORT`和`PEER_OPEN_PORT`一般不需要作修改，它是Hub Docker所监听的端口，启动脚本将保证端口不产生冲突；`MY_IP`代表本机IP；`SUPER_IP`代表中继链所在服务器IP；`OUT_PORT`代表本Hub对应外部程序监听的端口；`REDIS_PORT`代表Hub中redis映射到本机的端口，启动脚本将保证端口不产生冲突； `CERT_HTTP`与`CERT_HTTPS`代表本Hub作为一级Hub时为二级Hub授权时使用的端口

2. 启动业务链上的跨链节点容器

运行启动脚本`CrossChainHub\startAll.sh`，参数为`链名`和启动的节点数量`n`，例如启动Fabric链的全部10个跨链节点

```shell
./start_all.sh Fabric 10
```

`start_all.sh`脚本在启动容器的同时也会启动跨链服务，因此脚本只需运行一次即可

启动跨链服务的同时，每个跨链节点对应会执行一个outProcessor，称为外部程序；外部程序主要与跨链节点docker中的redis进行交互，同时对外充当跨链网关的角色，监听相应端口

3. 启动/停止跨链服务

执行停启脚本`operate.sh`可以停启跨链节点容器上的跨链服务，包括四个参数

```shell
./operate.sh start/stop [链名] 节点起始序号 节点结束序号
```

例如停止Fabric链3号到8号节点上的跨链服务，则命令为`./operate.sh stop Fabric 3 8`

`operate.sh`脚本不会停止节点容器，而是停止容器内的跨链服务

## 二、发起单链跨链调用

单链跨链调用指由链A向链B发起跨链请求，只在B链上执行操作

Fabric和FiscoBCOS的相关接口可以在`CrossChainHub/hubPeer/Interfaces/FabricInterface`中和`CrossChainHub/hubPeer/Interfaces/FiscoInterface`中分别查看，其中`CCRequestForServer.go`对应与跨链管理合约的交互，主要功能如下：

+ InitCCRequestClient：创建客户端
+ SingleCCRequest：单链跨链调用
+ QueryCCResult：查询跨链结果
+ SetCCResult：上传跨链结果
+ CallWithParam：通过跨链管理合约调用其他合约
+ CreateCallTree：构造双链跨链调用树
+ DoubleCCRequest：双链跨链调用
+ ExecuteCall：本链上根据调用树执行双链跨链调用
+ GetChainID：获取链ID
+ SetChainID：设置链ID

发起跨链调用可以参考`FabricBMTest.go`，利用Fabric Go SDK向跨链管理合约提交跨链请求

```go
// 单链跨链基本接口
func Fabric2OtherSingle(fabCli *FabricClient.Client, account string, toChainID string, address string, operation string, arguments []string) (bool, []byte) {

    ccrType := 1
    fromChainID := chainIDCFG["Fabric"][0]

    requestID, timestamp := util.GenFabricRequestID(account, ccrType, fromChainID, toChainID, address, operation, arguments)
    ok, txhash, retMsg := FabricInterface.SingleCCRequest(fabCli, requestID, ccrType, fromChainID, toChainID, address, timestamp, operation, arguments)
    if ok {
        fmt.Printf("[Hyperledger Fabric] 发起单链跨链交易 <%s> 成功, 交易哈希: %s, %s\n\n", requestID, txhash, retMsg)
    } else {
        fmt.Printf("[Hyperledger Fabric] 发起单链跨链交易 <%s> 失败, 交易哈希: %s, %s\n\n", requestID, txhash, retMsg)
    }

    time.Sleep(time.Second * 30)
    ok, payload := FabricInterface.QueryCCResult(fabCli, requestID)
    return ok, payload

}
```

一个跨链请求的基本格式如下：

```go
type CCRequest struct {
    RequestID   string   `json:"requestid"` // 跨链请求id
    CcrType     int      `json:"ccrtype"` // 跨链请求类型
    FromChainID string   `json:"fromchainid"` // 来源链ID
    ToChainID   string   `json:"tochainid"` // 目的链ID
    Ccaddress   string   `json:"ccaddress"` // 目的链合约地址
    Timestamp   string   `json:"timestamp"` // 时间戳
    Operation   string   `json:"operation"` // 跨链操作
    Arguments   string   `json:"arguments"` // 跨链参数
}
```

## 三、发起双链跨链调用

双链跨链调用指由链A向链B发起跨链请求，在A、B链上都执行相应操作

发起双链跨链调用可以参考，与单链跨链调用不同的是，双链跨链调用先创建一个调用树，同时锁定A链上的合约，当B链执行完成后再执行A链合约，最后释放锁定，其余过程与单链跨链调用一致

```go
// 双链跨链基本接口
func Fabric2OtherDouble(fabCli *FabricClient.Client, account string, toChainID string, address string, operation string, arguments []string,
    nodeNum int, indexes []string, chainCodeNames []string, channelNames []string, itfAndParams []string, parent []string, children []string) (bool, string, []byte) {

    ccrType := 2
    fromChainID := chainIDCFG["Fabric"][0]

    requestID, timestamp := util.GenFabricRequestID(account, ccrType, fromChainID, toChainID, address, operation, arguments)

    ok, retMsg := FabricInterface.CreateCallTree(fabCli, requestID, nodeNum, indexes, chainCodeNames, channelNames, itfAndParams, parent, children)
    if ok {
        fmt.Printf("[Hyperledger Fabric] 双链跨链请求 <%s> 创建调用树成功, %s\n\n", requestID, retMsg)
    } else {
        fmt.Printf("[Hyperledger Fabric] 双链跨链请求 <%s> 创建调用树失败, %s\n\n", requestID, retMsg)
    }

    ok, txhash, retMsg := FabricInterface.DoubleCCRequest(fabCli, requestID, ccrType, fromChainID, toChainID, address, timestamp, operation, arguments)
    if ok {
        fmt.Printf("[Hyperledger Fabric] 发起双链跨链交易 <%s> 成功, 交易哈希: %s, %s\n\n", requestID, txhash, retMsg)
    } else {
        fmt.Printf("[Hyperledger Fabric] 发起双链跨链交易 <%s> 失败, 交易哈希: %s, %s\n\n", requestID, txhash, retMsg)
    }

    time.Sleep(time.Second * 30)
    ok, payload := FabricInterface.QueryCCResult(fabCli, requestID)

    return ok, requestID, payload
}
```

## 四、查看中继链记录

因为中继链采用Fabric实现，故可以通过Go-SDK调用中继链链码完成

可以在`CrossChainHub/hubPeer/Interfaces/HubInterface`中查看接口实现，主要功能如下：

+ CertForSuperchain.go

  + CreateSuperClient：创建中继链客户端

  + RegisterChainID：注册链ID

  + GetRootCert：获取中继链根证书

  + LogCCRequest：登记跨链请求
  + UpdateCCRStatus：更新跨链请求结果
  + ApplyLicense：申请跨链许可
  + GetLicense：获取跨链许可
  + GetCCRequest：查询单一跨链请求详细信息
  + ListCCRequest：查询所有跨链请求
  + GetRoutes：查询某条链的路由信息
  + UpdateRoute：更新路由信息
  + ConfirmCCRequest：中继链确认跨链请求完成