# 智能合约模块

# 模块概述

• NULS智能合约采用了模块化设计的创新理念，并将其加入NULS的模块仓库，使得开发者在搭链时，可以直接选取NULS智能合约模块，就可以完成相关配置。
• NULS智能合约实现了分钟级别部署，在开发者编写完智能合约之后，可以快速在链上进行部署。
• NULS智能合约的NVM是基于JVM实现，NULS智能合约解释器将无缝支持JVM体系编程语言，并将陆续支持其他主流编程语言，应用开发者可以使用自己熟悉的语言，设计NULS智能合约。
• 通过这样的创新设计思维，NULS希望让智能合约的开发、部署和调用能够更加的便捷化，从而增加开发者对应用开发的兴趣，在不久的将来，能够打造一个丰富的智能合约库。

# 接口列表

# sc_batch_begin

执行合约一个批次的开始通知，生成当前批次的信息/batch begin

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	string	链id	是
blockHeight	string	当前打包的区块高度	是
blockTime	string	当前打包的区块时间	是
packingAddress	string	当前打包的区块打包地址	是
preStateRoot	string	上一个stateRoot	是

# 返回值

字段名	字段类型	参数描述
N/A	void	无特定返回值，没有错误即成功

# sc_batch_before_end

交易模块打包完交易，在做统一验证前，通知合约模块，合约模块停止接收交易，开始异步处理这个批次的结果/batch before end

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	string	链id	是
blockHeight	string	当前打包的区块高度	是

# 返回值

字段名	字段类型	参数描述
N/A	void	无特定返回值，没有错误即成功，如果返回错误，则废弃这个批次，批次内已执行的合约交易退还到待打包交易队列中

# sc_batch_end

通知当前批次结束并返回结果/batch end

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	string	链id	是
blockHeight	string	当前打包的区块高度	是

# 返回值

字段名	字段类型	参数描述
stateRoot	string	当前stateRoot
txList	list<string>	合约新生成的交易序列化字符串列表(可能有合约转账、合约共识、合约返回GAS)

# sc_package_batch_end

打包结束 - 通知当前批次结束并返回结果/batch end

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	string	链id	是
blockHeight	string	当前打包的区块高度	是

# 返回值

字段名	字段类型	参数描述
stateRoot	string	当前stateRoot
txList	list<string>	合约新生成的交易序列化字符串列表(可能有合约转账、合约共识、合约返回GAS)

# sc_contract_offline_tx_hash_list

返回指定区块中合约生成交易（合约返回GAS交易除外）的hash列表（合约新生成的交易除合约返回GAS交易外，不保存到区块中，合约模块保存了这些交易和指定区块的关系）/contract offline tx hash list

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	string	链id	是
blockHash	string	区块hash	是

# 返回值

字段名	字段类型	参数描述
list	list<string>	合约交易序列化字符串列表(可能有合约转账、合约共识)

# sc_initial_account_token

初始化账户token信息，节点导入账户时调用/initial account token

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	string	链id	是
address	string	账户地址	是

# 返回值

字段名	字段类型	参数描述
N/A	void	无特定返回值，没有错误即成功

# sc_register_cmd_for_contract

其他模块向合约模块注册可被合约调用的命令，注册后，可在合约代码内调用注册的命令/register cmd for contract

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	string	链id	是
moduleCode	string	模块代码	是
cmdRegisterList	string	注册信息列表	是

# 返回值

字段名	字段类型	参数描述
N/A	void	无特定返回值，没有错误即成功

# sc_trigger_payable_for_consensus_contract

共识奖励收益地址是合约地址时，会触发合约的_payable(String[][] args)方法，参数是节点收益地址明细
args[0] = new String[]{address, amount}
...
/trigger payable for consensus contract

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	string	链id	是
stateRoot	string	当前的stateRoot	是
blockHeight	string	当前打包的区块高度	是
contractAddress	string	合约地址	是
tx	string	当前打包区块中的CoinBase交易序列化字符串	是

# 返回值

字段名	字段类型	参数描述
value	string	变化后的stateRoot

# sc_invoke_contract

批次通知开始后，一笔一笔执行合约/invoke contract one by one

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	string	链id	是
tx	string	交易序列化的HEX编码字符串	是

# 返回值

