跳转至

Java SDK文档

这里将向您介绍JAVA SDK，并通过简单的示例帮助您快速熟悉JAVA SDK的使用方法，并构建自己的应用。 这里值得注意的是，本JAVA SDK仅面向linux服务端。项目地址：xuper-java-sdk

模块介绍

使用JAVA SDK可以快速的开发与百度超级链交互的应用程序，JAVA SDK提供以下几个方向的API：

  • 账户, 包括创建区块链账号，通过助记词恢复区块链账户，保存账号加密文件到本地，从本地加密文件恢复账户等
  • 合约账户, 包括创建合约账户等
  • 智能合约, 包括智能合约的部署、调用、查询等
  • 交易, 包括转账交易，查询交易，查询余额等

Quick Start

环境配置

  • 操作系统：支持Linux
  • 开发语言：JAVA1.7及以上
  • 编译器：GCC 4.8.x及以上
  • 版本控制工具：Git

代码获取及导入

点击链接进行下载

把下载的jar包放入java的lib中，如果使用maven管理工程的话可以在pom.xml中配置如下代码

<dependency>
    <groupId>xchain-sdk</groupId>
    <artifactId>sdk</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

<dependency>
    <groupId>net.java.dev.jna</groupId>
    <artifactId>jna</artifactId>
    <version>5.4.0</version>
</dependency>

使用样例

（1）初始化方法

调用者需要创建一个区块链sdk的对象才能使用区块链sdk的能力。

// 获取sdk客户端对象
xuper.Client client = new Client();

// 获取sdk客户端对象，使用host和bcname初始化
// 如果需要和区块链服务进行交互必须使用该方式
xuper.Client client = new Client("106.12.69.229:37101","xuper");


// 设置插件服务
client.setPluginCheck("106.12.72.1:8093", "grpcdemo", "true");
// 设置本地账户
client.setAuthorizedAccount(account.PrivateKey);

（2）账号

try {
    // 创建账户,需要自己将account解析成对象
    String account = client.createAccount(1, 1);
    System.out.println(account);

    // 通过助记词恢复账户
    String accountRet = client.retrieveAccount("来 璃 甚 肌 茶 饮 救 呀 婚 神 呈 即", 1);
    System.out.println(accountRet);
}
catch(Exception e) {
    System.out.println(e);
}

（3）合约账号

Gson gson = new Gson();
try {
    // 通过助记词获取账户
    String accountStr = client.retrieveAccount("玉 脸 驱 协 介 跨 尔 籍 杆 伏 愈 即", 1);
    Account account = gson.fromJson(accountStr, Account.class);

    // 创建合约账户
    String ret = client.createContractAccount("1234567890123456", "", account.JsonPrivateKey);
    System.out.println(ret);
}
catch(Exception e) {
    System.out.println(e);
}

（4）转账

Gson gson = new Gson();
try {
    String accountStr = client.retrieveAccount("玉 脸 驱 协 介 跨 尔 籍 杆 伏 愈 即", 1);
    System.out.println(accountStr);
    Account account = gson.fromJson(accountStr, Account.class);

    // 转账
    String toAddress = "bob";
    String toAmount = "10";
    String fee = "1";
    String desc = "desc";
    String txid = client.transfer(account.Address, account.JsonPrivateKey, toAddress, toAmount, fee, desc);
    System.out.println(txid);

    // 查询账户余额
    String balance = client.getBalanceDetailForSpecificChain(account.Address);
    System.out.println(balance);

    // 查询交易
    String tx = client.queryTx(txid);
    System.out.println(tx);
}
catch(Exception e) {
    System.out.println(e);
}

（5）智能合约

