Note

This documentation is under construction and the chain3.js 1.0 stable version isn’t released. If you’re using a version v0.1.x of chain3.js then please have a look at chain3js 0.1.x or https://github.com/MOACChain/moac-core/wiki/Chain3.

web3.eth.personal¶

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

Note

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!

import Web3 from 'web3';
import {Personal} from 'web3-eth-personal';

// "Web3.givenProvider" will be set if in an Ethereum supported browser.
const personal = new Personal(Web3.givenProvider || 'ws://some.local-or-remote.node:8546', null, options);


// or using the web3 umbrella package
const web3 = new Web3(Web3.givenProvider || 'ws://some.local-or-remote.node:8546', null, options);

// -> web3.eth.personal

options¶

An Chain3 module does provide several options for configuring the transaction confirmation worklfow or for defining default values. These are the currently available option properties on a Web3 module:

Module Options¶

transactionBlockTimeout

transactionConfirmationBlocks

transactionPollingTimeout

transactionSigner

Example¶

import Chain3 from 'chain3';

const options = {
    defaultAccount: '0x0',
    defaultBlock: 'latest',
    defaultGas: 1,
    defaultGasPrice: 0,
    transactionBlockTimeout: 50,
    transactionConfirmationBlocks: 24,
    transactionPollingTimeout: 480,
    transactionSigner: new CustomTransactionSigner()
}

const chain3 = new Chain3('http://localhost:8545', null, options);

defaultBlock¶

chain3.defaultBlock
chain3.mc.defaultBlock
...

The default block is used for all methods which have a block parameter. You can override it by passing the block parameter if a block is required.

Example:

Returns¶

The defaultBlock property can return the following values:

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

Default is "latest"

defaultAccount¶

chain3.defaultAccount
chain3.eth.defaultAccount
chain3.shh.defaultAccount
...

This default address is used as the default "from" property, if no "from" property is specified.

Returns¶

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

defaultGasPrice¶

chain3.defaultGasPrice
chain3.eth.defaultGasPrice
chain3.shh.defaultGasPrice
...

The default gas price which will be used for a request.

Returns¶

string|number: The current value of the defaultGasPrice property.

defaultGas¶

chain3.defaultGas
chain3.eth.defaultGas
chain3.shh.defaultGas
...

The default gas which will be used for a request.

Returns¶

string|number: The current value of the defaultGas property.

transactionBlockTimeout¶

chain3.transactionBlockTimeout
chain3.eth.transactionBlockTimeout
chain3.shh.transactionBlockTimeout
...

The transactionBlockTimeout will be used over a socket based connection. This option does define the amount of new blocks it should wait until the first confirmation happens. This means the PromiEvent rejects with a timeout error when the timeout got exceeded.

Returns¶

number: The current value of transactionBlockTimeout

transactionConfirmationBlocks¶

chain3.transactionConfirmationBlocks
chain3.eth.transactionConfirmationBlocks
chain3.shh.transactionConfirmationBlocks
...

This defines the number of blocks it requires until a transaction will be handled as confirmed.

Returns¶

number: The current value of transactionConfirmationBlocks

transactionPollingTimeout¶

chain3.transactionPollingTimeout
chain3.eth.transactionPollingTimeout
chain3.shh.transactionPollingTimeout
...

The transactionPollingTimeout will be used over a HTTP connection. This option does define the amount of polls (each second) it should wait until the first confirmation happens.

Returns¶

number: The current value of transactionPollingTimeout

transactionSigner¶

chain3.eth.transactionSigner
...

The transactionSigner property does provide us the possibility to customize the signing process of the Eth module and the related sub-modules.

The interface of a TransactionSigner:

interface TransactionSigner {
    sign(txObject: Transaction): Promise<SignedTransaction>
}

interface SignedTransaction {
    messageHash: string,
    v: string,
    r: string,
    s: string,
    rawTransaction: string
}

Returns¶

TransactionSigner: A JavaScript class of type TransactionSigner.

setProvider¶

chain3.setProvider(myProvider)
chain3.eth.setProvider(myProvider)
chain3.shh.setProvider(myProvider)
...

Will change the provider for its module.

Note

When called on the umbrella package chain3 it will also set the provider for all sub modules chain3.eth, chain3.shh, etc.

Parameters¶

Object|String - provider: a valid provider
Net - net: (optional) the node.js Net package. This is only required for the IPC provider.

Returns¶

Boolean

Example¶

import Web3 from 'chain3';

const chain3 = new Web3('http://localhost:8545');

// or
const chain3 = new Web3(new Web3.providers.HttpProvider('http://localhost:8545'));

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

// Using the IPC provider in node.js
const net = require('net');
const chain3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path

// or
const chain3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net)); // mac os path
// on windows the path is: '\\\\.\\pipe\\geth.ipc'
// on linux the path is: '/users/myuser/.ethereum/geth.ipc'

providers¶

Web3.providers
Eth.providers
...

Contains the current available providers.

Value¶

Object with the following providers:

Object - HttpProvider: The HTTP provider is deprecated, as it won’t work for subscriptions.

Object - WebsocketProvider: The Websocket provider is the standard for usage in legacy browsers.

Object - IpcProvider: The IPC provider is used node.js dapps when running a local node. Gives the most secure connection.

Example¶

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

// Using the IPC provider in node.js
const net = require('net');

