HVM合约内置方法和工具方法使用手册

1. 合约内置变量

目前合约的内置变量

• sender ：合约方法调用者的地址（当且仅当存在跨合约调用时值会与orgin不同）

• origin ：合约调用者的地址

• txHash ：当前交易的哈希

• blockTimestamp ：交易所在区块的时间戳

• blockNumber ：交易所在区块

• contractAddress ：合约地址

2. 合约内置方法

合约内置方法是HVM合约实现类继承自BaseContract的方法，可在合约主类中通过this引用直接使用。

获取交易extra信息

getValueFromExtra

获得当前交易的extra字段信息，其中extra记录了链上额外的存证信息，是一个json字符串。

public String getValueFromExtra(String path) {}

方法	参数	返回值
getVal ueFromExtra	path：对得 到的extra字段进行过滤的规则	String类型 ，从extra字段得到的信息

其中path是一系列由 . 分隔的key组成的字符串。

在key中可以包含一些特殊的通配符比如 * 和 ? 。如果要访问数组的指定元素，使用下标作为key。要获取数组的长度或者要基于数组添加子path，可以使用 # 。

你可以对一个数组使用条件查询， #[…] 将返回第一个匹配元素， #[…]# 将返回所有匹配元素，其中查询条件支持比较运算符： == ， != ， < ， <= ， > ， >= ，还有一些简单的模式匹配： % （like）和 !% （not like）。

注意： . 和 ? 和 * 可以通过 \ 转义成为一般字符。

实例:

{"name": {"first": "Tom", "last": "Anderson"},"age":37,"children": ["Sara","Alex","Jack"],"fav.movie": "Deer Hunter","friends": [{"first": "Dale", "last": "Murphy", "age": 44},{"first": "Roger", "last": "Craig", "age": 68},{"first": "Jane", "last": "Murphy", "age": 47}]}

Path	Result	说明
“name.last”	Anderson	name的属性
“age”	37	age属性
“children”	[“Sara”,“Al ex”,“Jack”]	children属性
“children.#”	3	children数组的长度
“children.1”	“Alex”	children数组的下标为1的元素
c?ildren.0”	“Sara”	匹配模式 为“c?ildren”的元素的下标为0的元素
“fav.movie”	“Deer Hunter”	转义.，“fav.movie”属性
“friends.#.first”	[ “Dale”,“Rog er”,“Jane”]	friends数组内每个元素的first属性
“friends.1.last”	“Craig”	friends数组的第2个元素的last属性
“friends.#[last= =”Murphy”].first”	“Dale”	friends数组中第一个满足last 属性等于“Murphy”的元素的first属性
“friends.#[last== ”Murphy”]#.first”	[“Da le”,“Jane”]	friends数组中所有满足last 属性等于“Murphy”的元素的first属性
“friends .#[age>45]#.last”	[“Craig ”,“Murphy”]	friends数组中所有 满足age属性大于45的元素的last属性
“friends.#[ first%”D*”].last”	“Murphy”	friends数组中第一个满足：first属 性符合”D*“模式，的元素的last属性
“friends.#[f irst!%”D*”].last”	“Craig”	f riends数组中第一个不满足：first属 性符合”D*“模式，的元素的last属性

示例:

String extra = this.getValueFromExtra("friends.1.last");

合约事件推送

hvm为合约的开发者提供了合约事件推送的功能，即可以在合约的执行过程中，将事件推送给客户端。订阅了相关事件类型的客户端可以接收到该事件消息。

合约事件的推送

合约事件推送的功能由合约基础类BaseContract实现，提供的接口如下:

public final void event(Object data, String name, String... topics);

参数：

• data：指定的合约推送数据，最后会转换json的数据的形式推送给客户端

• name：事件的名称，必须提供一个非空的字符串来作为标识。

• topics：用来事件的类型。用户订阅时，可以指定自己想要接收的topic来精确订阅相应的事件。通过topics来确定要接收哪些类型的事件。

示例:

Map<String, String> map = new HashMap<String, String>();
map.put("tom","99");
map.put("bob","98");
event(map, "testEvent", "topicA");

合约事件的订阅

用户可以通过LiteSdk提供的API来订阅合约事件，合约事件必须通过MQParam来注册订阅队列。

MQParam对象的创建示例如下:

