diff --git a/docs/Getting-Started/Private-Network-Quickstart.md b/docs/Getting-Started/Private-Network-Quickstart.md index 5dd5210da8..f4cb9df11d 100644 --- a/docs/Getting-Started/Private-Network-Quickstart.md +++ b/docs/Getting-Started/Private-Network-Quickstart.md @@ -15,7 +15,12 @@ This tutorial describes how to use Pantheon to run a private network of Pantheon To run this tutorial, you must have the following installed: -- [Docker and Docker-compose](https://docs.docker.com/compose/install/) +- For MacOS and Linux, [Docker and Docker-compose](https://docs.docker.com/compose/install/) + +- For Windows, [Docker for Windows](https://docs.docker.com/docker-for-windows/install/) + +!!!important + Docker for Windows requires Windows 10 Pro, Enterpise, or Education. The Private Network Quickstart does not support Docker Toolbox. - [Git command line](https://git-scm.com/) diff --git a/docs/Getting-Started/Starting-Pantheon.md b/docs/Getting-Started/Starting-Pantheon.md index 650532f70d..78a4aba2ff 100644 --- a/docs/Getting-Started/Starting-Pantheon.md +++ b/docs/Getting-Started/Starting-Pantheon.md @@ -19,8 +19,8 @@ To delete the local block data, delete the `database` directory in the `pantheon ## Genesis Configuration -Pantheon specifies the genesis configuration, and sets the network ID and bootnodes when connecting to [Mainnet](#run-a-node-on-ethereum-mainnet), -[Rinkeby](#run-a-node-on-rinkeby-testnet), and [Ropsten](#run-a-node-on-ropsten-testnet). +Pantheon specifies the genesis configuration, and sets the network ID and bootnodes when connecting +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. @@ -62,7 +62,7 @@ call [JSON-RPC API methods](../Reference/JSON-RPC-API-Methods.md) to confirm the } ``` -## Run a Node on Ethereum Mainnet +## Run a Node on Ethereum Mainnet To run a node on the Ethereum mainnet: @@ -79,11 +79,9 @@ $ bin/pantheon --rpc-enabled ## Run a Node on Ropsten Testnet !!!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. -Replace `` with the path to the `/pantheon` directory. - To run a node on Ropsten: ```bash @@ -96,15 +94,29 @@ To run a node on Ropsten with the HTTP JSON-RPC service enabled and allow Remix $ bin/pantheon --rpc-enabled --rpc-cors-origins "http://remix.ethereum.org" --network-id=3 --genesis=/pantheon/ethereum/core/src/main/resources/ropsten.json --bootnodes=enode://6332792c4a00e3e4ee0926ed89e0d27ef985424d97b6a45bf0f23e51f0dcb5e66b875777506458aea7af6f9e4ffb69f43f3778ee73c81ed9d34c51c4b16b0b0f@52.232.243.152:30303,enode://94c15d1b9e2fe7ce56e458b9a3b672ef11894ddedd0c6f247e0f1d3487f52b66208fb4aeb8179fce6e3a749ea93ed147c37976d67af557508d199d9594c35f09@192.81.208.223:30303 ``` -## Run a Node on Rinkeby Testnet +Where `` is the path to the `/pantheon` directory. -Replace `` with the path where the Rinkeby chain data is to be saved. +## Run a Node on Rinkeby Testnet To run a node on Rinkeby specifying a data directory: ```bash $ bin/pantheon --rinkeby --datadir=/rinkebyDataDir ``` +Where `` and `` are the path and directory where the Rinkeby chain data is to be saved. + +## Run a Node on Goerli Testnet + +To run a node on [Goerli](https://github.com/goerli/testnet) specifying a data directory: + +```bash +$ bin/pantheon --goerli --datadir=/ +``` + +Where `` and `` are the path and directory where the Goerli chain data is to be saved. + +!!!note + This option is only available from v0.8.3. ## Run a Node for Testing diff --git a/docs/Installation/Install-Chocolatey.md b/docs/Installation/Install-Chocolatey.md index 578a988165..91f7ae8425 100644 --- a/docs/Installation/Install-Chocolatey.md +++ b/docs/Installation/Install-Chocolatey.md @@ -5,7 +5,7 @@ description: Install Pantheon on Windows from Chocolatey package manager To install Chocolatey: -1. Open **cmd.exe** as the administrative user by right-clicking on **cmd.exe** in the Start menu and selecting **Run as administrator**. +1. Open **cmd.exe** as administrator by right-clicking on **cmd.exe** in the Start menu and selecting **Run as administrator**. 2. Run: diff --git a/docs/Reference/JSON-RPC-API-Methods.md b/docs/Reference/JSON-RPC-API-Methods.md index 8045d7c66e..fbc4d47c42 100644 --- a/docs/Reference/JSON-RPC-API-Methods.md +++ b/docs/Reference/JSON-RPC-API-Methods.md @@ -4,7 +4,7 @@ description: Pantheon JSON-RPC API methods reference # JSON-RPC API Methods !!! 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: @@ -26,10 +26,10 @@ Properties of the remote node object are: * `version` - P2P protocol version * `name` - Client name -* `caps` - P2P message capabilities +* `caps` - List of Ethereum sub-protocol capabilities * `network` - Addresses of local node and remote node -* `port` - Port -* `id` - Node public key. Excluding the `0x` prefix, the node public key is the ID in the enode URL `enode://@`. +* `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://@:`. !!! example ```bash tab="curl HTTP request" @@ -46,18 +46,22 @@ Properties of the remote node object are: "id" : 1, "result" : [ { - "version" : "0x5", - "name" : "Geth/v1.8.20-unstable-92639b67/linux-amd64/go1.11.1", - "caps" : [ - "eth/62", - "eth/63" - ], - "network" : { - "localAddress" : "192.168.1.229:51279", - "remoteAddress" : "52.3.158.184:30303" - }, - "port" : "0x0", - "id" : "0x343149e4feefa15d882d9fe4ac7d88f885bd05ebb735e547f12e12080a9fa07c8014ca6fd7f373123488102fe5e34111f8509cf0b7de3f5b44339c9f25e87cb8" + "version": "0x5", + "name": "Parity-Ethereum/v2.3.0-nightly-1c2e121-20181116/x86_64-linux-gnu/rustc1.30.0", + "caps": [ + "eth/62", + "eth/63", + "par/1", + "par/2", + "par/3", + "pip/1" + ], + "network": { + "localAddress": "192.168.1.229:50115", + "remoteAddress": "168.61.153.255:40303" + }, + "port": "0x9d6f", + "id": "0xea26ccaf0867771ba1fec32b3589c0169910cb4917017dba940efbef1d2515ce864f93a9abc846696ebad40c81de7c74d7b2b46794a71de8f95a0d019f494ff3" } ] } @@ -277,7 +281,7 @@ None Returns the [chain ID](../Configuring-Pantheon/NetworkID-And-ChainID.md). !!!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** @@ -404,7 +408,7 @@ None Returns a list of account addresses that the client owns. !!!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** @@ -502,7 +506,7 @@ Returns the value of a storage position at a specified address. `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** @@ -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). !!!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** @@ -754,7 +758,7 @@ You can interact with contracts using [eth_sendRawTransaction or eth_call](../Us *OBJECT* - [Transaction call object](JSON-RPC-API-Objects.md#transaction-call-object). -*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** @@ -1098,78 +1102,47 @@ Returns the receipt of a transaction by transaction hash. Receipts for pending t ### 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). **Parameters** `Object` - [Filter options object](JSON-RPC-API-Objects.md#filter-options-object). -!!!note - 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 * [A] - Match A in first position (and any topic thereafter) * [null, B] - Match any topic 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) - For example, params could be specified as follows: - !!!example - ```json - [{ - "fromBlock": "earliest", - "toBlock": "0x4", - "address": "0xc94770007dda54cF92009BFF0dE90c06F603a09f", - "topics": ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b", null, ["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b", "0x0000000000000000000000000aff3454fce5edbc8cca8697c15331677e6ebccc"]] - }] - ``` - +!!!note + `fromBlock` and `toBlock` in the filter options object default to `latest`. To obtain logs using `eth_getFilterLogs`, set `fromBlock` and `toBlock` appropriately. + **Returns** -`result` : *QUANTITY* - Filter ID. +`data` - Filter ID hash !!! example ```bash tab="curl HTTP request" - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"topics":[]}],"id":53}' + $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"fromBlock":"earliest", "toBlock":"latest", "topics":[]}],"id":1}' ``` ```bash tab="wscat WS request" - {"jsonrpc":"2.0","method":"eth_newFilter","params":[{"topics":[]}],"id":53} + {"jsonrpc":"2.0","method":"eth_newFilter","params":[{"fromBlock":"earliest", "toBlock":"latest", "topics":[]}],"id":1} ``` ```json tab="JSON result" { - "jsonrpc" : "2.0", - "id" : 53, - "result" : "0x3" + "jsonrpc": "2.0", + "id": 1, + "result": "0x1ddf0c00989044e9b41cc0ae40272df3" } ``` - -Invalid params error: - -!!! example - ```bash tab="curl HTTP request" - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newFilter","params":[{"fromBlock": "earliest","toBlock": "latest","address": "0xDD37f65dB31c107F773E82a4F85C693058fEf7a9","topics": []}],"id":53}' - ``` - ```bash tab="wscat WS request" - {"jsonrpc":"2.0","method":"eth_newFilter","params":[{"fromBlock": "earliest","toBlock": "latest","address": "0xDD37f65dB31c107F773E82a4F85C693058fEf7a9","topics": []}],"id":53} - ``` - - ```json tab="JSON result" - { - "jsonrpc" : "2.0", - "id" : 53, - "error" : { - "code" : -32602, - "message" : "Invalid params" - } - } - ``` - ### eth_newBlockFilter -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** @@ -1177,28 +1150,28 @@ None **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 ```bash tab="curl HTTP request" - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":53}' + $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1}' ``` ```bash tab="wscat WS request" - {"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":53} + {"jsonrpc":"2.0","method":"eth_newBlockFilter","params":[],"id":1} ``` ```json tab="JSON result" { - "jsonrpc" : "2.0", - "id" : 53, - "result" : "0x3" + "jsonrpc": "2.0", + "id": 1, + "result": "0x9d78b6780f844228b96ecc65a320a825" } ``` ### eth_newPendingTransactionFilter -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** @@ -1206,35 +1179,34 @@ None **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 ```bash tab="curl HTTP request" - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":53}' + $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":1}' ``` ```bash tab="wscat WS request" - {"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":53} + {"jsonrpc":"2.0","method":"eth_newPendingTransactionFilter","params":[],"id":1} ``` ```json tab="JSON result" { - "jsonrpc" : "2.0", - "id" : 53, - "result" : "0x4" + "jsonrpc": "2.0", + "id": 1, + "result": "0x443d6a77c4964707a8554c92f7e4debd" } ``` ### eth_uninstallFilter -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. - -This method deletes filters of any type: block filters, pending transaction filters, and state (topic) filters. +Uninstalls a filter with the specified ID. When a filter is no longer required, call this method. +Filters time out when they are not requested by [eth_getFilterChanges](#eth_getfilterchanges) for a period of time. **Parameters** -`QUANTITY` - Hexadecimal integer filter ID specifying the filter to be deleted. +`data` - Filter ID hash **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: ```bash tab="curl HTTP request" - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x4"],"id":53}' + $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x70355a0b574b437eaa19fe95adfedc0a"],"id":1}' ``` ```bash tab="wscat WS request" - {"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x4"],"id":53} + {"jsonrpc":"2.0","method":"eth_uninstallFilter","params":["0x70355a0b574b437eaa19fe95adfedc0a"],"id":1} ``` ```json tab="JSON result" { "jsonrpc" : "2.0", - "id" : 53, + "id" : 1, "result" : true } ``` ### eth_getFilterChanges -Polls the specified filter and returns an array of logs that have occurred since the last poll. +Polls the specified filter and returns an array of changes that have occurred since the last poll. **Parameters** -`QUANTITY` - Hexadecimal integer filter ID. +`data` - Filter ID hash **Returns** -`result` : `Array of Object` - List of logs, or an empty array if nothing has changed since the last poll. +`result` : `Array of Object` - If nothing has changed since the last poll, an empty list. Otherwise: -* For filters created with `eth_newBlockFilter`, returns 32-byte *DATA* block hashes; for example `["0x3454645634534..."]`. -* For filters created with `eth_newPendingTransactionFilter`, returns transaction hashes (32-byte *DATA*); for example `["0x6345343454645..."]`. +* For filters created with `eth_newBlockFilter`, returns block hashes. +* For filters created with `eth_newPendingTransactionFilter`, returns transaction hashes. * For filters created with `eth_newFilter`, returns [log objects](JSON-RPC-API-Objects.md#log-object). !!! example ```bash tab="curl HTTP request" - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xa"]:"id":53}' + $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xf8bf5598d9e04fbe84523d42640b9b0e"],"id":1}' ``` ```bash tab="wscat WS request" - {"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xa"]:"id":53} + {"jsonrpc":"2.0","method":"eth_getFilterChanges","params":["0xf8bf5598d9e04fbe84523d42640b9b0e"],"id":1} ``` ```json tab="JSON result" + + Example result from a filter created with `eth_newBlockFilter`: { - "jsonrpc" : "2.0", - "id" : 53, - "result" : [ ] + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0xda2bfe44bf85394f0d6aa702b5af89ae50ae22c0928c18b8903d9269abe17e0b", + "0x88cd3a37306db1306f01f7a0e5b25a9df52719ad2f87b0f88ee0e6753ed4a812", + "0x4d4c731fe129ff32b425e6060d433d3fde278b565bbd1fd624d5a804a34f8786" + ] } + + Example result from a filter created with `eth_newPendingTransactionFilter`: + { + "jsonrpc": "2.0", + "id": 1, + "result": [ + "0x1e977049b6db09362da09491bee3949d9362080ce3f4fc19721196d508580d46", + "0xa3abc4b9a4e497fd58dc59cdff52e9bb5609136bcd499e760798aa92802769be" + ] + } + + Example result from a filter created with `eth_newFilter`: + + { + "jsonrpc": "2.0", + "id": 1, + "result": [ + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x233", + "blockHash": "0xfc139f5e2edee9e9c888d8df9a2d2226133a9bd87c88ccbd9c930d3d4c9f9ef5", + "transactionHash": "0x66e7a140c8fa27fe98fde923defea7562c3ca2d6bb89798aabec65782c08f63d", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x0000000000000000000000000000000000000000000000000000000000000004", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" + ] + }, + { + "logIndex": "0x0", + "removed": false, + "blockNumber": "0x238", + "blockHash": "0x98b0ec0f9fea0018a644959accbe69cd046a8582e89402e1ab0ada91cad644ed", + "transactionHash": "0xdb17aa1c2ce609132f599155d384c0bc5334c988a6c368056d7e167e23eee058", + "transactionIndex": "0x0", + "address": "0x42699a7612a82f1d9c36148af9c77354759b210b", + "data": "0x0000000000000000000000000000000000000000000000000000000000000007", + "topics": [ + "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" + ] + } + ] + } + ``` + + ### eth_getFilterLogs -Returns an array of logs matching the filter with the specified ID. +Returns an array of logs for the specified filter. + +!!!note + `eth_getFilterLogs` is only used for filters created with `eth_newFilter`. + + You can use `eth_getLogs` to specify a filter object and get logs without without creating a filter. **Parameters** -`QUANTITY` - Integer representing the filter ID. +`data` - Filter ID hash **Returns** -Same as [eth_getFilterChanges](#eth_getfilterchanges). +`array` - [Log objects](JSON-RPC-API-Objects.md#log-object) !!! example - The following example requests logs for filter ID 0x16 (22 decimal): ```bash tab="curl HTTP request" - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x3"]"id":53}' + $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x5ace5de3985749b6a1b2b0d3f3e1fb69"],"id":1}' ``` ```bash tab="wscat WS request" - {"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x3"]"id":53} + {"jsonrpc":"2.0","method":"eth_getFilterLogs","params":["0x5ace5de3985749b6a1b2b0d3f3e1fb69"],"id":1} ``` ```json tab="JSON result" @@ -1322,20 +1352,30 @@ Same as [eth_getFilterChanges](#eth_getfilterchanges). "result" : [ { "logIndex" : "0x0", "removed" : false, - "blockNumber" : "0x14427", - "blockHash" : "0x677bf4b962464e6dfd548d6a30b6c703dd78c7cc3602825a7013a6e90a001d2a", - "transactionHash" : "0x7bf9876a9de3c0add38495e21a17b96c81b3f18e0990a4a3aecdf9f47fea0eed", + "blockNumber" : "0xb3", + "blockHash" : "0xe7cd776bfee2fad031d9cc1c463ef947654a031750b56fed3d5732bee9c61998", + "transactionHash" : "0xff36c03c0fba8ac4204e4b975a6632c862a3f08aa01b004f570cc59679ed4689", "transactionIndex" : "0x0", - "address" : "0xe8fe77d1576d0972d453b49bfaa84d716173d133", - "data" : "0x0000000000000000000000001046c9bdec0e634fbd7cf91afebd93cc854432b10000000000000000000000002101416eeaf73acb66d124f79efde9631662a83a0000000000000000000000006f72045702a34c473da863945221965c61528bd3", - "topics" : [ "0xc36800ebd6079fdafc3a7100d0d1172815751804a6d1b7eb365b85f6c9c80e61", "0x000000000000000000000000b344324aa2a82a6fda8459e40923e1fd65bfac36" ] + "address" : "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", + "data" : "0x0000000000000000000000000000000000000000000000000000000000000003", + "topics" : [ "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" ] + }, { + "logIndex" : "0x0", + "removed" : false, + "blockNumber" : "0xb6", + "blockHash" : "0x3f4cf35e7ed2667b0ef458cf9e0acd00269a4bc394bb78ee07733d7d7dc87afc", + "transactionHash" : "0x117a31d0dbcd3e2b9180c40aca476586a648bc400aa2f6039afdd0feab474399", + "transactionIndex" : "0x0", + "address" : "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", + "data" : "0x0000000000000000000000000000000000000000000000000000000000000005", + "topics" : [ "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" ] } ] } ``` ### eth_getLogs -Returns an array of all logs matching a specified filter object. +Returns an array of logs matching a specified filter object. **Parameters** @@ -1343,20 +1383,17 @@ Returns an array of all logs matching a specified filter object. **Returns** -Same as [eth_getFilterChanges](#eth_getfilterchanges). - -!!!note - You must be synchronized to at least the requested block for the request to return the logs. +`array` - [Log objects](JSON-RPC-API-Objects.md#log-object) !!! 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" - $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"blockhash":"0x677bf4b962464e6dfd548d6a30b6c703dd78c7cc3602825a7013a6e90a001d2a"}], "id":1}' + $ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"earliest", "toBlock":"latest", "address": "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", "topics":[]}], "id":1}' ``` ```bash tab="wscat WS request" - {"jsonrpc":"2.0","method":"eth_getLogs","params":[{"blockhash":"0x677bf4b962464e6dfd548d6a30b6c703dd78c7cc3602825a7013a6e90a001d2a"}], "id":1} + {"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"earliest", "toBlock":"latest", "address": "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", "topics":[]}], "id":1} ``` ```json tab="JSON result" @@ -1366,13 +1403,23 @@ Same as [eth_getFilterChanges](#eth_getfilterchanges). "result" : [ { "logIndex" : "0x0", "removed" : false, - "blockNumber" : "0x14427", - "blockHash" : "0x677bf4b962464e6dfd548d6a30b6c703dd78c7cc3602825a7013a6e90a001d2a", - "transactionHash" : "0x7bf9876a9de3c0add38495e21a17b96c81b3f18e0990a4a3aecdf9f47fea0eed", + "blockNumber" : "0xb3", + "blockHash" : "0xe7cd776bfee2fad031d9cc1c463ef947654a031750b56fed3d5732bee9c61998", + "transactionHash" : "0xff36c03c0fba8ac4204e4b975a6632c862a3f08aa01b004f570cc59679ed4689", + "transactionIndex" : "0x0", + "address" : "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", + "data" : "0x0000000000000000000000000000000000000000000000000000000000000003", + "topics" : [ "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" ] + }, { + "logIndex" : "0x0", + "removed" : false, + "blockNumber" : "0xb6", + "blockHash" : "0x3f4cf35e7ed2667b0ef458cf9e0acd00269a4bc394bb78ee07733d7d7dc87afc", + "transactionHash" : "0x117a31d0dbcd3e2b9180c40aca476586a648bc400aa2f6039afdd0feab474399", "transactionIndex" : "0x0", - "address" : "0xe8fe77d1576d0972d453b49bfaa84d716173d133", - "data" : "0x0000000000000000000000001046c9bdec0e634fbd7cf91afebd93cc854432b10000000000000000000000002101416eeaf73acb66d124f79efde9631662a83a0000000000000000000000006f72045702a34c473da863945221965c61528bd3", - "topics" : [ "0xc36800ebd6079fdafc3a7100d0d1172815751804a6d1b7eb365b85f6c9c80e61", "0x000000000000000000000000b344324aa2a82a6fda8459e40923e1fd65bfac36" ] + "address" : "0x2e1f232a9439c3d459fceca0beef13acc8259dd8", + "data" : "0x0000000000000000000000000000000000000000000000000000000000000005", + "topics" : [ "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3" ] } ] } ``` @@ -1574,7 +1621,7 @@ If the boolean value is `true`, the proposal is to add a signer. If `false`, the ### debug_metrics !!!note - This method is only available only from v0.8.3 or when [building from source](Installation). + This method is only available only from v0.8.3. Returns metrics providing information on the internal operation of Pantheon. diff --git a/docs/Reference/JSON-RPC-API-Objects.md b/docs/Reference/JSON-RPC-API-Objects.md index c6df636adc..1448b98b19 100644 --- a/docs/Reference/JSON-RPC-API-Objects.md +++ b/docs/Reference/JSON-RPC-API-Objects.md @@ -67,7 +67,7 @@ Returned by [eth_getFilterChanges](JSON-RPC-API-Methods.md#eth_getfilterchanges) ## Trace Object -Returned by [debug_traceTransaction](JSON-RPC-API-Methods.md#debug_traceTransaction). +Returned by [debug_traceTransaction](JSON-RPC-API-Methods.md#debug_tracetransaction). | Key | Type | Value | |-----------------|:-------:|-------------------------------------------------------------------| @@ -79,7 +79,7 @@ Returned by [debug_traceTransaction](JSON-RPC-API-Methods.md#debug_traceTransact ### Structured Log Object -Part of the [Trace object](#trace-object). +Log information returned as part of the [Trace object](#trace-object). | Key | Type | Value | |----------------------------|:----------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/docs/Reference/Pantheon-CLI-Syntax.md b/docs/Reference/Pantheon-CLI-Syntax.md index 615720686a..3b4a1dc141 100644 --- a/docs/Reference/Pantheon-CLI-Syntax.md +++ b/docs/Reference/Pantheon-CLI-Syntax.md @@ -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. !!!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 @@ -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. +### 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 ```bash tab="Syntax" ---host-whitelist=[,...]... +--host-whitelist=[,...]... or * or all ``` ```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`. !!!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 - This option is only available from v0.8.3 or when [building from source](../Installation/Build-From-Source.md). - Earlier versions allow access by all hostnames. + This option is only available from v0.8.3. Earlier versions allow access by all hostnames. ### max-peers @@ -277,7 +288,7 @@ otherwise, the existing key file specifies the node private key. The private key is not encrypted. !!!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 @@ -294,7 +305,7 @@ If you specify an empty list or [`--nodes-whitelist`](#nodes-whitelist) without !!!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 :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`. !!!note - This option is only available only from v0.8.2 or when [building from source](../Installation/Build-From-Source.md). - For v0.8.1, refer to [Ropsten section on Starting Pantheon page](../Getting-Started/Starting-Pantheon.md#run-a-node-on-ropsten-testnet). + 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). ### rpc-enabled diff --git a/docs/Reference/Using-JSON-RPC-API.md b/docs/Reference/Using-JSON-RPC-API.md index 9eaeb4bc5f..aa5dab2ad3 100644 --- a/docs/Reference/Using-JSON-RPC-API.md +++ b/docs/Reference/Using-JSON-RPC-API.md @@ -5,14 +5,14 @@ description: How to use Pantheon JSON-RPC API !!!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. - If not specified, the default value for [`--host-whitelist`](Pantheon-CLI-Syntax.md#host-whitelist) is `localhost`. + 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. + 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: ```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. diff --git a/docs/Using-Pantheon/RPC-PubSub.md b/docs/Using-Pantheon/RPC-PubSub.md index 0df1a40aa7..8a9676f492 100644 --- a/docs/Using-Pantheon/RPC-PubSub.md +++ b/docs/Using-Pantheon/RPC-PubSub.md @@ -5,23 +5,27 @@ description: Using RPC Pub/Sub with Pantheon Web Socket API ## Introduction -Use the RPC Pub/Sub methods over [WebSockets](../Reference/Using-JSON-RPC-API.md#endpoint-address-and-port) -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. +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. The RPC Pub/Sub methods are: -* `eth_subscribe` - call to create a subscription for specific events. -* `eth_unsubscribe` - call to 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`. +* `eth_subscribe` - create a subscription for specific events. +* `eth_unsubscribe` - cancel a subscription. !!!important 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 @@ -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. -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 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) * [Sychronizng](#synchronizing) -If the WebSockets connection is closed, all subscriptions are removed. - ### 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. -This means the subscription can publish notifications for multiple headers at the same height on the blockchain. +If a chain reorganization occurs, the subscription publishes notifications for blocks in the new chain. +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 -to filter blocks to determine which blocks have logs of interest to you. +The new headers notification returns [block objects](../Reference/JSON-RPC-API-Objects.md#block-object). The +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. !!!example To subscribe to new header notifications: ```json - {"id": 1, "method": "eth_subscribe", "params": ["newHeads"]} + {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {"includeTransactions": true}]} ``` Example result: @@ -83,7 +83,7 @@ to filter blocks to determine which blocks have logs of interest to you. {"jsonrpc":"2.0","id":2,"result":"0x1"} ``` - Example notification: + Example notification without the `{"includeTransactions": true}` parameter included: ```json { "jsonrpc": "2.0", @@ -109,21 +109,59 @@ to filter blocks to determine which blocks have logs of interest to you. "gasUsed":"0x11ac3a", "timestamp":"0x592afc24", "uncles":[], - "transactions":["0x419c69d21b14e2e8f911def22bb6d0156c876c0e1c61067de836713043364d6c","0x70a5b2cb2cee6e0b199232a1757fc2a9d6053a4691a7afef8508fd88aeeec703","0x4b3035f1d32339fe1a4f88147dc197a0fe5bbd63d3b9dec2dad96a3b46e4fddd"] - } + "transactions":["0x419c69d21b14e2e8f911def22bb6d0156c876c0e1c61067de836713043364d6c","0x70a5b2cb2cee6e0b199232a1757fc2a9d6053a4691a7afef8508fd88aeeec703","0x4b3035f1d32339fe1a4f88147dc197a0fe5bbd63d3b9dec2dad96a3b46e4fddd"], + }, } } ``` + + Example notification with the `{"includeTransactions": true}` parameter included: + ```json + { + "jsonrpc": "2.0", + "method": "eth_subscription", + "params":{ + "subscription":"0x1", + "result": { + .... + "transactions":[ + { + "blockHash":"0xa30ee4d7c271ae5150aec494131c5f1f34089c7aa8fb58bd8bb916a55275bb90", + "blockNumber":"0x63", + "from":"0xfe3b557e8fb62b89f4916b721be55ceb828dbd73", + "gas":"0x5208", + "gasPrice":"0x3b9aca00", + "hash":"0x11f66c3e96a92e3c14c1c33ad77381221bf8b58a887b4fed6aee456fc6f39b24", + "input":"0x", + "nonce":"0x1", + "to":"0x627306090abab3a6e1400e9345bc60c78a8bef57", + "transactionIndex":"0x0", + "value":"0x56bc75e2d63100000", + "v":"0xfe8", + "r":"0x4b57d179c74885ef5f9326fd000665ea7fae44095c1e2016a2817fc671beb8cc", + "s":"0x7ec060b115746dda392777df07ae1feacc0b83b3646f0a3de9a5fc3615af9bb8", + } + ], + }, + } + } + ``` #### Logs -Use the `logs` parameter with `eth_subscribe` to be notified of logs included in new blocks. +Use the `logs` parameter with `eth_subscribe` to be notified of logs included in new blocks. You can +specify a [filter object](../Reference/JSON-RPC-API-Objects.md#filter-options-object) to receive notifications +only for logs matching your filter. -Logs subscriptions have an `object` parameter with the following fields: +Logs subscriptions have an filter object parameter with the following fields: - `address` - (optional) Either an address or an array of addresses. Returns only logs created from these addresses. - `topics` - (optional) Returns only logs that match the specified topics. +!!!note + The `fromBlock` and `toBlock` attributes are not included in the filter object for the logs subscription + because the subscription waits for logs rather than requesting them. + If a chain reorganization occurs, the subscription publishes notifications for logs from the old chain with the `removed` property in the [log object](../Reference/JSON-RPC-API-Objects.md#log-object) set to `true`. This means the subscription can publish notifications for multiple logs for the same transaction. @@ -168,7 +206,8 @@ The logs subscription returns [Log objects](../Reference/JSON-RPC-API-Objects.md #### Pending Transactions -Use the `newPendingTransactions` parameter with `eth_subscribe` to be notified of new pending transactions of which your node is aware. +Use the `newPendingTransactions` parameter with `eth_subscribe` to be notified of pending transactions +added to the transaction pool for the node. The pending transactions subscription returns the transaction hashes of the pending transactions. @@ -204,8 +243,7 @@ This means the subscription can publish notifications for the same pending trans Use the `syncing` parameter with `eth_subscribe` to be notified about synchronization progress. -The sychronizing subscription either returns `false` indicating the synchronization has finished -or an `object` indicating the synchronization progress. +The sychronizing subscription returns an object indicating the synchronization progress. !!!example To subscribe to synchronizing notifications: @@ -237,7 +275,10 @@ or an `object` indicating the synchronization progress. ## Unsubscribing -Use the [subscription ID](#subscription-id) with `eth_unsubscribe` to cancel a subscription. +Use the [subscription ID](#subscription-id) with `eth_unsubscribe` to cancel a subscription. Only the +connection that created a subscription can unsubscribe from it. + +`eth_unsubscribe` returns `true` if subscription succuessfully unsubscribed; otherwise, an error is returned. !!!example To unsubscribe from a subsciption with subscription ID of `0x1`: @@ -245,8 +286,6 @@ Use the [subscription ID](#subscription-id) with `eth_unsubscribe` to cancel a s {"id": 1, "method": "eth_unsubscribe", "params": ["0x1"]} ``` - `eth_unsubscribe` returns `true` if subscription succuessfully unsubscribed; otherwise, an error is returned. - Example result: ```json {"jsonrpc":"2.0","id":1,"result":true}