@platonnetwork/web3-eth-personal 0.11.0 on npm

Web3.js Interface

Interact with nodes through web3 objects provided by web3.js. On the underlying implementation, it communicates with the local node through RPC calls. web3.js can connect to any PlatON node that exposes the RPC interface.

Usage

First, make sure the nodeJS environment is successfully installed locally. WEB3.JS uses the lerna management tool to optimize the workflow of the multi-package code base hosted on git/npm, so you should make sure the lerna package has been installed globally before installing. If not, execute the command npm i lerna -g for global installation.

Then you can integrate client-sdk-js into the project through package management tools such as npm or yarn, the steps are as follows:

npm: npm i PlatONnetwork/client-sdk-js#master
yarn: yarn add PlatONnetwork/client-sdk-js#master

Create a web3 instance and set up a provider. You can refer to the following code:

// in node.js
var Web3 = require('web3');

var web3 = new Web3('http://127.0.0.1:6789');
console.log(web3);
> {
    platon: ... ,
    utils: ...,
    ppos: ...,
    ...
}

After successful introduction, you can use the relevant API of web3.

API Reference

web3.version

web3.version: Contains the current package version of the web3.js library.

Method:

Web3.version
web3.version

Returns:

String: Current version number.

Example:

web3.version;
> "0.13.1"

web3.modules

web3.modules Will return an object with the classes of all major sub modules, to be able to instantiate them manually.

Method:

Web3.modules
web3.modules

Returns:

Object: A list of module constructors:

Platon - Function: The PlatON module for interacting with the PlatON network see web3.platon for more.
Net - Function: The Net module for interacting with network properties see web3.platon.net for more.
Personal - Function: The Personal module for interacting with the PlatON accounts see web3.platon.personal for more.

Example:

web3.modules
> {
    Platon: Platon function(provider),
    Net: Net function(provider),
    Personal: Personal function(provider)
}

web3.setProvider

web3.setProvider() Will change the provider for it's module.

Method:

web3.setProvider(myProvider)
web3.platon.setProvider(myProvider)
...

Notes: When called on the umbrella package web3 it will also set the provider for all sub modules web3.platon, web3.shh, etc EXCEPT web3.bzz which needs a separate provider at all times.

Parameter:

Object - myProvider: a valid provider.

Returns:

Boolean

Example:

var Web3 = require('web3');
var web3 = new Web3('http://localhost:8545');
// or
var web3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545'));

// change provider
web3.setProvider('ws://localhost:8546');
// or
web3.setProvider(new Web3.providers.WebsocketProvider('ws://localhost:8546'));

web3.providers

Contains the current available providers.

Method:

web3.providers
web3.platon.providers
...

Returns:

Object， with the following providers:

Object - HttpProvider: The HTTP provider is deprecated, as it won’t work for subscriptions.
Object - WebsocketProvider: The Websocket provider is the standard for usage in legacy browsers.

Example:

var Web3 = require('web3');
// // use the given Provider, e.g in Mist, or instantiate a new websocket provider.
var web3 = new Web3(Web3.givenProvider || 'ws://remotenode.com:8546');
// or
var web3 = new Web3(Web3.givenProvider || new Web3.providers.WebsocketProvider('ws://remotenode.com:8546'));

web3.givenProvider

When using web3.js in an PlatON compatible browser, it will set with the current native provider by that browser. Will return the given provider by the (browser) environment, otherwise null.

Method:

web3.givenProvider
web3.platon.givenProvider
...

Returns:

Object: The given provider set or null;

web3.currentProvider

web3.currentProvider Will return the current provider, otherwise null.

Method:

web3.currentProvider
web3.platon.currentProvider
...

Returns:

Object： The current provider set or null;

web3.BatchRequest

web3.BatchRequest Class to create and execute batch requests.

Method:

new web3.BatchRequest()
new web3.platon.BatchRequest()

Parameter:

none

Returns:

Object: With the following methods:

add(request): To add a request object to the batch call.
execute(): Will execute the batch request.

Example:

var contract = new web3.platon.Contract(abi, address);

var batch = new web3.BatchRequest();
batch.add(web3.platon.getBalance.request('lax1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmscn5j', 'latest', callback));
batch.add(contract.methods.balance(address).call.request({from: 'lax1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqmscn5j'}, callback2));
batch.execute();

web3.platon.defaultAccount

web3.platon.defaultAccount This default address is used as the default "from" property, if no "from" property is specified in the following methods:

web3.platon.sendTransaction()
web3.platon.call()
new web3.platon.Contract() -> myContract.methods.myMethod().call()
new web3.platon.Contract() -> myContract.methods.myMethod().send()

Method:

web3.platon.defaultAccount

Property：

String - 20 Bytes: 20 Bytes: Any PlatON address. You should have the private key for that address in your node or keystore. (Default is undefined)

Example:

web3.platon.defaultAccount;
> undefined

// set the default account
web3.platon.defaultAccount = 'atx1fyeszufxwxk62p46djncj86rd553skpph926ws';

Note:

All addresses must be quoted, as above: 'lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6'.

web3.platon.defaultBlock

web3.platon.defaultBlock The default block is used for certain methods.

web3.platon.getBalance()
web3.platon.getCode()
web3.platon.getTransactionCount()
web3.platon.getStorageAt()
web3.platon.call()
new web3.platon.Contract() -> myContract.methods.myMethod().call()

You can override it by passing in the defaultBlock as last parameter.

Method:

web3.platon.defaultBlock

Property:

Default block parameters can be one of the following:

Number: A block number
"genesis" - String: The genesis block
"latest" - String: The latest block (current head of the blockchain)
"pending" - String: The currently mined block (including pending transactions)

Default is "latest"

Example:

web3.platon.defaultBlock;
> "latest"

// set the default block
web3.platon.defaultBlock = 231;

web3.platon.getProtocolVersion

Returns the PlatON protocol version of the node.

Method:

web3.platon.getProtocolVersion([callback])

Returns:

Promise returns String: the protocol version.

Example:

web3.platon.getProtocolVersion().then(console.log);
> "63"

web3.platon.isSyncing

web3.platon.isSyncing() Checks if the node is currently syncing and returns either a syncing object, or false.

Method:

web3.platon.isSyncing([callback])

Returns:

Promise returns Object|Boolean - A sync object when the node is currently syncing or false:

startingBlock - Number: The block number where the sync started.
currentBlock - Number: The block number where at which block the node currently synced to already.
highestBlock - Number: The estimated block number to sync to.
knownStates - Number: The estimated states to download.
pulledStates - Number: The already downloaded states.

Example:

web3.platon.isSyncing().then(console.log);
> {
    startingBlock: 100,
    currentBlock: 312,
    highestBlock: 512,
    knownStates: 234566,
    pulledStates: 123455
}

web3.platon.getGasPrice

web3.platon.getGasPrice() Returns the current gas price oracle. The gas price is determined by the last few blocks median gas price.

Method:

web3.platon.getGasPrice([callback])

Returns:

Promise returns String - Number string of the current gas price in von.

Example:

web3.platon.getGasPrice().then(console.log);
> "20000000000"

web3.platon.getAccounts

web3.platon.getAccounts() Returns a list of accounts the node controls.

Method:

web3.platon.getAccounts([callback])

Returns:

Promise returns Array - An array of addresses controlled by node.

Example:

web3.platon.getAccounts().then(console.log);
> ["atx1fyeszufxwxk62p46djncj86rd553skpph926ws", "atx1kg7y7wfwzqsyxppyxcdvhkkkwlf64cclmnav7p"]

web3.platon.getBlockNumber

web3.platon.getBlockNumber() Returns the current block number.

Method:

web3.platon.getBlockNumber([callback])

Returns:

Promise returns Number - The number of the most recent block.

Example:

web3.platon.getBlockNumber().then(console.log);
> 2744

web3.platon.getBalance

web3.platon.getBalance() Get the balance of an address at a given block.

Method:

web3.platon.getBalance(address [, defaultBlock] [, callback])

Parameter:

address：String - The address to get the balance of.
defaultBlock：Number|String - (optional) If you pass this parameter it will not use the default block set with web3.platon.defaultBlock. Pre-defined block numbers as "latest", "earliest", "pending", and "genesis" can also be used.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns String - The current balance for the given address in von.

Example:

web3.platon.getBalance("atx1fyeszufxwxk62p46djncj86rd553skpph926ws")
.then(console.log);
> "1000000000000"

web3.platon.getStorageAt

web3.platon.getStorageAt() Get the storage at a specific position of an address.

Method:

web3.platon.getStorageAt(address, position [, defaultBlock] [, callback])

Parameter:

