# Smart contract module

# Module Overview

  • The nuls smart contract adopts the innovative concept of modular design and adds it to the nuls module warehouse. Developers can directly select the nuls smart contract module when they are connected, and then complete the relevant configuration.
  • The nuls smart contract implements a minute-level deployment that can be quickly deployed on the chain after the developer has written the smart contract.
  • Nuls smart contract nvm is based on jvm implementation, nuls smart contract interpreter will seamlessly support jvm system programming language, and will continue to support other mainstream programming languages, application developers can use their familiar language to design nuls smart contract.
  • Through such innovative design thinking, Nuls hopes to make the development, deployment and invocation of smart contracts more convenient. In a short timeframe a developer can build a rich, intelligent contract library.

# Interface List

# sc_batch_begin

Execute the start notification of a batch of the contract, generate the information of the current batch /batch begin.

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId string chain id yes
blockHeight string The current packaged block height Yes
blockTime string Current packed block time Yes
packingAddress string currently packaged block packed address Yes
preStateRoot string previous stateRoot yes

# return value

Field Name Field Type Parameter Description
N/A void No specific return value, no error is successful

# sc_batch_before_end

The transaction module packages the transaction, notifies the contract module before doing the unified verification, the contract module stops receiving the transaction, and starts to process the result of the batch asynchronously/batch before end

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId string chain id yes
blockHeight string The current packaged block height Yes

# return value

Field Name Field Type Parameter Description
N/A void No specific return value, no error is successful, if an error is returned, the batch is discarded, and the executed contract transaction in the batch is returned to the queue to be packaged

# sc_batch_end

Notify the current batch to end and return the result /batch end

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId string chain id yes
blockHeight string The current packaged block height Yes

# return value

Field Name Field Type Parameter Description
stateRoot string current stateRoot
txList list<string> List of newly generated transaction serialization strings for contracts (may have contract transfers, contractual consensus, contract returns to GAS)

# sc_package_batch_end

End of packaging - notify the current batch to end and return the result /batch end

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId string chain id yes
blockHeight string The current packaged block height Yes

# return value

Field Name Field Type Parameter Description
stateRoot string current stateRoot
txList list<string> List of newly generated transaction serialization strings for contracts (may have contract transfers, contractual consensus, contract returns to GAS)

# sc_contract_offline_tx_hash_list

Returns the hash list of the contract generation transaction (except the contract return GAS transaction) in the specified block (the newly generated transaction of the contract is not saved in the block except the contract returns to the GAS transaction, and the contract module saves the relationship between these transactions and the specified block. )/contract offline tx hash list

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId string chain id yes
blockHash string block hash yes

# return value

Field Name Field Type Parameter Description
list list<string> List of contract transaction serialization strings (possibly contract transfer, contract consensus)

# sc_initial_account_token

Initialize the account token information, and call /initial account token when the node imports the account.

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId string chain id yes
address string account address yes

# return value

Field Name Field Type Parameter Description
N/A void No specific return value, no error is successful

# sc_register_cmd_for_contract

Other modules register the contract module with commands that can be called by the contract. After registration, the registered command /register cmd for contract can be called within the contract code.

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId string chain id yes
moduleCode string module code yes
cmdRegisterList string Registration Information List Yes

# return value

Field Name Field Type Parameter Description
N/A void No specific return value, no error is successful

# sc_trigger_payable_for_consensus_contract

When the consensus reward income address is the contract address, the contract's _payable(String[][] args) method is triggered. The parameter is the node revenue address detail
args[0] = new String[]{address, amount}
...
/trigger payable for consensus contract

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId string chain id yes
stateRoot string current stateRoot yes
blockHeight string The current packaged block height Yes
contractAddress string contract address yes
tx string CoinBase transaction serialization string in the current packaging block Yes

# return value

Field Name Field Type Parameter Description
value string changed stateRoot

# sc_invoke_contract

After the batch notification begins, an execution contract /invoke contract one by one

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId string chain id yes
tx string Transaction serialized HEX encoded string Yes

# return value

Field Name Field Type Parameter Description
N/A void No specific return value, no error is successful, if an error is returned, the transaction is discarded

