重要

• 国密SSL连接只有在国密区块链环境下才可以使用。

• 是否选择国密SSL连接，SDK与区块链节点的配置要保持一致，节点配置参考配置链属性

• FISCO-BCOS 2.5及之后的版本，添加了SDK只能连本机构节点的限制，操作时需确认拷贝证书的路径，否则建联报错。

<?xml version="1.0" encoding="UTF-8" ?><beansxmlns="http://www.springframework.org/schema/beans"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:p="http://www.springframework.org/schema/p"xmlns:tx="http://www.springframework.org/schema/tx"xmlns:aop="http://www.springframework.org/schema/aop"xmlns:context="http://www.springframework.org/schema/context"xsi:schemaLocation="http://www.springframework.org/schema/beans    http://www.springframework.org/schema/beans/spring-beans-2.5.xsd         http://www.springframework.org/schema/tx    http://www.springframework.org/schema/tx/spring-tx-2.5.xsd         http://www.springframework.org/schema/aop    http://www.springframework.org/schema/aop/spring-aop-2.5.xsd"><beanid="encryptType"class="org.fisco.bcos.web3j.crypto.EncryptType"><constructor-argvalue="0"/><!-- 0:standard 1:guomi --></bean><beanid="groupChannelConnectionsConfig"class="org.fisco.bcos.channel.handler.GroupChannelConnectionsConfig"><!-- SSL certificate configuration --><propertyname="caCert"value="ca.crt"/><propertyname="sslCert"value="sdk.crt"/><propertyname="sslKey"value="sdk.key"/><!-- GM SSL certificate configuration --><propertyname="gmCaCert"value="gmca.crt"/><propertyname="gmEnSslCert"value="gmensdk.crt"/><propertyname="gmEnSslKey"value="gmensdk.key"/><propertyname="gmSslCert"value="gmsdk.crt"/><propertyname="gmSslKey"value="gmsdk.key"/><propertyname="allChannelConnections"><list><!-- 每个群组需要配置一个bean，每个群组可以配置多个节点 --><beanid="group1"class="org.fisco.bcos.channel.handler.ChannelConnections"><propertyname="groupId"value="1"/><!-- 群组的groupID --><propertyname="connectionsStr"><list><value>127.0.0.1:20200</value><!-- IP:channel_port --><value>127.0.0.1:20201</value></list></property></bean><beanid="group2"class="org.fisco.bcos.channel.handler.ChannelConnections"><propertyname="groupId"value="2"/><!-- 群组的groupID --><propertyname="connectionsStr"><list><value>127.0.0.1:20202</value><value>127.0.0.1:20203</value></list></property></bean></list></property></bean><beanid="channelService"class="org.fisco.bcos.channel.client.Service"depends-on="groupChannelConnectionsConfig"><propertyname="groupId"value="1"/><!-- 配置连接群组1 --><propertyname="agencyName"value="fisco"/><!-- 配置机构名 --><propertyname="allChannelConnections"ref="groupChannelConnectionsConfig"></property></bean></beans>

encrypt-type:# 0：普通， 1：国密encrypt-type:0group-channel-connections-config:caCert:ca.crtsslCert:sdk.crtsslKey:sdk.keyall-channel-connections:-group-id:1#group IDconnections-str:# 若节点小于v2.3.0版本，查看配置项listen_ip:channel_listen_port-127.0.0.1:20200# node channel_listen_ip:channel_listen_port-127.0.0.1:20201-group-id:2connections-str:# 若节点小于v2.3.0版本，查看配置项listen_ip:channel_listen_port-127.0.0.1:20202# node channel_listen_ip:channel_listen_port-127.0.0.1:20203channel-service:group-id:1# sdk实际连接的群组agency-name:fisco# 机构名称

调用SDK Web3j的API¶

加载配置文件，SDK与区块链节点建立连接，获取web3j对象，根据Web3j对象调用相关API。示例代码如下：

