Skip to main content

Private network API methods

Important
  • This reference contains API methods that apply to only private networks. For API methods that apply to both private and public networks, see the public network API reference.
  • All JSON-RPC HTTP examples use the default host and port endpoint http://127.0.0.1:8545. If using the --rpc-http-host or --rpc-http-port options, update the endpoint.

CLIQUE methods​

The CLIQUE API methods provide access to the Clique consensus engine.

note

The CLIQUE API methods are not enabled by default for JSON-RPC. To enable the CLIQUE API methods use the --rpc-http-api or --rpc-ws-api options.

clique_discard​

Discards a proposal to add or remove a signer with the specified address.

Parameters​

address: string - 20-byte address of proposed signer

Returns​

result: boolean - indicates if the proposal is discarded

curl -X POST --data '{"jsonrpc":"2.0","method":"clique_discard","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

clique_getSigners​

Lists signers for the specified block.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

note

pending returns the same value as latest.

Returns​

result: array of string - list of 20-byte addresses of signers

curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSigners","params":["latest"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

clique_getSignerMetrics​

Provides the following validator metrics for the specified range:

  • Number of blocks from each validator

  • Block number of the last block proposed by each validator (if any proposed in the specified range)

  • All validators present in the last block

Parameters​

  • fromBlockNumber: string - hexadecimal or decimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

  • toBlockNumber: string - hexadecimal or decimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

note

pending returns the same value as latest.

If you specify:

  • No parameters, the call provides metrics for the last 100 blocks, or all blocks if there are less than 100 blocks.

  • Only the first parameter, the call provides metrics for all blocks from the block specified to the latest block.

Returns​

result: array of objects - list of validator objects

note

The proposer of the genesis block has address 0x0000000000000000000000000000000000000000.

curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSignerMetrics","params":["1", "100"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

clique_getSignersAtHash​

Lists signers for the specified block.

Parameters​

hash: string - 32-byte block hash

Returns​

result: array of string - list of 20-byte addresses of signers

curl -X POST --data '{"jsonrpc":"2.0","method":"clique_getSignersAtHash","params":["0x98b2ddb5106b03649d2d337d42154702796438b3c74fd25a5782940e84237a48"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

clique_proposals​

Returns current proposals.

Parameters​

None

Returns​

result: map of strings to booleans - map of account addresses to corresponding boolean values indicating the proposal for each account (if true, the proposal is to add a signer; if false, the proposal is to remove a signer.)

curl -X POST --data '{"jsonrpc":"2.0","method":"clique_proposals","params":[], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

clique_propose​

Proposes to add or remove a signer with the specified address.

Parameters​

  • address: string - 20-byte address

  • proposal: boolean - true to propose adding signer or false to propose removing signer

Returns​

result: boolean - true

curl -X POST --data '{"jsonrpc":"2.0","method":"clique_propose","params":["0xFE3B557E8Fb62b89F4916B721be55cEb828dBd73", true], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

IBFT 2.0 methods​

The IBFT API methods provide access to the IBFT 2.0 consensus engine.

note

The IBFT API methods are not enabled by default for JSON-RPC. To enable the IBFT API methods, use the --rpc-http-api or --rpc-ws-api options.

ibft_discardValidatorVote​

Discards a proposal to add or remove a validator with the specified address.

Parameters​

address: string - 20-byte address of proposed validator

Returns​

result: boolean - indicates if the proposal is discarded

curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_discardValidatorVote","params":["0xef1bfb6a12794615c9b0b5a21e6741f01e570185"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

ibft_getPendingVotes​

Returns votes cast in the current epoch.

Parameters​

None

Returns​

result: map of strings to booleans - map of account addresses to corresponding boolean values indicating the vote for each account; if true, the vote is to add a validator. If false, the proposal is to remove a validator.

curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getPendingVotes","params":[], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

ibft_getSignerMetrics​

Provides the following validator metrics for the specified range:

  • Number of blocks from each validator

  • Block number of the last block proposed by each validator (if any proposed in the specified range)

  • All validators present in the last block of the range

Parameters​

  • fromBlockNumber: string - hexadecimal or decimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

  • toBlockNumber: string - hexadecimal or decimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

note

pending returns the same value as latest.

If you specify:

  • No parameters, the call provides metrics for the last 100 blocks, or all blocks if there are less than 100 blocks.

  • Only the first parameter, the call provides metrics for all blocks from the block specified to the latest block.

