search

AlayaNetwork / client-sdk-js

A javascript interface for interacting with the Alaya network.
Other
1 stars 3 forks source link

readme

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:

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:

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:

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:

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:

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.

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:

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:

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:

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:

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:

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:

Returns:

Promise returns Object - The block object:

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:

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:

Returns:

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

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:

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:

Returns:

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

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:

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:

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:

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:

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:

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:

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:

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:

Returns:

Promise returns Array - Array of log objects.

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

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:

Returns:

EventEmitter - A Subscription instance:

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:

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:

Returns:

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

Notification returns:

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:

Returns:

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

The structure of a returned block header is as follows:

Notification returns:

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:

Returns:

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

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

Notification returns:

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:

Returns:

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

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

Notification returns:

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:

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:

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.

Returns:

Object: The transaction object:

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:

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:

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:

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:

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:

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:

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:

Returns:

EventEmitter: The event emitter has the following events:

The structure of the returned event Object looks as follows:

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:

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：

Returns:

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：

Returns:

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:

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:

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:

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

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:

Returns:

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:

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:

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:

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:

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:

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:

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':          '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:

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:

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:

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 ofppos. But if you want to use the ppos object to send transactions on the chain, in addition to the provider passed in when instantiatingweb3, 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 ofppos 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, andinterval. 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:

Returns:

none

Example:

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

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

getSetting()

Querying configured parameters.

Parameters:

none

Returns:

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:

Returns:

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:

Returns:

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 ofstring, 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 or0X, 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 or0X, 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:

Returns:

Example:

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

async call(params)

Send a call query call toPPOS 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 thekey 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:

Returns:

  1. 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, theother 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:

Returns:

  1. 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.

  2. 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 ofuint32, 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. TheblockNumber of the proposal voting deadline is round1 + endVotingRounds. The consensus round produced block 250, ppos was announced 20 blocks ahead of time, 250, and20 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