//读取配置文件，SDK与区块链节点建立连接ApplicationContextcontext=newClassPathXmlApplicationContext("classpath:applicationContext.xml");Serviceservice=context.getBean(Service.class);service.run();ChannelEthereumServicechannelEthereumService=newChannelEthereumService();channelEthereumService.setChannelService(service);//获取Web3j对象Web3jweb3j=Web3j.build(channelEthereumService,service.getGroupId());//通过Web3j对象调用API接口getBlockNumberBigIntegerblockNumber=web3j.getBlockNumber().send().getBlockNumber();System.out.println(blockNumber);

注： SDK处理交易超时时间默认为60秒，即60秒内没有收到交易响应，判断为超时。该值可以通过ChannelEthereumService进行设置，示例如下：

// 设置交易超时时间为100000毫秒，即100秒channelEthereumService.setTimeout(100000);

调用SDK Precompiled的API¶

加载配置文件，SDK与区块链节点建立连接。获取SDK Precompiled Service对象，调用相关的API。示例代码如下：

//读取配置文件，SDK与区块链节点建立连接，获取Web3j对象ApplicationContextcontext=newClassPathXmlApplicationContext("classpath:applicationContext.xml");Serviceservice=context.getBean(Service.class);service.run();ChannelEthereumServicechannelEthereumService=newChannelEthereumService();channelEthereumService.setChannelService(service);Web3jweb3j=Web3j.build(channelEthereumService,service.getGroupId());StringprivateKey="b83261efa42895c38c6c2364ca878f43e77f3cddbc922bf57d0d48070f79feb6";//指定外部账户私钥，用于交易签名Credentialscredentials=GenCredential.create(privateKey);//获取SystemConfigService对象SystemConfigServicesystemConfigService=newSystemConfigService(web3j,credentials);//通过SystemConfigService对象调用API接口setValueByKeyStringresult=systemConfigService.setValueByKey("tx_count_limit","2000");//通过Web3j对象调用API接口getSystemConfigByKeyStringvalue=web3j.getSystemConfigByKey("tx_count_limit").send().getSystemConfigByKey();System.out.println(value);

创建并使用指定外部账户¶

SDK发送交易需要一个外部账户，下面是随机创建一个外部账户的方法。

//创建普通外部账户EncryptType.encryptType=0;//创建国密外部账户，向国密区块链节点发送交易需要使用国密外部账户// EncryptType.encryptType = 1;Credentialscredentials=GenCredential.create();//账户地址Stringaddress=credentials.getAddress();//账户私钥StringprivateKey=credentials.getEcKeyPair().getPrivateKey().toString(16);//账户公钥StringpublicKey=credentials.getEcKeyPair().getPublicKey().toString(16);

使用指定的外部账户

//通过指定外部账户私钥使用指定的外部账户Credentialscredentials=GenCredential.create(privateKey);

加载账户私钥文件¶

如果通过账户生成脚本get_accounts.sh生成了PEM或PKCS12格式的账户私钥文件(账户生成脚本的用法参考账户管理文档)，则可以通过加载PEM或PKCS12账户私钥文件使用账户。加载私钥有两个类：P12Manager和PEMManager，其中，P12Manager用于加载PKCS12格式的私钥文件，PEMManager用于加载PEM格式的私钥文件。

• P12Manager用法举例：在applicationContext.xml中配置PKCS12账户的私钥文件路径和密码

<beanid="p12"class="org.fisco.bcos.channel.client.P12Manager"init-method="load"><propertyname="password"value="123456"/><propertyname="p12File"value="classpath:0x0fc3c4bb89bd90299db4c62be0174c4966286c00.p12"/></bean>

开发代码

//加载BeanApplicationContextcontext=newClassPathXmlApplicationContext("classpath:applicationContext.xml");P12Managerp12=context.getBean(P12Manager.class);//提供密码获取ECKeyPair，密码在生产p12账户文件时指定ECKeyPairp12KeyPair=p12.getECKeyPair(p12.getPassword());//以十六进制串输出私钥和公钥System.out.println("p12 privateKey: "+p12KeyPair.getPrivateKey().toString(16));System.out.println("p12 publicKey: "+p12KeyPair.getPublicKey().toString(16));//生成Web3SDK使用的CredentialsCredentialscredentials=GenCredential.create(p12KeyPair.getPrivateKey().toString(16));System.out.println("p12 Address: "+credentials.getAddress());

• PEMManager使用举例

