SDK-Example使用说明
概述
本文将详细说明如何使用点融区块链云服务平台以及运行sdk-example示例。
示例场景: 用户创建了一个联盟链,并邀请其他成员加入
备注:私有链的场景也同样适用(本文不再详述)。
- 用户A在创建了一个联盟链(比如叫:ourchain)后,邀请用户B加入该联盟链。
- 用户B创建自己的组织并为之分配Peer节点,然后加入到联盟链中。
- 作为盟主,用户A新建一个联盟(比如叫:NewConsortium),其中包括自己的组织和用户B的组织。
- 接着,用户A在联盟NewConsortium上创建通道(比如叫:mychannel),成功之后,两个用户分别将自己的peer节点加入到该通道。
- 随后,用户A上传了智能合约或者从合约商店里购买了一个智能合约(本例是从商店里购买一个合约: dr_test_cc),然后发布到联盟链,这样链上所有的成员都可以安装该智能合约。
- 用户A和用户B,分别在已经加入到通道"mychannel"的Peer节点上安装智能合约。
- 用户A在通道"mychannel"上初始化智能合约。
- 用户A和用户B使用sdk-example来调用智能合约。
简称
如未作特殊说明,本文中使用的以下名词都代表特定含义。
名词 | 含义 |
---|---|
客户端 | 是指点融区块链客户端 |
BaaS平台 | 是指点融区块链云服务平台 |
用户 | 是指BaaS用户 |
通道(channel) | 是指基于Hyperledger Fabric区块链上的用于隔离账本的通道 |
智能合约或chaincode | 是指基于Hyperledger Fabric区块链的智能合约,也叫chaincode |
背书节点(endorser) | 是指安装了智能合约的Peer节点,它参与处理transaction proposal,并进行模拟交易,生成读写集合返回客户端。 |
提交节点(committer) | 是指未安装智能合约的Peer节点,它不参与处理transaction proposal。只负责对由Orderer节点发来的transaction进行验证、然后提交到本地的账本。endorser也是committer。 |
详细步骤
在BaaS平台上的准备工作
假定盟主已经创建了一个联盟链(ourchain),并拥有:
2个组织:
组织名称 MSP ID 用途 Org0 Org0MSP 分配给peer节点 OrdererOrg OrdererOrgMSP 分配给Orderer节点 2个Peer节点:
- peer0.Org0.example.com
- peer1.Org0.example.com
1个orderer节点: orderer0.OrdererOrg.example.com
在执行sdk-example之前,需要完成以下步骤:
用户 | 角色 | 步骤 | 哪里操作 |
---|---|---|---|
用户A | 盟主 | 在已有联盟链(ourchain)的基础上,邀请新成员用户B加入 | BaaS平台 |
用户B | 联盟成员 | 通过BaaS平台创建区块链,借助于客户端创建1个名为Org1的组织,并分配2个peer节点(peer0.Org1.example.com,peer1. Org1.example.com) | BaaS平台、客户端 |
用户A | 盟主 | 创建一个新的联盟,命名为NewConsortium,其中包含Org0,Org1。 备注:需要借助客户端来批准创建新联盟 | BaaS平台、客户端 |
用户A | 盟主 | 基于NewConsortium创建channel,命名为mychannel 备注:需要借助客户端来批准创建新的channel | BaaS平台、客户端 |
用户A | 盟主 | 将Org0的2个peer节点,加入到新创建的mychannel 备注:需要借助客户端来批准将Peer节点加入channel | BaaS平台、客户端 |
用户B | 联盟成员 | 将Org1的2个peer节点,加入到新创建的mychannel 备注:需要借助客户端来批准将Peer节点加入channel | BaaS平台、客户端 |
用户A | 盟主 | 从BaaS平台的合约商店购买名为dr_test_cc的智能合约。 | BaaS平台、客户端 |
用户A | 盟主 | 将智能合约dr_test_cc发布到联盟链(ourchain) 备注:发布成功后,链上所有成员均可以安装。 | BaaS平台、客户端 |
用户A | 盟主 | 在peer0.Org0.example.com、peer1.Org0.example.com节点上安装智能合约。 | BaaS平台、客户端 |
用户B | 联盟成员 | 在peer0.Org1.example.com、peer1.Org1.example.com节点上安装智能合约。 | BaaS平台、客户端 |
用户A | 盟主 | 在通道mychannel上,初始化智能合约dr_test_cc(即部署该智能合约到通道上): - 指定初始化参数为:{"Args":["init","a","10000","b","20000"]} - 指定自定义背书策略为: AND ('Org0MSP.peer','Org1MSP.peer') 备注: 只需一个用户来发起初始化。 | BaaS平台、客户端 |
运行sdk-example
应用相关配置
sdk-example是一个调用智能合约的应用程序。每个组织都应独立运行它。运行之前,每个组织还需完成如下配置:
将加入到通道“mychannel”的Peer节点以及所有的Orderer节点的ip地址写入/etc/hosts,如下:
106.75.218.141 orderer0.OrdererOrg.example.com 106.75.217.71 peer0.Org0.example.com 106.75.218.143 peer1.Org0.example.com 106.75.218.163 peer0.Org1.example.com 106.75.218.71 peer1.Org1.example.com
每个组织在点融区块链客户端上新建区块链用户,然后导出区块链用户的证书和密钥信息。
导出的区块链用户证书和私钥是一个压缩文件(如:blockchain_Org0.zip),将其解压到本地文件目录(称之为 User Credential根目录)。解压后的文件将包含以下信息(以组织Org0为例):注意: 1. 以下示例中User Credential根目录为"/Users/richie/Downloads/baas_config/blockchain_Org0" 2. users.yaml为User Credential的清单文件。请勿要更改该文件名,否则无法加载用户证书和密钥文件。 3. “User1”为您新建区块链用户时填写的名,客户端会将其拼接成完整的用户名:User1@org0.example.com。 richiedeMacBook-Pro:1.3 richie$ tree blockchain_Org0 blockchain_Org0 ├── org0.example.com │ ├── Admin@org0.example.com │ │ ├── keystore │ │ │ └── 95ee7d9fe16456355385a98c5d35337793c82959df75ab14176a90f39da3d834_sk │ │ └── signcerts │ │ └── Admin@org0.example.com-cert.pem │ └── User1@org0.example.com │ ├── keystore │ │ └── aa58308f8df7950f64fbfefee03ab55339d4d26f6c170318320af70f801e6941_sk │ └── signcerts │ └── User1@org0.example.com-cert.pem ├── tls │ └── tlsca.org0.example.com-cert.pem └── users.yaml 8 directories, 6 files
tls目录下是该组织的TLS CA证书。
users.yaml是UserCredential的清单文件,BaaS SDK通过解析该文件内容来找到每个用户的证书和私钥。
```
users:
- name: Admin@Org0.example.com
orgName: Org0
mspId: Org0MSP
roles:
- admin
affiliation: peerOrg0
certPath: Org0.example.com/Admin@Org0.example.com/signcerts/Admin@Org0.example.com-cert.pem
keyPath: Org0.example.com/Admin@Org0.example.com/keystore/8e639f3269c01a56a706983f952374c4dec39555154ebd08b23e6d3718dc59ee_sk
- name: User1@Org0.example.com
orgName: Org0
mspId: Org0MSP
roles:
- normal
affiliation: peerOrg0
certPath: Org0.example.com/User1@Org0.example.com/signcerts/User1@Org0.example.com-cert.pem
keyPath: Org0.example.com/User1@Org0.example.com/keystore/7e6101424af8a97b580a295e443ad6206d90bd5c2fb3c9de8ff5f34e7acb668f_sk
```
- BaaS SDK的参数配置。
BaaS SDK启动时将默认读取位于resources目录下的config.properties文件。需要配置三个参数:- discovery servers列表
- peer TLS CA证书路径
- 用户证书和私钥的根路径
本例中Org0的配置如下:
#######################################
# BaaS SDK configurations
#######################################
###########################
# channel settings
###########################
#
# If SDK works with service discovery (use ServiceDiscoveryChannelService to manage channels), the discovery servers must be set.
# SDK connects to service discovery peers to query the current channel config info.
# The peer list is seperated by comma, e.g. : peer0.Org0.example.com:7051, peer1.Org0.example.com:7051
# If port is not given, the default port is 7051.
com.dianrong.blockchain.baas.sdk.channel.config.discovery.servers= peer0.Org0.example.com:7051, peer1.Org0.example.com
#
# If SDK works with service discovery (use ServiceDiscoveryChannelService to mangage channels), the peer tls CA certificate path must be set.
com.dianrong.blockchain.baas.sdk.channel.config.discovery.peerTlsCaCertPath=/Users/richie/project/baas_config/blockchain_Org0/tls/tlsca.org1.aaa.com-cert.pem
# User Credentials
# The root path of user credentials which are exported from DianRong blockchain client.
# In this folder, there must be:
# 1. an user manifest file named by 'users.yaml'
# 2. each user's credential files (private key and certificate), which is referenced by the "users.yaml"
# If not set, the default value is the path of 'resources' folder.
#
#com.dianrong.blockchain.baas.sdk.user.userCredentialRootPath = /Users/richie/project/baas_config/blockchain_Org0
运行sdk-example
完成配置后,每个组织可运行自己的sdk-example。该实例将调用部署在“mychannel”通道上的智能合约"dr_test_cc",该智能合约实现一个简单在两个账户中转账的功能。
运行方法:
通过查看日志以及代码中的详细注释,可以理解BaaS SDK API的使用方法。
具体SDK的接口说明,请看baas-sdk-javadoc。
进入到sdk-example所在根目录,然后运行以下命令
richiedeMacBook-Pro:sdk-example richie$ gradle run
附件
####fabric sdk的配置参数 可以通过以下方式将fabric sdk的参数配置到跟baas sdk相同的配置文件中。
在代码中做如下设置:
System.setProperty("org.hyperledger.fabric.sdk.configuration", "/Users/richie/project/baas_config/1.2/config.properties");
System.setProperty("com.dianrong.blockchain.baas.sdk.configuration", "/Users/richie/project/baas_config/1.2/config.properties");
fabric sdk的配置参数如下:
#######################################
# Fabric SDK configurations
#######################################
## The timeout for a proposal requests to endorser in milliseconds.
org.hyperledger.fabric.sdk.proposal.wait.time = 20000
## Time in milliseconds to wait for genesis block
org.hyperledger.fabric.sdk.channel.genesisblock_wait_time=5000
## Time that events that are not being handled are cleaned up. This should never need to be changed.
org.hyperledger.fabric.sdk.client.transaction_cleanup_up_timeout_wait_time=600000
## Time waited between some orderer reties in ms.
org.hyperledger.fabric.sdk.orderer_retry.wait_time=200
## The time the peer event registration waits for first failure in ms
org.hyperledger.fabric.sdk.peer.eventRegistration.wait_time=5000
## The time the event hub waits to reconnect in ms
#EVENTHUB_CONNECTION_WAIT_TIME=5000
## The number of unsuccessful attempts by the eventhub to reconnect before another warning is issued. Set to -1 for none.
#EVENTHUB_RECONNECTION_WARNING_RATE=50
## The number of unsuccessful attempts by the peer eventing service to reconnect before another warning is issued. Set to -1 for none.
#PEER_EVENT_RECONNECTION_WARNING_RATE=50
## The time the peer eventing service wait to retry to connect in ms.
#org.hyperledger.fabric.sdk.peer.retry_wait_time=500
## The time to wait get the genesis block in ms. Usually needed to join the peer to a channel.
#org.hyperledger.fabric.sdk.channel.genesisblock_wait_time=5000
## Limits logging of some long strings to this many characters.
#org.hyperledger.fabric.sdk.log.stringlengthmax=64;
## Setting this to 10 or higher produce larger amounts of logging. Seldom beneficial.
#org.hyperledger.fabric.sdk.log.extraloglevel=10
## Quick way to set apache log4j setting. Default is not to set anything (null). Default for Apache log file is INFO. Can be
## TRACE, DEBUG, INFO, WARN, ERROR
#org.hyperledger.fabric.sdk.loglevel=null
## If true the SDK will perform a check on the endorsed proposals to guarantee they are consistent. This will be checked by the endorsing peers
## prior to committing the block and will fail regardless.
#org.hyperledger.fabric.sdk.proposal.consistency_validation=true
## Default ssl provider on grpc connections (openSSL, JDK)
#org.hyperledger.fabric.sdk.connections.ssl.sslProvider=openSSL
## Default negotiation type for grpc ssl connections. (TLS, plainText)
#org.hyperledger.fabric.sdk.connections.ssl.negotiationType=TLS
# System wide defaults for CryptoPrimitives objects. You can customize further by using the
# CryptoPrimitives.setProperties() method.
# If you change any of these values, please coordinate with the Fabric and Fabric-ca administrators as they
#will need to change peer and orderer configurations as well
#
# security level determines the elliptic curve used to generate keys. Valid values are 256 ( curve is P-256 )
# and 384 ( curve is secp384r1 )
# org.hyperledger.fabric.sdk.crypto.security_level = 256
# hash algorithm determines the message digest used when creating a signature. Valid values are
# SHA2 ( digest is SHA-256 ) and SHA3 ( digest is SHA-3 )
#org.hyperledger.fabric.sdk.crypto.hash_algorithm = SHA2
# The format for the certificate PEM files used by the SDK, Fabric and Fabric-ca components.
# currently X.509 is the only valid format supported. This entry is here to allow for future support
# org.hyperledger.fabric.sdk.crypto.certificate_format = X.509
# The algorithm used to generate a signature. Valid values are listed in the JCA Standard Algorithm Name Documentation
# e.g. http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#Signature
# org.hyperledger.fabric.sdk.crypto.default_signature_algorithm = SHA256withECDSA