字段名	字段类型	参数描述
N/A	void	无特定返回值，没有错误即成功，如果返回错误，则丢弃这笔交易

# sc_constructor

contract code constructor

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链ID	是
contractCode	string	智能合约代码(字节码的Hex编码字符串)	是

# 返回值

字段名	字段类型	参数描述
constructor	object	合约构造函数详情
name	string	方法名称
desc	string	方法描述
args	list<object>	方法参数列表
type	string	参数类型
name	string	参数名称
required	boolean	是否必填
returnArg	string	返回值类型
view	boolean	是否视图方法（调用此方法数据不上链）
event	boolean	是否是事件
payable	boolean	是否是可接受主链资产转账的方法
jsonSerializable	boolean	方法返回值是否JSON序列化
nrc20	boolean	是否是NRC20合约

# sc_delete

delete contract

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
sender	string	交易创建者账户地址	是
password	string	交易账户密码	是
contractAddress	string	合约地址	是
remark	string	交易备注	否

# 返回值

字段名	字段类型	参数描述
txHash	string	删除合约的交易hash

# sc_create

发布合约/create contract

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
sender	string	交易创建者账户地址	是
password	string	账户密码	是
alias	string	合约别名	是
gasLimit	long	GAS限制	是
price	long	GAS单价	是
contractCode	string	智能合约代码(字节码的Hex编码字符串)	是
args	object[]	参数列表	否
remark	string	交易备注	否

# 返回值

字段名	字段类型	参数描述
txHash	string	发布合约的交易hash
contractAddress	string	生成的合约地址

# sc_transfer

从账户地址向合约地址转账(主链资产)/transfer NULS from sender to contract address

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
address	string	转出者账户地址	是
toAddress	string	转入的合约地址	是
password	string	转出者账户密码	是
amount	biginteger	转出的主链资产金额	是
remark	string	交易备注	否

# 返回值

字段名	字段类型	参数描述
txHash	string	交易hash

# sc_validate_create

验证发布合约/validate create contract

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
sender	string	交易创建者账户地址	是
gasLimit	long	GAS限制	是
price	long	GAS单价	是
contractCode	string	智能合约代码(字节码的Hex编码字符串)	是
args	object[]	参数列表	否

# 返回值

字段名	字段类型	参数描述
N/A	void	无特定返回值，没有错误即验证成功

# sc_validate_call

validate call contract

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
sender	string	交易创建者账户地址	是
value	biginteger	调用者向合约地址转入的主网资产金额，没有此业务时填BigInteger.ZERO	是
gasLimit	long	GAS限制	是
price	long	GAS单价	是
contractAddress	string	合约地址	是
methodName	string	合约方法	是
methodDesc	string	合约方法描述，若合约内方法没有重载，则此参数可以为空	否
args	object[]	参数列表	否

# 返回值

字段名	字段类型	参数描述
N/A	void	无特定返回值，没有错误即验证成功

# sc_validate_delete

validate delete contract

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
sender	string	交易创建者账户地址	是
contractAddress	string	合约地址	是

# 返回值

字段名	字段类型	参数描述
N/A	void	无特定返回值，没有错误即验证成功

# sc_contract_result

contract result

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
hash	string	交易hash	是

# 返回值

字段名	字段类型	参数描述
success	boolean	合约执行是否成功
errorMessage	string	执行失败信息
contractAddress	string	合约地址
result	string	合约执行结果
gasLimit	long	GAS限制
gasUsed	long	已使用GAS
price	long	GAS单价
totalFee	string	交易总手续费
txSizeFee	string	交易大小手续费
actualContractFee	string	实际执行合约手续费
refundFee	string	合约返回的手续费
value	string	调用者向合约地址转入的主网资产金额，没有此业务时则为0
stackTrace	string	异常堆栈踪迹
transfers	list<object>	合约转账列表（从合约转出）
txHash	string	合约生成交易：合约转账交易hash
from	string	转出的合约地址
value	string	转账金额
outputs	list<object>	转入的地址列表
to	string	转入地址
value	string	转入金额
orginTxHash	string	调用合约交易hash（源交易hash，合约交易由调用合约交易派生而来）
events	list<string>	合约事件列表
tokenTransfers	list<object>	合约token转账列表
contractAddress	string	合约地址
from	string	付款方
to	string	收款方
value	string	转账金额
name	string	token名称
symbol	string	token符号
decimals	long	token支持的小数位数
invokeRegisterCmds	list<object>	合约调用外部命令的调用记录列表
cmdName	string	命令名称
args	map	命令参数，参数不固定，依据不同的命令而来，故此处不作描述，结构为 {参数名称=参数值}
cmdRegisterMode	string	注册的命令模式（QUERY_DATA or NEW_TX）
newTxHash	string	生成的交易hash（当调用的命令模式是 NEW_TX 时，会生成交易）
contractTxList	list<string>	合约生成交易的序列化字符串列表
remark	string	备注

