Skip to content

caict-4iot-dev/AntChainBridgePluginSDK

BranchesTags
 
 

Repository files navigation

am logo

AntChain Bridge Plugin SDK

pull requests welcome badge Language GitHub contributors License

介绍

AntChain Bridge将跨链互操作解释为两个层次：通信和可信，即跨链的目标在于实现区块链实体之间的可信通信。

在AntChain Bridge的架构中，中继需要与区块链进行交互，而异构链的通信协议各式各样，无法统一适配，因此AntChain Bridge抽象出了区块链桥接组件（Blockchain Bridge Component, BBC），来解决区块链和跨链网络的通信问题。

每种异构链要接入AntChain Bridge跨链网络，都需要实现一套标准的区块链桥接组件，可以分为链上和链下两部分，包括链下插件和系统合约。链下插件需要基于SDK完成开发，链上部分则通常是智能合约，要求实现特定的接口和逻辑，为降低开发难度，我们提供了Solidity版本的实现。

AntChain Bridge为开发者提供了SDK、手册和系统合约模板，来帮助开发者完成插件和合约的开发。同时，AntChain Bridge提供了插件服务（PluginServer）来运行插件，插件服务是一个独立的服务，具备插件管理和响应中继请求的功能。

在当前的工程实现中，BBC链下部分是以插件的形式实现的。AntChain Bridge实现了一套SDK，通过实现SDK中规定的接口（SPI），经过简单的编译，即可生成插件包。插件服务（PluginServer, PS）可以加载BBC链下插件，详情可以参考插件服务的介绍文档。

区块链域名服务（BlockChain Domain Name Service, BCDNS）为AntChain Bridge跨链网络提供身份、路由、信任管理等服务，在v0.2.0版本之后，加入了BCDNS模块以及其他数据结构，比如区块链域名证书等类型和工具，并在antchain-bridge-bcdns中增加了基于星火链网的BCDNS服务的客户端实现，该BCDNS服务由中国信息通信研究院开发支持，详情请见。

在SDK中抽象了BCDNS服务的接口IBlockChainDomainNameService，描述了BCDNS应该提供的功能，目前仅支持官方实现的BCDNS，支持的类型可见。

以下介绍了基于SDK的一个集成架构：

SDK共有五个部分，包括：

  • antchain-bridge-commons：包含很多工具方法和数据结构，帮助BBC实现快速开发；

  • antchain-bridge-plugin-lib：BBC插件化的依赖库，给出一个注解@BBCService，帮助插件开发者可以快速完成插件构建；

  • antchain-bridge-plugin-manager：插件的管理库，提供插件的加载、生命周期管理等能力，插件服务依赖于这个库；

  • antchain-bridge-spi：主要包含了接口IBBCService，描述了一个BBC实现类应该有的功能，开发者只要依次实现接口即可，详细接口介绍请见；

  • antchain-bridge-bcdns：主要包含了接口IBlockChainDomainNameService，描述了一个BCDNS客户端应该有的功能，目前仅支持星火链网（BIF）的BCDNS客户端实现，详细使用可以参考wiki中“如何实现跨链”的内容；

构建

*在开始之前，请您确保安装了maven和JDK，这里推荐使用openjdk-1.8版本

本地安装

在项目根目录下，直接使用maven编译即可：

mvn install -Dmaven.test.skip=true

或者在release页面找到适合的版本并下载到本地，解压之后，在根目录下，运行脚本完成SDK的安装：

./install_sdk.sh

提示信息如下，代表安装完成：

    ___            __   ______ __            _           ____         _      __
   /   |   ____   / /_ / ____// /_   ____ _ (_)____     / __ ) _____ (_)____/ /____ _ ___
  / /| |  / __ \ / __// /    / __ \ / __ `// // __ \   / __  |/ ___// // __  // __ `// _ \
 / ___ | / / / // /_ / /___ / / / // /_/ // // / / /  / /_/ // /   / // /_/ // /_/ //  __/
/_/  |_|/_/ /_/ \__/ \____//_/ /_/ \__,_//_//_/ /_/  /_____//_/   /_/ \__,_/ \__, / \___/
                                                                            /____/        

