跨链合约
按照跨链合约的设计，我们需要在有跨链需求的应用链上部署两种合约。一个合约负责对接跨链网关Pier，为跨链管理合约Broker；一个合约负责具体的业务场景，为业务合约。业务合约需要跨链时，要统一将跨链请求提交到Broker合约上，Broker统一和Pier进行交互。一个Broker合约可以负责对接多个业务合约。
跨链接入方无需对broker合约进行修改，直接部署使用即可；同时为了简化业务合约的编写，我们设计了业务合约的相应接口。
以下以以太坊上的solidity合约为例。
Broker 合约接口
// 提供给业务合约注册。注册且审核通过的业务合约才能调用Broker合约的跨链接口
function register(string addr) public
// 提供给管理员审核已经注册的业务合约
function audit(string addr, bool status) public returns(bool)
// getInnerMeta 是获取跨链请求相关的Meta信息的接口。以Broker所在的区块链为目的链的一系列跨链请求的序号信息。
// 如果Broker在A链，则可能有多条链和A进行跨链，如B->A:3; C->A:5。
// 返回的map中，key值为来源链ID，value对应该来源链已发送的最新的跨链请求的序号，如{B:3, C:5}。
function getInnerMeta() public view returns(address[] memory, uint64[] memory)
// getOuterMeta 是获取跨链请求相关的Meta信息的接口。以Broker所在的区块链为来源链的一系列跨链请求的序号信息。
// 如果以Broker在A链，则A可能和多条链进行跨链，如A->B:3; A->C:5。
// 返回的map中，key值为目的链ID，value对应已发送到该目的链的最新跨链请求的序号，如{B:3, C:5}。
function getOuterMeta() public view returns(address[] memory, uint64[] memory)
// getCallbackMeta 是获取跨链请求相关的Meta信息的接口。以Broker所在的区块链为来源链的一系列跨链请求的序号信息。
// 如果Broker在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发出的跨链请求部分是没有回调的）
function getCallbackMeta() public view returns(address[] memory, uint64[] memory)
// getInMessage 查询历史跨链请求所在的区块高度。查询键值中srcChainID指定来源链，idx指定序号，查询结果为以Broker所在的区块链作为目的链的跨链请求所在的区块高度。
function getInMessage(string srcChainID, uint64 idx) public view returns (uint)
// getOutMessage 查询历史跨链请求所在的区块高度。查询键值中dstChainID指定目的链，idx指定序号，查询结果为以Broker所在的区块链作为来源链的跨链请求所在的区块高度。
function getOutMessage(string dstChainID, uint64 idx) public view returns (uint)
// 提供给跨链网关调用的接口，跨链网关收到跨链请求时会调用该接口。
function invokeInterchain(address srcChainID, uint64 index, address destAddr, bool req, bytes calldata bizCallData) payable external
// 提供给跨链网关调用的接口，当跨链网关收到无效当跨链请求时会调用该接口。
function invokeIndexUpdateWithError(address srcChainID, uint64 index, bool req, string memory err) public
// 提供给业务合约发起通用的跨链交易的接口。
function emitInterchainEvent(address destChainID, string memory destAddr, string memory funcs, string memory args, string memory argscb, string memory argsrb) public onlyWhiteList
// 提供给合约部署初始化使用
function initialize() public
重要接口说明
emitInterchainEvent
该接口是业务合约发起通用的跨链调用的接口。接收的参数有：目的链ID，目的链业务合约地址或ID，调用的函数名、回调函数名、回滚函数名，调用函数的参数，回调函数的参数，回滚函数的参数。
Broker会记录跨链交易相应的元信息，对跨链交易进行编号，保证跨链交易有序进行, 并且抛出跨链事件，以通知跨链网关跨链交易的产生。
invokeInterchain
该接口是跨链网关对业务合约进行跨链调用或回调/回滚的接口。 接收参数有：来源链ID，交易序号，目的业务合约ID，是否是跨链请求，业务合约调用方法和参数的封装数据。
跨链网关对要调用的目的合约的方法和参数进行封装，通过该接口实现对不同目的合约的灵活调用，并返回目的合约的调用函数的返回值。
业务合约接口
业务合约现阶段分为资产类和数据交换类的业务合约，由于资产类的有操作原子性和安全性的考虑，需要的接口实现上比数据交换类的业务合约更复杂。
Transfer 合约
// 发起一笔跨链交易的接口
function transfer(string dstChainID, string destAddr, string sender, string receiver, string amount) public
// 提供给Broker合约收到跨链充值所调用的接口
function interchainCharge(string sender, string receiver, uint64 val) public onlyBroker returns(bool)
// 跨链交易失败之后，提供给Broker合约进行回滚的接口
function interchainRollback(string sender, uint64 val) public onlyBroker
// 获取transfer合约中某个账户的余额
function getBalance(string id) public view returns(uint64)
// 在transfer合约中给某个账户设置一定的余额
function setBalance(string id, uint64 amount) public
}
DataSwapper合约
// 发起一个跨链获取数据交易的接口
function get(string dstChainID, string dstAddr, string key) public
// 提供给Broker合约调用，当Broker收到跨链获取数据的请求时取数据的接口
function interchainGet(string key) public onlyBroker returns(bool, string memory)
// 跨链获取到的数据回写的接口
function interchainSet(string key, string value) public onlyBroker
具体实现
对于想要接入到我们的跨链平台中的Fabric区块链，我们已经有提供跨链管理合约Broker和相应的Plugin，你只需要对你的业务合约进行一定的改造便可拥有跨链功能。
如果是其他应用链，你可以根据我们的设计思路自行开发跨链管理合约以及相应的Plugin。
现在我们已经有Solidity版本和chaincode版本编写的跨链合约样例实现，具体说明如下：
如果你需要新的语言编写合约，你可以按照我们的设计思路和参考实现进行进一步的开发。
现在我们支持Hyperchain EVM合约、以太坊私链Solidity合约、BCOS EVM合约以及Fabric Chaincode合约。
Hyperchain、以太坊、BCOS上的EVM合约
本节主要说明在支持EVM合约的应用链上，如何使用我们提供的跨链管理合约Broker，在你已有的Solidity业务合约的基础上添加接口，以获得跨链能力。
当然不同的区块链可能在以太坊的EVM上做了一些二次开发和新增功能，请根据具体区块链的文档相应修改代码。
业务合约Demo
假设你已经有了一个简单的KV存储的业务合约，代码如下：
pragma solidity >=0.5.7;
contract DataSwapper {
mapping(string => string) dataM; // map for accounts
// 数据交换类的业务合约
function getData(string memory key) public returns(string memory) {
return dataM[key];
}
function setData(string memory key, string memory value) public {
dataM[key] = value;
}
}
现在你想在这个合约的基础上增加一个跨链获取数据的功能，如果使用我们的跨链管理合约提供的接口，很简单的增加几个接口就可以了。
发起跨链数据交换的接口
contract DataSwapper {
// broker合约地址
address BrokerAddr = 0x2346f3BA3F0B6676aa711595daB8A27d0317DB57;
Broker broker = Broker(BrokerAddr);
...
function get(address destChainID, string memory destAddr, string memory key) public {
broker.emitInterchainEvent(destChainID, destAddr, "interchainGet,interchainSet,", key, key, "");
}
}
contract Broker {
function emitInterchainEvent(address destChainID, string memory destAddr, string memory funcs, string memory args, string memory argscb, string memory argsrb) public;
}
其中Broker的地址和该业务合约需要使用到的接口需要在业务合约中声明，然后直接调用该接口发起跨链交易。
跨链获取的接口
contract DataSwapper {
...
modifier onlyBroker {
require(msg.sender == BrokerAddr, "Invoker are not the Broker");
_;
}
function interchainGet(string memory key) public onlyBroker returns(bool, string memory) {
return (true, dataM[key]);
}
}
跨链回写的接口
contract DataSwapper {
...
function interchainSet(string memory key, string memory value) public onlyBroker {
setData(key, value);
}
...
}
Fabric
本节主要说明在Fabric应用链上，如何使用我们提供的跨链管理合约Broker，在你已有业务合约的基础上添加接口，以获得跨链能力。
业务合约Demo
假设你已经有了一个简单的KV存储的业务合约，代码如下：
type KVStore struct{}
func (s *KVStore) Init(stub shim.ChaincodeStubInterface) peer.Response {
return shim.Success(nil)
}
func (s *KVStore) Invoke(stub shim.ChaincodeStubInterface) peer.Response {
function, args := stub.GetFunctionAndParameters()
fmt.Printf("invoke: %s\n", function)
switch function {
case "get":
return s.get(stub, args)
case "set":
return s.set(stub, args)
default:
return shim.Error("invalid function: " + function + ", args: " + strings.Join(args, ","))
}
}
func (s *KVStore) get(stub shim.ChaincodeStubInterface, args []string) peer.Response {
// args[0]: key
value, err := stub.GetState(args[0])
if err != nil {
return shim.Error(err.Error())
}
return shim.Success(value)
}
// get is business function which will invoke the to,tid,id
func (s *KVStore) set(stub shim.ChaincodeStubInterface, args []string) peer.Response {
if len(args) != 2 {
return shim.Error("incorrect number of arguments")
}
err := stub.PutState(args[0], []byte(args[1]))
if err != nil {
return shim.Error(err.Error())
}
return shim.Success(nil)
}
func main() {
err := shim.Start(new(KVStore))
if err != nil {
fmt.Printf("Error starting chaincode: %s", err)
}
}
现在你想在这个合约的基础上增加一个跨链获取数据的功能，如果使用我们的跨链管理合约提供的接口，很简单的增加几个接口就可以了。
发起跨链数据交换的接口
为了方便用户使用，我们在原来获取数据的接口基础上增加这个功能：
const (
channelID = "mychannel"
brokerContractName = "broker"
emitInterchainEventFunc = "EmitInterchainEvent"
)
func (s *KVStore) get(stub shim.ChaincodeStubInterface, args []string) peer.Response {
switch len(args) {
case 1:
// args[0]: key
value, err := stub.GetState(args[0])
if err != nil {
return shim.Error(err.Error())
}
return shim.Success(value)
case 3:
// args[0]: destination appchain id
// args[1]: destination contract address
// args[2]: key
b := util.ToChaincodeArgs(emitInterchainEventFunc, args[0], args[1], "interchainGet", args[2], "interchainSet", args[2], "", "")
response := stub.InvokeChaincode(brokerContractName, b, channelID)
if response.Status != shim.OK {
return shim.Error(fmt.Errorf("invoke broker chaincode %s error: %s", brokerContractName, response.Message).Error())
}
return shim.Success(nil)
default:
return shim.Error("incorrect number of arguments")
}
}
由于我们的跨链管理合约一旦部署之后，chaincode name和所在的channel和跨链接口都是不变的，所以在业务变量中直接使用常量指定Broker合约的相关信息。
b := util.ToChaincodeArgs(emitInterchainEventFunc, args[0], args[1], "interchainGet", args[2], "interchainSet", args[2], "", "")
response := stub.InvokeChaincode(brokerContractName, b, channelID)
这两行代码调用了我们的跨链管理合约，只需要提供参数：目的链ID，目的链上业务合约的地址，跨链调用函数，跨链调用函数参数，回调函数，回调函数参数，最后两个参数为回滚函数和回滚函数参数，因为该场景下即使目的链执行跨链交易失败，来源链也无需回滚，因此无需提供回滚信息。
跨链获取的接口
func (s *KVStore) interchainGet(stub shim.ChaincodeStubInterface, args []string) peer.Response {
if len(args) != 1 {
return shim.Error("incorrect number of arguments")
}
value, err := stub.GetState(args[0])
if err != nil {
return shim.Error(err.Error())
}
return shim.Success(value)
}
interchainGet 接收参数 key，在本合约中查询该Key值对应的value，并返回。该接口提供给Broker合约进行跨链获取数据的调用。
跨链回写的接口
func (s *KVStore) interchainSet(stub shim.ChaincodeStubInterface, args []string) peer.Response {
if len(args) != 2 {
return shim.Error("incorrect number of arguments")
}
err := stub.PutState(args[0], []byte(args[1]))
if err != nil {
return shim.Error(err.Error())
}
return shim.Success(nil)
}
interchainSet 接收参数 key，在本合约中设置Key值对应的value。该接口提供给Broker合约回写跨链获取数据的时候进行调用。
总结
经过上面的改造，你的业务合约已经具备跨链获取数据的功能了，完整的代码可以参考这里