Note

This documentation is under construction and documents the 2.x alpha versions of web3.js. The current stable version of web3.js is 1.0 and should get preferred for production use cases.

Debug Module

The web3-eth-debug module allows you to interact with the Ethereum node’s debug methods.

import Web3 from 'web3';
import {Debug} from 'web3-eth-debug';

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

options

An Web3 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:

Example

import Web3 from 'web3';

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

const web3 = new Web3('http://localhost:8545', null, options);

defaultBlock

web3.defaultBlock
web3.eth.defaultBlock
web3.shh.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

web3.defaultAccount
web3.eth.defaultAccount
web3.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

web3.defaultGasPrice
web3.eth.defaultGasPrice
web3.shh.defaultGasPrice
...

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

Returns

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


defaultGas

web3.defaultGas
web3.eth.defaultGas
web3.shh.defaultGas
...

The default gas which will be used for a request.

Returns

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


transactionBlockTimeout

web3.transactionBlockTimeout
web3.eth.transactionBlockTimeout
web3.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

web3.transactionConfirmationBlocks
web3.eth.transactionConfirmationBlocks
web3.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

web3.transactionPollingTimeout
web3.eth.transactionPollingTimeout
web3.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

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

web3.setProvider(myProvider)
web3.eth.setProvider(myProvider)
web3.shh.setProvider(myProvider)
...

Will change the provider for its module.

Note

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

Parameters

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

Returns

Boolean

Example

import Web3 from 'web3';

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

// or
const 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'));

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

// or
const web3 = 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('web3');
// use the given Provider, e.g in Mist, or instantiate a new websocket provider
const web3 = new Web3(Web3.givenProvider || 'ws://localhost:8546');
// or
const web3 = new Web3(Web3.givenProvider || new Web3.providers.WebsocketProvider('ws://localhost:8546'));

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

const web3 = new Web3('/Users/myuser/Library/Ethereum/geth.ipc', net); // mac os path
// or
const web3 = 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
web3.eth.givenProvider
web3.shh.givenProvider
...

When using web3.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

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

currentProvider

web3.currentProvider
web3.eth.currentProvider
web3.shh.currentProvider
...

Will return the current provider.

Returns

Object: The current provider set.

Example

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

BatchRequest

new web3.BatchRequest()
new web3.eth.BatchRequest()
new web3.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 web3.eth.Contract(abi, address);

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

setBackTraceAt

debug.setBackTraceAt(location, [callback])

Sets the logging backtrace location.

Parameters

  1. location - String: The location is specified as <filename>:<line>.
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

admin.setBackTraceAt('filename.go:200').then(console.log);

blockProfile

debug.blockProfile(file, seconds, [, callback])

Turns on block profiling for the given duration and writes profile data to disk. If a custom rate is desired, set the rate and write the profile manually using debug.writeBlockProfile.

Parameters

1. file - String 1. seconds - Number|String The seconds as Hex string or number. 2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.blockProfile('file', 100).then(console.log);
> null

cpuProfile

debug.cpuProfile(file, seconds, [, callback])

Turns on CPU profiling for the given duration and writes profile data to disk.

Parameters

1. file - String 1. seconds - Number | String The seconds as Hex string or number. 2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.cpuProfile('file', 100).then(console.log);
> null

dumpBlock

debug.dumpBlock(blockNumber, [, callback])

Retrieves the state that corresponds to the block number and returns a list of accounts (including storage and code).

Parameters

  1. blockNumber - Number | String The block number as Hex string or number.
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<Object>

Example

debug.dumpBlock('file', 100).then(console.log);
{
    root: "19f4ed94e188dd9c7eb04226bd240fa6b449401a6c656d6d2816a87ccaf206f1",
    accounts: {
        fff7ac99c8e4feb60c9750054bdc14ce1857f181: {
            balance: "49358640978154672",
            code: "",
            codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
            nonce: 2,
            root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
            storage: {}
        },
        fffbca3a38c3c5fcb3adbb8e63c04c3e629aafce: {
            balance: "3460945928",
            code: "",
            codeHash: "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470",
            nonce: 657,
            root: "56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
            storage: {}
        }
    },
}