address - String: The address to get the storage from.
position - Number: The index position of the storage.
defaultBlock -Number|String (optional) If you pass this parameter it will not use the default block set with web3.platon.defaultBlock. Pre-defined block numbers as "latest", "earliest", "pending", and "genesis" can also be used.
callback -Function: (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns String - The value in storage at the given position.

Example:

web3.platon.getStorageAt("atx1fyeszufxwxk62p46djncj86rd553skpph926ws", 0)
.then(console.log);
> "0x033456732123ffff2342342dd12342434324234234fd234fd23fd4f23d4234"

web3.platon.getCode

web3.platon.getCode() Get the code at a specific address.

Method:

web3.platon.getCode(address [, defaultBlock] [, callback])

Parameter:

address - String: The address to get the code from.
defaultBlock - Number|String: (optional) If you pass this parameter it will not use the default block set with web3.platon.defaultBlock. Pre-defined block numbers as "latest", "earliest", "pending", and "genesis" can also be used.
callback - Function: (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns String - The data at given address.

Example:

web3.platon.getCode("atx1fyeszufxwxk62p46djncj86rd553skpph926ws")
.then(console.log);
> "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056"

web3.platon.getBlock

web3.platon.getBlock() Returns a block matching the block number or block hash.

Method:

web3.platon.getBlock(blockHashOrBlockNumber [, returnTransactionObjects] [, callback])

Parameter:

blockHashOrBlockNumber - String|Number: The block number or block hash. Or the string "genesis", "latest", "earliest", or "pending" as in the default block parameter.
returnTransactionObjects - Boolean: (optional, default false) If specified true, the returned block will contain all transactions as objects. By default it is false so, there is no need to explictly specify false. And, if false it will only contains the transaction hashes.
callback - Function: (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns Object - The block object:

number - Number: The block number. null when it's pending block.
hash 32 Bytes - String: Hash of the block. null when it's pending block.
parentHash 32 Bytes - String: Hash of the parent block.
nonce 8 Bytes - String: Hash of the generated proof-of-work. null when it's pending block.
sha3Uncles 32 Bytes - String: SHA3 of the uncles data in the block.
logsBloom 256 Bytes - String: The bloom filter for the logs of the block. null when it's pending block.
transactionsRoot 32 Bytes - String: The root of the transaction trie of the block
stateRoot 32 Bytes - String: The root of the final state trie of the block.
miner - String: The address of the beneficiary to whom the mining rewards were given.
difficulty - String: Integer of the difficulty for this block.
totalDifficulty - String: Integer of the total difficulty of the chain until this block.
extraData - String: The “extra data” field of this block.
size - Number: Integer the size of this block in bytes.
gasLimit - Number: The maximum gas allowed in this block.
gasUsed - Number: The total used gas by all transactions in this block.
timestamp - Number: The unix timestamp for when the block was collated.
transactions - Array: Array of transaction objects, or 32 Bytes transaction hashes depending on the returnTransactionObjects parameter.
uncles - Array: Array of uncle hashes.

Example:

web3.platon.getBlock(3150)
.then(console.log);

> {
    "number": 3,
    "hash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
    "parentHash": "0x2302e1c0b972d00932deb5dab9eb2982f570597d9d42504c05d9c2147eaf9c88",
    "nonce": "0xfb6e1a62d119228b",
    "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
    "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
    "transactionsRoot": "0x3a1b03875115b79539e5bd33fb00d8f7b7cd61929d5a3c574f507b8acf415bee",
    "stateRoot": "0xf1133199d44695dfa8fd1bcfe424d82854b5cebef75bddd7e40ea94cda515bcb",
    "miner": "atx1fyeszufxwxk62p46djncj86rd553skpph926ws",
    "difficulty": '21345678965432',
    "totalDifficulty": '324567845321',
    "size": 616,
    "extraData": "0x",
    "gasLimit": 3141592,
    "gasUsed": 21662,
    "timestamp": 1429287689,
    "transactions": [
        "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b"
    ],
    "uncles": []
}

web3.platon.getBlockTransactionCount

web3.platon.getBlockTransactionCount() Returns the number of transaction in a given block.

Method:

web3.platon.getBlockTransactionCount(blockHashOrBlockNumber [, callback])

Parameter:

blockHashOrBlockNumber - String|Number: The block number or hash. Or the string "genesis", "latest", "earliest", or "pending" as in the default block parameter.
callback - Function: (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns Number - The number of transactions in the given block.

Example:

web3.platon.getBlockTransactionCount("atx1fyeszufxwxk62p46djncj86rd553skpph926ws")
.then(console.log);
> 1

web3.platon.getTransaction

web3.platon.getTransaction() Returns a transaction matching the given transaction hash.

Method:

web3.platon.getTransaction(transactionHash [, callback])

Parameter:

transactionHash - String: The transaction hash.
callback - Function: (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns Object - A transaction object it's hash transactionHash:

hash 32 Bytes - String: Hash of the transaction.
nonce - Number: The number of transactions made by the sender prior to this one.
blockHash 32 Bytes - String: Hash of the block where this transaction was in. null when it's pending.
blockNumber - Number: Block number where this transaction was in. null when it's pending.
transactionIndex - Number: Integer of the transactions index position in the block. null when it's pending.
from - String: Address of the sender.
to - String: Address of the receiver. null when it's a contract creation transaction.
value - String: Value transferred in von.
gasPrice - String: Gas price provided by the sender in von.
gas - Number: Gas provided by the sender.
input - String: The data sent along with the transaction.

Example:

web3.platon.getTransaction('0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b§234')
.then(console.log);
> {
    "hash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",
    "nonce": 2,
    "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
    "blockNumber": 3,
    "transactionIndex": 0,
    "from": "atx14984xa8uuhkmer32s6tuz5e3valxa0ctxj9j67",
    "to": "atx1v227ux60dht9q3mk97fyanfk0st740u06lv59d",
    "value": '123450000000000000',
    "gas": 314159,
    "gasPrice": '2000000000000',
    "input": "0x57cb2fc4"
}

web3.platon.getTransactionFromBlock

web3.platon.getTransactionFromBlock() Returns a transaction based on a block hash or number and the transactions index position.

Method:

getTransactionFromBlock(hashStringOrNumber, indexNumber [, callback])

Parameter:

hashStringOrNumber：String - A block number or hash. Or the string "genesis", "latest", "earliest", or "pending" as in the default block parameter.
indexNumber：Number - The transactions index position.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns Object - A transaction object, see web3.eth.getTransaction:

Example:

var transaction = web3.platon.getTransactionFromBlock('0x4534534534', 2)
.then(console.log);
> // see web3.platon.getTransaction

web3.platon.getTransactionReceipt

web3.platon.getTransactionReceipt() Returns the receipt of a transaction by transaction hash.

Notes: The receipt is not available for pending transactions and returns null.

Method:

web3.platon.getTransactionReceipt(hash [, callback])

Parameter:

hash：String - The transaction hash.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns Object - A transaction receipt object, or null when no receipt was found:

status - Boolean: TRUE if the transaction was successful, FALSE, if the EVM reverted the transaction.
blockHash 32 Bytes - String: Hash of the block where this transaction was in.
blockNumber - Number: Block number where this transaction was in.
transactionHash 32 Bytes - String: Hash of the transaction.
transactionIndex- Number: Integer of the transactions index position in the block.
from - String: Address of the sender.
to - String: Address of the receiver. null when it's a contract creation transaction.
contractAddress - String: The contract address created, if the transaction was a contract creation, otherwise null.
cumulativeGasUsed - Number: The total amount of gas used when this transaction was executed in the block.
gasUsed - Number: The amount of gas used by this specific transaction alone.
logs - Array: Array of log objects, which this transaction generated.

Example:

var receipt = web3.platon.getTransactionReceipt('0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b')
.then(console.log);
> {
  "status": true,
  "transactionHash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",
  "transactionIndex": 0,
  "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
  "blockNumber": 3,
  "contractAddress": "lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6",
  "cumulativeGasUsed": 314159,
  "gasUsed": 30234,
  "logs": [{
         // logs as returned by getPastLogs, etc.
     }, ...]
}

web3.platon.getTransactionCount

web3.platon.getTransactionCount() Get the numbers of transactions sent from this address.

Method:

web3.platon.getTransactionCount(address [, defaultBlock] [, callback])

Parameter:

address：String - The address to get the numbers of transactions from.
defaultBlock：Number|String - (optional) If you pass this parameter it will not use the default block set with web3.platon.defaultBlock. Pre-defined block numbers as "latest", "earliest", "pending", and "genesis" can also be used.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns Number - The number of transactions sent from the given address.

Example:

web3.platon.getTransactionCount("lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6")
.then(console.log);
> 1

web3.platon.sendTransaction

web3.platon.sendTransaction() Sends a transaction to the network.

Method:

web3.platon.sendTransaction(transactionObject [, callback])

Parameter:

transactionObject：Object - The transaction object to send:
- from - String|Number: The address for the sending account. Uses the web3.platon.defaultAccount property, if not specified. Or an address or index of a local wallet in web3.platon.accounts.wallet.
- to - String: (optional) The destination address of the message, left undefined for a contract-creation transaction.
- value - Number|String|BN|BigNumber: (optional) The value transferred for the transaction in wei, also the endowment if it’s a contract-creation transaction.
- gas - Number: (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded).
- gasPrice - Number|String|BN|BigNumber: (optional) The price of gas for this transaction in wei, defaults to web3.platon.gasPrice.
- data - String: (optional) Either a ABI byte string containing the data of the function call on a contract, or in the case of a contract-creation transaction the initialisation code.
- nonce - Number: (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.
callback - Function: (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

web3.platon.sendTransaction() The callback will return the 32 bytes transaction hash.

PromiEvent: A promise combined event emitter. Will be resolved when the transaction receipt is available. Additionally the following events are available:

"transactionHash" returns String: Is fired right after the transaction is sent and a transaction hash is available.
"receipt" returns Object: Is fired when the transaction receipt is available.
"confirmation" returns Number, Object: Is fired for every confirmation up to the 12th confirmation. Receives the confirmation number as the first and the receipt as the second argument. Fired from confirmation 0 on, which is the block where it's minded.
"error" returns Error and Object|undefined: Is fired if an error occurs during sending. If the transaction was rejected by the network with a receipt, the second parameter will be the receipt.

Example:

// compiled solidity source code using https://remix.ethereum.org
var code = "603d80600c6000396000f3007c01000000000000000000000000000000000000000000000000000000006000350463c6888fa18114602d57005b6007600435028060005260206000f3";

// using the callback
web3.platon.sendTransaction({
    from: 'atx1mc9jj4nf487e840j3k0vshjq7n9kj7aw9qvc0x',
    data: code // deploying a contracrt
}, function(error, hash){
    ...
});

// using the promise
web3.platon.sendTransaction({
    from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv',
    to: 'lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6',
    value: '1000000000000000'
})
.then(function(receipt){
    ...
});


// using the event emitter
web3.platon.sendTransaction({
    from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv',
    to: 'lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6',
    value: '1000000000000000'
})
.on('transactionHash', function(hash){
    ...
})
.on('receipt', function(receipt){
    ...
})
.on('confirmation', function(confirmationNumber, receipt){ ... })
.on('error', console.error); // If a out of gas error, the second parameter is the receipt.

web3.platon.sendSignedTransaction

web3.platon.sendSignedTransaction() Sends an already signed transaction, generated for example using web3.platon.accounts.signTransaction.

Method:

web3.platon.sendSignedTransaction(signedTransactionData [, callback])

Parameter:

signedTransactionData：String - Signed transaction data in HEX format.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

PromiEvent: A promise combined event emitter. Will be resolved when the transaction receipt is available.

Please see the return values for web3.platon.sendTransaction for details.

Example:

var Web3 = require("web3");
const transaction_demo = async function () {
    web3 = new Web3("http://127.0.0.1:6789");
    var privateKey="0xb416b341437c420a45cb6ba5ca883655eec169360d36866124d23682c03766ba";
    // 主网地址
    let from = web3.platon.accounts.privateKeyToAccount(privateKey).address;
    let nonce = web3.utils.numberToHex(await web3.platon.getTransactionCount(from));
    let tx = {
        from:from,
        to: "atp1j9x482k50kl86qvx5cyw7hp48qcx5mezayxj8t",
        value: "1000000000000000000",
        chainId: 201018,
        gasPrice: "10000000000000", 
        gas: "21000", 
        nonce: nonce,
    };
    // 签名交易
    let signTx = await web3.platon.accounts.signTransaction(tx, privateKey);
    // 发送交易
    let receipt = await web3.platon.sendSignedTransaction(signTx.rawTransaction);
    console.log("sign tx data:\n", signTx.rawTransaction)
}

web3.platon.sign

web3.platon.sign() Signs data using a specific account. This account needs to be unlocked.

Method:

web3.platon.sign(dataToSign, address [, callback])

Parameter:

dataToSign：String - Data to sign. If String it will be converted using web3.utils.utf8ToHex.
address：String|Number - Address to sign data with. Or an address or index of a local wallet in web3.platon.accounts.wallet.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns String - The signature.

Example:

web3.platon.sign("Hello world", "lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6")
.then(console.log);
> "0x30755ed65396facf86c53e6217c52b4daebe72aa4941d89635409de4c9c7f9466d4e9aaec7977f05e923889b33c0d0dd27d7226b6e6f56ce737465c5cfd04be400"

// the below is the same
web3.platon.sign(web3.utils.utf8ToHex("Hello world"), "lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6")
.then(console.log);
> "0x30755ed65396facf86c53e6217c52b4daebe72aa4941d89635409de4c9c7f9466d4e9aaec7977f05e923889b33c0d0dd27d7226b6e6f56ce737465c5cfd04be400"

web3.platon.signTransaction

web3.platon.signTransaction() Signs a transaction. This account needs to be unlocked.

Method:

web3.platon.signTransaction(transactionObject, address [, callback])

Parameter:

transactionObject：Object - The transaction data to sign web3.eth.sendTransaction() for more.
address：String - Address to sign transaction with.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns Object - The RLP encoded transaction. The raw property can be used to send the transaction using web3.platon.sendSignedTransaction.

Example:

web3.platon.signTransaction({
    from: "atx1avq5lrytgxxmddzhwnpjdg8xf3ufznwql8t8dx",
    gasPrice: "20000000000",
    gas: "21000",
    to: 'atx1x56n2df4x56n2df4x56n2df4x56n2df4fcrvnj',
    value: "1000000000000000000",
    data: ""
}).then(console.log);
> {
    raw: '0xf86c808504a817c800825208943535353535353535353535353535353535353535880de0b6b3a76400008025a04f4c17305743700648bc4f6cd3038ec6f6af0df73e31757007b7f59df7bee88da07e1941b264348e80c78c4027afc65a87b0a5e43e86742b8ca0823584c6788fd0',
    tx: {
        nonce: '0x0',
        gasPrice: '0x4a817c800',
        gas: '0x5208',
        to: 'atx1x56n2df4x56n2df4x56n2df4x56n2df4fcrvnj',
        value: '0xde0b6b3a7640000',
        input: '0x',
        v: '0x25',
        r: '0x4f4c17305743700648bc4f6cd3038ec6f6af0df73e31757007b7f59df7bee88d',
        s: '0x7e1941b264348e80c78c4027afc65a87b0a5e43e86742b8ca0823584c6788fd0',
        hash: '0xda3be87732110de6c1354c83770aae630ede9ac308d9f7b399ecfba23d923384'
    }
}

web3.platon.estimateGas

web3.platon.estimateGas() Executes a message call or transaction and returns the amount of the gas used.

Method:

web3.platon.estimateGas(callObject [, callback])

Parameter:

callObject：Object - A transaction object see web3.platon.sendTransaction, with the difference that for calls the from property is optional as well.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns Number - the used gas for the simulated call/transaction.

Example:

web3.platon.estimateGas({
    to: "lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6",
    data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003"
})
.then(console.log);
> "0x0000000000000000000000000000000000000000000000000000000000000015"

web3.platon.getPastLogs

web3.platon.getPastLogs() Gets past logs, matching the given options.

Method:

web3.platon.getPastLogs(options [, callback])

Parameter:

options：Object - The filter options as follows:
- fromBlock - Number|String: The number of the earliest block ("latest" may be given to mean the most recent and "pending" currently mining, block). By default "latest".
- toBlock - Number|String: The number of the latest block ("latest" may be given to mean the most recent and "pending" currently mining, block). By default "latest".
- address - String|Array: An address or a list of addresses to only get logs from particular account(s).
- topics - Array: An array of values which must each appear in the log entries. The order is important, if you want to leave topics out use null, e.g. [null, '0x12...']. You can also pass an array for each topic with options for that topic e.g. [null, ['option1', 'option2']]

Returns:

Promise returns Array - Array of log objects.

The structure of the returned event Object in the Array looks as follows:

address - String: From which this event originated from.
data - String: The data containing non-indexed log parameter.
topics - Array: An array with max 4 32 Byte topics, topic 1-3 contains indexed parameters of the log.
logIndex - Number: Integer of the event index position in the block.
transactionIndex - Number: Integer of the transaction’s index position, the event was created in.
transactionHash 32 Bytes - String: Hash of the transaction this event was created in.
blockHash 32 Bytes - String: Hash of the block where this event was created in. null when it's still pending.
blockNumber - Number: The block number where this log was created in. null when it's still pending.

Example:

web3.platon.getPastLogs({
    address: "lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6",
    topics: ["0x033456732123ffff2342342dd12342434324234234fd234fd23fd4f23d4234"]
})
.then(console.log);

> [{
    data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
    topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
    logIndex: 0,
    transactionIndex: 0,
    transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
    blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    blockNumber: 1234,
    address: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'
},{...}]

web3.platon.subscribe

The web3.platon.subscribe function lets you subscribe to specific events in the blockchain.

Method:

web3.platon.subscribe(type [, options] [, callback]);

Parameter:

type：String - The subscription, you want to subscribe to.
options：Mixed - (optional) Optional additional parameters, depending on the subscription type.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription, and the subscription itself as 3 parameter.

Returns:

EventEmitter - A Subscription instance:

subscription.id: The subscription id, used to identify and unsubscribing the subscription.
subscription.subscribe([callback]): Can be used to re-subscribe with the same parameters.
subscription.unsubscribe([callback]): Unsubscribes the subscription and returns TRUE in the callback if successfull.
subscription.arguments: The subscription arguments, used when re-subscribing. on("data") returns Object: Fires on each incoming log with the log object as argument.
on("changed") returns Object: Fires on each log which was removed from the blockchain. The log will have the additional property "removed: true".
on("error") returns Object: Fires when an error in the subscription occurs.
on("connected") returns String: Fires once after the subscription successfully connected. Returns the subscription id.

Notification returns:

Mixed - depends on the subscription, see the different subscriptions for more.

Example:

var subscription = web3.platon.subscribe('logs', {
    address: 'atx..',
    topics: ['atx...']
}, function(error, result){
    if (!error)
        console.log(log);
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

web3.platon.clearSubscriptions

web3.platon.clearSubscriptions() Resets subscriptions. This will not reset subscriptions from other packages like web3-shh, as they use their own requestManager.

Method:

web3.platon.clearSubscriptions(flag)

Parameters:

flag：Boolean - 值为true则表示保持同步订阅

Returns:

Boolean： If true it keeps the "syncing" subscription.

Example:

web3.platon.subscribe('logs', {} ,function(){ ... });

...

web3.platon.clearSubscriptions();

web3.platon.subscribe("pendingTransactions")

pendingTransactions Subscribes to incoming pending transactions.

Method:

web3.platon.subscribe('pendingTransactions' [, callback]);

Parameter:

type：String - "pendingTransactions"，the type of the subscription.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

Returns:

EventEmitter: An subscription instance as an event emitter with the following events:

"data" returns String: Fires on each incoming pending transaction and returns the transaction hash.
"error" returns Object: Fires when an error in the subscription occurs.

Notification returns:

Object|Null - First parameter is an error object if the subscription failed.
Object - Second parameter is the transaction hash.

Example:

var subscription = web3.platon.subscribe('pendingTransactions', function(error, result){
    if (!error)
        console.log(result);
})
.on("data", function(transaction){
    console.log(transaction);
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

web3.platon.subscribe('newBlockHeaders')

newBlockHeaders Subscribes to incoming block headers. This can be used as timer to check for changes on the blockchain.

Method:

web3.platon.subscribe('newBlockHeaders' [, callback]);

Parameter:

type：String - "newBlockHeaders", the type of the subscription.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

Returns:

EventEmitter: An subscription instance as an event emitter with the following events:

"data" returns Object: Fires on each incoming block header.
"error" returns Object: Fires when an error in the subscription occurs.

The structure of a returned block header is as follows:

number - Number: The block number. null when it's pending block.
hash 32 Bytes - String: Hash of the block. null when it's pending block.
parentHash 32 Bytes - String: Hash of the parent block.
nonce 8 Bytes - String: Hash of the generated proof-of-work. null when it's pending block.
sha3Uncles 32 Bytes - String: SHA3 of the uncles data in the block.
logsBloom 256 Bytes - String: The bloom filter for the logs of the block. null when it's pending block.
transactionsRoot 32 Bytes - String: The root of the transaction trie of the block
stateRoot 32 Bytes - String: The root of the final state trie of the block.
receiptsRoot 32 Bytes - String: The root of the receipts.
miner - String: The address of the beneficiary to whom the mining rewards were given.
extraData - String: The “extra data” field of this block.
gasLimit - Number: The maximum gas allowed in this block.
gasUsed - Number: The total used gas by all transactions in this block.
timestamp - Number: The unix timestamp for when the block was collated.

Notification returns:

Object|Null - First parameter is an error object if the subscription failed.
Object - The block header object like above.

Example:

var subscription = web3.platon.subscribe('newBlockHeaders', function(error, result){
    if (error)
        console.log(error);
})
.on("data", function(blockHeader){
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

web3.platon.subscribe('syncing')

syncing Subscribe to syncing events. This will return an object when the node is syncing and when it's finished syncing will return FALSE.

Method:

web3.platon.subscribe('syncing' [, callback]);

Parameter:

type：String - "syncing", the type of the subscription.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second. Will be called for each incoming subscription.

Returns:

EventEmitter: An subscription instance as an event emitter with the following events:

"data" returns Object: Fires on each incoming sync object as argument.
"changed" returns Object: Fires when the synchronisation is started with true and when finished with false.
"error" returns Object: Fires when an error in the subscription occurs.

For the structure of a returned event Object see web3.platon.isSyncing return values.

Notification returns:

Object|Null - First parameter is an error object if the subscription failed.
Object|Boolean - The syncing object, when started it will return true once or when finished it will return false once.

Example:

var subscription = web3.platon.subscribe('syncing', function(error, sync){
    if (!error)
        console.log(sync);
})
.on("data", function(sync){
    // show some syncing stats
})
.on("changed", function(isSyncing){
    if(isSyncing) {
        // stop app operation
    } else {
        // regain app operation
    }
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

web3.platon.subscribe('logs')

Subscribes to incoming logs, filtered by the given options. If a valid numerical fromBlock options property is set, Web3 will retrieve logs beginning from this point, backfilling the response as necessary.

Method:

web3.platon.subscribe('logs', options [, callback]);

Parameter:

"logs" ：String, the type of the subscription.
options：Object - The subscription options:
- fromBlock - Number: The number of the earliest block. By default null.
- address - String|Array: An address or a list of addresses to only get logs from particular account(s).
- topics - Array: An array of values which must each appear in the log entries. The order is important, if you want to leave topics out use null, e.g. [null, '0x00...']. You can also pass another array for each topic with options for that topic e.g. [null, ['option1', 'option2']]
callback - Function: An array of values which must each appear in the log entries. The order is important, if you want to leave topics out use null, e.g. [null, '0x00...']. You can also pass another array for each topic with options for that topic e.g. [null, ['option1', 'option2']].

Returns:

EventEmitter: An subscription instance as an event emitter with the following events:

"data" returns Object: Fires on each incoming log with the log object as argument.
"changed" returns Object: returns Object: Fires on each log which was removed from the blockchain. The log will have the additional property "removed: true".
"error" returns Object: Fires when an error in the subscription occurs.

For the structure of a returned event Object see web3.platon.getPastEvents return values.

Notification returns:

Object|Null - First parameter is an error object if the subscription failed.
Object - The log object like in web3.platon.getPastEvents return values.

Example:

var subscription = web3.platon.subscribe('logs', {
    address: 'atx..',
    topics: ['atx...']
}, function(error, result){
    if (!error)
        console.log(result);
})
.on("data", function(log){
    console.log(log);
})
.on("changed", function(log){
});

// unsubscribes the subscription
subscription.unsubscribe(function(error, success){
    if(success)
        console.log('Successfully unsubscribed!');
});

web3.platon.Contract

The web3.platon.Contract object makes it easy to interact with smart contracts on the PlatON blockchain. When you create a new contract object you give it the json interface of the respective smart contract and web3 will auto convert all calls into low level ABI calls over RPC for you.

This allows you to interact with smart contracts as if they were JavaScript objects.

To use it standalone:

new web3.platon.Contract(jsonInterface[, address][, options])

Parameter:

jsonInterface - Object: The json interface for the contract to instantiate
address - String: (optional): The address of the smart contract to call.
options - Object : (optional): The options of the contract. Some are used as fallbacks for calls and transactions:
- from - String: The address transactions should be made from.
- gasPrice - String: The gas price in von to use for transactions.
- gas - Number: The maximum gas provided for a transaction (gas limit).
- data - String: The byte code of the contract. Used when the contract gets deployed.
- vmType - Number: The contract type. 0 means solidity contract, 1 means WASM contract. The default is the solidity contract. (New field)
- net_type - String: The network type. lat represents the primary network, lax represents the test network. The default is to the test network. (New field)

Returns:

Object: The contract instance with all it's methods and events.

Example:

var myContract = new web3.platon.Contract([...], 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv', {
    from: 'lax1zg69v7yszg69v7yszg69v7yszg69v7y3q7dnwf', // default from address
    gasPrice: '20000000000' // default gas price in wei, 20 gwei in this case
});

options

The options object for the contract instance. from, gas and gasPrice are used as fallback values when sending transactions.

Method:

myContract.options

options options:

address - String: The address where the contract is deployed.
jsonInterface - Array: The json interface of the contract.
data - String: The byte code of the contract.
from - String: The address transactions should be made from.
gasPrice - String: The gas price in von to use for transactions.
gas - Number: The maximum gas provided for a transaction (gas limit).

Example:

myContract.options;
> {
    address: 'atx1zg69v7yszg69v7yszg69v7yszg69v7y3ut4wvr',
    jsonInterface: [...],
    from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv',
    gasPrice: '10000000000000',
    gas: 1000000
}

myContract.options.from = 'lax1zg69v7yszg69v7yszg69v7yszg69v7y3q7dnwf'; // default from address
myContract.options.gasPrice = '20000000000000'; // default gas price in wei
myContract.options.gas = 5000000; // provide as fallback always 5M gas

options.address - contract address

The address used for this contract instance. All transactions generated by web3.js from this contract will contain this address as the “to”. The address will be stored in lowercase.

Method:

myContract.options.address

Property:

address - String|null: The address for this contract, or null if it’s not yet set.

Example:

myContract.options.address;
> 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'

// set a new address
myContract.options.address = 'lax...';

options.jsonInterface

jsonInterface The json interface object derived from the ABI of this contract.

Method:

myContract.options.jsonInterface

Property:

jsonInterface - Array: The json interface for this contract. Re-setting this will regenerate the methods and events of the contract instance.

Example:

myContract.options.jsonInterface;
> [{
    "type":"function",
    "name":"foo",
    "inputs": [{"name":"a","type":"uint256"}],
    "outputs": [{"name":"b","type":"address"}]
},{
    "type":"event",
    "name":"Event"
    "inputs": [{"name":"a","type":"uint256","indexed":true},{"name":"b","type":"bytes32","indexed":false}],
}]

// set a new interface
myContract.options.jsonInterface = [...];

deploy

Call this function to deploy the contract to the blockchain. After successful deployment the promise will resolve with a new contract instance.

Method:

myContract.deploy(options)

Parameter:

options - Object: The options used for deployment.

data - String: The byte code of the contract.
arguments - Array: (optional): The arguments which get passed to the constructor on deployment. If you deploy a WASM contract, you can refer to WASM contract parameter passing reference。

Returns:

Object: The transaction object:

arguments: Array - The arguments passed to the method before. They can be changed.
send: Function - Will deploy the contract. The promise will resolve with the new contract instance, instead of the receipt!
estimateGas: Function - Will estimate the gas used for deploying.
encodeABI: Function - Encodes the ABI of the deployment, which is contract data + constructor parameters

Example:

myContract.deploy({
    data: '0x12345...',
    arguments: [123, 'My String']
})
.send({
    from: 'atx1zg69v7yszg69v7yszg69v7yszg69v7y3ut4wvr',
    gas: 1500000,
    gasPrice: '30000000000000'
}, function(error, transactionHash){ ... })
.on('error', function(error){ ... })
.on('transactionHash', function(transactionHash){ ... })
.on('receipt', function(receipt){
   console.log(receipt.contractAddress) // contains the new contract address
})
.on('confirmation', function(confirmationNumber, receipt){ ... })
.then(function(newContractInstance){
    console.log(newContractInstance.options.address) // instance with the new contract address
});


// When the data is already set as an option to the contract itself
myContract.options.data = '0x12345...';

myContract.deploy({
    arguments: [123, 'My String']
})
.send({
    from: 'atx1zg69v7yszg69v7yszg69v7yszg69v7y3ut4wvr',
    gas: 1500000,
    gasPrice: '30000000000000'
})
.then(function(newContractInstance){
    console.log(newContractInstance.options.address) // instance with the new contract address
});


// Simply encoding
myContract.deploy({
    data: '0x12345...',
    arguments: [123, 'My String']
})
.encodeABI();
> '0x12345...0000012345678765432'


// Gas estimation
myContract.deploy({
    data: '0x12345...',
    arguments: [123, 'My String']
})
.estimateGas(function(err, gas){
    console.log(gas);
});

methods

Creates a transaction object for that method, which then can be called, send, estimated.

If it is a WASM contract, you can refer to WASM contract parameter passing reference。 Method:

myContract.methods.myMethod([param1[, param2[, ...]]])

The methods of this smart contract are available through:

The name: myContract.methods.myMethod(123)
The name with parameters: myContract.methods['myMethod(uint256)'](123)
The signature: myContract.methods['0x58cf5f10'](123)

This allows calling functions with same name but different parameters from the JavaScript contract object.

Parameter:

Parameters of any method depend on the smart contracts methods, defined in the JSON interface.

Returns:

Object: The transaction object:

arguments: Array - The arguments passed to the method before. They can be changed.
call: Function - Will call the “constant” method and execute it's smart contract method in the EVM without sending a transaction (Can’t alter the smart contract state).
send: Function - Will send a transaction to the smart contract and execute it's method (Can alter the smart contract state).
estimateGas: Function - Will estimate the gas used when the method would be executed on chain.
encodeABI: Function - Encodes the ABI for this method. This can be send using a transaction, call the method or passing into another smart contracts method as argument.

Example:

// calling a method
myContract.methods.myMethod(123).call({from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'}, function(error, result){
    ...
});

// or sending and using a promise
myContract.methods.myMethod(123).send({from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'})
.then(function(receipt){
    // receipt can also be a new contract instance, when coming from a "contract.deploy({...}).send()"
});

// or sending and using the events
myContract.methods.myMethod(123).send({from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'})
.on('transactionHash', function(hash){
    ...
})
.on('receipt', function(receipt){
    ...
})
.on('confirmation', function(confirmationNumber, receipt){
    ...
})
.on('error', console.error);

methods.myMethod.call

Will call a “constant” method and execute it's smart contract method in the EVM without sending any transaction. Note calling can not alter the smart contract state.

Method:

myContract.methods.myMethod([param1[, param2[, ...]]]).call(options[, callback])

Parameter:

options - Object : (optional): The options used for calling.
- from - String (optional): The address the call “transaction” should be made from.
- gasPrice - String (optional): The gas price in wei to use for this call “transaction”.
- gas - Number (optional): The maximum gas provided for this call “transaction” (gas limit).
callback - Function : (optional): This callback will be fired with the result of the smart contract method execution as the second argument, or with an error object as the first argument.

Returns:

Promise returns Mixed: The return value(s) of the smart contract method. If it returns a single value, it’s returned as is. If it has multiple return values they are returned as an object with properties and indices: Example:

// using the callback
myContract.methods.myMethod(123).call({from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'}, function(error, result){
    ...
});

// using the promise
myContract.methods.myMethod(123).call({from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'})
.then(function(result){
    ...
});

MULTI-ARGUMENT RETURN:

// Solidity
contract MyContract {
    function myFunction() returns(uint256 myNumber, string myString) {
        return (23456, "Hello!%");
    }
}

// web3.js
var MyContract = new web3.platon.contract(abi, address);
MyContract.methods.myFunction().call()
.then(console.log);
> Result {
    myNumber: '23456',
    myString: 'Hello!%',
    0: '23456', // these are here as fallbacks if the name is not know or given
    1: 'Hello!%'
}

SINGLE-ARGUMENT RETURN:

// Solidity
contract MyContract {
    function myFunction() returns(string myString) {
        return "Hello!%";
    }
}

Then in web3.js, the call method will also return a single value:

// web3.js
var MyContract = new web3.platon.contract(abi, address);
MyContract.methods.myFunction().call()
.then(console.log);
> "Hello!%"

send - methods.myMethod.send

Will send a transaction to the smart contract and execute it's method. Note this can alter the smart contract state.

Method:

myContract.methods.myMethod([param1[, param2[, ...]]]).send(options[, callback])

Parameter:

options - Object: The options used for sending.
- from - String: The address the transaction should be sent from.
- gasPrice - String: (optional): The gas price in von to use for this transaction.
- gas - Number: (optional): The maximum gas provided for this transaction (gas limit).
- value - Number|String|BN|BigNumber: (optional): The value transferred for the transaction in von.
callback - Function: (optional): This callback will be fired first with the “transactionHash”, or with an error object as the first argument.

Returns:

The callback will return the 32 bytes transaction hash.

PromiEvent: A promise combined event emitter. Will be resolved when the transaction receipt is available, OR if this send() is called from a someContract.deploy(), then the promise will resolve with the new contract instance. Additionally the following events are available:

"transactionHash" returns String: is fired right after the transaction is sent and a transaction hash is available.
"receipt" returns Object: is fired when the transaction receipt is available. Receipts from contracts will have no logs property, but instead an events property with event names as keys and events as properties. See getPastEvents return values for details about the returned event object.
"confirmation" returns Number, Object: is fired for every confirmation up to the 24th confirmation. Receives the confirmation number as the first and the receipt as the second argument. Fired from confirmation 1 on, which is the block where it’s minded.
"error" returns Error and Object|undefined: Is fired if an error occurs during sending. If the transaction was rejected by the network with a receipt, the second parameter will be the receipt.

Example:

// using the callback
myContract.methods.myMethod(123).send({from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'}, function(error, transactionHash){
    ...
});

// using the promise
myContract.methods.myMethod(123).send({from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'})
.then(function(receipt){
    // receipt can also be a new contract instance, when coming from a "contract.deploy({...}).send()"
});


// using the event emitter
myContract.methods.myMethod(123).send({from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'})
.on('transactionHash', function(hash){
    ...
})
.on('confirmation', function(confirmationNumber, receipt){
    ...
})
.on('receipt', function(receipt){
    // receipt example
    console.log(receipt);
    > {
        "transactionHash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",
        "transactionIndex": 0,
        "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",
        "blockNumber": 3,
        "contractAddress": "lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6",
        "cumulativeGasUsed": 314159,
        "gasUsed": 30234,
        "events": {
            "MyEvent": {
                returnValues: {
                    myIndexedParam: 20,
                    myOtherIndexedParam: '0x123456789...',
                    myNonIndexParam: 'My String'
                },
                raw: {
                    data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                    topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
                },
                event: 'MyEvent',
                signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                logIndex: 0,
                transactionIndex: 0,
                transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
                blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
                blockNumber: 1234,
                address: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'
            },
            "MyOtherEvent": {
                ...
            },
            "MyMultipleEvent":[{...}, {...}] // If there are multiple of the same event, they will be in an array
        }
    }
})
.on('error', console.error); // If there's an out of gas error the second parameter is the receipt.

estimateGas - methods.myMethod.estimateGas

Will call estimate the gas a method execution will take when executed in the EVM without. The estimation can differ from the actual gas used when later sending a transaction, as the state of the smart contract can be different at that time.

Method:

myContract.methods.myMethod([param1[, param2[, ...]]]).estimateGas(options[, callback])

Parameter:

options - Object: (optional): The options used for calling.
- from - String: (optional): The address the call “transaction” should be made from.
- gas - Number : (optional): The maximum gas provided for this call “transaction” (gas limit). Setting a specific value helps to detect out of gas errors. If all gas is used it will return the same number.
- value - Number|String|BN|BigNumber: (optional): The value transferred for the call “transaction” in von.
callback - Function : (optional): This callback will be fired with the result of the gas estimation as the second argument, or with an error object as the first argument.

Returns:

Promise returns Number: The gas amount estimated.

Example:

// using the callback
myContract.methods.myMethod(123).estimateGas({gas: 5000000}, function(error, gasAmount){
    if(gasAmount == 5000000)
        console.log('Method ran out of gas');
});

// using the promise
myContract.methods.myMethod(123).estimateGas({from: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'})
.then(function(gasAmount){
    ...
})
.catch(function(error){
    ...
});

encodeABI - methods.myMethod.encodeABI

Encodes the ABI for this method. This can be used to send a transaction, call a method, or pass it into another smart contracts method as arguments.

Method:

myContract.methods.myMethod([param1[, param2[, ...]]]).encodeABI()

Parameter:

none

Returns:

String: The encoded ABI byte code to send via a transaction or call.

Example:

myContract.methods.myMethod(123).encodeABI();
> '0x58cf5f1000000000000000000000000000000000000000000000000000000000000007B'

events

Subscribe to an event.

Method:

myContract.events.MyEvent([options][, callback])

Parameter:

options - Object (optional): The options used for deployment：
- filter - Object (optional): Let you filter events by indexed parameters, e.g. {filter: {myNumber: [12,13]}} means all events where “myNumber” is 12 or 13.
- fromBlock - Number (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
- topics - Array (optional): This allows to manually set the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically.
callback - Function (optional): This callback will be fired for each event as the second argument, or an error as the first argument.

Returns:

EventEmitter: The event emitter has the following events:

"data" returns Object: Fires on each incoming event with the event object as argument.
"changed" returns Object: Fires on each event which was removed from the blockchain. The event will have the additional property "removed: true".
"error" returns Object: Fires when an error in the subscription occours.

The structure of the returned event Object looks as follows:

event - String: The event name.
signature - String|Null: The event signature, null if it’s an anonymous event.
address - String: Address this event originated from.
returnValues - Object: The return values coming from the event, e.g. {myVar: 1, myVar2: '0x234...'}.
logIndex - Number: Integer of the event index position in the block.
transactionIndex - Number: Integer of the transaction’s index position the event was created in.
transactionHash 32 Bytes - String Hash of the transaction this event was created in.
blockHash 32 Bytes - String: Hash of the block this event was created in. null when it’s still pending.
blockNumber - Number: The block number this log was created in. null when it's still pending.
raw.data - String: The data containing non-indexed log parameter.
raw.topics - Array: An array with max 4 32 Byte topics, topic 1-3 contains indexed parameters of the event.

Example:

myContract.events.MyEvent({
    filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
    fromBlock: 0
}, function(error, event){ console.log(event); })
.on('data', function(event){
    console.log(event); // same results as the optional callback above
})
.on('changed', function(event){
    // remove event from local database
})
.on('error', console.error);

// event output example
> {
    returnValues: {
        myIndexedParam: 20,
        myOtherIndexedParam: '0x123456789...',
        myNonIndexParam: 'My String'
    },
    raw: {
        data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
    },
    event: 'MyEvent',
    signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    logIndex: 0,
    transactionIndex: 0,
    transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
    blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    blockNumber: 1234,
    address: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'
}

events.allEvents

Method:

myContract.events.allEvents([options][, callback])

Same as events but receives all events from this smart contract. Optionally the filter property can filter those events.

getPastEvents

Gets past events for this contract.

Method:

myContract.getPastEvents(event[, options][, callback])

Parameter:

event - String: The name of the event in the contract, or "allEvents" to get all events.
options - Object (optional): The options used for deployment.
- filter - Object (optional): Lets you filter events by indexed parameters, e.g. {filter: {myNumber: [12,13]}} means all events where “myNumber” is 12 or 13.
- fromBlock - Number|String|BN|BigNumber (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
- toBlock - Number|String|BN|BigNumber (optional): The block number (less than or equal to) to get events up to (Defaults to "latest"). Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
- topics - Array (optional): This allows manually setting the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically.
callback - Function (optional): This callback will be fired with an array of event logs as the second argument, or an error as the first argument.

Returns:

Promise returns Array: An array with the past event Objects, matching the given event name and filter.

Example:

myContract.getPastEvents('MyEvent', {
    filter: {myIndexedParam: [20,23], myOtherIndexedParam: '0x123456789...'}, // Using an array means OR: e.g. 20 or 23
    fromBlock: 0,
    toBlock: 'latest'
}, function(error, events){ console.log(events); })
.then(function(events){
    console.log(events) // same results as the optional callback above
});

> [{
    returnValues: {
        myIndexedParam: 20,
        myOtherIndexedParam: '0x123456789...',
        myNonIndexParam: 'My String'
    },
    raw: {
        data: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
        topics: ['0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7', '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385']
    },
    event: 'MyEvent',
    signature: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    logIndex: 0,
    transactionIndex: 0,
    transactionHash: '0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385',
    blockHash: '0xfd43ade1c09fade1c0d57a7af66ab4ead7c2c2eb7b11a91ffdd57a7af66ab4ead7',
    blockNumber: 1234,
    address: 'lax1mc9jj4nf487e840j3k0vshjq7n9kj7awe459dv'
},{
    ...
}]

newFilter

newFilter creates a new filter and returns the filter id. It can be used to retrieve logs when the state changes.

Method:

myContract.newFilter(event[, options][, callback])

Parameter：

event - String: The name of the event in the contract, or "allEvents" to get all events.
options - Object (optional): The options used for deployment.
- filter - Object (optional): Lets you filter events by indexed parameters, e.g. {filter: {myNumber: [12,13]}} means all events where “myNumber” is 12 or 13.
- fromBlock - Number|String|BN|BigNumber (optional): The block number (greater than or equal to) from which to get events on. Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
- toBlock - Number|String|BN|BigNumber (optional): The block number (less than or equal to) to get events up to (Defaults to "latest"). Pre-defined block numbers as "latest", "earlist", "pending", and "genesis" can also be used.
- topics - Array (optional): This allows manually setting the topics for the event filter. If given the filter property and event signature, (topic[0]) will not be set automatically.
callback - Function (optional): This callback will be fired with an array of event logs as the second argument, or an error as the first argument.

Returns:

Returns a filter ID of type String.

Example:

myContract.newFilter(eventName, {
   filter: eventFilter,
   fromBlock: fromBlockNum,
   toBlock: "latest"
}, function(error, rpcId){ 
    console.log("rpcId:", rpcId); 
})

> rpcId: 0xa081d1f00117ade0e08769bb053ae7e

getFilterLogs

getFilterLogs returns the logs for the filter with the given id. If the filter could not be found an empty array of logs is returned.

Method:

myContract.getFilterLogs(rpcId[, callback])

Parameter：

rpcId- String: Filter ID, returned by calling the newFilter interface .

Returns:

Promise returns Array: An array with the past event Objects, matching the given event name and filter.

Example：

contract.getFilterLogs("0xa081d1f00117ade0e08769bb053ae7e", function(error, events){ 
     console.log(events); 
})

> [
  {
    address: 'lat1dw8t6q5jy6r3xqqkgc43nn403gpuzwx7penk3q',
    topics: [
      '0x0000000000000000000000000000000000000000007374727563744576656e74',
      '0x000000000000000000000000000000000000000000000000000000000000c180'
    ],
    data: '0xc0',
    blockNumber: '0x16375a',
    transactionHash: '0x59d68e32b6566877fb024f3ab356d9c5d2947f6f7a89bc4b34432496c34193d5',
    transactionIndex: '0x0',
    blockHash: '0x2843f645de8147cce62e6d18bb287c4cf06bbb6a3f3f5ec97917a7a09e300eee',
    logIndex: '0x0',
    removed: false
  }
]

Note: Read contract history events, which can be obtained using the newFilter and getFilterLogs interfaces.

web3.platon.personal

The web3-platon-personal package allows you to interact with the PlatON node’s accounts.

Notes: Many of these functions send sensitive information, like password. Never call these functions over a unsecured Websocket or HTTP provider, as your password will be sent in plain text!

Usage:

var Personal = require('web3.platon-personal');

// "Personal.providers.givenProvider" will be set if in an PlatON supported browser.
var personal = new Personal(Personal.givenProvider || 'ws://some.local-or-remote.node:8546');


// or using the web3 umbrella package

var Web3 = require('web3');
var web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546');

// -> web3.platon.personal

web3.platon.personal.newAccount

Creates a new account.

Notes: Never call this function over a unsecured Websocket or HTTP provider, as your password will be sent in plain text!

Method:

web3.platon.personal.newAccount(password, [callback])

Parameter:

password - String: The password to encrypt this account with.

Returns:

Promise returns String: The address of the newly created account.

Example:

web3.platon.personal.newAccount('!@superpassword')
.then(console.log);
> 'lax1uqug0zq7rcxddndleq4ux2ft3tv6dqljphydrl'

web3.platon.personal.sign

The sign method calculates an PlatON specific signature with:

Notes: Sending your account password over an unsecured HTTP RPC connection is highly unsecure.

Method:

web3.platon.personal.sign(dataToSign, address, password [, callback])

Parameter:

dataToSign：String - Data to sign. If String it will be converted using web3.utils.utf8ToHex.
address：String - Address to sign data with.
password：String - The password of the account to sign data with.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns String - The signature.

Example:

web3.platon.personal.sign("Hello world", "lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6", "test password!")
.then(console.log);
> "0x30755ed65396facf86c53e6217c52b4daebe72aa4941d89635409de4c9c7f9466d4e9aaec7977f05e923889b33c0d0dd27d7226b6e6f56ce737465c5cfd04be400"

// the below is the same
web3.platon.personal.sign(web3.utils.utf8ToHex("Hello world"), "lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6", "test password!")
.then(console.log);
> "0x30755ed65396facf86c53e6217c52b4daebe72aa4941d89635409de4c9c7f9466d4e9aaec7977f05e923889b33c0d0dd27d7226b6e6f56ce737465c5cfd04be400"

web3.platon.personal.ecRecover

Recovers the account that signed the data.

Method:

web3.platon.personal.ecRecover(dataThatWasSigned, signature [, callback])

Parameter:

dataThatWasSigned：String - Data that was signed. If String it will be converted using web3.utils.utf8ToHex.
signature：String - The signature.
Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns String - The account.

Example:

web3.platon.personal.ecRecover("Hello world", "0x30755ed65396facf86c53e6217c52b4daebe72aa4941d89635409de4c9c7f9466d4e9aaec7977f05e923889b33c0d0dd27d7226b6e6f56ce737465c5cfd04be400").then(console.log);
> "lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6"

web3.platon.personal.signTransaction

Signs a transaction. This account needs to be unlocked.

Notes: Sending your account password over an unsecured HTTP RPC connection is highly unsecure.

Method:

web3.platon.personal.signTransaction(transaction, password [, callback])

Parameter:

transaction：Object - The transaction data to sign web3.platon.sendTransaction() for more.
password：String - The password of the from account, to sign the transaction with.
callback：Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns:

Promise returns Object - The RLP encoded transaction. The raw property can be used to send the transaction using web3.platon.sendSignedTransaction.

Example:

web3.platon.signTransaction({
    from: "atx1avq5lrytgxxmddzhwnpjdg8xf3ufznwql8t8dx",
    gasPrice: "20000000000",
    gas: "21000",
    to: 'atx1x56n2df4x56n2df4x56n2df4x56n2df4fcrvnj',
    value: "1000000000000000000",
    data: ""
}, 'MyPassword!').then(console.log);
> {
    raw: '0xf86c808504a817c800825208943535353535353535353535353535353535353535880de0b6b3a76400008025a04f4c17305743700648bc4f6cd3038ec6f6af0df73e31757007b7f59df7bee88da07e1941b264348e80c78c4027afc65a87b0a5e43e86742b8ca0823584c6788fd0',
    tx: {
        nonce: '0x0',
        gasPrice: '0x4a817c800',
        gas: '0x5208',
        to: 'atx1x56n2df4x56n2df4x56n2df4x56n2df4fcrvnj',
        value: '0xde0b6b3a7640000',
        input: '0x',
        v: '0x25',
        r: '0x4f4c17305743700648bc4f6cd3038ec6f6af0df73e31757007b7f59df7bee88d',
        s: '0x7e1941b264348e80c78c4027afc65a87b0a5e43e86742b8ca0823584c6788fd0',
        hash: '0xda3be87732110de6c1354c83770aae630ede9ac308d9f7b399ecfba23d923384'
    }
}

web3.platon.abi

The web3.platon.abi functions let you de- and encode parameters to ABI (Application Binary Interface) for function calls to the EVM (Ethereum Virtual Machine).

Function List:

web3.platon.abi.encodeFunctionSignature
web3.platon.abi.encodeEventSignature
web3.platon.abi.encodeParameter
web3.platon.abi.encodeParameters
web3.platon.abi.encodeFunctionCall
web3.platon.abi.decodeParameter
web3.platon.abi.decodeParameters
web3.platon.abi.decodeLog

web3.platon.abi.encodeFunctionSignature

Encodes the function name to it's ABI signature, which are the first 4 bytes of the sha3 hash of the function name including types.

Method:

web3.platon.abi.encodeFunctionSignature(functionName);

Parameter:

functionName - String|Object: The function name to encode. or the JSON interface object of the function. If string it has to be in the form function(type,type,...), e.g: myFunction(uint256,uint32[],bytes10,bytes)

Returns:

String - The ABI signature of the function.

Example:

// From a JSON interface object
web3.platon.abi.encodeFunctionSignature({
    name: 'myMethod',
    type: 'function',
    inputs: [{
        type: 'uint256',
        name: 'myNumber'
    },{
        type: 'string',
        name: 'myString'
    }]
})
> 0x24ee0097

// Or string
web3.platon.abi.encodeFunctionSignature('myMethod(uint256,string)')
> '0x24ee0097'

web3.platon.abi.encodeEventSignature

Encodes the event name to it's ABI signature, which are the sha3 hash of the event name including input types.

Method:

web3.platon.abi.encodeEventSignature(eventName);

Parameter:

eventName - String|Object: The event name to encode. or the JSON interface object of the event. If string it has to be in the form event(type,type,...), e.g: myEvent(uint256,uint32[],bytes10,bytes)

Returns:

String - The ABI signature of the event.

Example:

// use params of string.
web3.platon.abi.encodeEventSignature('myEvent(uint256,bytes32)')
> 0xf2eeb729e636a8cb783be044acf6b7b1e2c5863735b60d6daae84c366ee87d97

// or from a json interface object
web3.platon.abi.encodeEventSignature({
    name: 'myEvent',
    type: 'event',
    inputs: [{
        type: 'uint256',
        name: 'myNumber'
    },{
        type: 'bytes32',
        name: 'myBytes'
    }]
})
> 0xf2eeb729e636a8cb783be044acf6b7b1e2c5863735b60d6daae84c366ee87d97

web3.platon.abi.encodeFunctionCall

Encodes a function call using it's JSON interface object and given paramaters.

Method:

web3.platon.abi.encodeFunctionCall(jsonInterface, parameters);

Parameter:

jsonInterface - Object: The JSON interface object of a function.
parameters - Array: The parameters to encode.

Returns:

String - The ABI encoded function call. Means function signature + parameters.

Example:

web3.platon.abi.encodeFunctionCall({
    name: 'myMethod',
    type: 'function',
    inputs: [{
        type: 'uint256',
        name: 'myNumber'
    },{
        type: 'string',
        name: 'myString'
    }]
}, ['2345675643', 'Hello!%']);
> "0x24ee0097000000000000000000000000000000000000000000000000000000008bd02b7b0000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000748656c6c6f212500000000000000000000000000000000000000000000000000"

web3.platon.abi.decodeParameter

Decodes an ABI encoded parameter to it's JavaScript type.

Method:

web3.platon.abi.decodeParameter(type, hexString);

Parameter:

type - String: The type of the parameter, see the solidity documentation for a list of types.
hexString - String: The ABI byte code to decode.

Returns:

Mixed - The decoded parameter.

Example:

web3.platon.abi.decodeParameter('uint256', '0x0000000000000000000000000000000000000000000000000000000000000010');
> "16"

web3.platon.abi.decodeParameter('string', '0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000848656c6c6f212521000000000000000000000000000000000000000000000000');
> "Hello!%!"

web3.platon.abi.decodeParameters

Decodes ABI encoded parameters to it's JavaScript types.

Method:

web3.platon.abi.decodeParameters(typesArray, hexString);

Parameter:

typesArray - Array|Object: An array with types or a JSON interface outputs array.
hexString - String: The ABI byte code to decode.

Returns:

Object - The result object containing the decoded parameters.

Example:

web3.platon.abi.decodeParameters(['string', 'uint256'], '0x000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000ea000000000000000000000000000000000000000000000000000000000000000848656c6c6f212521000000000000000000000000000000000000000000000000');
> Result { '0': 'Hello!%!', '1': '234' }

web3.platon.abi.decodeParameters([{
    type: 'string',
    name: 'myString'
},{
    type: 'uint256',
    name: 'myNumber'
}], '0x000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000ea000000000000000000000000000000000000000000000000000000000000000848656c6c6f212521000000000000000000000000000000000000000000000000');
> Result {
    '0': 'Hello!%!',
    '1': '234',
    myString: 'Hello!%!',
    myNumber: '234'
}

web3.platon.abi.decodeLog

Decodes ABI encoded log data and indexed topic data.

Method:

web3.platon.abi.decodeLog(inputs, hexString, topics);

Parameter:

inputs - Object: A JSON interface inputs array. See the solidity documentation for a list of types.
hexString - String: The ABI byte code in the data field of a log.
topics - Array: An array with the index parameter topics of the log, without the topic[0] if it's a non-anonymous event, otherwise with topic[0].

Returns:

Object - The result object containing the decoded parameters.

Example:

web3.platon.abi.decodeLog([{
    type: 'string',
    name: 'myString'
},{
    type: 'uint256',
    name: 'myNumber',
    indexed: true
},{
    type: 'uint8',
    name: 'mySmallNumber',
    indexed: true
}],
'0x0000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000748656c6c6f252100000000000000000000000000000000000000000000000000',
['0x000000000000000000000000000000000000000000000000000000000000f310', '0x0000000000000000000000000000000000000000000000000000000000000010']);
> Result {
    '0': 'Hello%!',
    '1': '62224',
    '2': '16',
    myString: 'Hello%!',
    myNumber: '62224',
    mySmallNumber: '16'
}

web3.utils

This package provides utility functions for PlatON dapps and other web3.js packages

Method:

Web3.utils
web3.utils

web3.utils.randomHex

The randomHex library to generate cryptographically strong pseudo-random HEX strings from a given byte size.

Method:

web3.utils.randomHex(size)

Parameter:

size - Number: The byte size for the HEX string, e.g. 32 will result in a 32 bytes HEX string with 64 characters preficed with “0x”.

Returns:

String: The generated random HEX string.

Example:

web3.utils.randomHex(32)
> "0xa5b9d60f32436310afebcfda832817a68921beb782fabf7915cc0460b443116a"

web3.utils.randomHex(4)
> "0x6892ffc6"

web3.utils.randomHex(2)
> "0x99d6"

web3.utils.randomHex(1)
> "0x9a"

web3.utils.randomHex(0)
> "0x"

web3.utils._

The underscore library for many convenience JavaScript functions.

See the underscore API reference for details.

Method:

web3.utils._

Example:

var _ = web3.utils._;

_.union([1,2],[3]);
> [1,2,3]

_.each({my: 'object'}, function(value, key){ ... })

web3.utils.BN

The BN.js library for calculating with big numbers in JavaScript. See the BN.js documentation for details.

Notes: For safe conversion of many types, incl BigNumber.js use utils.toBN

Method:

web3.utils.BN(mixed)

Parameter:

mixed - String|Number: A number, number string or HEX string to convert to a BN object.

Returns:

Object: The BN.js instance.

Example:

var BN = web3.utils.BN;

new BN(1234).toString();
> "1234"

new BN('1234').add(new BN('1')).toString();
> "1235"

new BN('0xea').toString();
> "234"

web3.utils.isBN

web3.utils.isBN() Checks if a given value is a BN.js instance.

Method:

web3.utils.isBN(bn)

Parameter:

bn - Object: An BN.js instance.

Returns:

Boolean

Example:

var number = new BN(10);

web3.utils.isBN(number);
> true

web3.utils.isBigNumber

Checks if a given value is a BigNumber.js instance.

Method:

web3.utils.isBigNumber(bignumber)

Parameter:

bignumber - Object: A BigNumber.js instance.

Returns:

Boolean

Example:

var number = new BigNumber(10);

web3.utils.isBigNumber(number);
> true

web3.utils.sha3

Will calculate the sha3 of the input.

Notes: To mimic the sha3 behaviour of solidity use soliditySha3.

Method:

web3.utils.sha3(string)
web3.utils.keccak256(string) // ALIAS

Parameter:

string - String: A string to hash.

Returns:

String: the result hash.

Example:

web3.utils.sha3('234'); // taken as string
> "0xc1912fee45d61c87cc5ea59dae311904cd86b84fee17cc96966216f811ce6a79"

web3.utils.sha3(new BN('234')); 
> "0xbc36789e7a1e281436464229828f817d6612f7b477d66591ff96a9e064bcc98a"

web3.utils.sha3(234); 
> null // can't calculate the has of a number

web3.utils.sha3(0xea); // same as above, just the HEX representation of the number
> null

web3.utils.sha3('0xea'); // will be converted to a byte array first, and then hashed
> "0x2f20677459120677484f7104c76deb6846a2c071f9b3152c103bb12cd54d1a4a"

web3.utils.soliditySha3

Will calculate the sha3 of given input parameters in the same way solidity would. This means arguments will be ABI converted and tightly packed before being hashed.

Method:

web3.utils.soliditySha3(param1 [, param2, ...])

Parameter:

paramX - Mixed: Any type, or an object with {type: 'uint', value: '123456'} or {t: 'bytes', v: '0xfff456'}. Basic types are autodetected as follows:

String non numerical UTF-8 string is interpreted as string.
String|Number|BN|HEX positive number is interpreted as uint256.
String|Number|BN negative number is interpreted as int256.
Boolean as bool.
String HEX string with leading 0x is interpreted as bytes.
HEX HEX number representation is interpreted as uint256.

Returns:

String: the result hash.

Example:

web3.utils.soliditySha3('234564535', '0xfff23243', true, -10);
// auto detects:        uint256,      bytes,     bool,   int256
> "0x3e27a893dc40ef8a7f0841d96639de2f58a132be5ae466d40087a2cfa83b7179"


web3.utils.soliditySha3('Hello!%'); // auto detects: string
> "0x661136a4267dba9ccdf6bfddb7c00e714de936674c4bdb065a531cf1cb15c7fc"


web3.utils.soliditySha3('234'); // auto detects: uint256
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"

web3.utils.soliditySha3(0xea); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"

web3.utils.soliditySha3(new BN('234')); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"

web3.utils.soliditySha3({type: 'uint256', value: '234'})); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"

web3.utils.soliditySha3({t: 'uint', v: new BN('234')})); // same as above
> "0x61c831beab28d67d1bb40b5ae1a11e2757fa842f031a2d0bc94a7867bc5d26c2"

web3.utils.soliditySha3('lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6');
> "0x4e8ebbefa452077428f93c9520d3edd60594ff452a29ac7d2ccc11d47f3ab95b"

web3.utils.soliditySha3({t: 'bytes', v: 'lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6'});
> "0x4e8ebbefa452077428f93c9520d3edd60594ff452a29ac7d2ccc11d47f3ab95b" // same result as above


web3.utils.soliditySha3({t: 'address', v: 'lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6'});
> "0x4e8ebbefa452077428f93c9520d3edd60594ff452a29ac7d2ccc11d47f3ab95b" //same as above, but will do a checksum check, if it's multi case


web3.utils.soliditySha3({t: 'bytes32', v: 'lax1fyeszufxwxk62p46djncj86rd553skpptsj8v6'});
> "0x3c69a194aaf415ba5d6afca734660d0a3d45acdc05d54cd1ca89a8988e7625b4" // different result as above


web3.utils.soliditySha3({t: 'string', v: 'Hello!%'}, {t: 'int8', v:-23}, {t: 'address', v: '0x85F43D8a49eeB85d32Cf465507DD71d507100C1d'});
> "0xa13b31627c1ed7aaded5aecec71baf02fe123797fffd45e662eac8e06fbe4955"

web3.utils.isHex

Checks if a given string is a HEX string.

Method:

web3.utils.isHex(hex)

Parameter:

hex - String|HEX: The given HEX string.

Returns:

Boolean：Returns true if the argument is a hexadecimal string, otherwise returns false.

Example:

web3.utils.isHex('0xc1912');
> true

web3.utils.isHex(0xc1912);
> true

web3.utils.isHex('c1912');
> true

web3.utils.isHex(345);
> true  // this is tricky, as 345 can be a a HEX representation or a number, be careful when not having a 0x in front!

web3.utils.isHex('0xZ1912');
> false

web3.utils.isHex('Hello');
> false

web3.utils.isHexStrict

Checks if a given string is a HEX string. Difference to web3.utils.isHex() is that it expects HEX to be prefixed with 0x.

Method:

web3.utils.isHexStrict(hex)

Parameter:

hex - String|HEX: The given HEX string.

Returns:

Boolean

Example:

web3.utils.isHexStrict('0xc1912');
> true

web3.utils.isHexStrict(0xc1912);
> false

web3.utils.isHexStrict('c1912');
> false

web3.utils.isHexStrict(345);
> false 

web3.utils.isHexStrict('0xZ1912');
> false

web3.utils.isHex('Hello');
> false

web3.utils.isAddress

Checks if a given string is a valid PlatON address. It will also check the checksum, if the address has upper and lowercase letters.

Method:

web3.utils.isAddress(address)

Parameter:

address - String: An address string.

Returns:

Boolean

Example:

web3.utils.isAddress('0xc1912fee45d61c87cc5ea59dae31190fffff232d');
> true

web3.utils.isAddress('c1912fee45d61c87cc5ea59dae31190fffff232d');
> true

web3.utils.isAddress('0XC1912FEE45D61C87CC5EA59DAE31190FFFFF232D');
> true // as all is uppercase, no checksum will be checked

web3.utils.isAddress('0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d');
> true

web3.utils.isAddress('0xC1912fEE45d61C87Cc5EA59DaE31190FFFFf232d');
> false // wrong checksum

web3.utils.isBech32Address

Check whether the specified character string is a valid address in bech32 format.

Method:

web3.utils.isBech32Address(bech32Address)

Parameter:

bech32Address - String: The address string to be checked in bech32 format; lax represents the test network address, and lat represents the main network address.

Returns:

Boolean: Valid address returns true, otherwise returns false.

Sample code:

web3.utils.isBech32Address('atx1zg69v7yszg69v7yszg69v7yszg69v7y3ut4wvr');
> true

web3.utils.isBech32Address('atp1zg69v7yszg69v7yszg69v7yszg69v7y3ut4wvr');
> false

web3.utils.isBech32Address('atp1zg69v7yszg69v7yszg69v7yszg69v7y3kdfylf');
> true

web3.utils.isBech32Address('atx1zg69v7yszg69v7yszg69v7yszg69v7y3kdfylf');
> false

web3.utils.toBech32Address

Convert a valid PlatON address to a bech32 format address of the designated network.

Method:

web3.utils.toBech32Address(hrp, address)

Parameters:

hrp - String: Specify the network parameters, lax indicates the test network address, and lat indicates the main network address.

address - String: PlatON address format string.

Returns:

String: Returns address string in bech32 format

Sample code:

web3.utils.toBech32Address('atx', '0x1234567890123456789012345678901234567891');
> 'atx1zg69v7yszg69v7yszg69v7yszg69v7y3ut4wvr'

web3.utils.toBech32Address('atp', '0x1234567890123456789012345678901234567891');
> 'atp1zg69v7yszg69v7yszg69v7yszg69v7y3kdfylf'

web3.utils.decodeBech32Address

Resolve the bech32 format address of the specified network into a valid PlatON address.

Method:

web3.utils.decodeBech32Address(hrp, bech32Address)

Parameters:

hrp - String: Specify the network parameters, lax indicates the test network address, and lat indicates the main network address.

bech32Address - String: Address string in bech32 format.

Returns:

String: The resolution correctly returns a valid PlatON address, otherwise it returns null.

Sample code:

web3.utils.decodeBech32Address('atx1zg69v7yszg69v7yszg69v7yszg69v7y3ut4wvr');
> '0x1234567890123456789012345678901234567891'

web3.utils.decodeBech32Address('atp1zg69v7yszg69v7yszg69v7yszg69v7y3kdfylf');
> '0x1234567890123456789012345678901234567891'

web3.utils.toChecksumAddress

Will convert an upper or lowercase PlatON address to a checksum address.

Method:

web3.utils.toChecksumAddress(address)

Parameter:

address - String: An address string.

Returns:

String: The checksum address.

Example:

web3.utils.toChecksumAddress('0xc1912fee45d61c87cc5ea59dae31190fffff2323');
> "0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d"

web3.utils.toChecksumAddress('0XC1912FEE45D61C87CC5EA59DAE31190FFFFF232D');
> "0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d" // same as above

web3.utils.checkAddressChecksum

Checks the checksum of a given address. Will also return false on non-checksum addresses.

Method:

web3.utils.checkAddressChecksum(address)

Parameter:

address - String: An address string.

Returns:

Boolean: true when the checksum of the address is valid, false if it's not a checksum address, or the checksum is invalid.

Example:

web3.utils.checkAddressChecksum('0xc1912fEE45d61C87Cc5EA59DaE31190FFFFf232d');
> true

web3.utils.toHex

Will auto convert any given value to HEX. Number strings will interpreted as numbers. Text strings will be interpreted as UTF-8 strings.

Method:

web3.utils.toHex(mixed)

Parameter:

mixed - String|Number|BN|BigNumber: The input to convert to HEX.

Returns:

String: The resulting HEX string.

Example:

web3.utils.toHex('234');
> "0xea"

web3.utils.toHex(234);
> "0xea"

web3.utils.toHex(new BN('234'));
> "0xea"

web3.utils.toHex(new BigNumber('234'));
> "0xea"

web3.utils.toHex('I have 100€');
> "0x49206861766520313030e282ac"

web3.utils.hexToNumberString

Returns the number representation of a given HEX value as a string.

Method:

web3.utils.hexToNumberString(hex)

Parameter:

hexString - String|HEX: A string to hash.

Returns:

String: The number as a string.

Example:

web3.utils.hexToNumberString('0xea');
> "234"

web3.utils.hexToNumber

Returns the number representation of a given HEX value.

This is not useful for big numbers, rather use utils.toBN instead.

Method:

web3.utils.hexToNumber(hex)
web3.utils.toDecimal(hex) // ALIAS, deprecated

Parameter:

hexString - String|HEX: A string to hash.

Returns:

Number

Example:

web3.utils.hexToNumber('0xea');
> 234

web3.utils.numberToHex

Returns the HEX representation of a given number value.

Method:

web3.utils.numberToHex(number)
web3.utils.fromDecimal(number) // ALIAS, deprecated

Parameter:

number - String|Number|BN|BigNumber: A number as string or number.

Returns:

String: The HEX value of the given number.

Example:

web3.utils.numberToHex('234');
> '0xea'

web3.utils.hexToUtf8

Returns the UTF-8 string representation of a given HEX value.

Method:

web3.utils.hexToUtf8(hex)
web3.utils.hexToString(hex) // ALIAS
web3.utils.toUtf8(hex) // ALIAS, deprecated

Parameter:

hex - String: A HEX string to convert to a UTF-8 string.

Returns:

String: The UTF-8 string.

Example:

web3.utils.hexToUtf8('0x49206861766520313030e282ac');
> "I have 100€"

web3.utils.hexToAscii

Returns the ASCII string representation of a given HEX value.

Method:

web3.utils.hexToAscii(hex)
web3.utils.toAscii(hex) // ALIAS, deprecated

Parameter:

hex - String: A HEX string to convert to a ASCII string.

Returns:

String: The ASCII string.

Example:

web3.utils.hexToAscii('0x4920686176652031303021');
> "I have 100!"

web3.utils.utf8ToHex

Returns the HEX representation of a given UTF-8 string.

Method:

web3.utils.utf8ToHex(string)
web3.utils.stringToHex(string) // ALIAS
web3.utils.fromUtf8(string) // ALIAS, deprecated

Parameter:

string - String: A UTF-8 string to convert to a HEX string.

Returns:

String: The HEX string.

Example:

web3.utils.utf8ToHex('I have 100€');
> "0x49206861766520313030e282ac"

web3.utils.asciiToHex

Returns the HEX representation of a given ASCII string.

Method:

web3.utils.asciiToHex(string)
web3.utils.fromAscii(string) // ALIAS, deprecated

Parameter:

string - String: A ASCII string to convert to a HEX string.

Returns:

String: The HEX string.

Example:

web3.utils.asciiToHex('I have 100!');
> "0x4920686176652031303021"

web3.utils.hexToBytes

Returns a byte array from the given HEX string.

Method:

web3.utils.hexToBytes(hex)

Parameter:

hex - String|HEX: A HEX to convert.

Returns:

Array: The byte array.

Example:

web3.utils.hexToBytes('0x000000ea');
> [ 0, 0, 0, 234 ]

web3.utils.hexToBytes(0x000000ea);
> [ 234 ]

web3.utils.toVon

Converts any lat value value into von.

von
kvon
mvon
gvon
microatp
milliatp
atp
katp
matp
gatp
tatp

'von':          '1',
'kvon':         '1000',
'mvon':         '1000000',
'gvon':         '1000000000',
'microatp':     '1000000000000',
'milliatp':     '1000000000000000',
'atp':          '1000000000000000000',
'katp':         '1000000000000000000000',
'matp':         '1000000000000000000000000',
'gatp':         '1000000000000000000000000000',
'tatp':         '1000000000000000000000000000000'

Method:

web3.utils.toVon(number [, unit])

Parameter:

number - String|Number|BN: The value.
unit - String，(optional, defaults to "lat"): The ether to convert from.

Returns:

String|BN: If a string is given it returns a number string, otherwise a BN.js instance.

Example:

web3.utils.toVon('1', 'atp');
> "1000000000000000000"

web3.utils.fromVon

Converts any von value into a lat value.

Method:

web3.utils.fromVon(number [, unit])

Converts any von value into a atp value.

Parameter:

number - String|Number|BN: The value in von. unit - String，(optional, defaults to "lat"): The ether to convert to. Possible units are:

von
kvon
mvon
gvon
microatp
milliatp
atp
katp
matp
gatp
tatp

Returns:

String|BN: It always returns a string number.

Example:

web3.utils.fromVon('1', 'atp');
> "0.000000000000000001"

web3.utils.padLeft

Adds a padding on the left of a string, Useful for adding paddings to HEX strings.

Method:

web3.utils.padLeft(string, characterAmount [, sign])
web3.utils.leftPad(string, characterAmount [, sign]) // ALIAS

Parameter:

string - String: The string to add padding on the left.
characterAmount - Number: The number of characters the total string should have.
sign - String(optional): The character sign to use, defaults to "0".

Returns:

String: The padded string.

Example:

web3.utils.padLeft('0x3456ff', 20);
> "0x000000000000003456ff"

web3.utils.padLeft(0x3456ff, 20);
> "0x000000000000003456ff"

web3.utils.padLeft('Hello', 20, 'x');
> "xxxxxxxxxxxxxxxHello"

Built-in Contract Call

Overview

The call or send function of ppos (the built-in contract related to the economic model) is used to convert the parameters passed into the parameters required by the rpc interface platon_call or platon_sendRawTransaction call, and then send the transaction to the node. And some helper functions needed to complete the call and send parameters.

Usage

When you call const web3 = new Web3('http://127.0.0.1:6789'); to instantiate a web3, the system will automatically append a ppos object after web3. In other words, you can use web3.ppos to call some methods of ppos. But if you want to use the ppos object to send transactions on the chain, in addition to the provider passed in when instantiating web3, you need to send at least the private key and chain id required for transaction signing, where the chain id can be passed through rpc Get chainId 'returned by interface admin_nodeInfo: xxx

Of course, in order to satisfy multiple ppos that can be instantiated arbitrarily (for example, I want to instantiate 3 ppos to different chains to send transaction calls at the same time), I will also attach a PPOS object to the web3 object (note all capitalization). You can call new PPOS (setting) to instantiate a ppos object. An example call is as follows:

(async () => {
    const Web3 = require('web3');
    const web3 = new Web3('http://192.168.120.164:6789');
    const ppos = web3.ppos; 

    // Update the configuration of ppos, this step must be done to send on-chain transactions.
    // Since the provider has been passed in when instantiating web3, it is not necessary to pass in the provider.
    ppos.updateSetting({
        privateKey: 'acc73b693b79bbb56f89f63ccc3a0c00bf1b8380111965bfe8ab22e32045600c',
        chainId: 104,
    })

    let data, reply;

    // Passing parameters to send transactions in the form of objects: 1000. createStaking (): initiate a pledge.
    const benefitAddress = 'lax1umevux40n6ljlclm4pmrh2ad7f0rld06hkzx3u';
    const nodeId = '80f1fcee54de74dbf7587450f31c31c0e057bedd4faaa2a10c179d52c900ca01f0fb255a630c49d83b39f970d175c42b12a341a37504be248d76ecf592d32bc0';
    const amount = '10000000000000000000000000000';
    const blsPubKey = 'd2459db974f49ca9cbf944d4d04c2d17888aef90858b62d6aec166341a6e886e8c0c0cfae9e469c2f618f5d9b7a249130d10047899da6154288c9cde07b576acacd75fef07ba0cfeb4eaa7510704e77a9007eff5f1a5f8d099e6ea664129780c';
    data = {
        funcType: 1000,
        typ: 0,
        benefitAddress: ppos.hexStrBuf(benefitAddress),
        nodeId: ppos.hexStrBuf(nodeId),
        externalId: 'externalId',
        nodeName: 'Me',
        website: 'www.platon.network',
        details: 'staking',
        amount: ppos.bigNumBuf(amount),
        rewardPer: 500, //传500就是5%的奖励作为委托奖励
        programVersion: undefined, // rpc get
        programVersionSign: undefined, // rpc get 
        blsPubKey: ppos.hexStrBuf(blsPubKey),
        blsProof: undefined, // rpc get 
    }
    let pv = await ppos.rpc('admin_getProgramVersion');
    let blsProof = await ppos.rpc('admin_getSchnorrNIZKProve');
    data.programVersion = pv.Version;
    data.programVersionSign = pv.Sign;
    data.blsProof = ppos.hexStrBuf(blsProof);
    reply = await ppos.send(data);
    console.log('createStaking params object reply: ', JSON.stringify(reply, null, 2));

    // Sending transactions as an array： 1000. createStaking() : Initiate a pledge.
    data = [
        1000,
        0,
        ppos.hexStrBuf(benefitAddress),
        ppos.hexStrBuf(nodeId),
        'externalId',
        'Me',
        'www.platon.network',
        'staking',
        ppos.bigNumBuf(amount),
        500,
        pv.Version,
        pv.Sign,
        ppos.hexStrBuf(blsPubKey),
        ppos.hexStrBuf(blsProof)
    ];
    //Since it has been called above, the trade fair is on the chain, but the business will fail.
    reply = await ppos.send(data);
    console.log('createStaking params array reply: ', reply);

    // Passing parameters as objects： 1102. getCandidateList() : Query all real-time candidate lists.
    data = {
        funcType: 1102,
    }
    reply = await ppos.call(data);
    console.log('getCandidateList params object reply: ', reply);

    //Passing parameters as an array： 1102. getCandidateList() : Query all real-time candidate lists.
    data = [1102];
    reply = await ppos.call(data);
    console.log('getCandidateList params array reply: ', reply);

    // Re-instantiate a ppos1 object and call it.
    const ppos1 = new web3.PPOS({
        provider: 'http://127.0.0.1:6789',
        privateKey: '9f9b18c72f8e5154a9c59af2a35f73d1bdad37b049387fc6cea2bac89804293b',
        chainId: 201018,
    })
    reply = await ppos1.call(data);
})()

The log information is output as follows. In order to save space, there are cuts:

createStaking params object reply:  {
  "blockHash": "0xdddd6b12919b69169b63d17fece52e8632fe3d8b48166c8b4ef8fdee39a1f35c",
  "blockNumber": "0xb",
  "contractAddress": null,
  "cumulativeGasUsed": "0x14f34",
  "from": "atx1w9x7ye4qalarnl9v59zzhyn7tug9864rll39n7",
  "gasUsed": "0x14f34",
  "logs": [
    {
      "address": "lax1w9x7ye4qalarnl9v59zzhyn7tug9864rr2fc35",
      "topics": [
        "0xd63087bea9f1800eed943829fc1d61e7869764805baa3259078c1caf3d4f5a48"
      ],
      "data": "0xe3a27b22436f6465223a302c2244617461223a22222c224572724d7367223a226f6b227d",
      "blockNumber": "0xb",
      "transactionHash": "0x4bee71e351076a81482e2576e469a8dfaa76da9b6cc848265c10968d6de67364",
      "transactionIndex": "0x0",
      "blockHash": "0xdddd6b12919b69169b63d17fece52e8632fe3d8b48166c8b4ef8fdee39a1f35c",
      "logIndex": "0x0",
      "removed": false,
      "dataStr": {
        "Code": 0,
        "Data": "",
        "ErrMsg": "ok"
      }
    }
  ],
  "logsBloom": "",
  "root": "0x3b7a41cea97f90196039586a3068f6a64c09aa7597898440c3c241a095e37984",
  "to": "atx1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzrzv4mm",
  "transactionHash": "0x4bee71e351076a81482e2576e469a8dfaa76da9b6cc848265c10968d6de67364",
  "transactionIndex": "0x0"
}

createStaking params array reply:  { blockHash:
   '0x43351e4a9f1b7173552094bacfd5b6f84f18a6c7c0c02d8a10506e3a61041117',
  blockNumber: '0x10',
  contractAddress: null,
  cumulativeGasUsed: '0x14f34',
  from: 'atx1w9x7ye4qalarnl9v59zzhyn7tug9864rll39n7',
  gasUsed: '0x14f34',
  logs:
   [ { address: 'atx1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzrzv4mm',
       topics: [Array],
       data:
        '0xf846b8447b22436f6465223a3330313130312c2244617461223a22222c224572724d7367223a22546869732063616e64696461746520697320616c7265616479206578697374227d',
       blockNumber: '0x10',
       transactionHash:
        '0xe5cbc728d6e284464c30ce6f0bbee5fb2b30351a591424f3a0edd37cc1bbdc05',
       transactionIndex: '0x0',
       blockHash:
        '0x43351e4a9f1b7173552094bacfd5b6f84f18a6c7c0c02d8a10506e3a61041117',
       logIndex: '0x0',
       removed: false,
       dataStr: [Object] } ],
  logsBloom:'',
  root:
   '0x45ffeda340b68a0d54c5556a51f925b0787307eab1fb120ed141fd8ba81183d4',
  to: 'atx1zqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqzrzv4mm',
  transactionHash:
   '0xe5cbc728d6e284464c30ce6f0bbee5fb2b30351a591424f3a0edd37cc1bbdc05',
  transactionIndex: '0x0' }

getCandidateList params object reply:  { 
  Code: 0,
  Data:
   [ { candidate1 info... },
     { candidate2 info... },
     { candidate3 info... },
     { candidate4 info... } 
   ],
  ErrMsg: 'ok' }

getCandidateList params array reply:  { 
  Code: 0,
  Data:
   [ { candidate1 info... },
     { candidate2 info... },
     { candidate3 info... },
     { candidate4 info... } 
   ],
  ErrMsg: 'ok' }

API Usage

updateSetting(setting)

Update the configuration parameters of the ppos object. If you only need to send a call, you only need to pass in the parameter provider. If you passed in the provider when instantiating web3, then the provider of ppos is the provider that you instantiate from web3 by default. Of course you can also update the provider at any time.

If you want to send a transaction via send, you need to pass in the parameters provider, the private key, and the chain id. Of course, sending transactions requires setting four parameters: gas, gasPrice, retry, and interval. See the async send (params, [other]) description for details.

For the parameters passed in, you can choose partial update. For example, if you want to use the private key A when sending a transaction to a ppos object, then you execute ppos.updateSetting before calling send (params, [other]) ({privateKey: youPrivateKeyA}) to update the private key. Once updated, the current configuration will be overwritten, and the send transaction interface will be called later, with the last updated configuration as the default.

Parameters:

setting - Object:
- provider - String: network link.
- privateKey - String: pairvate key.
- chainId - String: id of chain.
- gas - String: Maximum gas consumption value, please enter a hexadecimal string, such as '0xf4240'.
- gasPrice - String: Fuel price, please enter a hexadecimal string, such as '0x746a528800'.
- retry - Number: The number of times to query the receipt.
- interval - Number: Time interval to query the transaction receipt, the unit is ms.

Returns:

none

Example:

ppos.updateSetting({
    privateKey: 'acc73b693b79bbb56f89f63ccc3a0c00bf1b8380111965bfe8ab22e32045600c',
    chainId: 201018,
})

ppos.updateSetting({
    privateKey: '9f9b18c72f8e5154a9c59af2a35f73d1bdad37b049387fc6cea2bac89804293b'
})

getSetting()

Querying configured parameters.

Parameters:

none

Returns:

setting - Object
- provider - String: Network RPC link.
- privateKey - String: private key.
- chainId - String: id of chain.
- gas - String: Maximum limit of gas.
- gasPrice - String: Unit price of Gas.
- retry - Number: Number of retries for query receipt.
- interval - Number: Query the interval of the transaction receipt object, the unit is ms.

Example:

let setting = ppos.getSetting();

async rpc(method, [params])

Helper function to initiate rpc requests. Because some parameters need to be obtained through rpc during the process of calling ppos to send a transaction, an rpc is intentionally encapsulated for invocation. Note that this interface is an async function, you need to add await to return the result of the call, otherwise it returns a Promise object.

Parameters:

method - String: method name.
params - Array: Parameter required for calling the rpc interface. If the rpc interface does not require parameters, this parameter can be omitted.

Returns:

reply: Results returned by rpc call.

Example:

// Get program version
let reply = await ppos.rpc('admin_getProgramVersion'); 

// Get all accounts
let reply = await ppos.rpc('platon_accounts')

// Get the amount of the specified account.
let reply = await ppos.rpc('platon_getBalance', ["lax1w9x7ye4qalarnl9v59zzhyn7tug9864rr2fc35","latest"])

bigNumBuf(intStr)

Converts a large decimal integer into a buffer object that can be accepted by RLP encoding. A helper function. Because JavaScript's positive number range can only be expressed as a maximum of 2^53, in order for RLP to encode large integers, you need to convert the decimal large integer of the string into the corresponding Buffer. Note that this interface can only convert large decimal integers to Buffer temporarily. If it is a hexadecimal string, you need to convert it to a decimal string first.

Parameters:

intStr - String: String decimal large integer.

Returns:

buffer - Buffer: A cache area.

Example:

let buffer = ppos.bigNumBuf('1000000000000000000000000000000000000000000');

hexStrBuf(hexStr)

Converts a hexadecimal string into a buffer object that can be accepted by RLP encoding, a helper function. In the process of sending transactions by ppos, many parameters need to be transmitted as bytes instead of string, such as nodeId 64bytes pledged node Id (also called candidate node Id)`. The nodeId when writing code can only be expressed as a string. It needs to be converted into a 64 bytes Buffer.

Note: If the string you pass in starts with 0x or 0X, the system will assume that you are a hexadecimal string that does not encode the first two letters. If you really want to encode 0x or 0X, you must prefix the string with 0x. For example, if you want to encode the full string 0x31c0e0 (4 bytes), you must pass in 0x0x31c0e0.

Parameters:

hexStr - String: A hex string.

Returns:

buffer - Buffer: A cache area.

Example:

const nodeId = '80f1fcee54de74dbf7587450f31c31c0e057bedd4faaa2a10c179d52c900ca01f0fb255a630c49d83b39f970d175c42b12a341a37504be248d76ecf592d32bc0';
let buffer = ppos.hexStrBuf(nodeId);

async call(params)

Send a call query call to PPOS without changing the state. So you need to distinguish between querying and sending transactions. The input parameters can select objects or arrays. If you choose to pass in an object, then you need to use the specified string key, but the order of the key is not required. You can write {a: 1, b: 'hello'} or {b: 'hello', a: 1} without any problem.

If you choose to use an array as the input parameter, you must put the parameters into the array in the order of the input parameters. Note that for some string large integers and bytes' that need to be passed in, please choose the interfaces bigNumBuf (intStr) and hexStrBuf (hexStr) `provided above to convert them by themselves.

Note that this interface is an async function, you need to add await to return the result of the call, otherwise it returns a Promise object.

Parameters:

params - Object|Array: Call parameters.

Returns:

reply - Object: The result of the call. Note that I have turned the returned results into Object objects.

Code - Number: Return code, 0 means the result of the call is normal.
Data - Array|Object|String|Number: Return the corresponding type according to the result of the call.
ErrMsg - String: Error message.

Query the NodeID and Pledged Id of the node entrusted by the current account address The input parameters of this interface are from top to bottom. The input parameters are as follows:

name	Type	Desc
funcType	uint16(2bytes)	Method type code(1103)
addr	common.address(20bytes)	Client's account address

Example:

let params, reply;

// Called by passing in an object (the order is not required for the key)
params = {
    funcType: 1103,
    addr: ppos.hexStrBuf("lax1w9x7ye4qalarnl9v59zzhyn7tug9864rr2fc35")
}
reply = await ppos.call(params);

// Calling as an array object.
params = [1103, ppos.hexStrBuf("lax1w9x7ye4qalarnl9v59zzhyn7tug9864rr2fc35")];
reply = await ppos.call(params);

async send(params, [other])

Send a transaction to ppos.

Trading will involve some parameters, such as gas, gasPrice. After the transaction is sent, in order to confirm whether the transaction is on the chain, you need to continuously poll the result on the chain through the transaction hash. There is an interval between the number of polls retry and each poll.

For the four parameters mentioned above, gas, gasPrice, retry, interval, if the other input parameter is specified, the other parameter is used. If the other parameter is not specified, the parameter specified by updateSetting (setting) is used when calling the function, otherwise the default value is used.

Note: This interface is an async function, you need to add await to return the result of the call, otherwise it returns a Promise object.

Parameters:

params - Object|Array: Transaction parameters.
other - Object(Optional):
- gas - String: Gas limit, default '0xf4240'.
- gasPrice - String: Gas price, default '0x746a528800'.
- retry - Number: Query the number of transaction receipt objects. The default is 600 times.
- interval - Number: Query the interval of the transaction receipt object, the unit is ms. The default is 100 ms.

Returns:

reply - Object: Receipt object for the specified transaction hash.
- status - Boolean: Successful transaction returns true, false if EVM rolls back the transaction.
- blockHash 32 Bytes - String: The hash of the block
- blockNumber - Number: The number of the block
- transactionHash 32 Bytes - String: The hash of transaction.
- transactionIndex - Number: Index position of the transaction in the block.
- from - String: Address of the sender of the transaction.
- to - String: The address of the transaction receiver. For the transaction that created the contract, the value is null.
- contractAddress - String: For transactions that create a contract, the value is the contract address created, otherwise null.
- cumulativeGasUsed - Number: Cumulative total gas usage of the block where the transaction is executed.
- gasUsed - Number: Total gas consumed by this transaction.
- logs - Array: Array of log objects generated by this transaction.
errMsg - String: If the call fails and there is no receipt after the sending transaction returns, the error message no hash is returned. If there is a receipt after sending the transaction, but no receipt object is found within the specified time, then getTransactionReceipt txHash ${hash} interval ${interval} ms by ${retry} retry failed.

Call the interface that initiates the delegation. The input parameters are:

Parameter	Type	Desc
funcType	uint16(2bytes)	type code of method. (1004)
typ	uint16(2bytes)	Indicates whether to use the free amount of the account or the locked amount of the account as the commission, 0: free amount; 1: locked amount
nodeId	64bytes	NodeId of the pledged node
amount	big.Int(bytes)	Amount entrusted (Calculated in the smallest unit，1LAT = 10^18 von)

Example:

const nodeId = "f71e1bc638456363a66c4769284290ef3ccff03aba4a22fb60ffaed60b77f614bfd173532c3575abe254c366df6f4d6248b929cb9398aaac00cbcc959f7b2b7c";
let params, others, reply;

// Objects as parameters (the order is not required for keys)
params = {
    funcType: 1004,
    typ: 0,
    nodeId: ppos.hexStrBuf(nodeId),
    amount: ppos.bigNumBuf("10000000000000000000000")
}
reply = await ppos.send(params);

// Array as parameter.
params = [1004, 0, ppos.hexStrBuf(nodeId), ppos.bigNumBuf("10000000000000000000000")];
reply = await ppos.send(params);

// Default configuration
other = {
    retry: 300, 
    interval: 200 
}
params = [1004, 0, ppos.hexStrBuf(nodeId), ppos.bigNumBuf("10000000000000000000000")];
reply = await ppos.send(params, other);

Pledge Module

Initiate Pledge

Pledge by sending transactions via send.

Parameter	Type	Desc
funcType	uint16(2bytes)	Type code of method(1000)
typ	uint16(2bytes)	Indicates whether to use the account free amount or the account's locked amount as a pledge, 0: free amount; 1: locked amount
benefitAddress	20bytes	Revenue account for receiving block rewards and pledged rewards
nodeId	64bytes	The node ID of the pledged (also called the node ID of the candidate)
externalId	string	External Id (with a length limit, the Id described by the third-party pull node)
nodeName	string	The name of the node being pledged (there is a length limitation, indicating the name of the node)
website	string	The third-party home page of the node (the length is limited, indicating the home page of the node)
details	string	The description of the node (the length is limited, indicating the description of the node)
amount	*big.Int(bytes)	Pledged von
rewardPer	uint16(2bytes)	The percentage of rewards obtained from delegation is BasePoint 1BP = 0.01%
programVersion	uint32	Real version of the program, governance rpc acquisition
programVersionSign	65bytes	The true version signature of the program and the rpc interface of the governance module
blsPubKey	96bytes	bls public key
blsProof	64bytes	Proof of bls, obtained by pulling the proof interface

Update Pledge Information

Modify the pledge information by sending the transaction.

Parameter	Type	Desc
funcType	uint16(2bytes)	Method type code(1001)
benefitAddress	20bytes	Revenue account for receiving block rewards and pledged rewards
nodeId	64bytes	The node ID of the pledged (also called the node ID of the candidate)
rewardPer	uint16(2bytes)	The percentage of rewards obtained from delegation is BasePoint 1BP = 0.01%
externalId	string	External Id (with a length limit, the Id described by the third-party pull node)
nodeName	string	The name of the node being pledged (there is a length limitation, indicating the name of the node)
website	string	The third-party home page of the node (the length is limited, indicating the home page of the node)
details	string	The description of the node (the length is limited, indicating the description of the node)

Increase Pledge

Increase pledge by sending transactions.

Parameters:

Parameter	Type	Desc
funcType	uint16(2bytes)	Method type code(1002)
nodeId	64bytes	The node ID of the pledged (also called the node ID of the candidate)
typ	uint16(2bytes)	Indicates whether to use the account free amount or the account's locked amount as a pledge, 0: free amount; 1: locked amount
amount	*big.Int(bytes)	Increased von

Cancellation Of Pledge

Send the transaction to cancel the pledge.

Notes: All cancellations are initiated at once, and the amount is divided into multiple returns to the account.

Parameter	Type	Desc
funcType	uint16(2bytes)	Method type code(1003)
nodeId	64bytes	NodeId of the pledged node

Initiate Delegation

Initiate delegation by sending a transaction.

Parameter	Type	Desc
funcType	uint16(2bytes)	Method type code(1004)
typ	uint16(2bytes)	Indicates whether to use the free amount of the account or the locked amount of the account as the commission, 0: free amount; 1: locked amount
nodeId	64bytes	NodeId of the pledged node
amount	*big.Int(bytes)	Amount entrusted (based on the smallest unit, 1LAT = 10 ** 18 von)

Reduction/Revocation Delegation

Completed by sending a transaction(All reductions are cancelled).

Parameter	Type	Desc
funcType	uint16(2bytes)	Method type code(1005)
stakingBlockNum	uint64(8bytes)	A unique identifier representing a pledge of a node
nodeId	64bytes	NodeId of the pledged node
amount	*big.Int(bytes)	Amount of reduction entrustment (calculated by the smallest unit, `1LAT = 10 ** 18 von`)

Query Validators

Query the validator of the current settlement cycle by calling.

Parameters:

Parameter	Type	Desc
funcType	uint16(2bytes)	Method type code(1100)

Unified query result format

Field	Type	Desc
Code	uint32	Indicates the error code returned by the ppos built-in contract
Data	string	Query result of json string
ErrMsg	string	Error message

Note: The following query interfaces (the interfaces called by platon_call) are returned in the above format unless otherwise specified

Returns: List

Field	Type	Desc
NodeId	64bytes	The node ID of the pledged (also called the node ID of the candidate)
StakingAddress	20bytes	The account used when initiating the pledge (this account can only be used for subsequent pledge information. When the pledge is cancelled, `von` will be returned to the account or the account lock information)
BenefitAddress	20bytes	Revenue account for receiving block rewards and pledged rewards
StakingTxIndex	uint32(4bytes)	Index of transactions when pledge is initiated
ProgramVersion	uint32	The real version number of the PlatON process of the pledged node (the interface for obtaining the version number is provided by the governance)
StakingBlockNum	uint64(8bytes)	Block height when pledge is initiated
Shares	*big.Int(bytes)	The current candidate's total pledge plus the number of `von` entrusted
ExternalId	string	External Id (with a length limit, the Id described by the third-party pull node)
NodeName	string	The name of the node being pledged (there is a length limitation, indicating the name of the node)
Website	string	The third-party home page of the node (the length is limited, indicating the home page of the node)
Details	string	The description of the node (the length is limited, indicating the description of the node)
ValidatorTerm	uint32(4bytes)	Validator's term (it will always be 0 in the 101 validator snapshots of the settlement cycle, and will only be valued when the validator of the consensus round, it is also 0 when it is just selected, and +1 when it stays in office)

Query Validator list

Query the list of validators by call.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(1101)

Returns: List

Field	Type	Remark
NodeId	64bytes	The node ID of the pledged (also called the node ID of the candidate).
StakingAddress	20bytes	The account used when initiating the pledge (the pledge information can only be used for this operation in subsequent operations. When the pledge is cancelled, von will be returned to the account or the account lock information)
BenefitAddress	20bytes	Revenue account for receiving block rewards and pledged rewards
StakingTxIndex	uint32(4bytes)	Index of transactions when pledge is initiated
ProgramVersion	uint32(4bytes)	The real version number of the PlatON process of the pledged node (the interface for obtaining the version number is provided by the governance)
StakingBlockNum	uint64(8bytes)	Block height when pledge is initiated
Shares	*big.Int(bytes)	The current candidate's total pledge plus the number of entrusted von
ExternalId	string	External Id (with a length limit, the Id described by the third-party pull node)
NodeName	string	The name of the node being pledged (there is a length limitation, indicating the name of the node)
Website	string	The third-party home page of the node (the length is limited, indicating the home page of the node)
Details	string	The description of the node (the length is limited, indicating the description of the node)
ValidatorTerm	uint32(4bytes)	Validator's term (it will always be 0 in the 101 validator snapshots of the settlement cycle, and will only be valued when the validator of the consensus round, it is also 0 when it is just selected, and +1 when it stays in office)

Query Real-time Candidate List

Query real-time candidate list by call.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(1102)

Returns:List

Field	Type	Remark
NodeId	64bytes	The node ID of the pledged (also called the node ID of the candidate).
StakingAddress	20bytes	The account used when initiating the pledge (the pledge information can only be used for this operation in subsequent operations. When the pledge is cancelled, von will be returned to the account or the account lock information)
BenefitAddress	20bytes	Revenue account for receiving block rewards and pledged rewards
StakingTxIndex	uint32(4bytes)	Index of transactions when pledge is initiated
ProgramVersion	uint32(4bytes)	The real version number of the PlatON process of the pledged node (the interface for obtaining the version number is provided by the governance)
Status	uint32(4bytes)	The status of the candidate (the status is placed according to the 32bit of uint32, there can be multiple states at the same time, and the value is the sum of multiple simultaneous state values [0: node available (32 bits are all 0); 1: node Not available (only the last bit is 1); 2: The node has a low block generation rate but does not meet the removal condition (only the penultimate bit is 1); 4: The node's von is not enough to meet the minimum pledge threshold (only the penultimate bit 1); 8: The node is reported with a double sign (only the penultimate bit is 1)); 16: the node's block generation rate is low and the removal condition is met (the penultimate bit is 1); 32: the node actively initiates the cancellation (Only the penultimate bit is 1)]
StakingEpoch	uint32(4bytes)	Settlement cycle when current pledge amount is changed
StakingBlockNum	uint64(8bytes)	Block height when pledge is initiated
Shares	string	The current candidate's total pledge plus the number of entrusted von
Released	string	Initiating a free amount locked period pledge of a pledged account `von`
ReleasedHes	string	Freedom to initiate a pledge account with a hesitation period of von von
RestrictingPlan	string	Initiating the lock-up period of the pledged account's lock-up amount `von`
RestrictingPlanHes	string	Initiating the hedging period of the pledged account's hedging amount `von`
ExternalId	string	External Id (with a length limit, the Id described by the third-party pull node)
NodeName	string	The name of the node being pledged (there is a length limitation, indicating the name of the node)
Website	string	The third-party home page of the node (the length is limited, indicating the home page of the node)
Details	string	The description of the node (the length is limited, indicating the description of the node)

Query The NodeID And Pledged Id of The Delegated Node

Query the NodeID and Pledged Id of the node entrusted by the current account address.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(1103)
addr	common.address(20bytes)	Client's account address

Returns: List

Field	Type	Remark
Addr	20bytes	Client's account address
NodeId	64bytes	Node ID of the validator
StakingBlockNum	uint64(8bytes)	Block height when pledge is initiated

Query Delegated Informations

Query the current single delegate information, using the call method.

Parameters:

Field	Type	Remark
funcType	uint16	Method type code(1104)
stakingBlockNum	uint64(8bytes)	Block height when pledge is initiated
delAddr	20bytes	Client's account address
nodeId	64bytes	Node ID of the validator

Returns: List

Field	Type	Remark
Addr	20bytes	Client's account address
NodeId	64bytes	Node ID of the validator
StakingBlockNum	uint64(8bytes)	Block height when pledge is initiated
DelegateEpoch	uint32(4bytes)	Settlement cycle at the time of the most recent commission for this candidate
Released	string	The free amount of the account that initiated the commission, the `von` that was commissioned during the lock-up period.
ReleasedHes	string	Number of von commissioned during the hesitation period of the free amount of the commission account
RestrictingPlan	string	Number of von commissioned during the lock period that initiated the lockup amount of the commissioned account
RestrictingPlanHes	string	Number of von commissioned during the hesitation period of the hedging amount of the commissioned account
Reduction	string	`von` in revocation plan

Query Pledge Information

Query the pledge information of the current node.

Parameters:

Field	Type	Remark
funcType	uint16	Method type code(1105)
nodeId	64bytes	Node ID of the validator

Returns: List

Field	Type	Remark
NodeId	64bytes	The node ID of the pledged (also called the node ID of the candidate).
StakingAddress	20bytes	The account used when initiating the pledge (the pledge information can only be used for this operation in subsequent operations. When the pledge is cancelled, von will be returned to the account or the account lock information)
BenefitAddress	20bytes	Revenue account for receiving block rewards and pledged rewards
StakingTxIndex	uint32(4bytes)	Index of transactions when pledge is initiated
ProgramVersion	uint32(4bytes)	The real version number of the PlatON process of the pledged node (the interface for obtaining the version number is provided by the governance)
Status	uint32(4bytes)	The status of the candidate (the status is placed according to the `32bit` of `uint32`, multiple states can exist at the same time, and the value of multiple simultaneous state values is added [`0`: the node is available (32 bits are all 0); `1`: The node is unavailable (only the last bit is 1); `2`: The node has a low block rate but does not meet the removal condition (only the penultimate bit is 1); `4`: The node Von is lower than the minimum pledge threshold (only the penultimate bit is 1); `8`: the node is reported as a double sign (only the penultimate bit is 1); `16`: the node block rate is low and the removal condition is met (The penultimate bit is 1); `32`: the node actively initiates the revocation (only the penultimate bit is 1)]
StakingEpoch	uint32(4bytes)	Settlement cycle when current pledge amount is changed
StakingBlockNum	uint64(8bytes)	Block height when pledge is initiated
Shares	string	The current candidate's total pledge plus the number of entrusted von
Released	string	Initiating a free amount locked period pledge of a pledged account `von`
ReleasedHes	string	Freedom to initiate a pledge account with a hesitation period of von von
RestrictingPlan	string	Initiating the lock-up period of the pledged account's lock-up amount `von`
RestrictingPlanHes	string	Initiating the hedging period of the pledged account's hedging amount `von`
ExternalId	string	External Id (with a length limit, the Id described by the third-party pull node)
NodeName	string	The name of the node being pledged (there is a length limitation, indicating the name of the node)
Website	string	The third-party home page of the node (the length is limited, indicating the home page of the node)
Details	string	The description of the node (the length is limited, indicating the description of the node)

Governance Module

Submit Text Proposal

Submit a text proposal by sending a transaction.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(2000)
verifier	discover.NodeID(64bytes)	Submit a validator
pIDID	string(uint64)	PIPID

Submit Upgrade Proposal

Submit an upgrade proposal by sending a transaction.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(2001)
verifier	discover.NodeID(64bytes)	Validator of proposal
pIDID	string(uint64)	PIPID
newVersion	uint32(4bytes)	updated version
endVotingRounds	uint64	Number of voting consensus rounds. Note: Assume that the number of the consensus round when the transaction that submitted the proposal is packaged into the block is `round1`. The `blockNumber` of the proposal voting deadline is `round1 + endVotingRounds`. The consensus round produced block 250, ppos was announced 20 blocks ahead of time, `250`, and `20` are all configurable), of which `0 <endVotingRounds <= 4840` (about 2 weeks, the actual discussion can be calculated according to the configuration), And is an integer)

Submit Cancellation Proposal

Submit cancellation proposal by sending transaction.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(2005)
verifier	discover.NodeID(64bytes)	Validator of proposal
pIDID	string(uint64)	PIPID
endVotingRounds	uint64	Number of voting consensus rounds. Refer to the description of submitting an upgrade proposal. At the same time, the value of this parameter in this interface cannot be greater than the value in the corresponding upgrade proposal.
tobeCanceledProposalID	common.hash(32bytes)	Upgrade proposal ID to be canceled

Vote On Proposal

Vote on a proposal by sending a transaction.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(2003)
verifier	discover.NodeID(64bytes)	Vote validator
proposalID	common.Hash(32bytes)	Proposal ID
option	uint8(1byte)	Voting options
programVersion	uint32(4bytes)	The code version of the node, obtained by the `getProgramVersion` interface of rpc
versionSign	common.VesionSign(65bytes)	Code version signature, obtained by rpc's getProgramVersion interface

Version Declaration

Declaring the version by sending a transaction.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(2004)
verifier	discover.NodeID(64bytes)	The declared node can only be a validator/candidate
programVersion	uint32(4bytes)	Declared version, obtained by rpc's getProgramVersion interface
versionSign	common.VesionSign(65bytes)	Declared version signature, obtained by rpc's getProgramVersion interface

Query Proposal

Query proposal by calling.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	2100)
proposalID	common.Hash(32bytes)	Proposal ID

Returns:

JSON string of object implementing interface Proposal.

Query Proposal Results

Query proposal results through calling operation.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(2101)
proposalID	common.Hash(32bytes)	Proposal ID

Returns:

TallyResult: Json string of TallyResult object.

Query Proposal List

Query proposal list through calling operation.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(2102)

Returns:

Proposal: A json string of an object that implements the interface Proposal.

Query Version In Effect

Query the version in effect through calling operation.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(2103)

Returns:

String: The json string of the version number, such as {65536}, indicates that the version is: 1.0.0. When parsing, ver needs to be converted into 4 bytes. Major version: second byte; minor version: third byte, patch version, fourth byte.

Query The Cumulative Voteable Number Of Proposals

Query the cumulative voteable number of proposals through calling operation.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(2105)
proposalID	common.Hash(32bytes)	Proposal ID
blockHash	common.Hash(32bytes)	块hash

Returns:

Array - []uint16: An array.

Field	Type	Remark
	uint16	Number of cumulative votes
	uint16	Number of in favour votes
	uint16	Number of negative votes
	uint16	Number of Abstained votes

Definition

ProposalType

Type	Definition	Description
TextProposal	0x01	Text proposal
VersionProposal	0x02	Upgrade proposal
CancelProposal	0x04	Cancel proposal

ProposalStatus

For text proposals, there are three states: 0x01, 0x02, 0x03; For the upgrade proposal, there are four states: 0x01, 0x03, 0x04, 0x05, 0x06. For cancellation proposals, there are three states: 0x01, 0x02, 0x03;

Type	Definition	Description
Voting	0x01	Voting
Pass	0x02	Voted successfully
Failed	0x03	Vote failed
PreActive	0x04	(Upgrade Proposal) Pre-Effective
Active	0x05	(Upgrade Proposal) Effective
Canceled	0x06	(Upgrade proposal) cancelled

VoteOption

Type	Definition	Description
Yeas	0x01	agree
Nays	0x02	Against
Abstentions	0x03	Abstain

Proposal(TextProposal)

Field	Type	Remark
ProposalID	common.Hash(32bytes)	Proposal ID
Proposer	common.NodeID(64bytes)	Proposal Node ID
ProposalType	byte	Proposal type, `0x01`: text proposal; `0x02`: upgrade proposal; `0x03` parameter proposal; `0x04` cancel proposal.
PIPID	string	Proposal PIPID
SubmitBlock	8bytes	Submitted blockNumber
EndVotingBlock	8bytes	BlockNumber of proposal voting ended, according to SubmitBlock

Proposal(VersionProposal)

Field	Type	Remark
ProposalID	common.Hash(32bytes)	Proposal ID
Proposer	common.NodeID(64bytes)	Proposal Node ID
ProposalType	byte	Proposal type, `0x01`: text proposal; `0x02`: upgrade proposal; `0x03` parameter proposal; `0x04` cancel proposal.
PIPID	string	Proposal PIPID
SubmitBlock	8bytes	Submitted blockNumber
EndVotingRounds	8bytes	Number of voting consensus cycles
EndVotingBlock	8bytes	The block height at the end of proposal voting is calculated by the system according to SubmitBlock, EndVotingRounds
ActiveBlock	8bytes	Proposal effective block height, calculated by the system based on EndVotingBlock
NewVersion	uint	updated version

Proposal CancelProposal

Field	Type	Remark
ProposalID	common.Hash(32bytes)	Proposal ID
Proposer	common.NodeID(64bytes)	Proposal Node ID
ProposalType	byte	Proposal type, `0x01`: text proposal; `0x02`: upgrade proposal; `0x03` parameter proposal; `0x04` cancel proposal.
PIPID	string	Proposal PIPID
SubmitBlock	8bytes	Submitted blockNumber
EndVotingRounds	8bytes	Number of voting consensus cycles
EndVotingBlock	8bytes	The block height at the end of proposal voting is calculated by the system according to SubmitBlock, EndVotingRounds
TobeCanceled	common.Hash(32bytes)	ID of the promotion proposal to cancel

Vote

Field	Type	Remark
voter	64bytes	Vote validator
proposalID	common.Hash(32bytes)	Proposal ID
option	VoteOption	Voting options

TallyResult

Field	Type	Remark
proposalID	common.Hash(32bytes)	Proposal ID
yeas	uint16(2bytes)	Approve
nays	uint16(2bytes)	Against
abstentions	uint16(2bytes)	Abstention
accuVerifiers	uint16(2bytes)	Total number of validators who have qualified to vote during the entire voting period
status	byte	status
canceledBy	common.Hash(32bytes)	When status = 0x06, the ProposalID of the record that initiated the cancellation

Exposure/Punishment Module

Report Double Sign

Report a double sign by sending a transaction.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(3000)
typ	uint8	Stands for double sign type 1：prepareBlock，2：prepareVote，3：viewChange
data	string	The json value of a single evidence. The format is [RPC interface Evidences] [evidences_interface]

Query Whether Node Has Been Reported As Oversigned

Query whether a node has been reported as oversigned by sending a transaction.

Parameters:

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(3001)
typ	uint32	Stands for double sign type, 1：prepareBlock，2：prepareVote，3：viewChange
addr	20bytes	Reporting node address
blockNumber	uint64	Multi-Signed BlockNumber

Returns:

Type	Remark
String	Reported Transaction Hash

Lockout Module

Create Hedging Plan

Create hedging plan by sending a transaction.

Parameters:

Field	Type	Remark
account	20bytes	`Lock release to account`
plan	[]RestrictingPlan	plan is a list (array) of type RestrictingPlan. RestrictingPlan is defined as follows: type RestrictingPlan struct { Epoch uint64 Amount: \ * big.Int } Among them, Epoch : Represents a multiple of the settlement cycle. The product of the number of blocks per settlement cycle indicates the release of locked funds at the height of the target block. Epoch \ * The number of blocks per cycle must be at least greater than the highest irreversible block height. Amount: indicates the amount to be released on the target block.

Get Lock Information

Get lock information by calling.

Note: This interface supports the acquisition of historical data. The block height can be attached to the request. By default, the latest block data is queried.

Parameters:

Field	Type	Remark
account	20bytes	`The account that was posted after the lockout was released`

Returns:

Returns a json format string with the following fields:

Field	Type	Remark
balance	string(Hex)	Amount of remaining locked positions
pledge	string(Hex)	Pledge / mortgage amount
debt	string(Hex)	Amount due for release
plans	bytes	Locked entry information, json array：[{"blockNumber":"","amount":""},...,{"blockNumber":"","amount":""}]. among: blockNumber：*big.Int，Release blockNumber amount：\string(Hex string), Release amount

Reward Interface

Withdraw Delegate Reward

Withdraw all currently available delegate rewards from the account and send the transaction.

Parameters：

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(5000)

Returns:

Note: The transaction results are stored in the logs.data of the transaction receipt. If the transaction is successful, rlp.Encode (byte {[] byte (status code 0), rlp.Encode (node income list)}). If the transaction is unsuccessful, it is consistent with the previous method.

The returned node income list is an array

Field	Type	Remark
NodeID	discover.NodeID(64bytes)	Node ID
StakingNum	uint64	Node stake block Number
Reward	*big.Int	Received reward

Query Delegate Reward

The query account did not withdraw the delegate reward at each node, and call query.

Parameters：

Field	Type	Remark
funcType	uint16(2bytes)	Method type code(5100)
address	20bytes	The address of the account to be queried
nodeIDs	[]discover.NodeID	The node to be queried, if it is empty, all nodes entrusted by the account are queried

Returns：

Is a []Reward array

Field	Type	Remark
nodeID	discover.NodeID(64bytes)	Node ID
stakingNum	uint64	Node stake block Number
reward	string(0x hex string)	Did not withdraw the delegate reward

Error Code Description

ErrorCode	Remark
301000	Wrong bls public key
301001	Wrong bls public key proof
301002	The Description length is wrong
301003	The program version sign is wrong
301004	The program version of the relates node's is too low
301005	DeclareVersion is failed on create staking
301006	The address must be the same as initiated staking
301100	Staking deposit too low
301101	This candidate is already exist
301102	This candidate is not exist
301103	This candidate status was invalided
301104	IncreaseStake von is too low
301105	Delegate deposit too low
301106	The account is not allowed to be used for delegating
301107	The candidate does not accept the delegation
301108	Withdrew delegation von is too low
301109	This delegation is not exist
301110	The von operation type is wrong
301111	The von of account is not enough
301112	The blockNumber is disordered
301113	The von of delegation is not enough
301114	Withdrew delegation von calculation is wrong
301115	The validator is not exist
301116	The fn params is wrong
301117	The slashing type is wrong
301118	Slashing amount is overflow
301119	Slashing candidate von calculate is wrong
301200	Getting verifierList is failed
301201	Getting validatorList is failed
301202	Getting candidateList is failed
301203	Getting related of delegate is failed
301204	Query candidate info failed
301205	Query delegate info failed