Returns​

result: array of objects - list of validator objects

note

The proposer of the genesis block has address 0x0000000000000000000000000000000000000000.

curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getSignerMetrics","params":["1", "100"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

ibft_getValidatorsByBlockHash​

Lists the validators defined in the specified block.

Parameters​

block: string - 32-byte block hash

Returns​

result: array of strings - list of validator addresses

curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockHash","params":["0xbae7d3feafd743343b9a4c578cab5e5d65eb735f6855fb845c00cab356331256"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

ibft_getValidatorsByBlockNumber​

Lists the validators defined in the specified block.

Parameters​

blockNumber: string - hexadecimal or decimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

note

pending returns the same value as latest.

Returns​

result: array of strings - list of validator addresses

curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_getValidatorsByBlockNumber","params":["latest"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

ibft_proposeValidatorVote​

Proposes to add or remove a validator with the specified address.

Parameters​

  • address: string - account address

  • proposal: boolean - true to propose adding validator or false to propose removing validator

Returns​

result: boolean - true

curl -X POST --data '{"jsonrpc":"2.0","method":"ibft_proposeValidatorVote","params":["42d4287eac8078828cf5f3486cfe601a275a49a5",true], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

PERM (Permissioning) methods​

The PERM API methods provide permissioning functionality. Use these methods for local permissioning only.

important

The PERM API methods are not enabled by default for JSON-RPC. To enable the PERM API methods, use the --rpc-http-api or --rpc-ws-api CLI options.

perm_addAccountsToAllowlist​

Adds accounts (participants) to the accounts permission list.

Parameters​

addresses: array of strings - list of account addresses

note

The parameters list contains a list which is why the account addresses are enclosed by double square brackets.

Returns​

result: string - Success or error (errors include attempting to add accounts already on the allowlist and including invalid account addresses.)

curl -X POST --data '{"jsonrpc":"2.0","method":"perm_addAccountsToAllowlist","params":[["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"]], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

perm_addNodesToAllowlist​

Adds nodes to the nodes allowlist.

To use domain names in enode URLs, ensure you enable DNS support to avoid receiving a request contains an invalid node error.

warning

Enode URL domain name support is an early access feature.

Parameters​

enodes: array of strings - list of enode URLs

note

The parameters list contains a list which is why the enode URLs are enclosed by double square brackets.

Returns​

result: string - Success or error; errors include attempting to add nodes already on the allowlist or including invalid enode URLs.

curl -X POST --data '{"jsonrpc":"2.0","method":"perm_addNodesToAllowlist","params":[["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304"]], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

perm_getAccountsAllowlist​

Lists accounts (participants) in the accounts permissions list.

Parameters​

None

Returns​

result: array of strings - list of accounts (participants) in the accounts allowlist

curl -X POST --data '{"jsonrpc":"2.0","method":"perm_getAccountsAllowlist","params":[], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

perm_getNodesAllowlist​

Lists nodes in the nodes allowlist.

Parameters​

None

Returns​

result: array of strings - enode URLs of nodes in the nodes allowlist

curl -X POST --data '{"jsonrpc":"2.0","method":"perm_getNodesAllowlist","params":[], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

perm_reloadPermissionsFromFile​

Reloads the accounts and nodes allowlists from the permissions configuration file.

Parameters​

None

Returns​

result: string - Success, or error if the permissions configuration file is not valid

curl -X POST --data '{"jsonrpc":"2.0","method":"perm_reloadPermissionsFromFile","params":[], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

perm_removeAccountsFromAllowlist​

Removes accounts (participants) from the accounts permissions list.

Parameters​

addresses: array of strings - list of account addresses

note

The parameters list contains a list which is why the account addresses are enclosed by double square brackets.

Returns​

result: string - Success or error (errors include attempting to remove accounts not on the allowlist and including invalid account addresses.)

curl -X POST --data '{"jsonrpc":"2.0","method":"perm_removeAccountsFromAllowlist","params":[["0xb9b81ee349c3807e46bc71aa2632203c5b462032", "0xb9b81ee349c3807e46bc71aa2632203c5b462034"]], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

perm_removeNodesFromAllowlist​

Removes nodes from the nodes allowlist.

Parameters​

enodes: array of strings - list of enode URLs

note