在applicationContext.xml中配置PEM账户的私钥文件路径

<beanid="pem"class="org.fisco.bcos.channel.client.PEMManager"init-method="load"><propertyname="pemFile"value="classpath:0x0fc3c4bb89bd90299db4c62be0174c4966286c00.pem"/></bean>

使用代码加载

//加载BeanApplicationContextcontext=newClassPathXmlApplicationContext("classpath:applicationContext-keystore-sample.xml");PEMManagerpem=context.getBean(PEMManager.class);ECKeyPairpemKeyPair=pem.getECKeyPair();//以十六进制串输出私钥和公钥System.out.println("PEM privateKey: "+pemKeyPair.getPrivateKey().toString(16));System.out.println("PEM publicKey: "+pemKeyPair.getPublicKey().toString(16));//生成Web3SDK使用的CredentialsCredentialscredentialsPEM=GenCredential.create(pemKeyPair.getPrivateKey().toString(16));System.out.println("PEM Address: "+credentialsPEM.getAddress());

准备Java合约文件¶

控制台提供一个专门的编译合约工具，方便开发者将Solidity合约文件编译为Java合约文件，具体使用方式参考这里。

部署并调用合约¶

SDK的核心功能是部署/加载合约，然后调用合约相关接口，实现相关业务功能。部署合约调用Java合约类的deploy方法，获取合约对象。通过合约对象可以调用getContractAddress方法获取部署合约的地址以及调用该合约的其他方法实现业务功能。如果合约已部署，则通过部署的合约地址可以调用load方法加载合约对象，然后调用该合约的相关方法。

//读取配置文件，SDK与区块链节点建立连接，获取web3j对象ApplicationContextcontext=newClassPathXmlApplicationContext("classpath:applicationContext.xml");Serviceservice=context.getBean(Service.class);service.run();ChannelEthereumServicechannelEthereumService=newChannelEthereumService();channelEthereumService.setChannelService(service);channelEthereumService.setTimeout(10000);Web3jweb3j=Web3j.build(channelEthereumService,service.getGroupId());//准备部署和调用合约的参数BigIntegergasPrice=newBigInteger("300000000");BigIntegergasLimit=newBigInteger("300000000");StringprivateKey="b83261efa42895c38c6c2364ca878f43e77f3cddbc922bf57d0d48070f79feb6";//指定外部账户私钥，用于交易签名Credentialscredentials=GenCredential.create(privateKey);//部署合约YourSmartContractcontract=YourSmartContract.deploy(web3j,credentials,newStaticGasProvider(gasPrice,gasLimit)).send();//根据合约地址加载合约//YourSmartContract contract = YourSmartContract.load(address, web3j, credentials, new StaticGasProvider(gasPrice, gasLimit));//调用合约方法发送交易TransactionReceipttransactionReceipt=contract.someMethod(<param1>,...).send();//查询合约方法查询该合约的数据状态Typeresult=contract.someMethod(<param1>,...).send();

pragma solidity^0.4.24;contractTxDecodeSample{eventEvent1(uint256_u,int256_i,bool_b,address_addr,bytes32_bs32,string_s,bytes_bs);eventEvent2(uint256_u,int256_i,bool_b,address_addr,bytes32_bs32,string_s,bytes_bs);functionecho(uint256_u,int256_i,bool_b,address_addr,bytes32_bs32,string_s,bytes_bs)publicconstantreturns(uint256,int256,bool,address,bytes32,string,bytes){Event1(_u,_i,_b,_addr,_bs32,_s,_bs);return(_u,_i,_b,_addr,_bs32,_s,_bs);}functiondo_event(uint256_u,int256_i,bool_b,address_addr,bytes32_bs32,string_s,bytes_bs)public{Event1(_u,_i,_b,_addr,_bs32,_s,_bs);Event2(_u,_i,_b,_addr,_bs32,_s,_bs);}}