# sc_contract_result_list

contract result list

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
hashList	list<string>	交易hash列表	是

# 返回值

字段名	字段类型	参数描述
hash1 or hash2 or hash3...	object	以交易hash列表中的hash值作为key，这里的key name是动态的
success	boolean	合约执行是否成功
errorMessage	string	执行失败信息
contractAddress	string	合约地址
result	string	合约执行结果
gasLimit	long	GAS限制
gasUsed	long	已使用GAS
price	long	GAS单价
totalFee	string	交易总手续费
txSizeFee	string	交易大小手续费
actualContractFee	string	实际执行合约手续费
refundFee	string	合约返回的手续费
value	string	调用者向合约地址转入的主网资产金额，没有此业务时则为0
stackTrace	string	异常堆栈踪迹
transfers	list<object>	合约转账列表（从合约转出）
txHash	string	合约生成交易：合约转账交易hash
from	string	转出的合约地址
value	string	转账金额
outputs	list<object>	转入的地址列表
to	string	转入地址
value	string	转入金额
orginTxHash	string	调用合约交易hash（源交易hash，合约交易由调用合约交易派生而来）
events	list<string>	合约事件列表
tokenTransfers	list<object>	合约token转账列表
contractAddress	string	合约地址
from	string	付款方
to	string	收款方
value	string	转账金额
name	string	token名称
symbol	string	token符号
decimals	long	token支持的小数位数
invokeRegisterCmds	list<object>	合约调用外部命令的调用记录列表
cmdName	string	命令名称
args	map	命令参数，参数不固定，依据不同的命令而来，故此处不作描述，结构为 {参数名称=参数值}
cmdRegisterMode	string	注册的命令模式（QUERY_DATA or NEW_TX）
newTxHash	string	生成的交易hash（当调用的命令模式是 NEW_TX 时，会生成交易）
contractTxList	list<string>	合约生成交易的序列化字符串列表
remark	string	备注

# sc_imputed_create_gas

预估发布合约消耗的GAS/imputed create gas

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
sender	string	交易创建者账户地址	是
contractCode	string	智能合约代码(字节码的Hex编码字符串)	是
args	object[]	参数列表	否

# 返回值

字段名	字段类型	参数描述
gasLimit	long	消耗的gas值，执行失败返回数值1

# sc_imputed_call_gas

imputed call gas

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
sender	string	交易创建者账户地址	是
value	biginteger	调用者向合约地址转入的主网资产金额，没有此业务时填BigInteger.ZERO	是
contractAddress	string	合约地址	是
methodName	string	合约方法	是
methodDesc	string	合约方法描述，若合约内方法没有重载，则此参数可以为空	否
args	object[]	参数列表	否

# 返回值

字段名	字段类型	参数描述
gasLimit	long	消耗的gas值，执行失败返回数值1

# sc_token_transfer

NRC20-token转账/transfer NRC20-token from address to toAddress

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
address	string	转出者账户地址	是
toAddress	string	转入地址	是
contractAddress	string	token合约地址	是
password	string	转出者账户密码	是
amount	biginteger	转出的token资产金额	是
remark	string	交易备注	否

# 返回值

字段名	字段类型	参数描述
txHash	string	交易hash

# sc_token_balance

NRC20代币余额详情/NRC20-token balance

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链ID	是
contractAddress	string	合约地址	是
address	string	账户地址	是

# 返回值

字段名	字段类型	参数描述
contractAddress	string	合约地址
name	string	token名称
symbol	string	token符号
amount	string	token数量
decimals	long	token支持的小数位数
blockHeight	long	合约创建时的区块高度
status	int	合约状态(0-不存在, 1-正常, 2-终止)

# sc_invoke_view