ArrayList<String> array = new ArrayList<String>();
array.add("SignedMQBlock");
array.add("MQLog");
array.add("MQException");
String qname = "node1queue";
MQParam mqParam = new MQParam.Builder().
       //队列订阅相关的参数
       msgTypes(array).     //表示要订阅的消息类型
       queueName(qname).    //表示队列名称
       // MQlog事件订阅需要的参数
       logFromBlock("1").       //表示需要推送log事件的起始区块号
       logToBlock("2").         //表示需要推送log事件的终止区块号
       logAddress("0x12...").   //表示log事件需要匹配的合约地址
       logTopics(new String[]{"topicA", "topicB"}).
       //表示log事件需要匹配的topic集合
       logTopics(new String[]{"topicC", "topicD"}).
       //可多次调用添加多个topic数组
       build();

详细的订阅规则请查看LiteSdk使用文档的 第七章. MQ相关接口(MQService) 以及Litedk的 MQ使用手册

获取内置变量

获取合约方法调用者地址

getSender

得到sender，合约方法调用者的地址（当且仅当存在跨合约调用时值会与orgin不同）

public final String getSender() {}

方法	参数	返回值
getSender	无	sender，即合约方法调用者的地址

示例:

String sender = this.getSender();

获取合约调用者地址

getOrigin

得到origin，合约调用者的地址:

public final String getOrigin() {}

方法	参数	返回值
getOrigin	无	origin，即合约调用者的地址

示例:

String origin = this.getOrigin();

获取交易哈希

getTxHash

得到txHash，当前交易哈希

public final String getTxHash() {}

方法	参数	返回值
getTxHash	无	txHash，即当前交易的hash

示例:

String txHash = this.getTxHash();

获取时间戳

getBlockTimestamp

得到blockTimestamp，交易所在区块的时间戳

public final long getBlockTimestamp() {}

方法	参数	返回值
getBlockTimestamp	无	blockTimestamp，即交易所在区块的时间戳

示例:

long blockTimestamp = this.getBlockTimestamp();

获取区块号

getBlockNumber

得到blockNumber，交易所在的区块号

public final long getBlockNumber() {}

方法	参数	返回值
getBlockNumber	无	blockNumber，即交易所在区块号

示例:

long blockNumber = this.getBlockNumber();

获取合约地址

getContractAddress

得到contractAddress，合约地址

public String getContractAddress() {}

方法	参数	返回值
getContractAddress	无	contractAddress，即合约地址

示例:

String contractAddress = this.getContractAddress();

合约内置方法使用demo

【源码包可参考HVM使用手册 - HVM合约Demo附件源码- hvm-manual-demo的contractMethodDemo目录】

3. HVM合约工具方法

概述

本文档介绍HVM合约编写过程可能使用到的工具方法，将分为以下8类进行说明。

• ByteUtil

• CryproUtil

• HashUtil

• ObjectsUtil

• StringUtil

• Logger

• DIDUtil

• Hyperson

ByteUtil

byte数组与Hex String转换

bytesToHex

byte数组转换为十六进制String类型

public static native String bytesToHex(byte[] input);

方法	参数	返回值
bytesToHex	input：需要转换的byte数组	十六进制String

示例:

byte[] input = new byte[]{'a','b'};
String hexString = ByteUtil.bytesToHex(byte[] input);

fromHexString

十六进制String类型转换为byte数组

public static native byte[] fromHexString(String s);

方法	参数	返回值
fromHexString	s：需要转换的十六进制String	byte[]类型

示例:

String s1 = "0xabd43f";
ByteUtil.fromHexString(s1);

String s2 = "abd43f";
byte[] bytes = ByteUtil.fromHexString(s2);
//结果相同

byte数组和int转换

bytesToInt

byte数组转换为int类型

public static int bytesToInt(byte[] bytes) {}

方法	参数	返回值
bytesToHex	input：需要转换的byte数组	十六进制String

示例:

byte[] bytes = new byte[]{'a','b','c','d'};
int result = ByteUtil.bytesToInt(bytes);

intToBytes

int类型转换为byte数组

public static byte[] intToBytes(int value) {}

方法	参数	返回值
intToBytes	value：需要转换的int类型	byte[] 类型

示例:

int value = 48;
byte[] intBytes = ByteUtil.intToBytes(value);

base64编码转byte数组

fromBase64Str

将base64编码的String转换为byte数组