// TxDecodeSample合约ABIStringabi="[{\"constant\":false,\"inputs\":[{\"name\":\"_u\",\"type\":\"uint256\"},{\"name\":\"_i\",\"type\":\"int256\"},{\"name\":\"_b\",\"type\":\"bool\"},{\"name\":\"_addr\",\"type\":\"address\"},{\"name\":\"_bs32\",\"type\":\"bytes32\"},{\"name\":\"_s\",\"type\":\"string\"},{\"name\":\"_bs\",\"type\":\"bytes\"}],\"name\":\"do_event\",\"outputs\":[],\"payable\":false,\"stateMutability\":\"nonpayable\",\"type\":\"function\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":false,\"name\":\"_u\",\"type\":\"uint256\"},{\"indexed\":false,\"name\":\"_i\",\"type\":\"int256\"},{\"indexed\":false,\"name\":\"_b\",\"type\":\"bool\"},{\"indexed\":false,\"name\":\"_addr\",\"type\":\"address\"},{\"indexed\":false,\"name\":\"_bs32\",\"type\":\"bytes32\"},{\"indexed\":false,\"name\":\"_s\",\"type\":\"string\"},{\"indexed\":false,\"name\":\"_bs\",\"type\":\"bytes\"}],\"name\":\"Event1\",\"type\":\"event\"},{\"anonymous\":false,\"inputs\":[{\"indexed\":false,\"name\":\"_u\",\"type\":\"uint256\"},{\"indexed\":false,\"name\":\"_i\",\"type\":\"int256\"},{\"indexed\":false,\"name\":\"_b\",\"type\":\"bool\"},{\"indexed\":false,\"name\":\"_addr\",\"type\":\"address\"},{\"indexed\":false,\"name\":\"_bs32\",\"type\":\"bytes32\"},{\"indexed\":false,\"name\":\"_s\",\"type\":\"string\"},{\"indexed\":false,\"name\":\"_bs\",\"type\":\"bytes\"}],\"name\":\"Event2\",\"type\":\"event\"},{\"constant\":true,\"inputs\":[{\"name\":\"_u\",\"type\":\"uint256\"},{\"name\":\"_i\",\"type\":\"int256\"},{\"name\":\"_b\",\"type\":\"bool\"},{\"name\":\"_addr\",\"type\":\"address\"},{\"name\":\"_bs32\",\"type\":\"bytes32\"},{\"name\":\"_s\",\"type\":\"string\"},{\"name\":\"_bs\",\"type\":\"bytes\"}],\"name\":\"echo\",\"outputs\":[{\"name\":\"\",\"type\":\"uint256\"},{\"name\":\"\",\"type\":\"int256\"},{\"name\":\"\",\"type\":\"bool\"},{\"name\":\"\",\"type\":\"address\"},{\"name\":\"\",\"type\":\"bytes32\"},{\"name\":\"\",\"type\":\"string\"},{\"name\":\"\",\"type\":\"bytes\"}],\"payable\":false,\"stateMutability\":\"view\",\"type\":\"function\"}]";Stringbin="";TransactionDecodertxDecodeSampleDecoder=TransactionDecoderFactory.buildTransactionDecoder(abi,bin);

params注册参数¶

事件回调请求注册的参数：

publicclassEventLogUserParams{privateStringfromBlock;privateStringtoBlock;privateList<String>addresses;privateList<Object>topics;}

callback回调对象¶

publicabstractclassEventLogPushCallback{publicvoidonPushEventLog(intstatus,List<LogResult>logs);}

• status 回调返回状态：

    0       : 正常推送，此时logs为节点推送的Event日志    1       : 推送完成，执行区间的区块都已经处理    -41000  : 参数无效，客户端验证参数错误返回    -41001  : 参数错误，节点验证参数错误返回    -41002  : 群组不存在    -41003  : 请求错误的区块区间    -41004  : 节点推送数据格式错误    -41005  : 请求发送超时    -41006  : 其他错误

• logs表示回调的EventLog对象列表，status为0有效

publicclassLogResult{privateList<EventResultEntity>logParams;privateLoglog;}// Log对象publicclassLog{privateStringlogIndex;privateStringtransactionIndex;privateStringtransactionHash;privateStringblockHash;privateStringblockNumber;privateStringaddress;privateStringdata;privateStringtype;privateList<String>topics;}

Loglog：Log对象

List<EventResultEntity>logParams：默认值null，可以在子类中解析Log的data字段，将结果保存入logParams[参考交易解析]