invoke view contract

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
contractAddress	string	合约地址	是
methodName	string	合约方法	是
methodDesc	string	合约方法描述，若合约内方法没有重载，则此参数可以为空	否
args	object[]	参数列表	否

# 返回值

字段名	字段类型	参数描述
result	string	视图方法的调用结果

# sc_contract_info

合约信息详情/contract info

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链ID	是
contractAddress	string	合约地址	是

# 返回值

字段名	字段类型	参数描述
createTxHash	string	发布合约的交易hash
address	string	合约地址
creater	string	合约创建者地址
alias	string	合约别名
createTime	long	合约创建时间（单位：秒）
blockHeight	long	合约创建时的区块高度
directPayable	boolean	是否接受直接转账
tokenType	int	token类型, 0 - 非token, 1 - NRC20, 2 - NRC721
nrc20	boolean	是否是NRC20合约
nrc20TokenName	string	NRC20-token名称
nrc20TokenSymbol	string	NRC20-token符号
decimals	long	NRC20-token支持的小数位数
totalSupply	string	NRC20-token发行总量
status	string	合约状态（not_found, normal, stop）
method	list<object>	合约方法列表
name	string	方法名称
desc	string	方法描述
args	list<object>	方法参数列表
type	string	参数类型
name	string	参数名称
required	boolean	是否必填
returnArg	string	返回值类型
view	boolean	是否视图方法（调用此方法数据不上链）
event	boolean	是否是事件
payable	boolean	是否是可接受主链资产转账的方法
jsonSerializable	boolean	方法返回值是否JSON序列化

# sc_contract_tx

合约交易/contract tx

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
hash	string	交易hash	是

# 返回值

字段名	字段类型	参数描述
hash	string	交易hash
type	integer	交易类型
time	long	交易时间
blockHeight	long	区块高度
fee	string	交易手续费
value	string	交易金额
remark	string	备注
scriptSig	string	签名信息
status	integer	交易状态（0 - 确认中，1 - 已确认）
confirmCount	long	交易确认次数
size	int	交易大小
inputs	list<object>	交易输入集合
address	string	输入地址
assetsChainId	int	资产链ID
assetsId	int	资产ID
amount	string	花费金额
nonce	string	地址的账本nonce值
locked	byte	解锁交易的标签（0 - 非解锁交易，1 - 解锁交易）
outputs	list<object>	交易输出集合
address	string	输出地址
assetsChainId	int	资产链ID
assetsId	int	资产ID
amount	string	输出金额
lockTime	long	锁定时间
txData	map	合约交易业务数据
data	object	根据合约交易类型反映不同的业务数据（这里为了描述四种情况，四种业务放在一起描述，实际上不同时存在，只存在一个）
create	object	发布合约交易的业务数据
sender	string	交易创建者地址
contractAddress	string	创建的合约地址
alias	string	合约别名
hexCode	string	智能合约代码(字节码的Hex编码字符串)
gasLimit	long	GAS限制
price	long	GAS单价
args	string[][]	参数列表
call	object	调用合约交易的业务数据
sender	string	交易创建者地址
contractAddress	string	合约地址
value	string	调用者向合约地址转入的主网资产金额，没有此业务时填BigInteger.ZERO
gasLimit	long	GAS限制
price	long	GAS单价
methodName	string	合约方法
methodDesc	string	合约方法描述，若合约内方法没有重载，则此参数可以为空
args	string[][]	参数列表
delete	object	删除合约交易的业务数据
sender	string	交易创建者地址
contractAddress	string	合约地址
transfer	object	合约转账交易的业务数据
orginTxHash	string	调用合约交易hash（源交易hash，合约交易由调用合约交易派生而来）
contractAddress	string	合约地址
contractResult	object	合约执行结果
success	boolean	合约执行是否成功
errorMessage	string	执行失败信息
contractAddress	string	合约地址
result	string	合约执行结果
gasLimit	long	GAS限制
gasUsed	long	已使用GAS
price	long	GAS单价
totalFee	string	交易总手续费
txSizeFee	string	交易大小手续费
actualContractFee	string	实际执行合约手续费
refundFee	string	合约返回的手续费
value	string	调用者向合约地址转入的主网资产金额，没有此业务时则为0
stackTrace	string	异常堆栈踪迹
transfers	list<object>	合约转账列表（从合约转出）
txHash	string	合约生成交易：合约转账交易hash
from	string	转出的合约地址
value	string	转账金额
outputs	list<object>	转入的地址列表
to	string	转入地址
value	string	转入金额
orginTxHash	string	调用合约交易hash（源交易hash，合约交易由调用合约交易派生而来）
events	list<string>	合约事件列表
tokenTransfers	list<object>	合约token转账列表
contractAddress	string	合约地址
from	string	付款方
to	string	收款方
value	string	转账金额
name	string	token名称
symbol	string	token符号
decimals	long	token支持的小数位数
invokeRegisterCmds	list<object>	合约调用外部命令的调用记录列表
cmdName	string	命令名称
args	map	命令参数，参数不固定，依据不同的命令而来，故此处不作描述，结构为 {参数名称=参数值}
cmdRegisterMode	string	注册的命令模式（QUERY_DATA or NEW_TX）
newTxHash	string	生成的交易hash（当调用的命令模式是 NEW_TX 时，会生成交易）
contractTxList	list<string>	合约生成交易的序列化字符串列表
remark	string	备注