Gson gson = new Gson();
try {
    String accountStr = client.retrieveAccount("玉 脸 驱 协 介 跨 尔 籍 杆 伏 愈 即", 1);
    System.out.println(accountStr);
    Account account = gson.fromJson(accountStr, Account.class);

    // 部署wasm智能合约
    String accountName = "XC1234567890123456@xuper";
    String contractName = "counter";
    String language = "c";
    String desc = "desc";
    String initArgs = "{\"creator\":\"xuper\"}";
    String codepath = "。/counter.wasm";
    String txid = client.deployWasmContract(accountName, contractName, language, desc, initArgs, codepath, account.JsonPrivateKey);
    System.out.println(txid);

    // 调用wasm智能合约
    String methodName = "increase";
    String args = "{\"key\":\"counter\"}";
    txid = client.invokeWasmContract(accountName, contractName, methodName, desc, args, account.JsonPrivateKey);
    System.out.println(txid);

    // 调用wasm查询合约
    methodName = "increase";
    String queryArgs = "{\"key\":\"counter\"}";
    String ret = client.queryWasmContract(contractName, methodName, queryArgs, account.Address);
    System.out.println(ret);
}
catch(Exception e) {
    System.out.println(e);
}

API详解

除用户账户相关的操作外，其余类型的操作均需要先初始化一个相关的客户端，然后通过客户端调用相关方法。这个客户端实际上维持了对应操作所需要的基础数据，一个客户端可以多次调用同类型的操作。

初始化

在使用API之前必须要初始化一个客户端对象。需要依次调用下面的几个方法。

（1）初始化对象

a）方法名称

构造方法

  • public Client(String host, String bcname)

b）参数

参数名 含义 类型
host 区块链服务地址 string
bcname 区块链链名 string

（2）设置插件校验的签名地址

a）方法名称

  • public void setAuthorizedAccount(String strJsonPrivateKey)

b）参数

参数名 含义 类型
strJsonPrivateKey 区块链账户私钥 string

（3）设置插件地址

a）方法名称

  • public void setPluginCheck(String pluginServiceHost, String plugins, String needPluginCheck)

b）参数

参数名 含义 类型
pluginServiceHost 插件服务地址 string
plugins 要校验的插件，以逗号分隔 string
needPluginCheck 是否需要插件校验，一般为true string

（4）账户

账户是指用户在区块链上的账户，账户一般包括地址、公私钥、助记词。其中，通过助记词可以恢复账户的公私钥和地址，助记词丢失则不可恢复，创建账户后请妥善保存自己的助记词。在创建账户时，也可以选择将私钥通过安全码加密后保存到本地的方式，使用时必须使用安全码解密，这样可以防止私钥文件的泄露。

创建账户

创建一个区块链账户，账户包括助记词、地址、公私钥，请妥善保存助记词，之后可以通过助记词来恢复账户。创建时，也可以通过参数指定助记词的强度以及助记词的语言。

（1）创建账户

a）方法名称

  • public String createAccount(int strength, int language) throws Exception

b）参数

参数名 含义 类型
strength 助记词强度，取值可以为
  • 1:助记词个数 12
  • 2:助记词个数 18
  • 3:助记词个数 24
 unit8
language 助记词语言，取值可以为
  • 1:中文
  • 2:英文
 int

c）返回

类型 含义
String 成员为Address, PrivateKey, PublicKey, Mnemonic的结构体json序列化的结果

（2）通过助记词恢复账户

使用助记词来恢复一个区块链账户

a）方法名称

  • public String retrieveAccount(String mnemonic, int language) throws Exception

b）参数

参数名 含义 类型
mnemonic 助记词 string
language 助记词语言，取值可以为
  • 1:中文
  • 2:英文
 int

c）返回

类型 含义
String 成员为Address, PrivateKey, PublicKey, Mnemonic的结构体json序列化的结果

（3）从本地恢复账户

通过本地加密的私钥文件以及安全码恢复账户

a）方法名称

  • public String getBinaryEcdsaPrivateKeyFromFile(String path, String password) throws Exception

b）参数

参数名 含义 类型
path 私钥存储路径 string
passwd 安全码，用来解密私钥 string

c）返回

类型 含义
String 成员为Address, PrivateKey, PublicKey, Mnemonic的结构体json序列化的结果

合约账户

合约账户相关的操作，目前仅提供合约账户创建的功能。合约账户是管理合约的单位，即合约必须安装在合约账户上。

（1）创建合约账户

直接创建一个合约账户,并返回创建合约账户的交易id。在创建合约账户的过程中，需要支付创建合约账户的gas，gas会根据执行的难度收取，如果想获取gas具体数值需要通过方法c预执行和d执行来创建合约账户。