• 实现回调对象

Java SDK默认实现的回调类ServiceEventLogPushCallback，将status与logs在日志中打印，用户可以通过继承ServiceEventLogPushCallback类，重写onPushEventLog接口，实现自己的回调逻辑处理。

classMyEventLogPushCallBackextendsServiceEventLogPushCallback{@OverridepublicvoidonPushEventLog(intstatus,List<LogResult>logs){// ADD CODE}}

注意：onPushEventLog接口多次回调的logs有重复的可能性，可以根据Log对象中的blockNumber，transactionIndex，logIndex进行去重

topic工具¶

org.fisco.bcos.channel.event.filter.TopicTools提供将各种类型参数转换为对应topic的工具，用户设置EventLogUserParams的topics参数可以使用。

classTopicTools{// int1/uint1~uint1/uint256publicstaticStringintegerToTopic(BigIntegeri)// boolpublicstaticStringboolToTopic(booleanb)// addresspublicstaticStringaddressToTopic(Strings)// stringpublicstaticStringstringToTopic(Strings)// bytespublicstaticStringbytesToTopic(byte[]b)// byte1~byte32publicstaticStringbyteNToTopic(byte[]b)}

registerTransferEventEventLogFilter¶

这两个接口对org.fisco.bcos.channel.client.Service.registerEventLogFilter进行了封装，调用等价于将registerEventLogFilter的params参数设置为：

EventLogUserParamsparams=newEventLogUserParams();// fromBlock, 无参数设置为“latest”params.setFromBlock(fromBlock);// params.setFromBlock("latest");// toBlock, 无参数设置为“latest”params.setToBlock(toBlock);// params.setToBlock("latest");// addresses，设置为Java合约对象的地址// 当前java合约对象为：Asset assetArrayList<String>addresses=newArrayList<String>();addresses.add(asset.getContractedAddress());params.setAddresses(addresses);// topics, topic0设置为Event接口对应的topicArrayList<Object>topics=newArrayList<>();topics.add(TopicTools.stringToTopic("TransferEvent(int256,string,string,uint256)"));// 其他topic设置， 没有则忽略topics.addAll(otherTopics);

可以看出，在关注指定地址特定合约的某个Event，使用生成的Java合约对象中的接口，更加简单方便。

EventLogPushWithDecodeCallback¶

EventLogPushWithDecodeCallback与ServiceEventLogPushCallback相同，是EventLogPushCallback的子类，区别在于：

• ServiceEventLogPushCallback回调接口onPushEventLog(intstatus,List<LogResult>logs)LogResult成员logParams为空，用户需要使用Log数据时需要解析数据

• EventLogPushWithDecodeCallback作为Asset对象的成员，可以根据其保存的ABI成员构造对应Event的解析工具，解析返回的Log数据，解析结果保存在logParams中。

// 其他初始化逻辑，省略// 参数设置EventLogUserParamsparams=newEventLogUserParams();// 全部Event fromBlock设置为"1"params.setFromBlock("1");// 最新Event fromBlock设置为"latest"// params.setFromBlock("latest");// toBlock设置为"latest"，处理至最新区块继续等待新的区块params.setToBlock("latest");// addresses设置为空数组，匹配所有的合约地址params.setAddresses(newArrayList<String>());// topics设置为空数组，匹配所有的Eventparams.setTopics(newArrayList<Object>());// 回调，用户可以替换为自己实现的类的回调对象ServiceEventLogPushCallbackcallback=newServiceEventLogPushCallback();service.registerEventLogFilter(params,callback);

// 其他初始化逻辑，省略// 设置参数EventLogUserParamsparams=newEventLogUserParams();// 从最新区块开始，fromBlock设置为"latest"params.setFromBlock("latest");// toBlock设置为"latest"，处理至最新区块继续等待新的区块params.setToBlock("latest");// addresses设置为空数组，匹配所有的合约地址params.setAddresses(newArrayList<String>());// topic0，TransferEvent(int256,string,string,uint256)ArrayList<Object>topics=newArrayList<>();topics.add(TopicTools.stringToTopic("TransferEvent(int256,string,string,uint256)"));params.setTopics(topics);// 回调，用户可以替换为自己实现的类的回调对象ServiceEventLogPushCallbackcallback=newServiceEventLogPushCallback();service.registerEventLogFilter(params,callback);

// 其他初始化逻辑，省略Stringaddr="0x06922a844c542df030a2a2be8f835892db99f324";// 设置参数EventLogUserParamsparams=newEventLogUserParams();// 从最新区块开始，fromBlock设置为"latest"params.setFromBlock("latest");// toBlock设置为"latest"，处理至最新块并继续等待共识出块params.setToBlock("latest");// 合约地址ArrayList<String>addresses=newArrayList<String>();addresses.add(addr);params.setAddresses(addresses);// topic0，匹配 TransferEvent(int256,string,string,uint256) 事件ArrayList<Object>topics=newArrayList<>();topics.add(TopicTools.stringToTopic("TransferEvent(int256,string,uint256)"));params.setTopics(topics);ServiceEventLogPushCallbackcallback=newServiceEventLogPushCallback();service.registerEventLogFilter(params,callback);

// 其他初始化逻辑，省略Stringaddr="0x06922a844c542df030a2a2be8f835892db99f324";// 构造Asset合约对象Assetasset=Asset.load(addr,...);EventLogPushWithDecodeCallbackcallback=newEventLogPushWithDecodeCallback();asset.registerTransferEventEventLogFilter(callback);

// 其他初始化逻辑，省略// 设置参数EventLogUserParamsparams=newEventLogUserParams();// 从最初区块开始，fromBlock设置为"1"params.setFromBlock("1");// toBlock设置为"latest"，处理至最新块并继续等待共识出块params.setToBlock("latest");// 设置合约地址ArrayList<String>addresses=newArrayList<String>();addresses.add(addr);params.setAddresses(addresses);// TransferEvent(int256,string,string,uint256) 转换为topicArrayList<Object>topics=newArrayList<>();topics.add(TopicTools.stringToTopic("TransferEvent(int256,string,string,uint256)"));params.setTopics(topics);ServiceEventLogPushCallbackcallback=newServiceEventLogPushCallback();service.registerEventLogFilter(params,callback);

// 其他初始化逻辑，省略Assetasset=Asset.load(addr,...);// 设置区块范围StringfromBlock="1";StringtoBlock="latest";// 参数topic为空ArrayList<Object>otherTopics=newArrayList<>();EventLogPushWithDecodeCallbackcallback=newEventLogPushWithDecodeCallback();asset.registerTransferEventEventLogFilter(fromBlock,toBlock,otherTopics,callback);

// 其他初始化逻辑，省略Stringaddr="0x06922a844c542df030a2a2be8f835892db99f324";StringfromAccount="account";// 参数EventLogUserParamsparams=newEventLogUserParams();// 从最初区块开始，fromBlock设置为"1"params.setFromBlock("1");// toBlock设置为"latest"params.setToBlock("latest");// 设置合约地址ArrayList<String>addresses=newArrayList<String>();addresses.add(addr);params.setAddresses(addresses);// 设置topicArrayList<Object>topics=newArrayList<>();// TransferEvent(int256,string,string,uint256) 转换为topictopics.add(TopicTools.stringToTopic("TransferEvent(int256,string,string,uint256)"));// 转账账户 fromAccount转换为topictopics.add(TopicTools.stringToTopic(fromAccount));params.setTopics(topics);ServiceEventLogPushCallbackcallback=newServiceEventLogPushCallback();service.registerEventLogFilter(params,callback);

// 其他初始化逻辑，省略Stringaddr="0x06922a844c542df030a2a2be8f835892db99f324";StringfromAccount="account";// 加载合约地址，生成Java合约对象Assetasset=Asset.load(addr,...);// 回调函数EventLogPushWithDecodeCallbackcallback=newEventLogPushWithDecodeCallback();// 设置区块范围StringfromBlock="1";StringtoBlock="latest";// 参数topicArrayList<Object>otherTopics=newArrayList<>();// 转账账户 fromAccount转换为topicotherTopics.add(TopicTools.stringToTopic(fromAccount));asset.registerRegisterEventEventLogFilter(fromBlock,toBlock,otherTopics,callback);