# sc_token_assets_list

token资产集合/token assets list

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链ID	是
address	string	账户地址	是
pageNumber	int	页码	否
pageSize	int	每页大小	否

# 返回值

字段名	字段类型	参数描述
contractAddress	string	合约地址
name	string	token名称
symbol	string	token符号
amount	string	token数量
decimals	long	token支持的小数位数
blockHeight	long	合约创建时的区块高度
status	int	合约状态(0-不存在, 1-正常, 2-终止)

# sc_token_transfer_list

token转账交易列表/token transfer list

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链ID	是
address	string	账户地址	是
pageNumber	int	页码	否
pageSize	int	每页大小	否

# 返回值

字段名	字段类型	参数描述
contractAddress	string	合约地址
from	string	付款方
to	string	收款方
value	string	转账金额
time	long	交易时间
status	byte	交易状态（0 - 确认中， 1 - 已确认， 2 - 失败）
txHash	string	交易hash
blockHeight	long	区块高度
name	string	token名称
symbol	string	token符号
decimals	long	token支持的小数位数
info	string	token资产变动信息

# sc_account_contracts

账户的合约地址列表/account contract list

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链ID	是
address	string	账户地址	是
pageNumber	int	页码	否
pageSize	int	每页大小	否

# 返回值

字段名	字段类型	参数描述
contractAddress	string	合约地址
createTime	long	合约创建时间
height	long	合约创建时区块高度
confirmCount	long	合约创建确认次数
alias	string	合约别名
status	int	合约状态（0 - 不存在或者创建中, 1 - 正常, 2 - 已删除, 3 - 创建失败, 4 - 锁定中）
msg	string	合约创建失败的错误信息

# sc_upload

合约代码jar包上传/upload

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
jarFileData	string	文件描述和文件字节流转换Base64编码字符串（文件描述和Base64字符串以逗号隔开）	是

# 返回值

字段名	字段类型	参数描述
constructor	object	合约构造函数详情
name	string	方法名称
desc	string	方法描述
args	list<object>	方法参数列表
type	string	参数类型
name	string	参数名称
required	boolean	是否必填
returnArg	string	返回值类型
view	boolean	是否视图方法（调用此方法数据不上链）
event	boolean	是否是事件
payable	boolean	是否是可接受主链资产转账的方法
jsonSerializable	boolean	方法返回值是否JSON序列化
isNrc20	boolean	是否是NRC20合约
code	string	智能合约代码(字节码的Hex编码字符串)

# sc_call

call contract

# scope:public

# version:1.0

# 参数列表

参数名	参数类型	参数描述	是否非空
chainId	int	链id	是
sender	string	交易创建者账户地址	是
password	string	调用者账户密码	是
value	biginteger	调用者向合约地址转入的主网资产金额，没有此业务时填BigInteger.ZERO	是
gasLimit	long	GAS限制	是
price	long	GAS单价	是
contractAddress	string	合约地址	是
methodName	string	合约方法	是
methodDesc	string	合约方法描述，若合约内方法没有重载，则此参数可以为空	否
args	object[]	参数列表	否
remark	string	交易备注	否

# 返回值

字段名	字段类型	参数描述
txHash	string	调用合约的交易hash