const chain3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path
// or
const chain3 = new Web3(new Web3.providers.IpcProvider('/Users/myuser/Library/Ethereum/geth.ipc', net)); // mac os path
// on windows the path is: '\\\\.\\pipe\\geth.ipc'
// on linux the path is: '/users/myuser/.ethereum/geth.ipc'

givenProvider¶

Web3.givenProvider
chain3.eth.givenProvider
chain3.shh.givenProvider
...

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

Returns¶

Object: The given provider set or false.

Example¶

chain3.setProvider(Web3.givenProvider || 'ws://localhost:8546');

currentProvider¶

chain3.currentProvider
chain3.eth.currentProvider
chain3.shh.currentProvider
...

Will return the current provider.

Returns¶

Object: The current provider set.

Example¶

if (!chain3.currentProvider) {
    chain3.setProvider('http://localhost:8545');
}

BatchRequest¶

new chain3.BatchRequest()
new chain3.eth.BatchRequest()
new chain3.shh.BatchRequest()
...

Class to create and execute batch requests.

Parameters¶

none

Returns¶

Object: With the following methods:

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

execute(): Will execute the batch request.

Example¶

const contract = new chain3.eth.Contract(abi, address);

const batch = new chain3.BatchRequest();
batch.add(chain3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 'latest'));
batch.add(contract.methods.balance(address).call.request({from: '0x0000000000000000000000000000000000000000'}));
batch.execute().then(...);

newAccount¶

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

Create a new account on the node that Web3 is connected to with its provider. The RPC method used is personal_newAccount. It differs from web3.eth.accounts.create() where the key pair is created only on client and it’s up to the developer to manage it.

Note

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

Parameters¶

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

Returns¶

Promise<string> - The address of the newly created account.

Example¶

web3.eth.personal.newAccount('!@superpassword')
.then(console.log);
> '0x1234567891011121314151617181920212223456'

sign¶

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

Signs data using a specific account. This data is before UTF-8 HEX decoded and enveloped as follows: "\x19Ethereum Signed Message:\n" + message.length + message.

Note

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

Parameters¶

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

Returns¶

Promise<string> - The signature.

Example¶

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

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

ecRecover¶

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

Recovers the account that signed the data.

Parameters¶

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

Returns¶

Promise<string> - The account.

Example¶

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

signTransaction¶

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

Signs a transaction. This account needs to be unlocked.

Note

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

Parameters¶

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

Returns¶

Promise<Object> - The RLP encoded transaction. The raw property can be used to send the transaction using web3.eth.sendSignedTransaction.

Example¶

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

sendTransaction¶

web3.eth.personal.sendTransaction(transactionOptions, password [, callback])

This method sends a transaction over the management API.

Note

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

Parameters¶

Object - The transaction options
String - The passphrase for the current account
Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns¶

Promise<string> - The transaction hash.

Example¶

web3.eth.sendTransaction({
    from: "0xEB014f8c8B418Db6b45774c326A0E64C78914dC0",
    gasPrice: "20000000000",
    gas: "21000",
    to: '0x3535353535353535353535353535353535353535',
    value: "1000000000000000000",
    data: ""
}, 'MyPassword!').then(console.log);
> '0xda3be87732110de6c1354c83770aae630ede9ac308d9f7b399ecfba23d923384'

unlockAccount¶

web3.eth.personal.unlockAccount(address, password, unlockDuraction [, callback])

Unlocks the given account.

Note

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

Parameters¶

address - String: The account address.
password - String - The password of the account.
unlockDuration - Number - The duration for the account to remain unlocked.
Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns¶

Promise<boolean> - True if the account got unlocked successful otherwise false.

Example¶

web3.eth.personal.unlockAccount("0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe", "test password!", 600)
.then(console.log('Account unlocked!'));
> "Account unlocked!"

lockAccount¶

web3.eth.personal.lockAccount(address [, callback])

Locks the given account.

Note

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

Parameters¶

1. address - String: The account address. 4. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns¶

Promise<boolean>

Example¶

web3.eth.personal.lockAccount("0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe")
.then(console.log('Account locked!'));
> "Account locked!"

getAccounts¶

web3.eth.personal.getAccounts([callback])

Returns a list of accounts the node controls by using the provider and calling the RPC method personal_listAccounts. Using web3.eth.accounts.create() will not add accounts into this list. For that use web3.eth.personal.newAccount().

The results are the same as web3.eth.getAccounts() except that calls the RPC method eth_accounts.

Returns¶

Promise<Array> - An array of addresses controlled by node.

Example¶

web3.eth.personal.getAccounts()
.then(console.log);
> ["0x11f4d0A3c12e86B4b5F39B213F7E19D048276DAe", "0xDCc6960376d6C6dEa93647383FfB245CfCed97Cf"]

importRawKey¶

web3.eth.personal.importRawKey(privateKey, password)

Imports the given private key into the key store, encrypting it with the passphrase.

Returns the address of the new account.

Note

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

Parameters¶

privateKey - String - An unencrypted private key (hex string).
password - String - The password of the account.

Returns¶

Promise<string> - The address of the account.

Example¶

web3.eth.personal.importRawKey("cd3376bb711cb332ee3fb2ca04c6a8b9f70c316fcdf7a1f44ef4c7999483295e", "password1234")
.then(console.log);
> "0x8f337bf484b2fc75e4b0436645dcc226ee2ac531"