From c925a1027aa38a37e8bf261f706c2db74e2fb274 Mon Sep 17 00:00:00 2001 From: MadelineMurray <43356962+MadelineMurray@users.noreply.github.com> Date: Tue, 19 Feb 2019 18:10:12 +1000 Subject: [PATCH] JSON-RPC Authentication --- docs/JSON-RPC-API/Authentication.md | 96 +++++++++ docs/JSON-RPC-API/JSON-RPC-API.md | 19 ++ .../Using-JSON-RPC-API.md | 56 +++-- docs/Reference/JSON-RPC-API-Methods.md | 31 ++- docs/Reference/JSON-RPC-API-Objects.md | 4 +- docs/Reference/JSON-RPC-API.md | 12 -- docs/Reference/Pantheon-CLI-Syntax.md | 194 ++++++++++++------ docs/Tutorials/Create-Private-Network.md | 2 +- docs/Using-Pantheon/RPC-PubSub.md | 2 +- docs/index.md | 2 +- mkdocs.yml | 11 +- 11 files changed, 293 insertions(+), 136 deletions(-) create mode 100644 docs/JSON-RPC-API/Authentication.md create mode 100644 docs/JSON-RPC-API/JSON-RPC-API.md rename docs/{Reference => JSON-RPC-API}/Using-JSON-RPC-API.md (62%) delete mode 100644 docs/Reference/JSON-RPC-API.md diff --git a/docs/JSON-RPC-API/Authentication.md b/docs/JSON-RPC-API/Authentication.md new file mode 100644 index 0000000000..48a044a7fc --- /dev/null +++ b/docs/JSON-RPC-API/Authentication.md @@ -0,0 +1,96 @@ +# Authentication and Authorization + +Authentication identifies a user based on a username and password. Authorization verifies whether the user has +access to the JSON-RPC method they are requesting. + +Pantheon uses the username and password to authenticate users and [JWT tokens](https://jwt.io/introduction/) to authorize JSON-RPC API requests. + +!!! important + Authenticated requests must be made over HTTPS. HTTPS is encrypted which prevents eavesdropping on the connection + to obtain the JWT token from the requests. + +## Credentials File + +The credentials file is a `toml` file defining user details and the JSON-RPC methods to which they have access. + +!!! example "Example Credentials File" + ```toml + [Users.username1] + password = "$2a$10$l3GA7K8g6rJ/Yv.YFSygCuI9byngpEzxgWS9qEg5emYDZomQW7fGC" + permissions=["net:*","eth:blockNumber"] + + [Users.username2] + password = "$2b$10$6sHt1J0MVUGIoNKvJiK33uaZzUwNmMmJlaVLkIwinkPiS1UBnAnF2" + permissions=["net:version","admin:*"] + ``` + +Each user requiring JSON-RPC access is listed with: + +* Username. `Users.` is mandatory and followed by the username. That is, replace `` in `[Users.]` with the username being defined. +* Hash of the user password. Use the [`password hash`](../Reference/Pantheon-CLI-Syntax.md#password) subcommand to generate the hash. +* JSON-RPC permissions. + +!!! example "password hash Subcommand" + ```bash + pantheon password hash --password=pegasys + ``` + +## JSON-RPC Permissions + +Each user has a list of permissions strings defining the methods they can access. To give access to: + +* All API methods, specify `["*:*"]`. +* All API methods in an API group, specify `[":*"]`. For example, `["eth:*"]`. +* Specific API methods, specify `[":"]`. For example, `["admin:peers"]`. + +If authentication is enabled, to explicitly specify a user cannot access any methods, include the user with an empty permissions list (`[]`). +Users with an empty permissions list and users not included in the credentials file cannot access any JSON-RPC +methods. + +## Enabling Authentication + +Use the [` --rpc-http-authentication-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-enabled) or + [`--rpc-ws-authentication-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-enabled) + options to require authentication for the JSON-RPC API. + +Use the [`--rpc-http-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-authentication-credentials-file) +and [`--rpc-ws-authentication-credentials-file`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-authentication-credentials-file) +options to specify the [credentials file](#credentials-file). + +## Obtaining an Authentication Token + +To obtain an authentication token, make a request to the `/login` endpoint with your username and password. + +!!! example + ```bash tab="curl HTTPS request" + $ curl -X POST --data '{"username":"username1","password":"pegasys"}' /login + ``` + + ```json tab="JSON result" + {"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MDYwNCwiZXhwIjoxNTUwNDYwOTA0fQ.l2Ycqzl_AyvReXBeUSayOlOMS_E8-DCuz3q0Db0DKD7mqyl6q-giWoEtfdWzUEvZbRRi2_ecKO3N6JkXq7zMKQAJbVAEzobfbaaXWcQEpHOjtnK4_Yz-UPyKiXtu7HGdcdl5Tfx3dKoksbqkBl3U3vFWxzmFnuu3dAISfVJYUNA"} + ``` + +Authentication tokens expire 5 minutes after being generated. It is necessary to generate a new authentication +token if access is required after token expiration. + +## Using an Authentication Token to Make Requests + +Specify the authentication token as a `Bearer` token in the JSON-RPC request header. + +### Postman + +In the _Authorization_ tab in the _TYPE_ drop-down list, select *Bearer Token* and specify the token +generated by the [`login` request](#obtaining-an-authentication-token). + +### Curl + +Specify the `Bearer` in the header. + +!!! example + ```bash tab="curl Request with Authentication Placeholders" + curl -X POST -H 'Authorization: Bearer ' -d '{"jsonrpc":"2.0","method":"","params":[],"id":1}' + ``` + + ```bash tab="curl Request with Authentication" + curl -X POST -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJwZXJtaXNzaW9ucyI6WyIqOioiXSwidXNlcm5hbWUiOiJ1c2VyMiIsImlhdCI6MTU1MDQ2MTQxNiwiZXhwIjoxNTUwNDYxNzE2fQ.WQ1mqpqzRLHaoL8gOSEZPvnRs_qf6j__7A3Sg8vf9RKvWdNTww_vRJF1gjcVy-FFh96AchVnQyXVx0aNUz9O0txt8VN3jqABVWbGMfSk2T_CFdSw5aDjuriCsves9BQpP70Vhj-tseaudg-XU5hCokX0tChbAqd9fB2138zYm5M' -d '{"jsonrpc":"2.0","method":"net_listening","params":[],"id":1}' https://localhost:8545 + ``` \ No newline at end of file diff --git a/docs/JSON-RPC-API/JSON-RPC-API.md b/docs/JSON-RPC-API/JSON-RPC-API.md new file mode 100644 index 0000000000..7f7def361a --- /dev/null +++ b/docs/JSON-RPC-API/JSON-RPC-API.md @@ -0,0 +1,19 @@ +description: Pantheon JSON-RPC API reference + + +# JSON-RPC API Overview + +The Pantheon JSON-RPC API uses the [JSON-RPC v2.0](https://www.jsonrpc.org/specification) specification of the JSON-RPC protocol. + +The [JSON](http://json.org/) (RFC 4627) format which represents +objects and data fields as collections of name/value pairs, in a readable, hierarchical form. +Values have specific data types such as quantities (decimal integers, hexadecimal numbers, strings) and +unformatted data (byte arrays, account addresses, hashes, and bytecode arrays). + +RPC is the remote procedure call protocol (RFC 1831). The protocol is stateless and transport agnostic in that the concepts +can be used within the same process, over sockets, over HTTP, or in various message passing environments. + +* [Using the Pantheon JSON-RPC API](Using-JSON-RPC-API.md) +* [Authentication](Authentication.md) +* [JSON-RPC API Methods](../Reference/JSON-RPC-API-Methods.md) +* [JSON-RPC API Objects](../Reference/JSON-RPC-API-Objects.md) \ No newline at end of file diff --git a/docs/Reference/Using-JSON-RPC-API.md b/docs/JSON-RPC-API/Using-JSON-RPC-API.md similarity index 62% rename from docs/Reference/Using-JSON-RPC-API.md rename to docs/JSON-RPC-API/Using-JSON-RPC-API.md index cdc7e99971..b606a4189a 100644 --- a/docs/Reference/Using-JSON-RPC-API.md +++ b/docs/JSON-RPC-API/Using-JSON-RPC-API.md @@ -3,31 +3,13 @@ description: How to use Pantheon JSON-RPC API # Using the JSON-RPC API -!!!attention "Breaking Change in v0.8.3" - - 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 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=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. - - **This is not recommended for production code.** - -## Using the Pantheon JSON-RPC API - -### Postman +## Postman Use the button to import our collection of examples to [Postman](https://www.getpostman.com/). [![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/cffe1bc034b3ab139fa7) -### Endpoint Host and Port +## Endpoint Host and Port The placeholder `` and `` represents an endpoint (IP address and port) @@ -51,19 +33,23 @@ options to specify the port on which the JSON-RPC listens. The default ports are * 8545 for HTTP * 8546 for WebSockets -### HTTP and WebSocket Requests +## JSON-RPC Authentication -#### HTTP +[Authentication](Authentication.md) is disabled by default. -To make RPC over HTTP requests, you can use the `curl` tool, available in many systems using [curl source code or pre-compiled packages](https://curl.haxx.se/download.html). +## HTTP and WebSocket Requests + +### HTTP + +To make RPC requests over HTTP, you can use [`curl`](https://curl.haxx.se/download.html). ```bash $ curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53}' ``` -#### WebSockets +### WebSockets -To make requests over WebSockets, this reference uses [wscat](https://github.com/websockets/wscat), a Node.js based command-line tool. +To make RPC requests over WebSockets, you can use [wscat](https://github.com/websockets/wscat), a Node.js based command-line tool. First connect to the WebSockets server using `wscat` (you only need to connect once per session): @@ -78,28 +64,38 @@ Send individual requests as a JSON data package at each prompt: > {"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53} ``` +<<<<<<< HEAD:docs/JSON-RPC-API/Using-JSON-RPC-API.md +The [RPC Pub/Sub methods](../Using-Pantheon/RPC-PubSub.md) can also be used over WebSockets. + +!!! note + `wscat` does not support headers. [Authentication](Authentication.md) requires an authentication token to be passed in the + request header. To use authentication with WebSockets, an app that supports headers is required. + +## API Methods Enabled by Default +======= ### API Methods Enabled by Default +>>>>>>> 149c0c24631231f8a96f5740534d309774e99ff5:docs/Reference/Using-JSON-RPC-API.md The `ETH`, `NET`, and `WEB3` API methods are enabled by default. -Use the [`--rpc-http-api`](Pantheon-CLI-Syntax.md#rpc-http-api) or [`--rpc-ws-api`](Pantheon-CLI-Syntax.md#rpc-ws-api) +Use the [`--rpc-http-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-http-api) or [`--rpc-ws-api`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-api) options to enable the `ADMIN` ,`CLIQUE`,`DEBUG`, `IBFT` and `MINER` API methods. !!! note IBFT 2.0 is under development and will be available in v1.0. -### Block Parameter +## Block Parameter When you make requests that might have different results depending on the block accessed, the block parameter specifies the block. -Several methods, such as [eth_getTransactionByBlockNumberAndIndex](JSON-RPC-API-Methods.md#eth_gettransactionbyblocknumberandindex), have a block parameter. +Several methods, such as [eth_getTransactionByBlockNumberAndIndex](../Reference/JSON-RPC-API-Methods.md#eth_gettransactionbyblocknumberandindex), have a block parameter. The block parameter can have the following values: * `blockNumber` : `quantity` - Block number. Can be specified in hexadecimal or decimal. 0 represents the genesis block. * `earliest` : `tag` - Earliest (genesis) block. * `latest` : `tag` - Last block mined. -* `pending` : `tag` - Last block mined plus pending transactions. Use only with [eth_getTransactionCount](JSON-RPC-API-Methods.md#eth_gettransactioncount). +* `pending` : `tag` - Last block mined plus pending transactions. Use only with [eth_getTransactionCount](../Reference/JSON-RPC-API-Methods.md#eth_gettransactioncount). ## Not Supported by Pantheon @@ -107,7 +103,7 @@ The block parameter can have the following values: Account management relies on private key management in the client which is not implemented by Pantheon. -Use [`eth_sendRawTransaction`](JSON-RPC-API-Methods.md#eth_sendrawtransaction) to send signed transactions; `eth_sendTransaction` is not implemented. +Use [`eth_sendRawTransaction`](../Reference/JSON-RPC-API-Methods.md#eth_sendrawtransaction) to send signed transactions; `eth_sendTransaction` is not implemented. Use third-party wallets for [account management](../Using-Pantheon/Account-Management.md). diff --git a/docs/Reference/JSON-RPC-API-Methods.md b/docs/Reference/JSON-RPC-API-Methods.md index 7d988aa2b3..87122529e6 100644 --- a/docs/Reference/JSON-RPC-API-Methods.md +++ b/docs/Reference/JSON-RPC-API-Methods.md @@ -3,11 +3,6 @@ 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) option. - -The following lists the Pantheon JSON-RPC API commands: - ## Admin Methods !!! note @@ -482,7 +477,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). + This method returns an empty object because Pantheon [does not support account management](../JSON-RPC-API/Using-JSON-RPC-API.md#account-management). **Parameters** @@ -547,7 +542,7 @@ Returns the account balance of the specified address. `DATA` - 20-byte account address from which to retrieve the balance. -`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). +`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/Using-JSON-RPC-API.md#block-parameter). **Returns** @@ -580,7 +575,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](Using-JSON-RPC-API.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](../JSON-RPC-API/Using-JSON-RPC-API.md#block-parameter). **Returns** @@ -613,7 +608,7 @@ Returns the number of transactions sent from a specified address. `DATA` - 20-byte account address. -`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). +`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/Using-JSON-RPC-API.md#block-parameter). **Returns** @@ -671,7 +666,7 @@ Returns the number of transactions in a block matching the specified block numbe **Parameters** -`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). +`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/Using-JSON-RPC-API.md#block-parameter). **Returns** @@ -729,7 +724,7 @@ Returns the number of uncles in a block matching the specified block number. **Parameters** -`QUANTITY|TAG` - Integer representing either the 0-based index of the block within the blockchain, or one of the string tags `latest`, `earliest`, or `pending`, as described in [Block Parameter](Using-JSON-RPC-API.md#block-parameter). +`QUANTITY|TAG` - Integer representing either the 0-based index of the block within the blockchain, or one of the string tags `latest`, `earliest`, or `pending`, as described in [Block Parameter](../JSON-RPC-API/Using-JSON-RPC-API.md#block-parameter). **Returns** @@ -760,7 +755,7 @@ Returns the code of the smart contract at the specified address. Compiled smart `DATA` - 20-byte contract address. -`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). +`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/Using-JSON-RPC-API.md#block-parameter). **Returns** @@ -792,7 +787,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 `eth_sendRawTransaction`. !!!important - Pantheon does not implement [eth_sendTransaction](Using-JSON-RPC-API.md#account-management). + Pantheon does not implement [eth_sendTransaction](../JSON-RPC-API/Using-JSON-RPC-API.md#account-management). **Parameters** @@ -834,7 +829,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](Using-JSON-RPC-API.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](../JSON-RPC-API/Using-JSON-RPC-API.md#block-parameter). **Returns** @@ -986,7 +981,7 @@ Returns information about a block by block number. **Parameters** -`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). +`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/Using-JSON-RPC-API.md#block-parameter). `Boolean` - If `true`, returns the full [transaction objects](JSON-RPC-API-Objects.md#transaction-object); if `false`, returns only the hashes of the transactions. @@ -1127,7 +1122,7 @@ Returns transaction information for the specified block number and transaction i **Parameters** -`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). +`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/Using-JSON-RPC-API.md#block-parameter). `QUANTITY` - The transaction index position. @@ -1609,7 +1604,7 @@ Lists signers for the specified block. **Parameters** -`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). +`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/Using-JSON-RPC-API.md#block-parameter). **Returns** @@ -2132,7 +2127,7 @@ Lists the validators defined in the specified block. **Parameters** -`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). +`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/Using-JSON-RPC-API.md#block-parameter). **Returns** diff --git a/docs/Reference/JSON-RPC-API-Objects.md b/docs/Reference/JSON-RPC-API-Objects.md index c590e2b2f4..3ef0d00b6c 100644 --- a/docs/Reference/JSON-RPC-API-Objects.md +++ b/docs/Reference/JSON-RPC-API-Objects.md @@ -38,8 +38,8 @@ Parameter for [eth_newFilter](JSON-RPC-API-Methods.md#eth_newfilter) and [eth_ge | Key | Type | Required/Optional | Value | |---------------|:---------------------------------:|:-----------------:|---------------------------------------------------------------------------------------------------------------------------------------------| -| **fromBlock** | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](Using-JSON-RPC-API.md#block-parameter). Default is `latest`. | -| **toBlock** | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](Using-JSON-RPC-API.md#block-parameter). Default is `latest`. | +| **fromBlock** | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](../JSON-RPC-API/Using-JSON-RPC-API.md#block-parameter). Default is `latest`. | +| **toBlock** | Quantity | Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](../JSON-RPC-API/Using-JSON-RPC-API.md#block-parameter). Default is `latest`. | | **address** | Data | Array | Optional | Contract address or array of addresses from which [logs](../Using-Pantheon/Events-and-Logs.md) originate. | | **topics** | Array of Data, 32 bytes each | Optional | Array of topics by which to [filter logs](../Using-Pantheon/Events-and-Logs.md#topic-filters). | diff --git a/docs/Reference/JSON-RPC-API.md b/docs/Reference/JSON-RPC-API.md deleted file mode 100644 index 0a03a998e9..0000000000 --- a/docs/Reference/JSON-RPC-API.md +++ /dev/null @@ -1,12 +0,0 @@ -description: Pantheon JSON-RPC API reference - - -# JSON-RPC API overview - -The Pantheon JSON-RPC API uses the [JSON](http://json.org/) (RFC 4627) data format, which can represent objects and data fields as collections of name/value pairs, in a relatively readable, hierarchical form. Values have specific data types such as QUANTITIES (decimal integers, hexadecimal numbers, strings) and UNFORMATTED DATA (byte arrays, account addresses, hashes, and bytecode arrays). - -RPC is the remote procedure call protocol (RFC 1831), which is stateless and transport agnostic in that the concepts can be used within the same process, over sockets, over HTTP, or in many various message passing environments. - -* [Using the Pantheon JSON-RPC API](Using-JSON-RPC-API.md) -* [JSON-RPC API Methods](JSON-RPC-API-Methods.md) -* [JSON-RPC API Objects](JSON-RPC-API-Objects.md) \ No newline at end of file diff --git a/docs/Reference/Pantheon-CLI-Syntax.md b/docs/Reference/Pantheon-CLI-Syntax.md index 7470fda0bd..6b447a4b8a 100644 --- a/docs/Reference/Pantheon-CLI-Syntax.md +++ b/docs/Reference/Pantheon-CLI-Syntax.md @@ -553,10 +553,7 @@ permissions-accounts-enabled=true ``` Set to enable account level permissions. -The default is `false`. - -!!!note - Permissions is under development and will be available in v1.0. +The default is `false`. ### permissions-config-file @@ -595,9 +592,6 @@ permissions-nodes-enabled=true Set to enable node level permissions. The default is `false`. -!!!note - Permissions is under development and will be available in v1.0. - ### privacy-enabled ```bash tab="Syntax" @@ -652,93 +646,64 @@ URL on which enclave is running. !!!note Privacy is under development and will be available in v1.1. -### rpc-http-enabled - -```bash tab="Syntax" ---rpc-http-enabled -``` - -```bash tab="Example Configuration File" -rpc-http-enabled=true -``` - -Set to `true` to enable the HTTP JSON-RPC service. -The default is `false`. - -### rpc-http-host +### rpc-http-api ```bash tab="Syntax" ---rpc-http-host= +--rpc-http-api=[,...]... ``` ```bash tab="Example Command Line" -# to listen on all interfaces ---rpc-http-host=0.0.0.0 +--rpc-http-api=ETH,NET,WEB3 ``` ```bash tab="Example Configuration File" -rpc-http-host="0.0.0.0" +rpc-http-api=["ETH","NET","WEB3"] ``` -Specifies the host on which HTTP JSON-RPC listens. -The default is 127.0.0.1. - -To allow remote connections, set to `0.0.0.0` - -!!! caution - Setting the host to 0.0.0.0 exposes the RPC connection on your node to any remote connection. In a - production environment, ensure you are using a firewall to avoid exposing your node to the internet. +Comma-separated APIs to enable on the HTTP JSON-RPC channel. +When you use this option, the `--rpc-http-enabled` option must also be specified. +The available API options are: `ADMIN`, `ETH`, `NET`, `WEB3`, `CLIQUE`, `IBFT`, `PERM`, `DEBUG`, `MINER`, and `EEA`. +The default is: `ETH`, `NET`, `WEB3`. !!!note - This option is not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md#exposing-ports). + EEA methods are for privacy features. Privacy features are under development and will be available in v1.1. -### rpc-http-port +!!!tip + The singular `--rpc-http-api` and plural `--rpc-http-apis` are available and are just two + names for the same option. + +### rpc-http-authentication-credentials-file ```bash tab="Syntax" ---rpc-http-port= +--rpc-http-authentication-credentials-file= ``` ```bash tab="Example Command Line" -# to listen on port 3435 ---rpc-http-port=3435 +--rpc-http-authentication-credentials-file=/home/me/me_node/auth.toml ``` ```bash tab="Example Configuration File" -rpc-http-port="3435" +rpc-http-authentication-credentials-file="/home/me/me_node/auth.toml" ``` -Specifies the port on which HTTP JSON-RPC listens. -The default is 8545. - -!!!note - This option is not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md#exposing-ports). +[Credentials file](../JSON-RPC-API/Authentication.md#credentials-file) for JSON-RPC API [authentication](../JSON-RPC-API/Authentication.md). -### rpc-http-api +### rpc-http-authentication-enabled ```bash tab="Syntax" ---rpc-http-api=[,...]... +--rpc-http-authentication-enabled ``` ```bash tab="Example Command Line" ---rpc-http-api=ETH,NET,WEB3 +--rpc-http-authentication-enabled ``` ```bash tab="Example Configuration File" -rpc-http-api=["ETH","NET","WEB3"] +rpc-http-authentication-enabled=true ``` -Comma-separated APIs to enable on the HTTP JSON-RPC channel. -When you use this option, the `--rpc-http-enabled` option must also be specified. -The available API options are: `ADMIN`, `ETH`, `NET`, `WEB3`, `CLIQUE`, `IBFT`, `DEBUG`, and `MINER`. -The default is: `ETH`, `NET`, `WEB3`. +Set to `true` to require [authentication](../JSON-RPC-API/Authentication.md) for the HTTP JSON-RPC service. -!!!note - IBFT 2.0 is under development and will be available in v1.0. - -!!!tip - The singular `--rpc-http-api` and plural `--rpc-http-apis` are available and are just two - names for the same option. - ### rpc-http-cors-origins ```bash tab="Syntax" @@ -779,19 +744,67 @@ If you don't whitelist any domains, browser apps cannot interact with your Panth For development purposes, you can use `"all"` or `"*"` to accept requests from any domain, but we don't recommend this for production code. -### rpc-ws-enabled +### rpc-http-enabled ```bash tab="Syntax" ---rpc-ws-enabled +--rpc-http-enabled ``` ```bash tab="Example Configuration File" -rpc-ws-enabled=true +rpc-http-enabled=true ``` -Set to `true` to enable the WebSockets JSON-RPC service. +Set to `true` to enable the HTTP JSON-RPC service. The default is `false`. +### rpc-http-host + +```bash tab="Syntax" +--rpc-http-host= +``` + +```bash tab="Example Command Line" +# to listen on all interfaces +--rpc-http-host=0.0.0.0 +``` + +```bash tab="Example Configuration File" +rpc-http-host="0.0.0.0" +``` + +Specifies the host on which HTTP JSON-RPC listens. +The default is 127.0.0.1. + +To allow remote connections, set to `0.0.0.0` + +!!! caution + Setting the host to 0.0.0.0 exposes the RPC connection on your node to any remote connection. In a + production environment, ensure you are using a firewall to avoid exposing your node to the internet. + +!!!note + This option is not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md#exposing-ports). + +### rpc-http-port + +```bash tab="Syntax" +--rpc-http-port= +``` + +```bash tab="Example Command Line" +# to listen on port 3435 +--rpc-http-port=3435 +``` + +```bash tab="Example Configuration File" +rpc-http-port="3435" +``` + +Specifies the port on which HTTP JSON-RPC listens. +The default is 8545. + +!!!note + This option is not used when running Pantheon from the [Docker image](../Getting-Started/Run-Docker-Image.md#exposing-ports). + ### rpc-ws-api ```bash tab="Syntax" @@ -806,17 +819,66 @@ The default is `false`. rpc-ws-api=["ETH","NET","WEB3"] ``` -Comma-separated APIs to enable on Websockets channel. +Comma-separated APIs to enable on WebSockets channel. When you use this option, the `--rpc-ws-enabled` option must also be specified. -The available API options are: `ETH`, `NET`, `WEB3`, `CLIQUE`, `IBFT`, `DEBUG`, and `MINER`. +The available API options are: `ETH`, `NET`, `WEB3`, `CLIQUE`, `IBFT`, `PERM', DEBUG`, `MINER` and `EEA`. The default is: `ETH`, `NET`, `WEB3`. !!!note - IBFT 2.0 is under development and will be available in v1.0. + EEA methods are for privacy features. Privacy features are under development and will be available in v1.1. !!!tip The singular `--rpc-ws-api` and plural `--rpc-ws-apis` are available and are just two names for the same option. + +### rpc-ws-authentication-credentials-file + +```bash tab="Syntax" +--rpc-ws-authentication-credentials-file= +``` + +```bash tab="Example Command Line" +--rpc-ws-authentication-credentials-file=/home/me/me_node/auth.toml +``` + +```bash tab="Example Configuration File" +rpc-ws-authentication-credentials-file="/home/me/me_node/auth.toml" +``` + +[Credentials file](../JSON-RPC-API/Authentication.md#credentials-file) for JSON-RPC API [authentication](../JSON-RPC-API/Authentication.md). + +### rpc-ws-authentication-enabled + +```bash tab="Syntax" +--rpc-ws-authentication-enabled +``` + +```bash tab="Example Command Line" +--rpc-ws-authentication-enabled +``` + +```bash tab="Example Configuration File" +rpc-ws-authentication-enabled=true +``` + +Set to `true` to require [authentication](../JSON-RPC-API/Authentication.md) for the WebSockets JSON-RPC service. + +!!! note + `wscat` does not support headers. [Authentication](../JSON-RPC-API/Authentication.md) requires an authentication token to be passed in the + request header. To use authentication with WebSockets, an app that supports headers is required. + +### rpc-ws-enabled + +```bash tab="Syntax" +--rpc-ws-enabled +``` + +```bash tab="Example Configuration File" +rpc-ws-enabled=true +``` + +Set to `true` to enable the WebSockets JSON-RPC service. +The default is `false`. ### rpc-ws-host diff --git a/docs/Tutorials/Create-Private-Network.md b/docs/Tutorials/Create-Private-Network.md index 7a1dcfd013..be66b23a09 100644 --- a/docs/Tutorials/Create-Private-Network.md +++ b/docs/Tutorials/Create-Private-Network.md @@ -201,7 +201,7 @@ Import accounts to MetaMask and send transactions as described in the [Private N Send transactions using `eth_sendRawTransaction` to [send ether or, deploy or invoke contracts](../Using-Pantheon/Transactions.md). -Use the [JSON-RPC API](../Reference/Using-JSON-RPC-API.md). +Use the [JSON-RPC API](../JSON-RPC-API/Using-JSON-RPC-API.md). Start a node with the [`--rpc-ws-enabled`](../Reference/Pantheon-CLI-Syntax.md#rpc-ws-enabled) option and use the [RPC Pub/Sub API](../Using-Pantheon/RPC-PubSub.md). diff --git a/docs/Using-Pantheon/RPC-PubSub.md b/docs/Using-Pantheon/RPC-PubSub.md index 0f7de3c2a8..6a9d0e7eaf 100644 --- a/docs/Using-Pantheon/RPC-PubSub.md +++ b/docs/Using-Pantheon/RPC-PubSub.md @@ -19,7 +19,7 @@ The RPC Pub/Sub methods are: ### 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). +The RPC Pub/Sub API is supported on [WebSockets](../JSON-RPC-API/Using-JSON-RPC-API.md#http-and-websocket-requests). Use `eth_subscribe` to create subscriptions. Once subscribed, notifications are published by the API using `eth_subscription`. diff --git a/docs/index.md b/docs/index.md index 8b429e8f1b..fe415307d2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,7 +20,7 @@ enterprise features. ## What can you do with Pantheon? -Pantheon includes a [command line interface](Reference/Pantheon-CLI-Syntax.md) and [JSON-RPC API](Reference/JSON-RPC-API.md) +Pantheon includes a [command line interface](Reference/Pantheon-CLI-Syntax.md) and [JSON-RPC API](JSON-RPC-API/JSON-RPC-API.md) for running, maintaining, debugging, and monitoring node operations in an Ethereum network. You can use the API via RPC over HTTP or via WebSockets transport, and Pub/Sub is supported. The API supports typical Ethereum functionalities such as: diff --git a/mkdocs.yml b/mkdocs.yml index 1cd85bcf62..b4f05906c8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,6 +60,10 @@ nav: - Comparing PoA Consensus Protocols: Consensus-Protocols/Comparing-PoA.md - Clique: Consensus-Protocols/Clique.md - IBFT 2.0: Consensus-Protocols/IBFT.md + - JSON-RPC API: + - Overview: JSON-RPC-API/JSON-RPC-API.md + - Using the JSON-RPC API: JSON-RPC-API/Using-JSON-RPC-API.md + - Authentication: JSON-RPC-API/Authentication.md - Configuring Pantheon: - Configuration File: Configuring-Pantheon/Using-Configuration-File.md - Network ID and Chain ID: Configuring-Pantheon/NetworkID-And-ChainID.md @@ -83,11 +87,8 @@ nav: - Debugging Pantheon: Using-Pantheon/Debugging.md - Reference: - Pantheon Command Line: Reference/Pantheon-CLI-Syntax.md - - Pantheon JSON-RPC API: - - JSON-RPC API Overview: Reference/JSON-RPC-API.md - - Using the JSON-RPC API: Reference/Using-JSON-RPC-API.md - - JSON-RPC API Methods: Reference/JSON-RPC-API-Methods.md - - JSON-RPC API Objects: Reference/JSON-RPC-API-Objects.md + - JSON-RPC API Methods: Reference/JSON-RPC-API-Methods.md + - JSON-RPC API Objects: Reference/JSON-RPC-API-Objects.md markdown_extensions: - toc: