2. SDK
2.1. 概述
长安链SDK
是业务模块与长安链交互的桥梁,支持双向TLS
认证,提供安全可靠的加密通信信道。
长安链提供了多种语言的SDK
,包括:Go SDK
、Java SDK
、Python SDK
(实现中)、Nodejs SDK
(实现中)方便开发者根据需要进行选用。
提供的SDK
接口,覆盖合约管理、链配置管理、证书管理、多签收集、各类查询操作、事件订阅等场景,满足了不同的业务场景需要。
2.2. 约定概念
Node
(节点):代表一个链节点的基本信息,包括:节点地址、连接数、是否启用TLS
认证等信息ChainClient
(链客户端):所有客户端对链节点的操作接口都来自ChainClient
压缩证书:可以为
ChainClient
开启证书压缩功能,开启后可以减小交易包大小,提升处理性能
2.3. 开发指南
2.3.1. Go SDK
2.3.1.1. 环境依赖
golang
版本为1.15或以上
下载地址:https://golang.org/dl/
若已安装,请通过命令查看版本:
$ go version
go version go1.15 linux/amd64
2.3.1.2. 下载安装
$ git clone --recursive -b v1.2.0 https://git.chainmaker.org.cn/chainmaker/chainmaker-sdk-go.git
2.3.1.3. 示例代码
2.3.1.3.1. 创建节点
// 创建节点
func createNode(nodeAddr string, connCnt int) *NodeConfig {
node := NewNodeConfig(
// 节点地址,格式:127.0.0.1:12301
WithNodeAddr(nodeAddr),
// 节点连接数
WithNodeConnCnt(connCnt),
// 节点是否启用TLS认证
WithNodeUseTLS(true),
// 根证书路径,支持多个
WithNodeCAPaths(caPaths),
// TLS Hostname
WithNodeTLSHostName(tlsHostName),
)
return node
}
2.3.1.3.2. 以参数形式创建ChainClient
更多内容请参看:
sdk_client_test.go
注:示例中证书采用路径方式去设置,也可以使用证书内容去设置,具体请参看
createClientWithCaCerts
方法
// 创建ChainClient
func createClient() (*ChainClient, error) {
if node1 == nil {
// 创建节点1
node1 = createNode(nodeAddr1, connCnt1)
}
if node2 == nil {
// 创建节点2
node2 = createNode(nodeAddr2, connCnt2)
}
chainClient, err := NewChainClient(
// 设置归属组织
WithChainClientOrgId(chainOrgId),
// 设置链ID
WithChainClientChainId(chainId),
// 设置logger句柄,若不设置,将采用默认日志文件输出日志
WithChainClientLogger(getDefaultLogger()),
// 设置客户端用户私钥路径
WithUserKeyFilePath(userKeyPath),
// 设置客户端用户证书
WithUserCrtFilePath(userCrtPath),
// 添加节点1
AddChainClientNodeConfig(node1),
// 添加节点2
AddChainClientNodeConfig(node2),
)
if err != nil {
return nil, err
}
//启用证书压缩(开启证书压缩可以减小交易包大小,提升处理性能)
err = chainClient.EnableCertHash()
if err != nil {
log.Fatal(err)
}
return chainClient, nil
}
2.3.1.3.3. 以配置文件形式创建ChainClient
注:参数形式和配置文件形式两个可以同时使用,同时配置时,以参数传入为准
func createClientWithConfig() (*ChainClient, error) {
chainClient, err := NewChainClient(
WithConfPath("./testdata/sdk_config.yml"),
)
if err != nil {
return nil, err
}
//启用证书压缩(开启证书压缩可以减小交易包大小,提升处理性能)
err = chainClient.EnableCertHash()
if err != nil {
return nil, err
}
return chainClient, nil
}
2.3.1.3.4. 创建合约
sdk_user_contract_claim_test.go
func testUserContractClaimCreate(t *testing.T, client *ChainClient,
admin1, admin2, admin3, admin4 *ChainClient, withSyncResult bool, isIgnoreSameContract bool) {
resp, err := createUserContract(client, admin1, admin2, admin3, admin4,
claimContractName, claimVersion, claimByteCodePath, common.RuntimeType_WASMER, []*common.KeyValuePair{}, withSyncResult)
if !isIgnoreSameContract {
require.Nil(t, err)
}
fmt.Printf("CREATE claim contract resp: %+v\n", resp)
}
func createUserContract(client *ChainClient, admin1, admin2, admin3, admin4 *ChainClient,
contractName, version, byteCodePath string, runtime common.RuntimeType, kvs []*common.KeyValuePair, withSyncResult bool) (*common.TxResponse, error) {
payloadBytes, err := client.CreateContractCreatePayload(contractName, version, byteCodePath, runtime, kvs)
if err != nil {
return nil, err
}
// 各组织Admin权限用户签名
signedPayloadBytes1, err := admin1.SignContractManagePayload(payloadBytes)
if err != nil {
return nil, err
}
signedPayloadBytes2, err := admin2.SignContractManagePayload(payloadBytes)
if err != nil {
return nil, err
}
signedPayloadBytes3, err := admin3.SignContractManagePayload(payloadBytes)
if err != nil {
return nil, err
}
signedPayloadBytes4, err := admin4.SignContractManagePayload(payloadBytes)
if err != nil {
return nil, err
}
// 收集并合并签名
mergeSignedPayloadBytes, err := client.MergeContractManageSignedPayload([][]byte{signedPayloadBytes1,
signedPayloadBytes2, signedPayloadBytes3, signedPayloadBytes4})
if err != nil {
return nil, err
}
// 发送创建合约请求
resp, err := client.SendContractManageRequest(mergeSignedPayloadBytes, createContractTimeout, withSyncResult)
if err != nil {
return nil, err
}
err = checkProposalRequestResp(resp, true)
if err != nil {
return nil, err
}
return resp, nil
2.3.1.3.5. 调用合约
sdk_user_contract_claim_test.go
func testUserContractClaimInvoke(client *ChainClient,
method string, withSyncResult bool) (string, error) {
curTime := fmt.Sprintf("%d", CurrentTimeMillisSeconds())
fileHash := uuid.GetUUID()
params := map[string]string{
"time": curTime,
"file_hash": fileHash,
"file_name": fmt.Sprintf("file_%s", curTime),
}
err := invokeUserContract(client, claimContractName, method, "", params, withSyncResult)
if err != nil {
return "", err
}
return fileHash, nil
}
func invokeUserContract(client *ChainClient, contractName, method, txId string, params map[string]string, withSyncResult bool) error {
resp, err := client.InvokeContract(contractName, method, txId, params, -1, withSyncResult)
if err != nil {
return err
}
if resp.Code != common.TxStatusCode_SUCCESS {
return fmt.Errorf("invoke contract failed, [code:%d]/[msg:%s]\n", resp.Code, resp.Message)
}
if !withSyncResult {
fmt.Printf("invoke contract success, resp: [code:%d]/[msg:%s]/[txId:%s]\n", resp.Code, resp.Message, resp.ContractResult.Result)
} else {
fmt.Printf("invoke contract success, resp: [code:%d]/[msg:%s]/[contractResult:%s]\n", resp.Code, resp.Message, resp.ContractResult)
}
return nil
}
2.3.1.3.6. 更多示例和用法
更多示例和用法,请参看单元测试用例
功能 | 单测代码 |
---|---|
用户合约 | sdk_user_contract_test.go |
系统合约 | sdk_system_contract_test.go |
链配置 | sdk_chain_config_test.go |
证书管理 | sdk_cert_manage_test.go |
消息订阅 | sdk_subscribe_test.go |
2.3.1.4. 接口说明
2.3.2. Java SDK
2.3.2.1. 环境依赖
java
jdk 1.8.0_202或以下
下载地址:https://www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html
若已安装,请通过命令查看版本:
$ java -version
java version "1.8.0_202"
2.3.2.2. 下载安装
$ git clone -b v1.2.0 https://git.chainmaker.org.cn/chainmaker/chainmaker-sdk-java.git
2.3.2.3. 示例代码
2.3.2.3.1. 创建节点
更多内容请参看:
TestBase
// 创建节点
Node node = Node.builder()
.clientKeyBytes(keyBytes)
.clientCertBytes(certBytes)
.tlsCertBytes(tlsCertBytes)
.hostname(TLS_HOST_NAME1)
.grpcUrl(NODE_GRPC_URL1)
.sslProvider(OPENSSL_PROVIDER)
.negotiationType(TLS_NEGOTIATION).build();
2.3.2.3.2. 创建ChainClient
更多内容请参看:
TestBase
// 创建ChainClient
chainManager = ChainManager.getInstance();
chainClient = chainManager.getChainClient(CHAIN_ID);
if (chainClient == null) {
chainClient = chainManager.createChainClient(CHAIN_ID, ORG_ID, FileUtils.getResourceFileBytes(USER_KEY_PATH),
FileUtils.getResourceFileBytes(USER_CERT_PATH), chainNode);
}
2.3.2.3.3. 创建合约
更多内容请参看:
TestUserContract
public void testCreateContract() throws IOException, InterruptedException, ExecutionException, TimeoutException {
byte[] byteCode = FileUtils.getResourceFileBytes(CONTRACT_FILE_PATH);
// 1. create payload
byte[] payload = chainClient.createPayloadOfContractCreation(CONTRACT_NAME,
"1", Contract.RuntimeType.WASMER_RUST, null, byteCode);
// 2. create payloads with endorsement
byte[] payloadWithEndorsement1 = chainClient.signPayloadOfContractMgmt(payload);
// 3. merge endorsements using payloadsWithEndorsement
byte[][] payloadsWithEndorsement = new byte[1][];
payloadsWithEndorsement[0] = payloadWithEndorsement1;
byte[] payloadWithEndorsement = chainClient.mergeSignedPayloadsOfContractMgmt(payloadsWithEndorsement);
// 4. create contract
ResponseInfo responseInfo = chainClient.createContract(payloadWithEndorsement, 5000, 5000);
}
2.3.2.3.4. 调用合约
更多内容请参看:
TestUserContract
public void testInvokeContract() throws Exception {
Map<String, String> params = new HashMap<>();
params.put("time", System.currentTimeMillis()+"");
params.put("file_hash", UUID.randomUUID().toString());
params.put("file_name", UUID.randomUUID().toString()+System.currentTimeMillis());
ResponseInfo responseInfo = chainClient.invokeContract(QUERY_CONTRACT_NAME, QUERY_CONTRACT_METHOD, params, 5000, 5000);
}
2.3.2.3.5. 更多示例和用法
更多示例和用法,请参看单元测试用例
功能 | 单测代码 |
---|---|
基础配置 | TestBase |
用户合约 | TestUserContract |
系统合约 | TestSystemContract |
链配置 | TestChainConfig |
证书管理 | TestBaseCertManage |
消息订阅 | TestSubscribe |
2.3.2.4. 接口说明
2.3.3. Nodejs SDK
2.3.3.1. 环境依赖
nodejs
nodejs 14.0.0+
下载地址:https://nodejs.org/dist/
若已安装,请通过命令查看版本:
$ node --version
v14.0.0
2.3.3.2. 下载安装
$ git clone -b v1.2.0 https://git.chainmaker.org.cn/chainmaker/chainmaker-sdk-nodejs.git
2.3.3.3. 示例代码
2.3.3.3.1. 创建节点
更多内容请参看:
sdkInit.js
// 创建节点
this.node = new Node(nodeConfigArray, timeout);
2.3.3.3.2. 创建ChainClient
更多内容请参看:
sdkInit.js
// 创建ChainClient
const ChainClient = new Sdk(chainID, orgID, userKeyPathFile, userCertPathFile, nodeConfigArray, 30000, archiveConfig);
2.3.3.3.3. 创建合约
更多内容请参看:
testUserContractMgr.js
const testCreateUserContract = async (sdk, contractName, contractVersion, contractFilePath) => {
const response = await sdk.userContractMgr.createUserContract({
contractName,
contractVersion,
contractFilePath,
runtimeType: utils.common.RuntimeType.GASM,
params: {
key1: 'value1',
key2: 'value2',
},
});
return response;
};
2.3.3.3.4. 调用合约
更多内容请参看:
testUserContractMgr.js
const testInvokeUserContract = async (sdk, contractName) => {
const response = await sdk.callUserContract.invokeUserContract({
contractName, method: 'save', params: {
file_hash: '1234567890',
file_name: 'test.txt',
},
});
return response;
};
2.3.3.3.5. 更多示例和用法
更多示例和用法,请参看单元测试用例
安装mocha:
$ npm install -g mocha
使用脚本搭建chainmaker运行环境(4组织4节点),将build文件中的cryptogen复制到当前项目的test/testFile文件中
运行测试命令:
$ npm test
功能 | 单测代码 |
---|---|
基础配置 | sdkInit.js |
用户合约 | userContract.js |
系统合约 | systemContract.js |
链配置 | chainConfig.js |
证书管理 | cert.js |
消息订阅 | subscribe.js |