The parameters list contains a list which is why the enode URLs are enclosed by double square brackets.

Returns​

result: string - Success or error (errors include attempting to remove nodes not on the allowlist and including invalid enode URLs.)

curl -X POST --data '{"jsonrpc":"2.0","method":"perm_removeNodesFromAllowlist","params":[["enode://7e4ef30e9ec683f26ad76ffca5b5148fa7a6575f4cfad4eb0f52f9c3d8335f4a9b6f9e66fcc73ef95ed7a2a52784d4f372e7750ac8ae0b544309a5b391a23dd7@127.0.0.1:30303","enode://2feb33b3c6c4a8f77d84a5ce44954e83e5f163e7a65f7f7a7fec499ceb0ddd76a46ef635408c513d64c076470eac86b7f2c8ae4fcd112cb28ce82c0d64ec2c94@127.0.0.1:30304"]], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

QBFT methods​

The QBFT API methods provide access to the QBFT consensus engine.

note

The QBFT API methods are not enabled by default for JSON-RPC. To enable the QBFT API methods, use the --rpc-http-api or --rpc-ws-api options.

qbft_discardValidatorVote​

Discards a proposal to add or remove a validator with the specified address.

Parameters​

address: string - 20-byte address of proposed validator

Returns​

result: boolean - indicates if the proposal is discarded

curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_discardValidatorVote","params":["0xef1bfb6a12794615c9b0b5a21e6741f01e570185"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

qbft_getPendingVotes​

Returns votes cast in the current epoch.

Parameters​

None

Returns​

result: map of strings to booleans - map of account addresses to corresponding boolean values indicating the vote for each account; if true, the vote is to add a validator. If false, the proposal is to remove a validator.

curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getPendingVotes","params":[], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

qbft_getSignerMetrics​

Provides the following validator metrics for the specified range:

  • Number of blocks from each validator

  • Block number of the last block proposed by each validator (if any proposed in the specified range)

  • All validators present in the last block of the range

Parameters​

  • fromBlockNumber: string - hexadecimal or decimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

  • toBlockNumber: string - hexadecimal or decimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

note

pending returns the same value as latest.

If you specify:

  • No parameters, the call provides metrics for the last 100 blocks, or all blocks if there are less than 100 blocks.

  • Only the first parameter, the call provides metrics for all blocks from the block specified to the latest block.

Returns​

result: array of objects - list of validator objects

note

The proposer of the genesis block has address 0x0000000000000000000000000000000000000000.

curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getSignerMetrics","params":["1", "100"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

qbft_getValidatorsByBlockHash​

Lists the validators defined in the specified block.

Parameters​

block: string - 32-byte block hash

Returns​

result: array of strings - list of validator addresses

curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockHash","params":["0xbae7d3feafd743343b9a4c578cab5e5d65eb735f6855fb845c00cab356331256"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

qbft_getValidatorsByBlockNumber​

Lists the validators for the specified block.

For all blocks up to the chain head block this method returns the validators that were used at the time the block was produced.

Use blockNumber to get the list of validators for that block.

For the chain head block there are two validator lists associated with it:

  1. The validators that were used at the time the block was produced. This list is returned by passing latest as the input parameter.
  2. The validators that will be used to produce the next block. This list is returned by passing pending as the input parameter.

In most instances the two lists for the chain head block are the same. However, when voting has completed to add or remove a validator, the validators that will be used to produce the next block are different. Comparing the two lists can be helpful when diagnosing a stalled chain.

note

When the validator list changes, an INFO log message displays, showing the previous list of validators and the new list of validators.

Parameters​

  • blockNumber: string - hexadecimal or decimal integer representing a block number, or one of the string tags latest, earliest, pending, finalized, or safe, as described in block parameter

Returns​

result: array of strings - list of validator addresses

curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_getValidatorsByBlockNumber","params":["latest"], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"

qbft_proposeValidatorVote​

Proposes to add or remove a validator with the specified address.

Parameters​

  • address: string - account address

  • proposal: boolean - true to propose adding validator or false to propose removing validator

Returns​

result: boolean - true

curl -X POST --data '{"jsonrpc":"2.0","method":"qbft_proposeValidatorVote","params":["42d4287eac8078828cf5f3486cfe601a275a49a5",true], "id":1}' http://127.0.0.1:8545/ -H "Content-Type: application/json"