a）方法名称

  • public String createContractAccount(String accountName, String desc, String binaryPrivateKey) throws Exception

b）参数

参数名 含义 类型
accountName 合约账户名字, 规则为 16个数字，例如: "1234567890123456" string
desc 交易描述信息 string
binaryPrivateKey 账户的私钥 string

c）返回

类型 含义
string 创建合约账号的交易ID
error
  • nil: 创建成功
  • non-nil: 失败

转账

普通转账交易，可以完成区块链上价值的转移。

（1）转账交易

普通转账交易。

a）方法名称

  • public String transfer(String address, String binaryPrivateKey, String toAddress, String toAmount, String fee, String desc) throws Exception

b）参数

参数名 含义 类型
address 转账来源地址 string
binaryPrivateKey 转账来源地址的私钥 string
toAddress 转账目的地址 string
toAmount 转账金额 string
fee 转账可选支付的手续费 string
desc 交易描述信息 string

c）返回

类型 含义
string 生成的转账交易ID
error
  • nil: 创建成功
  • non-nil: 失败

（2）查询交易详情

根据交易id来查询交易的详情，该交易可以为普通转账交易、合约创建交易、合约调用交易等

a）方法名称

  • public String queryTx(String txid) throws Exception

b）参数

参数名 含义 类型
txid 待查询的交易ID string

c）返回

类型 含义
string 得到交易的详细信息和状态，json序列化之后的结果

（3）查询用户账户余额

查询本区块链账户的链上余额

a）方法名称

  • public String getBalanceDetailForSpecificChain(String address) throws Exception

b）参数

参数名 含义 类型
address 要查询邮件的地址

c）返回

类型 含义
string 得到所在账户的余额，和冻结的金额，json序列化之后的结果

智能合约

智能合约相关的操作，包括智能合约的部署、调用、查询等。合约名为区分一条链上合约的唯一标识。

（1）部署安装合约

直接部署合约，并返回部署合约的交易id。也可以通过操作c预执行+操作d执行来完成相同的操作。

a）方法名称

  • public String deployWasmContract(String accountName, String contractName, String language, String desc, String initArgs, String codepath, String binaryPrivateKey) throws Exception

b）参数

参数名 含义 类型
accountName 合约账户名字, 规则为XC+16个数字+@链名，例如: "XC1234567890123456@xuper" string
contractName 要操作的合约名称 string
language 合约语言，例如'c' string
desc 合约描述 string
initArgs 合约部署参数，map序列化后的字符串 string
codepath 合约文件位置 string
binaryPrivateKey 安装合约账户的私钥 string

c）返回

类型 含义
string 创建合约账号的交易ID

（2）调用合约

调用wasm智能合约，并返回调用智能合约交易的交易id。

a）方法名称

  • public String invokeWasmContract(String accountName, String contractName, String methodName, String desc, String args, String strJsonPrivateKey) throws Exception

b）参数

参数名 含义 类型
accountName 合约账户名字, 规则为XC+16个数字+@链名，例如: "XC1234567890123456@xuper" string
contractName 要操作的合约名称 string
methodName 合约方法 string
desc 合约描述 string
args 合约方法参数，map序列化的字符串 string
strJsonPrivateKey 安装合约账户的私钥 string

c）返回

类型 含义
string 调用合约的交易ID

（3）查询合约

调用wasm合约查询方法，查询方法仅访问合约维护的数据，并不能将操作上链。

a）方法名称

  • public String queryWasmContract(String contractName, String methodName, String args, String addr)

b）参数

参数名 含义 类型
contractName 要操作的合约名称 string
methodName 合约方法 string
args 合约方法参数，map序列化的字符串 string
address 调用合约的地址 string

c）返回

类型 含义
string 合约预执行产生的结构体序列化字符串

词汇表

类型 含义
区块链账户 普通用户，有自己的addres，公私钥
合约账户 合约账户名字, 规则为 XC+16个数字+@+链名，例如: “XC1234567890123456@xuper”
交易 普通转账
智能合约 用户实现的分布式应用

常见问题

问题一：A用户给B用户转账10月，小费为5元，为什么完成交易后，A用户发现多扣了10元？

答：因为每笔交易会有合规性检查，需要花费10元