@ -19,8 +19,8 @@ To delete the local block data, delete the `database` directory in the `pantheon
## Genesis Configuration
## Genesis Configuration
Pantheon specifies the genesis configuration, and sets the network ID and bootnodes when connecting to [Mainnet](#run-a-node-on-ethereum-mainnet),
Pantheon specifies the genesis configuration, and sets the network ID and bootnodes when connecting
[Rinkeby](#run-a-node-on-rinkeby-testnet), and [Ropsten](#run-a-node-on-ropsten-testnet).
to [Mainnet](#run-a-node-on-ethereum-mainnet), [Goerli](#run-a-node-on-goerli-testnet), [Rinkeby](#run-a-node-on-rinkeby-testnet), and [Ropsten](#run-a-node-on-ropsten-testnet).
When [`--dev-mode`](../Reference/Pantheon-CLI-Syntax.md#dev-mode) is specified, Pantheon uses the development mode genesis configuration.
When [`--dev-mode`](../Reference/Pantheon-CLI-Syntax.md#dev-mode) is specified, Pantheon uses the development mode genesis configuration.
@ -79,11 +79,9 @@ $ bin/pantheon --rpc-enabled
## Run a Node on Ropsten Testnet
## Run a Node on Ropsten Testnet
!!!note
!!!note
From v0.8.2 or when [building from source](../Installation/Overview.md), use the [`--ropsten` option](../Reference/Pantheon-CLI-Syntax.md#options)
From v0.8.2, use the [`--ropsten` option](../Reference/Pantheon-CLI-Syntax.md#options)
instead of the following options. For v0.8.1, use the following options.
instead of the following options. For v0.8.1, use the following options.
Replace `<path>` with the path to the `/pantheon` directory.
To run a node on Ropsten:
To run a node on Ropsten:
```bash
```bash
@ -96,15 +94,29 @@ To run a node on Ropsten with the HTTP JSON-RPC service enabled and allow Remix
@ -4,7 +4,7 @@ description: Pantheon JSON-RPC API methods reference
# JSON-RPC API Methods
# JSON-RPC API Methods
!!! danger "Breaking Change in v0.8.3"
!!! danger "Breaking Change in v0.8.3"
From v0.8.3, incoming HTTP requests are only accepted from hostnames specified using the [`--host-whitelist`](Using-JSON-RPC-API.md#breaking-change-in-v083) option.
From v0.8.3, incoming HTTP requests are only accepted from hostnames specified using the [`--host-whitelist`](Using-JSON-RPC-API.md) option.
The following lists the Pantheon JSON-RPC API commands:
The following lists the Pantheon JSON-RPC API commands:
@ -26,10 +26,10 @@ Properties of the remote node object are:
* `version` - P2P protocol version
* `version` - P2P protocol version
* `name` - Client name
* `name` - Client name
* `caps` - P2P message capabilities
* `caps` - List of Ethereum sub-protocol capabilities
* `network` - Addresses of local node and remote node
* `network` - Addresses of local node and remote node
* `port` - Port
* `port` - Port on the remote node on which P2P peer discovery is listening
* `id` - Node public key. Excluding the `0x` prefix, the node public key is the ID in the enode URL `enode://<id ex 0x>@<host:port>`.
* `id` - Node public key. Excluding the `0x` prefix, the node public key is the ID in the enode URL `enode://<id ex 0x>@<host>:<port>`.
!!! example
!!! example
```bash tab="curl HTTP request"
```bash tab="curl HTTP request"
@ -46,18 +46,22 @@ Properties of the remote node object are:
Returns the [chain ID](../Configuring-Pantheon/NetworkID-And-ChainID.md).
Returns the [chain ID](../Configuring-Pantheon/NetworkID-And-ChainID.md).
!!!note
!!!note
This method is only available from v0.8.2 or when you [build from source](../Installation/Build-From-Source.md).
This method is only available from v0.8.2.
**Parameters**
**Parameters**
@ -404,7 +408,7 @@ None
Returns a list of account addresses that the client owns.
Returns a list of account addresses that the client owns.
!!!note
!!!note
This method returns an empty object because Pantheon [does not support account management](Using-JSON-RPC-API.md#account-management-not-supported-by-pantheon).
This method returns an empty object because Pantheon [does not support account management](Using-JSON-RPC-API.md#account-management).
**Parameters**
**Parameters**
@ -502,7 +506,7 @@ Returns the value of a storage position at a specified address.
`QUANTITY` - Integer index of the storage position.
`QUANTITY` - Integer index of the storage position.
`QUANTITY|TAG` - Integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in [Block Parameter](JSON-RPC-API-Objects.md#block-parameter).
`QUANTITY|TAG` - Integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in [Block Parameter](Using-JSON-RPC-API.md#block-parameter).
**Returns**
**Returns**
@ -714,7 +718,7 @@ You can interact with contracts using [eth_sendRawTransaction or eth_call](../Us
To avoid exposing your private key, create signed transactions offline and send the signed transaction data using this method. For information on creating signed transactions and using `eth_sendRawTransaction`, refer to [Using Pantheon](../Using-Pantheon/Transactions.md).
To avoid exposing your private key, create signed transactions offline and send the signed transaction data using this method. For information on creating signed transactions and using `eth_sendRawTransaction`, refer to [Using Pantheon](../Using-Pantheon/Transactions.md).
!!!important
!!!important
Pantheon does not implement [eth_sendTransaction](Using-JSON-RPC-API.md#account-management-not-supported-by-pantheon).
Pantheon does not implement [eth_sendTransaction](Using-JSON-RPC-API.md#account-management).
**Parameters**
**Parameters**
@ -754,7 +758,7 @@ You can interact with contracts using [eth_sendRawTransaction or eth_call](../Us
*QUANTITY|TAG* - Integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in [Block Parameter](JSON-RPC-API-Objects.md#block-parameter).
*QUANTITY|TAG* - Integer representing a block number or one of the string tags `latest`, `earliest`, or `pending`, as described in [Block Parameter](Using-JSON-RPC-API.md#block-parameter).
**Returns**
**Returns**
@ -1098,14 +1102,13 @@ Returns the receipt of a transaction by transaction hash. Receipts for pending t
### eth_newFilter
### eth_newFilter
Creates a topic filter with the specified options to notify (log) when the state changes. To determine whether the state has changed, call [eth_getFilterChanges](#eth_getfilterchanges).
Creates a logs filter to log state changes. To poll for state changes, use [eth_getFilterChanges](#eth_getfilterchanges).
Topics are order-dependent. A transaction with a log containing topics `[A, B]` would be matched with the following topic filters:
Topics are order-dependent. A transaction with a log containing topics `[A, B]` would be matched with the following topic filters:
* [] - Match any topic
* [] - Match any topic
* [A] - Match A in first position (and any topic thereafter)
* [A] - Match A in first position (and any topic thereafter)
@ -1113,63 +1116,33 @@ Creates a topic filter with the specified options to notify (log) when the state
* [A, B] - Match A in first position AND B in second position (and any topic thereafter)
* [A, B] - Match A in first position AND B in second position (and any topic thereafter)
* [[A, B], [A, B]] - Match (A OR B) in first position AND (A OR B) in second position (and any topic thereafter)
* [[A, B], [A, B]] - Match (A OR B) in first position AND (A OR B) in second position (and any topic thereafter)
For example, params could be specified as follows:
!!!note
!!!example
`fromBlock` and `toBlock` in the filter options object default to `latest`. To obtain logs using `eth_getFilterLogs`, set `fromBlock` and `toBlock` appropriately.
Creates a filter in the node that notifies when a new block arrives. To determine whether the state has changed, call [eth_getFilterChanges](#eth_getfilterchanges).
Creates a filter to log when a new block arrives. To poll for new blocks, use [eth_getFilterChanges](#eth_getfilterchanges).
**Parameters**
**Parameters**
@ -1177,28 +1150,28 @@ None
**Returns**
**Returns**
`QUANTITY` - Hexadecimal integer filter ID. Each time you call this method, it creates a new filter, and the index is incremented by 1.
`data` - Filter ID hash
!!! example
!!! example
```bash tab="curl HTTP request"
```bash tab="curl HTTP request"
$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":53}' <JSON-RPC-http-endpoint:port>
$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' <JSON-RPC-http-endpoint:port>
Creates a filter in the node that notifies when new pending transactions arrive. To check if the state has changed, call [eth_getFilterChanges](#eth_getfilterchanges).
Creates a filter to log when new pending transactions arrive. To poll for new pending transactions, use [eth_getFilterChanges](#eth_getfilterchanges).
**Parameters**
**Parameters**
@ -1206,35 +1179,34 @@ None
**Returns**
**Returns**
`QUANTITY` - Hexadecimal integer filter ID. Each time you call this method, it creates a new filter, and the index is incremented by 1.
`data` - Filter ID hash
!!! example
!!! example
```bash tab="curl HTTP request"
```bash tab="curl HTTP request"
$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":53}' <JSON-RPC-http-endpoint:port>
$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":1}' <JSON-RPC-http-endpoint:port>
Uninstalls a filter with the specified ID. This method should always be called when notification is no longer needed. Note that filters time out when they are not requested with [eth_getFilterChanges](#eth_getfilterchanges) for a period of time.
Uninstalls a filter with the specified ID. When a filter is no longer required, call this method.
This method deletes filters of any type: block filters, pending transaction filters, and state (topic) filters.
Filters time out when they are not requested by [eth_getFilterChanges](#eth_getfilterchanges) for a period of time.
**Parameters**
**Parameters**
`QUANTITY` - Hexadecimal integer filter ID specifying the filter to be deleted.
`data` - Filter ID hash
**Returns**
**Returns**
@ -1244,75 +1216,133 @@ This method deletes filters of any type: block filters, pending transaction filt
The following request deletes the block filter with an ID of 0x4:
The following request deletes the block filter with an ID of 0x4:
```bash tab="curl HTTP request"
```bash tab="curl HTTP request"
$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x4"],"id":53}' <JSON-RPC-http-endpoint:port>
$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x70355a0b574b437eaa19fe95adfedc0a"],"id":1}' <JSON-RPC-http-endpoint:port>
You must be synchronized to at least the requested block for the request to return the logs.
!!! example
!!! example
The request above returns the logs for the 82893 block on the Ropsten testnet. You can also view this [block](https://ropsten.etherscan.io/block/82983) on Etherscan.
The following request returns all logs for the contract at address `0x2e1f232a9439c3d459fceca0beef13acc8259dd8`.
```bash tab="curl HTTP request"
```bash tab="curl HTTP request"
$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"blockhash":"0x677bf4b962464e6dfd548d6a30b6c703dd78c7cc3602825a7013a6e90a001d2a"}], "id":1}' <JSON-RPC-http-endpoint:port>
@ -26,7 +26,7 @@ Runs the Pantheon Ethereum full node client.
List of node IDs with which this node will not peer. The node ID is the public key of the node. You can specify the banned node IDs with or without the `0x` prefix.
List of node IDs with which this node will not peer. The node ID is the public key of the node. You can specify the banned node IDs with or without the `0x` prefix.
!!!info
!!!info
This option is only available from v0.8.2 or when [building from source](../Installation/Build-From-Source.md).
This option is only available from v0.8.2.
### bootnodes
### bootnodes
@ -138,10 +138,22 @@ When using this option, it is recommended to also set the [`--network-id`](#netw
If both are specified, the specified genesis file is ignored and the development mode configuration used.
If both are specified, the specified genesis file is ignored and the development mode configuration used.
### goerli
```bash tab="Syntax"
--goerli
```
Uses the Goerli test network. Default is false.
!!!note
This option is only available from v0.8.3.
### host-whitelist
### host-whitelist
```bash tab="Syntax"
```bash tab="Syntax"
--host-whitelist=<hostname>[,<hostname>...]...
--host-whitelist=<hostname>[,<hostname>...]... or * or all
```
```
```bash tab="Example"
```bash tab="Example"
@ -151,11 +163,10 @@ When using this option, it is recommended to also set the [`--network-id`](#netw
Comma-separated list of hostnames to allow access to the HTTP JSON-RPC API. Default is `localhost`.
Comma-separated list of hostnames to allow access to the HTTP JSON-RPC API. Default is `localhost`.
!!!tip
!!!tip
To allow all hostnames, use `*` or `all`. We don't recommend this for production code.
To allow all hostnames, use `*` or `all`. We don't recommend allowing all hostnames for production code.
!!!note
!!!note
This option is only available from v0.8.3 or when [building from source](../Installation/Build-From-Source.md).
This option is only available from v0.8.3. Earlier versions allow access by all hostnames.
Earlier versions allow access by all hostnames.
### max-peers
### max-peers
@ -277,7 +288,7 @@ otherwise, the existing key file specifies the node private key.
The private key is not encrypted.
The private key is not encrypted.
!!!note
!!!note
This option is only available from v0.8.2 or when [building from source](../Installation/Build-From-Source.md).
This option is only available from v0.8.2.
### nodes-whitelist
### nodes-whitelist
@ -294,7 +305,7 @@ If you specify an empty list or [`--nodes-whitelist`](#nodes-whitelist) without
!!!note
!!!note
This option is only available from v0.8.3 or when [building from source](../Installation/Build-From-Source.md).
This option is only available from v0.8.3.
!!!note
!!!note
:construction: Permissioning is not currently supported. Support for permissioning is in active development.
:construction: Permissioning is not currently supported. Support for permissioning is in active development.
@ -347,8 +358,7 @@ Uses the Ropsten test network.
Default is `false`.
Default is `false`.
!!!note
!!!note
This option is only available only from v0.8.2 or when [building from source](../Installation/Build-From-Source.md).
This option is only available only from v0.8.2. For v0.8.1, refer to [Starting Pantheon](../Getting-Started/Starting-Pantheon.md#run-a-node-on-ropsten-testnet).
For v0.8.1, refer to [Ropsten section on Starting Pantheon page](../Getting-Started/Starting-Pantheon.md#run-a-node-on-ropsten-testnet).
@ -5,14 +5,14 @@ description: How to use Pantheon JSON-RPC API
!!!attention "Breaking Change in v0.8.3"
!!!attention "Breaking Change in v0.8.3"
From v0.8.3, incoming HTTP requests are only accepted from hostnames specified using the [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) option.
From v0.8.3, to prevent an issue known as DNS rebinding incoming HTTP requests are only accepted from hostnames specified using the [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) option.
If not specified, the default value for [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) is `localhost`.
The default value for [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) is `localhost`.
If using the URL `http://127.0.0.1` to make JSON-RPC calls, use [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) to specify the hostname `127.0.0.1` or update the hostname to `localhost`.
If using the URL `http://127.0.0.1` to make JSON-RPC calls, use [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) to specify the hostname `127.0.0.1` or update the hostname in the JSON-RPC call to `localhost`.
If your application publishes RPC ports, specify the hostnames when starting Pantheon. For example:
If your application publishes RPC ports, specify the hostnames when starting Pantheon. For example:
```bash
```bash
pantheon --host-whitelist=foo.com
pantheon --host-whitelist=example.com
```
```
Specify `*` or `all` for [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) to effectively disable host protection and replicate pre-v0.8.3 behavior.
Specify `*` or `all` for [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) to effectively disable host protection and replicate pre-v0.8.3 behavior.
@ -5,23 +5,27 @@ description: Using RPC Pub/Sub with Pantheon Web Socket API
## Introduction
## Introduction
Use the RPC Pub/Sub methods over [WebSockets](../Reference/Using-JSON-RPC-API.md#endpoint-address-and-port)
Use the RPC Pub/Sub API to wait for events instead of polling for them. For example, a Dapp can subscribe to logs to be notified when a specific event has occurred.
to wait for events instead of polling for them. For example, if a Dapp submits a transaction to the network,
you can use the RPC Pub/Sub interface to wait for the transaction confirmation followed by a specified
number of new blocks before confirming the transaction to the user.
The RPC Pub/Sub methods are:
The RPC Pub/Sub methods are:
* `eth_subscribe` - call to create a subscription for specific events.
* `eth_subscribe` - create a subscription for specific events.
* `eth_unsubscribe` - call to cancel a subscription.
* `eth_unsubscribe` - cancel a subscription.
* `eth_subscription` - invoked to publish event notifications to your client.
!!!info
Notifications are published by `eth_subscription`; you do not need to call `eth_subscription`.
!!!important
!!!important
Unlike other [JSON RPC-API methods](../Reference/JSON-RPC-API-Methods.md),
Unlike other [JSON RPC-API methods](../Reference/JSON-RPC-API-Methods.md),
the RPC Pub/Sub methods cannot be called over HTTP as well as WebSockets.
the RPC Pub/Sub methods cannot be called over HTTP.
### Using RPC Pub/Sub
The RPC Pub/Sub API requires a persistent connection. Connect to the RPC Pub/Sub API using a tool such as [WebSockets](../Reference/Using-JSON-RPC-API.md#endpoint-address-and-port).
Use `eth_subscribe` to create subscriptions. Once subscribed, notifications are published by the API using `eth_subscription`.
!!!note
Notifications are published by `eth_subscription`; you do not need to call `eth_subscription`.
Subscriptions are coupled to a connection. If the connection is closed, all subscriptions created over this connection are removed.
### Subscription ID
### Subscription ID
@ -47,9 +51,6 @@ The RPC Pub/Sub methods are:
Subscribing to some events (for example, logs) can cause a flood of notifications while the node is synchronizing.
Subscribing to some events (for example, logs) can cause a flood of notifications while the node is synchronizing.
Notifications are stored in an internal buffer to be sent to the client.
If the client falls behind and the number of buffered notifications reaches the limit of ==10,000==, the connection is closed.
## Subscribing
## Subscribing
Use `eth_subscribe` to create subscriptions for the following event types:
Use `eth_subscribe` to create subscriptions for the following event types:
@ -59,23 +60,22 @@ Use `eth_subscribe` to create subscriptions for the following event types:
* [Pending transactions](#pending-transactions)
* [Pending transactions](#pending-transactions)
* [Sychronizng](#synchronizing)
* [Sychronizng](#synchronizing)
If the WebSockets connection is closed, all subscriptions are removed.
### New Headers
### New Headers
Use the `newHeads` parameter with `eth_subscribe` to be notified each time a new header is added to the blockchain.
Use the `newHeads` parameter with `eth_subscribe` to be notified each time a block is added to the blockchain.
If a chain reorganization occurs, the subscription publishes notifications for headers in the new chain.
If a chain reorganization occurs, the subscription publishes notifications for blocks in the new chain.
This means the subscription can publish notifications for multiple headers at the same height on the blockchain.
This means the subscription can publish notifications for multiple blocks at the same height on the blockchain.
The new headers notification returns [Block Objects](Objects#block-object). Use the `logsBloom` parameter
The new headers notification returns [block objects](../Reference/JSON-RPC-API-Objects.md#block-object). The
to filter blocks to determine which blocks have logs of interest to you.
second parameter is optional. If specified, whole [transaction objects](../Reference/JSON-RPC-API-Objects.md#transaction-object)
are included in the notifications. Otherwise, the transaction hashes are included.
MadelineMurray
6 years ago
committed by
GitHub