getGCStats

debug.getGCStats([, callback])

Returns GC statistics. See https://golang.org/pkg/runtime/debug/#GCStats for information about the fields of the returned object.

Parameters

  1. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<Object>

Example

debug.getGCStats().then(console.log);

getBlockRlp

debug.getBlockRlp(number, [, callback])

Retrieves and returns the RLP encoded block by number.

Parameters

  1. number - Number | String The block number as hex string or number.
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<string>

Example

debug.getBlockRlp(100).then(console.log);
> '0x0'

goTrace

debug.goTrace(file, seconds, [, callback])

Turns on Go runtime tracing for the given duration and writes trace data to disk.

Parameters

1. file - String 1. seconds - Number | String The seconds as Hex string or number. 2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.goTrace('file', 100).then(console.log);
> null

getMemStats

debug.getMemStats([, callback])

Returns detailed runtime memory statistics.

Parameters

  1. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<Object>

Example

debug.getMemStats().then(console.log);
> MemStats // MemStats object from Go

getSeedHash

debug.getSeedHash(number, [, callback])

Fetches and retrieves the seed hash of the block by number

Parameters

1. number - Number | String The block number as Hex string or number. 1. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<string>

Example

debug.getSeedHash().then(console.log);
> '0x0'

setBlockProfileRate

debug.setBlockProfileRate(rate, [, callback])

Sets the rate (in samples/sec) of goroutine block profile data collection. A non-zero rate enables block profiling, setting it to zero stops the profile. Collected profile data can be written using debug.writeBlockProfile.

Parameters

  1. number - Number | String The block profile rate as number or Hex string.
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.setBlockProfileRate().then(console.log);
> null

setHead

debug.setHead(number, [, callback])

Sets the current head of the local chain by block number. Note, this is a destructive action and may severely damage your chain. Use with extreme caution.

Parameters

  1. number - Number | String The block number as Hex string or number.
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.setHead(100).then(console.log);
> null

getStacks

debug.getStacks([, callback])

Returns a printed representation of the stacks of all goroutines.

Parameters

  1. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<string>

Example

debug.getStacks().then(console.log);

startCPUProfile

debug.startCPUProfile(file, [, callback])

Turns on CPU profiling indefinitely, writing to the given file.

Parameters

  1. file - String
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.startCPUProfile().then(console.log);
> null

stopCPUProfile

debug.stopCPUProfile([, callback])

Stops an ongoing CPU profile.

Parameters

  1. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.stopCPUProfile().then(console.log);
> null

startGoTrace

debug.startGoTrace(file, [, callback])

Turns on CPU profiling indefinitely, writing to the given file.

Parameters

  1. file - String
  2. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.startGoTrace('file').then(console.log);
> null

stopGoTrace

debug.stopGoTrace([, callback])

Stops writing the Go runtime trace.

Parameters

  1. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.stopGoTrace().then(console.log);
> null

getBlockTrace

debug.getBlockTrace(blockRlp, options, [, callback])

The traceBlock method will return a full stack trace of all invoked opcodes of all transaction that were included included in this block. Note, the parent of this block must be present or it will fail.

Parameters

  1. blockRlp - String RLP encoded block
  2. options - Object The block trace object
  3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<Object>

Example

debug.getBlockTrace('0x0', {}).then(console.log);
> {
    gas: 85301,
    returnValue: "",
    structLogs: [{...}]
}

getBlockTraceByNumber

debug.getBlockTraceByNumber(number, options, [, callback])

The traceBlockByNumber method accepts a block number and will replay the block that is already present in the database.

Parameters

  1. number - Number | String The block number as Hex string or number.
  2. options - Object The block trace object
  3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<Object>

Example