# sc_constructor

contract code constructor

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int Chain ID Yes
ContractCode string Smart Contract Code (Hex encoded string of bytecode) Yes

# return value

Field Name Field Type Parameter Description
Constructor object contract constructor details
        name string method name
        desc string Method Description
        args list<object> Method parameter list
                type string Parameter Type
                name string Parameter Name
                required boolean Required
        returnArg string Return value type
        view boolean Whether view method (calling this method data is not on the chain)
        event boolean Whether it is an event
        payable boolean Is it acceptable to transfer the main chain asset
        jsonSerializable boolean Method Returns whether JSON is serialized
nrc20 boolean Is it a NRC20 contract

# sc_delete

delete contract

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
sender string Transaction Creator Account Address Yes
password string Trading Account Password Yes
contractAddress string contract address yes
remark string Transaction Notes No

# return value

Field Name Field Type Parameter Description
txHash string delete contract transaction hash

# sc_create

Release contract

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
sender string Transaction Creator Account Address Yes
password string account password yes
alias string contract alias yes
gasLimit long GAS Limit Yes
price long GAS unit price Yes
ContractCode string Smart Contract Code (Hex encoded string of bytecode) Yes
args object[] List of parameters No
remark string Transaction Notes No

# return value

Field Name Field Type Parameter Description
txHash string publish contract trading hash
contractAddress string generated contract address

# sc_transfer

Transfer from account address to contract address (main chain asset) /transfer NULS from sender to contract address

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
address string Transferring Account Address Yes
toAddress string Transferred contract address Yes
password string Transferring Account Password Yes
amount biginteger Transferred main chain asset amount Yes
remark string Transaction Notes No

# return value

Field Name Field Type Parameter Description
txHash string Trading hash

# sc_validate_create

Verify release contract /validate create contract

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
sender string Transaction Creator Account Address Yes
gasLimit long GAS Limit Yes
price long GAS unit price Yes
ContractCode string Smart Contract Code (Hex encoded string of bytecode) Yes
args object[] List of parameters No

# return value

Field Name Field Type Parameter Description
N/A void No specific return value, no validation is successful

# sc_validate_call

validate call contract

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
sender string Transaction Creator Account Address Yes
value biginteger The amount of the primary network asset that the caller transferred to the contract address. If there is no such service, fill BigInteger.ZERO Yes
gasLimit long GAS Limit Yes
price long GAS unit price Yes
contractAddress string contract address yes
methodName string contract method yes
methodDesc string Contract method description, if the method in the contract is not overloaded, this parameter can be empty No
args object[] List of parameters No

# return value

Field Name Field Type Parameter Description
N/A void No specific return value, no validation is successful

# sc_validate_delete

validate delete contract

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
sender string Transaction Creator Account Address Yes
contractAddress string contract address yes

# return value

Field Name Field Type Parameter Description
N/A void No specific return value, no validation is successful

# sc_contract_result

contract result

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
hash string transaction hash yes

# return value

Field Name Field Type Parameter Description
success boolean Successful contract execution
errorMessage string Execution failure information
contractAddress string contract address
result string Contract execution result
gasLimit long GAS Limit
gasUsed long GAS has been used
price long GAS unit price
totalFee string Total transaction fee
txSizeFee string Transaction Size Fee
actualContractFee string Actual execution contract fee
refundFee string Contract return fee
value string The amount of the primary network asset that the caller transferred to the contract address. If there is no such service, it is 0
stackTrace string Exception Stack Trace
transfers list<object> Contract Transfer List (from contract)
        txHash string Contract Generation Transaction: Contract Transfer Transaction hash
        from string Transferred contract address
        value string Transfer amount
        outputs list<object> Transferred Address List
                to string
                value string
        orginTxHash string Call contract transaction hash (source transaction hash, contract transaction derived from calling contract transaction)
events list<string> Contract Event List
tokenTransfers list<object> Contract Token Transfer List
        contractAddress string Contract Address
        from string Payment Party
        to string Payee
        value string Transfer amount
        name string token name
        symbol string token symbol
        decimals long Number of decimal places supported by token