public native static byte[] fromBase64Str(String string);

方法	参数	返回值
fromBase64Str	string：需要转换的base64编码的String类型	byte[] 类型

示例:

byte[] bytes = ByteUtil.fromBase64Str(string);

CryptoUtil

ECDSA账户验签

verifySignature

EC账户验签，通过公钥、原文和签名内容来验证签名内容。

public static boolean verifySignature(byte[] addr, byte[] origin, byte[] signature) {}

方法	参数	返回值
fromBase64Str	string：需要转换的base64编码的String类型	byte[] 类型

示例:

//以下代码使用了一些litesdk的工具类
ECKey ecKey = new ECKey(new SecureRandom());
byte[] address = ecKey.getAddress();
byte[] origin = "hyperchain".getBytes();
byte[] hash = HashUtil.sha3(origin);
byte[] signature = ecKey.sign(hash).toByteArray();
CryptoUtil.verifySignature(address, hash, signature);

SM2国密账户验签

verifySM2Signature

SM账户验签，通过公钥、原文和签名内容来验证签名内容是否正确。

public static boolean verifySM2Signature(byte[] pubKey, byte[] origin, byte[] signature) {}

方法	参数	返回值
verifySM2 Signature	pubKey：byte[] 类型的公钥origin：byte[]类 型的原文signature：byte[]类型的签名。	布尔值，签名正 确则返回true， 否则返回false。

示例:

//以下代码使用类litesdk的工具类
AsymmetricCipherKeyPair keyPair = SM2Util.generateKeyPair();
ECPublicKeyParameters ecPub;
ecpub = (ECPublicKeyParameters) keyPair.getPublic();
byte[] origin = "hyperchain".getBytes();
byte[] publicKey = ecPub.getQ().getEncoded(false);
byte[] signature = SM2Util.sign(keyPair, origin);
CryptoUtil.verifySM2Signature(publicKey,origin,signature);

SM4加解密

sm4Encrypt

sm4加密:

public static byte[] sm4Encrypt(byte[] key, byte[] src) {}

方法	参数	返回值
sm4Encrypt	key：16字节的 对称加密密钥src：需要被加密的内容	byte[] 类型被加密的密文

sm4Decrypt

sm4解密:

public static byte[] sm4Decrypt(byte[] key, byte[] src) {}

方法	参数	返回值
sm4Decrypt	key：16字节的 对称加密密钥src：需要被解密的内容	byte[] 类型被解密的原文

示例:

byte[] key = new byte[]{'e','h','r','s','e','h','r','s','e','h','r','s','e','h','r','s'};
byte[] src = "hyperchain".getBytes();
byte[] encryptBytes = CryptoUtil.sm4Encrypt(key, src);
byte[] decryptBytes = CryptoUtil.sm4Decrypt(key, encryptBytes);
ByteUtil.bytesToHex(src).equals(ByteUtil.bytesToHex(decryptBytes));

AES加解密

aesEncrypt

AES加密:

public static byte[] aesEncrypt(byte[] key, byte[] src) {}

方法	参数	返回值
aesEncrypt	key：32字节的 对称加密密钥src：需要被加密的内容	byte[] 类型被加密的密文

aesDecrypt

AES解密:

public static byte[] aesDecrypt(byte[] key, byte[] src) {}

方法	参数	返回值
aesDecrypt	key：32字节的 对称加密密钥src：需要被解密的内容	byte[] 类型被解密的原文

示例:

keyStr = keyStr.substring(0, 32);
byte[] key = keyStr.getBytes();
byte[] src = "hyperchain".getBytes();
byte[] encryptBytes = CryptoUtil.aesEncrypt(key, src);
byte[] decryptBytes = CryptoUtil.aesDecrypt(key, encryptBytes);
ByteUtil.bytesToHex(src).equals(ByteUtil.bytesToHex(decryptBytes));

tripleDES加解密

tripleDESEncrypt

tripleDES 加密:

public static byte[] tripleDESEncrypt(byte[] key, byte[] src) {}

方法	参数	返回值
tripleDESEncrypt	key：24字节的对称 加密密钥src：需要被加密的内容	byte[] 类 型被加密的密文

tripleDESDecrypt

tripleDES 解密:

public static byte[] tripleDESDecrypt(byte[] key, byte[] src) {}

