Skip to content

Latest commit

 

History

History
449 lines (330 loc) · 22.1 KB

README.md

File metadata and controls

449 lines (330 loc) · 22.1 KB
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,支持的类型可

在v0.3.0之后,拆分出单独的BCDNS Factory模块,用于快速启动不同类型BCDNS的客户端,并剥离依赖。增加关于Embedded BCDNS的实现代码,并提供Spring Boot Starter方便快速启动Embedded 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中“如何实现跨链”的内容;

  • antchain-bridge-bcdns-factory:包含一个工厂类,支持依据类型创建BCDNS客户端,目前支持星火链网(BIF)的BCDNS客户端和Embedded BCDNS的实现,详细使用可以参考wiki中“如何实现跨链”的内容;

构建

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

本地安装

在项目根目录下,直接使用maven编译即可:

mvn install -Dmaven.test.skip=true

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

然后,可以通过在maven的pom.xml配置依赖就可以了,比如下面一段配置,${antchain-bridge.sdk.version}为当前仓库的版本号,可以在项目目录的pom.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>
<dependency>
    <groupId>com.alipay.antchain.bridge</groupId>
    <artifactId>antchain-bridge-bcdns-factory</artifactId>
    <version>${antchain-bridge.sdk.version}</version>
</dependency>

快速开始

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_INFOBID

  • 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实例。

Embedded BCDNS

Embedded BCDNS是内嵌在服务内部的BCDNS,提供中心化的权威服务,会使用一把私钥为跨链网络提供认证、准入等功能,按照服务端要求可以通过简单配置接入BCDNS,具体内容可以参考这里

社区治理

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

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

  • 钉钉

scan dingding2024

  • 邮件

发送邮件到antchainbridge@service.alipay.com

License

详情参考LICENSE