invokeRegisterCmds list<object> Contract Call List of Calls to External Commands
        cmdName string command name
        args map Command parameters, parameters are not fixed, according to different commands, so not described here, the structure is {parameter name=parameter value}
        cmdRegisterMode string Registered Command Mode (QUERY_DATA or NEW_TX)
        newTxHash string generated transaction hash (when the command mode called is NEW_TX, the transaction is generated)
contractTxList list<string> List of serialized strings for contract generation transactions
remark string Notes

# sc_contract_result_list

contract result list

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
hashList list<string> Trading hash list Yes

# return value

Field Name Field Type Parameter Description
hash1 or hash2 or hash3... object Use the hash value in the transaction hash list as the key, where the key name is dynamic
        success boolean Successful contract execution
        errorMessage string Execution Failure Information
        contractAddress string Contract Address
        result string Contract execution results
        gasLimit long GAS Limit
        gasUsed long GAS has been used
        price long GAS unit price
        totalFee string Total Transaction Fees
        txSizeFee string Transaction Size Fees
        actualContractFee string Actual Execution Contract Fee
        refundFee string Fees returned by the contract
        value string The amount of the primary network asset that the caller transferred to the contract address, or 0 if there is no such service
        stackTrace string Exception Stack Trace
        transfers list<object> Contract Transfer List (from contract)
                txHash string Contract Generation Transaction: Contract Transfer Transaction hash
                from string Transferred contract address
                value string Transfer amount
                outputs list<object> Transferred Address List
                        to string transfer address
                        value string Transfer amount
                orginTxHash string Call contract transaction hash (source transaction hash, contract transaction is called Contract trading is derived)
        events list<string> Contract Event List
        tokenTransfers list<object> Contract Token Transfer List
                contractAddress string contract address
                from string payment
                to string Payee
                value string Transfer amount
                name string token name
                symbol string token symbol
                decimals long Number of decimal places supported by token
        invokeRegisterCmds list<object> Contract Call List of Calls for External Commands
                cmdName string command name
                args map command parameters, parameters are not fixed, depending on different commands Therefore, it is not described here, and the structure is {parameter name=parameter value}
                cmdRegisterMode string Registered Command Mode (QUERY_DATA or NEW_TX)
                newTxHash string generated transaction hash (when the command mode is called NEW\ When _TX, a transaction will be generated)
        contractTxList list<string> Serialized String List for Contract Generation Transactions
        remark string Notes

# sc_imputed_create_gas

Estimated GAS/imputed create gas consumed by the release contract

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
sender string Transaction Creator Account Address Yes
ContractCode string Smart Contract Code (Hex encoded string of bytecode) Yes
args object[] List of parameters No

# return value

Field Name Field Type Parameter Description
gasLimit long The consumed gas value, the execution failed to return the value 1

# sc_imputed_call_gas

imputed call gas

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
sender string Transaction Creator Account Address Yes
value biginteger The amount of the primary network asset that the caller transferred to the contract address. If there is no such service, fill BigInteger.ZERO Yes
contractAddress string contract address yes
methodName string contract method yes
methodDesc string Contract method description, if the method in the contract is not overloaded, this parameter can be empty No
args object[] List of parameters No

# return value

Field Name Field Type Parameter Description
gasLimit long The consumed gas value, the execution failed to return the value 1

# sc_token_transfer

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

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
address string Transferring Account Address Yes
toAddress string Transfer to address Yes
contractAddress string token contract address Yes
password string Transferring Account Password Yes
amount biginteger Amount of transferred token assets Yes
remark string Transaction Notes No

# return value

Field Name Field Type Parameter Description
txHash string Trading hash

# sc_token_balance

NRC20 token balance details / NRC20-token balance

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int Chain ID Yes
contractAddress string contract address yes
address string account address yes

# return value

Field Name Field Type Parameter Description
contractAddress string contract address
name string token name
symbol string token symbol
amount string token quantity
decimals long Number of decimal places supported by token
blockHeight long Block Height at Contract Creation
status int Contract Status (0-None, 1-Normal, 2-End)

# sc_invoke_view

invoke view contract

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
contractAddress string contract address yes
methodName string contract method yes
methodDesc string Contract method description, if the method in the contract is not overloaded, this parameter can be empty No
args object[] List of parameters No

