# 智能合约模块

# 模块概述

  • 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
Last Updated: 2019/9/3 下午4:38:35