debug.getBlockTraceByNumber(100, {}).then(console.log);
> {
    gas: 85301,
    returnValue: "",
    structLogs: [{...}]
}

getBlockTraceByHash

debug.getBlockTraceByHash(hash, options, [, callback])

The traceBlockByHash accepts a block hash and will replay the block that is already present in the database.

Parameters

  1. hash - String The block hash
  2. options - Object The block trace object
  3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<Object>

Example

debug.getBlockTraceByHash('0x0', {}).then(console.log);
> {
    gas: 85301,
    returnValue: "",
    structLogs: [{...}]
}

getBlockTraceFromFile

debug.getBlockTraceFromFile(fileName, options, [, callback])

The traceBlockFromFile accepts a file containing the RLP of the block.

Parameters

  1. fileName - String The file name
  2. options - Object The block trace object
  3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<Object>

Example

debug.getBlockTraceFromFile('filename', {}).then(console.log);
> {
    gas: 85301,
    returnValue: "",
    structLogs: [{...}]
}

getTransactionTrace

debug.getTransactionTrace(txHash, options, [, callback])

The traceTransaction debugging method will attempt to run the transaction in the exact same manner as it was executed on the network. It will replay any transaction that may have been executed prior to this one before it will finally attempt to execute the transaction that corresponds to the given hash.

In addition to the hash of the transaction you may give it a secondary optional argument, which specifies the options for this specific call.

The possible options are:

1. disableStorage - boolean Setting this to true will disable storage capture (default = false). 1. disableMemory - boolean Setting this to true will disable memory capture (default = false). 1. disableStack - boolean Setting this to true will disable stack capture (default = false). 1. tracer - string Setting this will enable JavaScript-based transaction tracing, described below. If set, the previous four arguments will be ignored. 1. timeout - string Overrides the default timeout of 5 seconds for JavaScript-based tracing calls

JSON-RPC specification for debug_traceTransaction

Parameters

  1. txHash - String The transaction hash
  2. options - Object The block trace object
  3. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<Object>

Example

debug.getTransactionTrace('0x0', {}).then(console.log);
> {
    gas: 85301,
    returnValue: "",
    structLogs: [{...}]
}

setVerbosity

debug.setVerbosity(level, [, callback])

Sets the logging verbosity ceiling. Log messages with level up to and including the given level will be printed. The verbosity of individual packages and source files can be raised using debug.setVerbosityPattern.

Parameters

1. level - Number | String The verbosity level as Hex string or number. 1. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

debug.setVerbosity(1).then(console.log);
> null

setVerbosityPattern

debug.setVerbosityPattern(pattern, [, callback])

Sets the logging verbosity pattern.

Parameters

1. pattern - String The verbosity pattern 1. Function - (optional) Optional callback, returns an error object as first parameter and the result as second.

Returns

Promise<null>

Example

// If you want to see messages from a particular Go package (directory) and all subdirectories, use:
debug.setVerbosityPattern('eth/*=6').then(console.log);
> null

// If you want to restrict messages to a particular package (e.g. p2p) but exclude subdirectories, use:
debug.setVerbosityPattern('p2p=6').then(console.log);
> null

// If you want to see log messages from a particular source file, use:
debug.setVerbosityPattern('server.go=6').then(console.log);
> null

// You can compose these basic patterns. If you want to see all output from peer.go in a package below eth
// (eth/peer.go, eth/downloader/peer.go) as well as output from package p2p at level <= 5, use:
debug.setVerbosityPattern('eth/*/peer.go=6,p2p=5').then(console.log);
> null

writeBlockProfile

debug.writeBlockProfile(file, [, callback])

Writes a goroutine blocking profile to the given file.

Parameters

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

Returns

Promise<null>

Example

debug.writeBlockProfile('file').then(console.log);
> null

writeMemProfile

debug.writeMemProfile(file, [, callback])

Writes an allocation profile to the given file.

Parameters

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

Returns

Promise<null>

Example

debug.writeBlockProfile('file').then(console.log);
> null