# return value

Field Name Field Type Parameter Description
result string Call result of view method

# sc_contract_info

Contract information details / contract info

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int Chain ID Yes
contractAddress string contract address yes

# return value

Field Name Field Type Parameter Description
createTxHash string publish contract trading hash
address string contract address
creater string contract creator address
alias string contract alias
createTime long contract creation time (unit: second)
blockHeight long Block Height at Contract Creation
directPayable boolean Accept direct transfer
tokenType int token type, 0 - non-token, 1 - NRC20, 2 - NRC721
nrc20 boolean Is it a NRC20 contract
nrc20TokenName string NRC20-token name
nrc20TokenSymbol string NRC20-token symbol
decimals long Number of decimal places supported by NRC20-token
totalSupply string NRC20-token Distribution Total
status string contract status (not_found, normal, stop)
method list<object> Contract Method List
        name string method name
        desc string Method Description
        args list<object> Method parameter list
                type string Parameter Type
                name string Parameter Name
                required boolean Required
        returnArg string Return value type
        view boolean Whether view method (calling this method data is not on the chain)
        event boolean Whether it is an event
        payable boolean Is it acceptable to transfer the main chain asset
        jsonSerializable boolean Method Returns whether JSON is serialized

# sc_contract_tx

Contract transaction / contract tx

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
hash string transaction hash yes

# return value

Field Name Field Type Parameter Description
hash string transaction hash
type integer Transaction Type
time long Trading Hours
blockHeight long Block Height
fee string transaction fee
value string transaction amount
remark string Notes
scriptSig string Signature Information
status integer Transaction Status (0 - Confirmation, 1 - Confirmed)
confirmCount long Transaction Confirmation Times
size int Transactions Size
inputs list<object> Transaction Input Collection
        address string Enter address
        assetsChainId int Asset Chain ID
        assetsId int Asset ID
        amount string Spend Amount
        nonce string address book's nonce value
        locked byte Unlock the deal's tag (0 - non-unlocked deal, 1 - unlock deal)
outputs list<object> Trade Output Collection
        address string output address
        assetsChainId int Asset Chain ID
        assetsId int Asset ID
        amount string Output Amount
        lockTime long Lock Time
txData map Contract Trading Business Data
        data object Reflect different business data according to the contract transaction type (here, in order to describe the four cases, the four services are described together, in fact not at the same time) Exist, there is only one)
                create object Publish business data for contract transactions
                        sender string Transaction Creator Address
                        contractAddress string created contract address
                        alias string contract alias
                        hexCode string Smart Contract Code (Hex encoded string of bytecode)
                        gasLimit long GAS Limit
                        price long GAS unit price
                        args string[][] Parameter List
                call object Calling Business Data for Contract Transactions
                        sender string Transaction Creator Address
                        contractAddress string contract address
                        value string The amount of the primary network asset that the caller transferred to the contract address. If there is no such service, fill in BigInteger.ZERO
                        gasLimit long GAS Limit
                        price long GAS unit price
                        methodName string contract method
                        methodDesc string Contract method description, if the method in the contract is not overloaded, this parameter can be empty
                        args string[][] Parameter List
                delete object Delete business data for contract transactions
                        sender string Transaction Creator Address
                        contractAddress string contract address
                transfer object Business Data for Contract Transfer Transactions
                         orginTxHash string call contract transaction hash (source transaction hash, contract transaction is derived from calling contract transaction)
                        contractAddress string contract address