方法	参数	返回值
tripleDESDecrypt	key：24字节的对称 加密密钥src：需要被解密的内容	byte[] 类 型被解密的原文

示例:

keyStr = keyStr.substring(0, 24);
byte[] key = keyStr.getBytes();
byte[] src = "hyperchain".getBytes();
byte[] encryptBytes = CryptoUtil.tripleDESEncrypt(key, src);
byte[] decryptBytes = CryptoUtil.tripleDESDecrypt(key, encryptBytes);
ByteUtil.bytesToHex(src).equals(ByteUtil.bytesToHex(decryptBytes));

ecc加密

eccEncrypt:

public static byte[] eccEncrypt(byte[] publicKey, byte[] src) {

方法	参数	返回值
eccEncrypt	key：加密密钥src：需要被加密的内容	byte[] 类型被加密的原文

CryptoUtil使用demo

【源码包可参考HVM使用手册 - HVM合约Demo附件源码 -** hvm-manual-demo的cryptoCallDemo目录**】

HashUtil

sha3-256哈希计算

sha3

对输入的byte数组进行sha3-256哈希计算，返回散列值:

public static byte[] sha3(byte[] input) {}

方法	参数	返回值
sha3	input：需要哈希的byte数组	byte[] 类型散列值

示例:

byte[] input = new byte[]{'a','b','c','d'};
byte[] hashResult = HashUtil.sha3(input);

ObjectsUtil

判断对象是否相等

equals

判断Object是否相等，返回布尔值:

public static boolean equals(final Object x, final Object y) {

方法	参数	返回值
equals	x：Java Object。y：Java Object	布尔值，x和y相等， 返回true，否则返回false。

示例:

String x = new String("test");
Integer y = new Integet(0);
boolean isEqual = ObjectsUtil.equals(x, y);

哈希计算

hash

计算多个Object的哈希值，返回多个Object的哈希值:

public static int hash(final Object... values) {}

方法	参数	返回值
hash	values：0个或多个Java Object。	多个Object的哈希值

示例:

String object1 = new String("test");
Integer object2 = new Integet(0);
int hashResult0 = ObjectsUtil.hash();
int hashResult1 = ObjectsUtil.hash(object1);
int hashResult2 = ObjectsUtil.hash(object1, object2);

StringUtil

检查String对象是否为空

checkEmpty

public static boolean checkEmpty(String string) {}

方法	参数	返回值
checkEmpty	string: 需检查的String对象	布尔值，String对象 为空则返回true，否则返回false。

示例:

String string = new String();
boolean isEmpty = StringUtil.checkEmpty(string);

Logger

Logger类提供了打印对应classlog信息的功能。

获取logger

getLogger

public static Logger getLogger(Class clazz) {}

方法	参数	返回值
getLogger	clazz: 对应的class对象	Logger对象

示例:

public class InvokeTripleDES implements BaseInvoke<Boolean, ICrypto> {
   private Logger logger = Logger.getLogger(InvokeTripleDES.class);
}

日志级别

critical级别的日志:

public void critical(Object message) {}

方法	参数	返回值
critical	message: Object对象，需打印的日志信息	无

示例:

logger.critical("logger critical message");

err级别的日志:

public void err(Object message) {}

方法	参数	返回值
err	message: Object对象，需打印的日志信息	无

示例:

logger.err("logger err message");

warning级别的日志:

public void warning(Object message) {}

方法	参数	返回值
warning	message: Object对象，需打印的日志信息	无

示例:

logger.warning("logger warning message");

notice级别的日志:

public void notice(Object message) {}

方法	参数	返回值
notice	message: Object对象，需打印的日志信息	无

示例:

logger.notice("logger notice message");

info级别的日志:

public void info(Object message) {}

方法	参数	返回值
info	message: Object对象，需打印的日志信息	无

示例:

logger.info("logger info message");

debug级别的日志:

public void debug(Object message) {}

方法	参数	返回值
debug	message: Object对象，需打印的日志信息	无

示例:

logger.debug("logger debug message");

DIDUtil

检查凭证是否有效

credentialIsValid:

public static native boolean credentialIsValid(String creID);

方法	参数	返回值
credent ialIsValid	string: 需检查的凭证ID	布尔值，凭证被 吊销或过期则返回false，否则返回true。

示例:

boolean isValid = DIDUtil.credentialIsValid(creID)

检查凭证是否吊销

credentialIsAbondoned:

public static native boolean credentialIsAbondoned(String creID);

方法	参数	返回值
credent ialIsAbondoned	string: 需检查的凭证ID	布尔值，凭证 被吊销则返回true，否则返回false。

示例:

boolean isValid = DIDUtil.credentialIsAbondoned(creID)

Hyperson

Hyperson提供了 toHyperson 方法将Java对象序列化成json字符串，以及 fromHyperson 方法将json字符串反序列化成Java对象。

在使用Hyperson提供的序列化和反序列化方法之前，首先要构造一个Hyperson对象，可通过构造方法以及HypersonBuilder来构建，示例如下:

// 无参构造函数, 配置均按照默认值
Hyperson hyperson = new Hyperson();

// 有参构造函数，可传入相关配置
Hyperson hyperson = new Hyperson(escapeHtml, serialzeNull, excludeAnnotationField, excludeClassField);

// HypersonBuilder构建
Hyperson hyperson = new Hyperson.HypersonBuilder()
       .disableEscapeHtml()
       .enableSerializeNull()
       .addExcludeAnnotationField(StoreField.class)
       .addExcludeClassField(PersonName.class)
       .create();

配置项说明如下：

• serializeNull 控制是否序列化对象中值为null的字段，设置为true，则序列化值为null的字段；设置为false，则忽略值为null的字段，默认为false。

• escapeHtml 控制是否转义html字符，如 < ，设置为true，则对html字符进行转义；设置为false，则不对html字符转义，默认为true。

• excludeAnnotationField 记录了注解类型，序列化和反序列化的过程中，将会忽略添加了这些注解的字段。即如果不想序列化对象中的某些字段，可以给相应字段添加注解，并将该注解类型设置到excludeAnnotationField中，那么添加了该注解的对象字段将不会被序列化。

• excludeClassField 记录了不被序列化及反序列化的字段类型。即如果不想序列化某一类型的字段，则可以将该类型设置到excludeClassField中，那么该类型的字段将不会被序列化。

序列化

toHyperson:

public String toHyperson(Object object);

方法	参数	返回值
toHyperson	object: 需序列化的对象	字符串，对象序列化后的json字符串

示例:

Hyperson hyperson = new Hyperson();
Student student = new Student();
String json = hyperson.toHyperson(student);

反序列化

fromHyperson:

public <T> T fromHyperson(String hyperson, Type type);

方法	参数	返回值
fromHyperson	hyperson: 对象的json字符串type：对象的类型	反 序列化生成 的对象实例

示例:

Hyperson hyperson = new Hyperson();

String json = "test";
Type type = String.class;
String res = hyperson.fromHyperson(json, type);

String mapJson = "{\"key\":\"value\"}";
Type mapType = new ParameterizedTypeImpl(HashMap.class, new Type[]{String.class, String.class}, null);
Map mapRes = hyperson.fromHyperson(mapJson, mapType);

注意事项

• 对象中不允许存在同名字段，即父类和子类不能存在同名字段

• 序列化Map类型的对象时，其key不能为复杂类型，可为八大基本类型或String类型

• 反序列化时，传入的类型参数必须是class类型对象或者实现了ParameterizedType接口的对象

• 反序列化时，如果没有传入相应的类型参数，则数组、集合对象默认反序列化为ArrayList；byte、short、int、long、float、double默认为Double；char、String默认为String；boolean默认为Boolean；其他对象反序列化为LinkedHashMap对象

• 反序列化时，当传入的类型参数是抽象类或接口时，如果其为继承或实现Collection的接口或抽象类类型，则SortedSet接口类型对应TreeSet类型，EnumSet类型对应EnumSet的子类，Set接口类型对应LinkedHashSet类型，Queue接口类型对应ArrayDeque类型，其他为ArrayList类型；如果其为继承或实现Map的接口或抽象类类型，则ConcurrentNavigableMap接口类型对应ConcurrentSkipListMap类型，ConcurrentMap接口类型对应ConcurrentHashMap类型，SortedMap接口类型对应TreeMap类型，其他为LinkedHashMap类型。如果不为Map、Collection以及Number，其他抽象类或接口会反序列化失败。

• 浮点数不允许为NaN或者inf(无穷值）

• Hyperson不支持对增加了注释的json字符串进行反序列化