[ INFO ]_[ 2023-12-27 17:40:42.170 ] : successful to install antchain-bridge-commons-0.2.0.jar
[ INFO ]_[ 2023-12-27 17:40:44.170 ] : successful to install antchain-bridge-spi-0.2.0.jar
[ INFO ]_[ 2023-12-27 17:40:45.170 ] : successful to install antchain-bridge-plugin-lib-0.2.0.jar
[ INFO ]_[ 2023-12-27 17:40:47.170 ] : successful to install antchain-bridge-plugin-manager-0.2.0.jar
[ INFO ]_[ 2023-12-27 17:40:48.170 ] : successful to install antchain-bridge-bcdns-0.2.0.jar
[ INFO ]_[ 2023-12-27 17:40:48.170 ] : success

这样，SDK的Jar包就被安装在本地了。

然后，可以通过在maven的pom.xml配置依赖就可以了，比如下面一段配置，${antchain-bridge.sdk.version}为当前仓库的版本号，可以在项目目录的po m.xml看到。

<dependency>
    <groupId>com.alipay.antchain.bridge</groupId>
    <artifactId>antchain-bridge-plugin-lib</artifactId>
    <version>${antchain-bridge.sdk.version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.antchain.bridge</groupId>
    <artifactId>antchain-bridge-plugin-manager</artifactId>
    <version>${antchain-bridge.sdk.version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.antchain.bridge</groupId>
    <artifactId>antchain-bridge-spi</artifactId>
    <version>${antchain-bridge.sdk.version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.antchain.bridge</groupId>
    <artifactId>antchain-bridge-commons</artifactId>
    <version>${antchain-bridge.sdk.version}</version>
</dependency>
<dependency>
    <groupId>com.alipay.antchain.bridge</groupId>
    <artifactId>antchain-bridge-bcdns</artifactId>
    <version>${antchain-bridge.sdk.version}</version>
</dependency>

通过GitHub Package安装

参考这里配置您的maven，在setting.xml中配置上您的GitHub账号和Token。

在您的项目pom.xml中，配置上我们的repository：

<repositories>
    <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/AntChainOpenLab/*</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

这样您就可以导入上面的dependency来使用SDK。

快速开始

BBC插件

Testchain

Testchain是一个用于讲解如何开发BBC插件的demo工程，结合AntChain Bridge的文档，可以更好地理解BBC的开发过程。

详细的开发教程请参考本仓库的Wiki。

以太坊

基于SDK，我们开发了一个打通以太坊的BBC插件。

进入以太坊插件的路径下，可以看到以下文件：

# tree -L 4 .        
.
├── offchain-plugin
│   ├── README.md
│   ├── pom.xml
│   └── src
└── onchain-plugin
    ├── README.md
    └── solidity
        ├── scenarios
        │   └── nft_crosschain
        └── sys
            ├── AppContract.sol
            ├── AuthMsg.sol
            ├── SDPMsg.sol
            ├── interfaces
            └── lib
  • offchain-plugin工程下面，我们基于Web3j，实现了以太坊的BBC插件的链下部分；
  • onchain-plugin工程下面，主要分为两部分：
    • sys：包含以太坊的BBC链上部分，实现了AM、SDP等逻辑。
    • scenarios：本路径下的nft_crosschain中，我们实现了一套跨链桥方案，用于ERC1155资产的跨链。

详细操作请见。

EOS

基于SDK，我们提供了一个打通EOS链的BBC插件。

  • offchain-plugin工程下面实现了EOS的BBC插件的链下部分；
  • onchain-plugin工程下面，主要分为两部分：
    • 合约代码：合约代码放在路径下面，包含AM合约、SDP合约、Demo合约，详情请见。

详细操作请见。

Mychain

基于SDK我们给出了打通蚂蚁链（Mychain）的BBC插件，目前内部依赖发布中，发布之后即可编译使用。

BCDNS

跨链身份

BCDNS为AntChain Bridge提供了身份服务，通过签发各类身份证书，实现区块链域名申请、域名验证、Relayer互认等流程。

BCDNS会为AntChain Bridge提供域名证书、域名空间证书、Relayer证书、PTC证书和信任根证书。

证书结构介绍

证书的类型枚举可以参考代码，证书的基本结构可以参考代码。

整体类图如下：

classDiagram
direction LR
class CrossChainCertificateTypeEnum {
<<enumeration>>
  +  BCDNS_TRUST_ROOT_CERTIFICATE
  +  DOMAIN_NAME_CERTIFICATE
  +  RELAYER_CERTIFICATE
  +  PROOF_TRANSFORMATION_COMPONENT_CERTIFICATE
}

class AbstractCrossChainCertificate {
   CrossChainCertificateTypeEnum type
   String version
   String id
   ObjectIdentity issuer
   byte[] credentialSubject
   IssueProof proof
   long expirationDate
   long issuanceDate
}
class IssueProof {
   byte[] rawProof
   byte[] certHash
   String sigAlgo
   String hashAlgo
}

class ObjectIdentity {
  - byte[] rawId
  - ObjectIdentityType type
}
class ObjectIdentityType {
<<enumeration>>
  +  X509_PUBLIC_KEY_INFO
  +  BID
}

ObjectIdentity "1" *--> "type 1" ObjectIdentityType 
AbstractCrossChainCertificate "1" *--> "type 1" CrossChainCertificateTypeEnum 
AbstractCrossChainCertificate "1" *--> "proof 1" IssueProof 
AbstractCrossChainCertificate "1" *--> "issuer 1" ObjectIdentity 
AbstractCrossChainCertificate  -->  IssueProof
Loading

从上图，可以看到证书的类型，域名和域名空间证书，都作为DOMAIN_NAME_CERTIFICATE类型。

AbstractCrossChainCertificate为证书的主要实现，包含下列字段：

  • type：证书类型；
  • version：证书结构的版本号；
  • id：某一本证书的ID，由BCDNS签发时确定；
  • issuer：签发该证书的主体ID，使用类型ObjectIdentity表示，下文会有所介绍；
  • credentialSubject：持有该证书的主体信息，不同类型证书有不同的主体结构，下文会有所介绍；
  • proof：签发主体对该证书作出的证明，目前支持非对称密钥的签名；
  • expirationDate：该证书的超时的时间戳，以秒为单位。
  • issuanceDate：签发该证书的时间戳，以秒为单位。

主体结构介绍

上文中提到了主体ID类型ObjectIdentity，目前支持两种类型X509_PUBLIC_KEY_INFO和BID。

  • X509_PUBLIC_KEY_INFO

    该类型使用了X.509 Subject Public Key Info作为主体ID，在rawId字段中存放了encoded的X.509 Subject Public Key Info，详细可以参考RFC5280。

  • BID

    该类型使用了星火链的DID方案。星火标识BID(Blockchain-based Identifier, BID)，BID标识是基于W3C DID标准开发的新型分布式标识，任意实体可自主生成星火标识，在rawId字段中存放了encoded的BID。

证书的credentialSubject字段可以按照证书类型反序列化为不同的类型：

  • 域名主体

    classDiagram
direction LR
class DomainNameCredentialSubject {
   String version
   DomainNameTypeEnum domainNameType
   CrossChainDomain domainName
   CrossChainDomain parentDomainSpace
   ObjectIdentity applicant
   byte[] subject
}

class DomainNameTypeEnum {
<<enumeration>>
  +  DOMAIN_NAME
  +  DOMAIN_NAME_SPACE
}

DomainNameCredentialSubject "1" *--> "type 1" DomainNameTypeEnum
    Loading

    上图介绍了域名主体包含的字段：

    • version：该主体类型的版本号；
    • domainNameType：当前主体表达的类型，是域名的宣称还是域名空间的宣称；
    • domainName：域名或者域名空间的值；
    • parentDomainSpace：签发BCDNS的域名空间，规定根BCDNS的域名空间为空字符串，可见代码的ROOT_DOMAIN_SPACE；l
    • applicant：主体ID；
    • subject：序列化的主体身份，根据主体ID类型，如果主体ID是X509_PUBLIC_KEY_INFO，则为空，如果是BID类型，则为BID文档（BID Document）内容，subject的主要作用是保存主体的公钥内容，BID文档的使用较为简单，主要是使用publicKey字段；

  • 域名空间主体

    域名空间和域名的主体结构相同，只有domainNameType不同，为DOMAIN_NAME_SPACE。

    域名空间应当以点“.”开头，后接空间名字，比如‘’.web3“，如果是域名，则不应该以点开头。域名和域名空间的长度都不应该超过128字节，且建议使用小写英文字母表示，比如antchain.web3。

  • Relayer主体

    classDiagram
direction BT
class RelayerCredentialSubject {
   String version
   String name
   ObjectIdentity applicant
   byte[] subjectInfo
}
    Loading

    上图介绍了Relayer主体包含的字段：

    • version：该主体类型的版本号；
    • name：Relayer的名称，这里可以随意填写；
    • applicant：主体ID；
    • subject：序列化的主体身份；

    Relayer的运行需要依赖Relayer证书，详情请参考AntChain Bridge Relayer。

  • PTC证书

    classDiagram
direction LR
class PTCCredentialSubject {
   String version
	 String name
	 PTCTypeEnum type
   ObjectIdentity applicant
   byte[] subjectInfo
}

class PTCTypeEnum {
<<enumeration>>
  +  SIGNING_MACHINE
  +  BLOCKCHAIN
}

PTCCredentialSubject "1" *--> "type 1" PTCTypeEnum
    Loading

    证明转换服务（PTC）会为AntChain Bridge 提供异构链跨链消息存在性验证服务，以及提供背书证明，PTC需要向BCDNS申请身份并注册信任根，对每条链都会提供第三方区块链信任锚（TP-BTA），以供跨链中的接收链验证跨链消息证明（TP-Proof）。

    PTC将会在2024年进行开发并完成开源，目前计划支持多种类型的PTC，比如PTCTypeEnum中的签名机（SIGNING_MACHINE）、区块链（BLOCKCHAIN），区块链类型可以看作常见的中继链跨链方案。

  • 信任根证书

    classDiagram
direction BT
class BCDNSTrustRootCredentialSubject {
   String name
	 ObjectIdentity bcdnsRootOwner
   byte[] bcdnsRootSubjectInfo
}
    Loading

    最后是持有根域名的BCDNS信任根主体，上面字段包含主体的name，以及主体ID和主体信息。

    域名空间证书用于表示某个BCDNS持有该域名空间，该空间不可以是根空间，这些BCDNS为下级BCDNS，而根BCDNS为最高级BCDNS，比如当前的星火链BCDNS，上级BCDNS可以给下级签发域名空间证书，每个BCDNS可以签发自己空间的区块链域名。

序列化介绍

跨链证书的序列化使用了AntChain Bridge 提供的一个TLV序列化工具（使用介绍）。

跨链证书支持保存为PEM格式，证书对象可以通过CrossChainCertificateUtil转化至PEM格式，比如：

-----BEGIN BCDNS TRUST ROOT CERTIFICATE-----
AADZAQAAAAABAAAAMQEABAAAAHRlc3QCAAEAAAAAAwA7AAAAAAA1AAAAAAABAAAA
AQEAKAAAAGRpZDpiaWQ6ZWZiVGh5NXNiRzdQM21GVXAyRVdONW9RR1g2TFVHd2cE
AAgAAAChN2RlAAAAAAUACAAAACFrRWcAAAAABgDQAAAAAADKAAAAAAADAAAAYmlm
AQA7AAAAAAA1AAAAAAABAAAAAQEAKAAAAGRpZDpiaWQ6ZWZiVGh5NXNiRzdQM21G
VXAyRVdONW9RR1g2TFVHd2cCAHoAAAB7InB1YmxpY0tleSI6W3sidHlwZSI6IkVE
MjU1MTkiLCJwdWJsaWNLZXlIZXgiOiJiMDY1NjZhZjY2NWVlNTUwNjM1ZTk4Mzc1
YzdiMzg4NzZhMmNjMzFlM2E5ZDgxODk1N2U0NmEyNGEwZjI1YTc0YTQ0Y2NlIn1d
fQcAiAAAAAAAggAAAAAAAwAAAFNNMwEAIAAAALKKKxzUTalyw2vp96hOJ3TuDsNZ
/pjgltTL+ip2bsRNAgAHAAAARWQyNTUxOQMAQAAAAMsFd4D9Gf3hiIebiq5MFTpw
IV4AUtT9d+Y8gRK/kmNySzlJ32Shw3FNj8Uvy3yjBxjO6vKOWH5Jhu936zMWOgk=
-----END BCDNS TRUST ROOT CERTIFICATE-----

星火链网（BIF）BCDNS

目前SDK仅支持星火链网的BCDNS服务客户端，这里介绍其配置项和如何实例化该客户端。

首先介绍配置，代码可见，主要分为两部分，一部分certificationServiceConfig是用于和颁证服务通信、鉴权，另一部分chainConfig用于和星火链网交互。

{
	"certificationServiceConfig":{
		"authorizedKeyPem":"-----BEGIN PRIVATE KEY-----\nMFECAQEwB...WnSkTM4=\n-----END PRIVATE KEY-----\n",
		"authorizedPublicKeyPem":"-----BEGIN PUBLIC KEY-----\nMCowBQYDK2Vw...KDyWnSkTM4=\n-----END PUBLIC KEY-----\n",
		"authorizedSigAlgo":"Ed25519",
		"clientCrossChainCertPem":"-----BEGIN RELAYER CERTIFICATE-----\nAAAIA...DyLBh2ITiTQ4IVYlXkYjSBw==\n-----END RELAYER CERTIFICATE-----\n",
		"clientPrivateKeyPem":"-----BEGIN PRIVATE KEY-----\nMFECAQE...V+RqJKDyWnSkTM4=\n-----END PRIVATE KEY-----\n",
		"sigAlgo":"Ed25519",
		"url":"http://localhost:8112"
	},
	"chainConfig":{
		"bifAddress":"did:bid:efbThy5sb...5oQGX6LUGwg",
		"bifChainRpcUrl":"http://test.bifcore.bitfactory.cn",
		"bifPrivateKey":"priSPKgnr1a...JNaackZJUo",
		"domainGovernContract":"did:bid:efjQKy4HEshTueHGKzrJPATKoFeNgHKo",
		"ptcGovernContract":"did:bid:efgTq9DtP2zHAhmKp7M4BhN6AVYMVWV2",
		"relayerGovernContract":"did:bid:efSnvCFJSnpWiQiVhnh8Eimgyi4RoNpA"
	}
}

下面对各个配置项给出解释：

首先是颁证服务的配置：

  • authorizedKeyPem：有权限申请跨链身份（Relayer、PTC）的私钥，填入PEM格式的PKCS#8的私钥，目前仅支持Ed25519算法。
  • authorizedPublicKeyPem：authorizedKeyPem对应的公钥，填入PEM格式的PKCS#8的公钥，目前仅支持Ed25519算法。
  • authorizedSigAlgo：authorizedKeyPem私钥的签名算法，目前仅支持Ed25519算法。
  • clientCrossChainCertPem：Relayer的跨链证书，需要提前从BCDNS处获取。
  • clientPrivateKeyPem：Relayer跨链证书持有者的私钥，填入PEM格式的PKCS#8的私钥，目前仅支持Ed25519算法。
  • sigAlgo：clientPrivateKeyPem私钥的签名算法，目前仅支持Ed25519算法。
  • url：颁证服务的URL。

然后是星火链网的配置：

  • bifAddress：星火链网的账户地址，这里需要使用Relayer的公钥来生成该地址，可以参考代码。
  • bifChainRpcUrl：星火链网节点的RPC地址。
  • bifChainRpcPort：星火链网节点的PRC端口，如果不需要则可以不填。
  • clientPrivateKeyPem：星火链网账户的私钥，这里需要使用Relayer的私钥clientPrivateKeyPem来生成该地址，可以参考代码。
  • domainGovernContract：域名管理合约，参考星火链网BCDNS，依赖的星火链网BCDNS应当有唯一一本域名管理合约。
  • ptcGovernContract：PTC身份管理合约，依赖的星火链网BCDNS应当有唯一一本PTC身份管理合约。
  • relayerGovernContract：Relayer身份管理合约，依赖的星火链网BCDNS应当有唯一一本Relayer身份管理合约。

准备完配置之后，可以根据这里创建一个BCDNS实例。

社区治理

AntChain Bridge 欢迎您以任何形式参与社区建设。

您可以通过以下方式参与社区讨论

  • 钉钉

scan dingding

  • 邮件

发送邮件到[email protected]

License

详情参考LICENSE。

About

AntChainBridge 插件SDK和插件池

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • Java 77.8%
  • Solidity 17.0%
  • C++ 4.6%
  • Shell 0.6%