contractResult object Contract execution results
        success boolean Successful contract execution
        errorMessage string Execution Failure Information
        contractAddress string Contract Address
        result string Contract execution results
        gasLimit long GAS Limit
        gasUsed long GAS has been used
        price long GAS unit price
        totalFee string Total Transaction Fees
        txSizeFee string Transaction Size Fees
        actualContractFee string Actual Execution Contract Fee
        refundFee string Fees returned by the contract
        value string The amount of the primary network asset that the caller transferred to the contract address, or 0 if there is no such service
        stackTrace string Exception Stack Trace
        transfers list<object> Contract Transfer List (from contract)
                txHash string Contract Generation Transaction: Contract Transfer Transaction hash
                from string Transferred contract address
                value string Transfer amount
                outputs list<object> Transferred Address List
                        to string transfer address
                        value string Transfer amount
                orginTxHash string Call contract transaction hash (source transaction hash, contract transaction is called Contract trading is derived)
        events list<string> Contract Event List
        tokenTransfers list<object> Contract Token Transfer List
                contractAddress string contract address
                from string payment
                to string Payee
                value string Transfer amount
                name string token name
                symbol string token symbol
                decimals long Number of decimal places supported by token
        invokeRegisterCmds list<object> Contract Call List of Calls for External Commands
                cmdName string command name
                args map command parameters, parameters are not fixed, depending on different commands Therefore, it is not described here, and the structure is {parameter name=parameter value}
                cmdRegisterMode string Registered Command Mode (QUERY_DATA or NEW_TX)
                newTxHash string generated transaction hash (when the command mode is called NEW\ When _TX, a transaction will be generated)
        contractTxList list<string> Serialized String List for Contract Generation Transactions
        remark string Notes

# sc_token_assets_list

Token asset collection/token assets list

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int Chain ID Yes
address string account address yes
pageNumber int Page Number No
pageSize int per page size no

# return value

Field Name Field Type Parameter Description
contractAddress string contract address
name string token name
symbol string token symbol
amount string token quantity
decimals long Number of decimal places supported by token
blockHeight long Block Height at Contract Creation
status int Contract Status (0-None, 1-Normal, 2-End)

# sc_token_transfer_list

Token transfer transaction list/token transfer list

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int Chain ID Yes
address string account address yes
pageNumber int Page Number No
pageSize int per page size no

# return value

Field Name Field Type Parameter Description
contractAddress string contract address
from string Payment Party
to string Receiver
value string Transfer amount
time long Trading Hours
status byte Transaction Status (0 - Confirmation, 1 - Confirmed, 2 - Failed)
txHash string Trading hash
blockHeight long Block Height
name string token name
symbol string token symbol
decimals long Number of decimal places supported by token
info string token asset change information

# sc_account_contracts

Account's contract address list / account contract list

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int Chain ID Yes
address string account address yes
pageNumber int Page Number No
pageSize int per page size no

# return value

Field Name Field Type Parameter Description
contractAddress string contract address
createTime long contract creation time
height long block height at contract creation
confirmCount long Contract Creation Confirmation Times
alias string contract alias
status int Contract Status (0 - does not exist or is created, 1 - normal, 2 - deleted, 3 - failed to create, 4 - locked)
msg string Error message for contract creation failure

# sc_upload

Contract code jar package upload /upload

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
jarFileData string File description and file byte stream conversion Base64 encoded string (file description and Base64 string separated by commas) Yes

# return value

Field Name Field Type Parameter Description
Constructor object contract constructor details
        name string method name
        desc string Method Description
        args list<object> Method parameter list
                type string Parameter Type
                name string Parameter Name
                required boolean Required
        returnArg string Return value type
        view boolean Whether view method (calling this method data is not on the chain)
        event boolean Whether it is an event
        payable boolean Is it acceptable to transfer the main chain asset
        jsonSerializable boolean Method Returns whether JSON is serialized
isNrc20 boolean Is it a NRC20 contract
code string Smart Contract Code (Hex encoded string of bytecode)

# sc_call

call contract

# scope:public

# version:1.0

# parameter list

Parameter Name Parameter Type Parameter Description Is Not Empty
chainId int chain id yes
sender string Transaction Creator Account Address Yes
password string caller account password yes
value biginteger The amount of the primary network asset that the caller transferred to the contract address. If there is no such service, fill BigInteger.ZERO Yes
gasLimit long GAS Limit Yes
price long GAS unit price Yes
contractAddress string contract address yes
methodName string contract method yes
methodDesc string Contract method description, if the method in the contract is not overloaded, this parameter can be empty No
args object[] List of parameters No
remark string Transaction Notes No

# return value

Field Name Field Type Parameter Description
txHash string Call contract trading hash
Last Updated: 2/2/2020, 7:47:31 AM