应用方数字资产集成开发最佳实践

1. 综述

数字资产是一套由智能合约控制的链上协议，支持数字藏品、数字权益、数字纪念品等各类数字资产应用。 应用方可参考以下文档完成账户开户、区块链节点安装、数字资产发行、数字资产交易等。

2. 应用方账户开户和燃料获取

区块链账户是区块链世界里面的身份，通过密码学算法自动生成。一个账户的组成包括：公钥、私钥、区块链地址。

智能合约的部署和数字资产的管理均需要用应用平台账户私钥对相关内容做交易签名，确保该操作是由拥有私钥的账户发起。

对安顺网络节点的任何智能合约写入调用都需要消耗燃料，请确保与链交互的地址上具备足够的燃料。

3. 接入安顺网络

• 如使用RPC方式接入，你将不需要准备机器来运行任何的安顺网络节点即可完成与安顺网络的交互，请直接接入安顺链官方提供的节点。

• 如需要使用全节点方式接入，你将需要自行准备一台机器来运行安顺网络的一个节点，这样你可以只与自己的节点进行交互就能发送和接收安顺网络的数据， 请参考全节点接入。

4. 开发和部署合约

安顺链网支持基于EVM的Solidity智能合约的运行，Solidity技术文档请参考Solidity开发文档。

本文将基于最佳实践示例合约进行阐述开发流程。

推荐使用Hardhat进行合约开发，也可使用以太坊主流IDE(如Remix，Truffule)进行合约开发和部署。

5. 应用层合约调用

调用方案将以Java为例，使用Web3j SDK进行链上调用，开发者可基于该SDK使用Java语言接入到平台的各项服务。

5.1. 准备工作

5.1.1. 示例Java运行环境

java version "1.8.0_45"
Java(TM) SE Runtime Environment (build 1.8.0_45-b14)

5.1.2. 依赖安装

安装Maven依赖：

<dependencies>
        <dependency>
            <groupId>org.web3j</groupId>
            <artifactId>core</artifactId>
            <version>4.9.5</version>
        </dependency>
</dependencies>

安装Gradle依赖：

implementation('org.web3j:core:4.9.5')

5.1.3. 使用Web3j CLI生成智能合约的函数包装类

Web3j 支持从 Solidity ABI 文件自动生成 Java 中的智能合约函数包装器。

Web3j命令行工具工具附带一个命令行实用程序，用于生成智能合约函数包装类：

安装Web3j CLI：

curl -L get.web3j.io | sh && source ~/.web3j/source.sh

生成智能合约函数包装类：

$ web3j generate solidity [-hV] [-jt] [-st] -a=<abiFile> [-b=<binFile>] -o=<destinationFileDir> -p=<packageName>

   -h, --help                        Show this help message and exit.
   -V, --version                     Print version information and exit.
   -jt, --javaTypes                  use native java types. Default: true
   -st, --solidityTypes              use solidity types.
   -a, --abiFile=<abiFile>           abi file with contract definition.
   -b, --binFile=<binFile>           optional bin file with contract compiled code in order to generate deploy methods.
   -o, --outputDir=<destinationFileDir> destination base directory.
   -p, --package=<packageName>       base package name.

将生成的Java文件放入开发程序中，以便进行合约调用。

5.2. 数字资产铸造

• 功能描述

调用合约铸造数字资产，传入接收对象以及资产属性信息。

交易发起成功后，系统需要记录交易Hash和tokenID，并和用户数字资产账户进行关联。

Java示例代码如下：

String contractAddress = "0xaee43417565576fc696a84c695d8ad8d3ab5092e";
String chainId = "1088";  //区块链网络标识，这里以测试链为例
String nftbody = "{...}"  //按照数字资产结构生成JSON字符串 
String toAddress = "0xB101235d39288578DeE0796e4ccB6a5aaE32772a";       //使用接收用户账户地址
Web3j web3 = Web3j.build(new HttpService("https://blockchain-node/")); //节点部署地址
StaticGasProvider gasProvider = new StaticGasProvider(BigInteger.valueOf(4_100_000_000L), BigInteger.valueOf(1_000_000));

TransactionReceipt txReceipt;
try {
    Credentials credentials =  Credentials.create("....");//输入应用平台私钥
    RawTransactionManager rawTransactionManager = new RawTransactionManager(web3, credentials, Long.parseLong(chainId));
    MyERC721 myERC721 = MyERC721.load(contractAddress, web3, rawTransactionManager, gasProvider);
    txReceipt = myERC721.mint(toAddress，nftbody).send();
    if (!txReceipt.isStatusOK()) {
        System.out.println("mintNft status error: "+ txReceipt.getStatus());
        return;
    }
} catch (Exception ex) {
    System.out.println("mintNft error: ");
}
        
//后续业务处理,包括将交易Hash和数字资产ID关联到用户资产账户。
String hash = txReceipt.getTransactionHash();

5.3. 交易查询

• 功能描述

根据交易Hash查询区块链交易情况。

Java示例代码如下：

EthGetTransactionReceipt  transactionReceipt = web3.ethGetTransactionReceipt("0x00170e5c90475e0b1553c06eedaed9dce8e6da79c38eb26c4f652ac68e5ce4c1").send();
if (transactionReceipt.hasError()) {
       throw new Exception("Error processing request: " + transactionReceipt.getError().getMessage());
}
//以下将返回交易信息
return transactionReceipt.getResult();

5.4. 数字资产查询

• 功能描述

根据TokenID查询数字资产情况

Java示例代码如下：

String tokenId = "1234"; 
String contractAddress = "0xaee43417565576fc696a84c695d8ad8d3ab5092e"; //智能合约地址
Web3j web3 = Web3j.build(new HttpService("https://blockchain-node/"));//节点部署地址
String chainId = "1088";  //区块链网络标识，这里以测试链为例
RawTransactionManager rawTransactionManager = new RawTransactionManager(web3, credentials, Long.parseLong(chainId));
MyERC721 myERC721 = MyERC721.load(contractAddress, web3, rawTransactionManager, gasProvider);
return myERC721.tokenURI(BigInteger.valueOf(tokenId)).send();

5.5. 数字资产转账（含转赠）交易

• 功能描述

应用平台将代理用户账户根据将数字资产转账到其他账户地址，为防止应用平台的恶意转账，转账入参中需要携带发起方用户的私钥签名，表示发起方用户授权应用平台进行资产转账。

Java示例代码如下：

String contractAddress = "0xaee43417565576fc696a84c695d8ad8d3ab5092e";
String chainId = "1088";
Web3j web3 = Web3j.build(new HttpService("https://blockchain-node/"));//节点部署地址
StaticGasProvider gasProvider = new StaticGasProvider(BigInteger.valueOf(4_100_000_000L), BigInteger.valueOf(1_000_000));

Credentials credentials = Credentials.create("....");//输入应用平台私钥
String accountFrom= "..."; //发起方用户地址
String accountTo= "..."; //接收方用户地址
BigNumber timeLimit = BigInteger.valueOf(Instant.now().getEpochSecond() + 300L); //签名有效时间
String signature = "..."; //用户对上链文本的签名

RawTransactionManager rawTransactionManager = new RawTransactionManager(web3, credentials, Long.parseLong(chainId));
MyERC721 myERC721 = MyERC721.load(contractAddress, web3, rawTransactionManager, gasProvider);
txReceipt = myERC721.safeTransferWithSignature(accountFrom, accountTo ,BigInteger.valueOf(2), timeLimit, signature).send();
if (!txReceipt.isStatusOK()) {
    throw new Exception("Error processing request: " + txReceipt.getStatus());
    return;
}