diff --git a/docs/HowTo/Interact/APIs/API.md b/docs/HowTo/Interact/APIs/API.md index d20231c75d5..6868e4279a0 100644 --- a/docs/HowTo/Interact/APIs/API.md +++ b/docs/HowTo/Interact/APIs/API.md @@ -1,71 +1,87 @@ +--- description: Hyperledger Besu API - +--- + +# Access the Hyperledger Besu API Access the [Hyperledger Besu API](../../../Reference/API-Methods.md) using: -* [JSON-RPC over HTTP or WebSockets](Using-JSON-RPC-API.md) +* [JSON-RPC over HTTP or WebSockets](Using-JSON-RPC-API.md) * [RPC Pub/Sub over WebSockets](RPC-PubSub.md) -* [GraphQL over HTTP](GraphQL.md) +* [GraphQL over HTTP](GraphQL.md). + +The following sections provide information about JSON-RPC, RPC Pub/Sub, and GraphQL. -Information applying to JSON-RPC, RPC Pub/Sub, and GraphQL is included below. +## Enabling API access -## Enabling API Access +To enable API access, use the +[`--rpc-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled), +[`--ws-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-enabled), and +[`--graphql-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-enabled) options. -Use the [`--rpc-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled), [`--ws-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-enabled), -and [`--graphql-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-enabled) options to enable API access. +## Service hosts -## Service Hosts +To specify the host the API service listens on, use the +[`--rpc-http-host`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-host), +[`--rpc-ws-host`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-host), and +[`--graphql-http-host`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-host) options. The +default host is `127.0.0.1`. -Use the [`--rpc-http-host`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-host), [`--rpc-ws-host`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-host), -and [`--graphql-http-host`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-host) options to specify the host on which the API service listens. -The default host is 127.0.0.1. +To allow remote connections, set the host to `0.0.0.0`. -Set the host to `0.0.0.0` to allow remote connections. +!!! caution -!!! caution - Setting the host to 0.0.0.0 exposes the API service connection on your node to any remote connection. In a - production environment, ensure you use a firewall to avoid exposing your node to the internet. + Setting the host to `0.0.0.0` exposes the API service connection on your node to any remote + connection. In a production environment, ensure you use a firewall to avoid exposing your node + to the internet. -## Service Ports +## Service ports -Use the [`--rpc-http-port`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-port), [`--rpc-ws-port`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-port), -and [`--graphql-http-port`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-port) options to specify the port on which the API service listens. +To specify the port the API service listens on, use the +[`--rpc-http-port`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-port), +[`--rpc-ws-port`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-port), and +[`--graphql-http-port`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-port) options. -The default ports are: +The default ports are: * 8545 for JSON-RPC over HTTP * 8546 for JSON-RPC over WebSockets -* 8547 for GraphQL over HTTP +* 8547 for GraphQL over HTTP. Ports must be [exposed appropriately](../../Find-and-Connect/Managing-Peers.md#port-configuration). -## Host Whitelist +## Host whitelist -To prevent DNS rebinding, incoming HTTP requests, WebSockets connections, and GraphQL requests are only accepted from hostnames -specified using the [`--host-whitelist`](../../../Reference/CLI/CLI-Syntax.md#host-whitelist) option. -By default, `localhost` and `127.0.0.1` are accepted. +To prevent DNS rebinding, Besu accepts incoming HTTP requests, WebSockets connections, and GraphQL +requests only from hostnames specified using the +[`--host-whitelist`](../../../Reference/CLI/CLI-Syntax.md#host-whitelist) option. Besu accepts +incoming requests and connections from `localhost` and `127.0.0.1` by default. If your application publishes RPC ports, specify the hostnames when starting Besu. - + !!! example + ```bash besu --host-whitelist=example.com ``` - + Specify "*" for `--host-whitelist` to effectively disable host protection. -!!! caution +!!! caution + Specifying "*" for `--host-whitelist` is not recommended for production code. - -## Not Supported by Besu -### Account Management +## Not supported by Besu + +### Account management -Account management relies on private key management in the client which is not implemented by Besu. +Account management relies on private key management in the client, which is not supported by Besu. -Use [`eth_sendRawTransaction`](../../../Reference/API-Methods.md#eth_sendrawtransaction) to send signed transactions; `eth_sendTransaction` is not implemented. +To send signed transactions, use +[`eth_sendRawTransaction`](../../../Reference/API-Methods.md#eth_sendrawtransaction). +`eth_sendTransaction` is not implemented. -Use third-party wallets for [account management](../../Send-Transactions/Account-Management.md). +For [account management](../../Send-Transactions/Account-Management.md), use third-party wallets. ### Protocols diff --git a/docs/HowTo/Interact/APIs/Authentication.md b/docs/HowTo/Interact/APIs/Authentication.md index e94f325f004..6b7a349a487 100644 --- a/docs/HowTo/Interact/APIs/Authentication.md +++ b/docs/HowTo/Interact/APIs/Authentication.md @@ -1,176 +1,200 @@ +--- description: Hyperledger Besu authentication and Authorization for JSON-RPC - +--- -# Authentication and Authorization for JSON-RPC +# Authentication and authorization for JSON-RPC -Authentication identifies a user, and authorization verifies user -access to requested JSON-RPC methods. Users are verified using a [JWT token](https://jwt.io/introduction/). -JWT tokens are also used in [multi-tenancy](../../../Concepts/Privacy/Multi-Tenancy.md) to verify tenant data access. +Authentication identifies a user, and authorization verifies user access to requested JSON-RPC +methods. Hyperledger Besu verifies users using a [JWT token](https://jwt.io/introduction/).JWT +tokens are also used in [multi-tenancy](../../../Concepts/Privacy/Multi-Tenancy.md) to verify +tenant data access. -Hyperledger Besu supports two mutually exclusive authentication methods: +Besu supports two mutually exclusive authentication methods: * [Username and password](#username-and-password-authentication) * [JWT public key](#jwt-public-key-authentication). -JWT tokens are created internally with [username and password authentication](#username-and-password-authentication), and externally with [JWT public key authentication](#jwt-public-key-authentication). +Besu creates JWT tokens internally with +[username and password authentication](#username-and-password-authentication), and externally with +[JWT public key authentication](#jwt-public-key-authentication). -!!! important - To prevent interception of authentication credentials and authenticated tokens, make authenticated requests over HTTPS. - We recommended production deployments are run behind a network layer that provides SSL termination. - Besu does not provide a HTTPS connection natively. +!!! important + + To prevent interception of authentication credentials and authenticated tokens, make + authenticated requests over HTTPS. We recommended production deployments run behind a network + layer that provides SSL termination. Besu does not provide a HTTPS connection natively. +## Username and password authentication -## Username and Password Authentication +Enable authentication from the command line. Supply the credentials file and send a request to the +`/login` endpoint using the username and password. The `/login` endpoint creates a JWT token for +making permitted JSON RPC requests. -Enable authentication from the command line. Supply the credentials file and send a request to the `/login` endpoint using the username and password. The `/login` endpoint creates a JWT token that can be used to make permitted JSON RPC requests. +Using [public key authentication](#jwt-public-key-authentication) disables the `/login` endpoint. -The `/login` endpoint is disabled when using [public key authentication](#jwt-public-key-authentication). +### 1. Create the credentials file -### 1. Create the Credentials File +The `toml` credentials file defines user details and the JSON-RPC methods they can access. -The `toml` file defines user details and the JSON-RPC methods to which they have access. +!!! example "Sample Credentials File" -!!! example "Example Credentials File" ```toml [Users.username1] password = "$2a$10$l3GA7K8g6rJ/Yv.YFSygCuI9byngpEzxgWS9qEg5emYDZomQW7fGC" permissions=["net:*","eth:blockNumber"] privacyPublicKey="U7ANiOOd5L9Z/dMxRFjdbhA1Qragw6fLuYgmgCvLoX4=" - + [Users.username2] password = "$2b$10$6sHt1J0MVUGIoNKvJiK33uaZzUwNmMmJlaVLkIwinkPiS1UBnAnF2" permissions=["net:version","admin:*"] privacyPublicKey="quhb1pQPGN1w8ZSZSyiIfncEAlVY/M/rauSyQ5wVMRE=" ``` -Each user requiring JSON-RPC access is listed with: +Each user requiring JSON-RPC access the configuration file lists the: -* 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/CLI/CLI-Subcommands.md#password) subcommand to generate the hash. +* Username. `Users.` is mandatory and followed by the username. That is, replace `` in + `[Users.]` with the username. +* Hash of the user password. Use the + [`password hash`](../../../Reference/CLI/CLI-Subcommands.md#password) subcommand to generate the + hash. * [JSON-RPC permissions](#json-rpc-permissions). -* Optional. The tenant's Orion public key using `privacyPublicKey`. Only used -for [multi-tenancy](../../../Concepts/Privacy/Multi-Tenancy.md). +* Optional. The tenant's Orion public key using `privacyPublicKey`. Only used for + [multi-tenancy](../../../Concepts/Privacy/Multi-Tenancy.md). !!! example "password hash Subcommand" + ```bash besu password hash --password=pegasys ``` - - -### 2. Enable Authentication - -Use the [` --rpc-http-authentication-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-authentication-enabled) or - [`--rpc-ws-authentication-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-authentication-enabled) - options to require authentication for the JSON-RPC API. - -Use the [`--rpc-http-authentication-credentials-file`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-authentication-credentials-file) -and [`--rpc-ws-authentication-credentials-file`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-authentication-credentials-file) -options to specify the [credentials file](#1-create-the-credentials-file). - -### 3. Obtain an Authentication Token - -To obtain an authentication token, make a request to the `/login` endpoint with your username and password. Specify the -HTTP port or the WS port to obtain a token to authenticate over HTTP or WS respectively. A different token is required -for HTTP and WS. + +### 2. Enable authentication + +To require authentication for the JSON-RPC API, use the +[`--rpc-http-authentication-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-authentication-enabled) +or [`--rpc-ws-authentication-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-authentication-enabled) +options. + +To specify the [credentials file](#1-create-the-credentials-file), use the +[`--rpc-http-authentication-credentials-file`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-authentication-credentials-file) +and [`--rpc-ws-authentication-credentials-file`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-authentication-credentials-file) +options. + +### 3. Generate an authentication token + +To generate an authentication token, make a request to the `/login` endpoint with your username and +password. Specify the HTTP port or the WS port to generate a token to authenticate over HTTP or WS +respectively. HTTP and WS requires a different token. !!! example - ```bash tab="Obtain Token for HTTP" + + ```bash tab="Generate a token for HTTP" curl -X POST --data '{"username":"username1","password":"pegasys"}' /login ``` - + ```bash tab="Example for HTTP" curl -X POST --data '{"username":"username1","password":"pegasys"}' http://localhost:8545/login ``` - - ```bash tab="Obtain Token for WS" + + ```bash tab="Generate a token for WS" curl -X POST --data '{"username":"username1","password":"pegasys"}' /login ``` - + ```bash tab="Example for WS" curl -X POST --data '{"username":"username1","password":"pegasys"}' http://localhost:8546/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. +Authentication tokens expire five minutes after generation. If you require access after the token +expires, you need to generate a new token. -## JWT Public Key Authentication +## JWT public key authentication Enable authentication from the command line and supply the public key of the external JWT token. -JWT public authentication disables the Besu `/login` endpoint, meaning [username and password authentication](#username-and-password-authentication) will not work. +JWT public authentication disables the Besu `/login` endpoint, meaning +[username and password authentication](#username-and-password-authentication) will not work. + +### 1. generate a private and public key pair -### 1. Generate a Private and Public Key Pair +The private and accompanying public key files must be in `.pem` format. -The private and accompanying public key files must be in the `.pem` format. +The key must use an RSA private key of at least 2048 bits. -The key must use a RSA private key of at least 2048 bits. +!!! example "Sample using OpenSSL" -!!! example "Example using OpenSSL" ```bash openssl genrsa -out privateKey.pem 2048 openssl rsa -pubout -in privateKey.pem -pubout -out publicKey.pem ``` -### 2. Create the JWT Token +### 2. create the JWT token -Create the JWT token using an external tool. +Create the JWT token using an external tool. !!! important - The JWT token must use the `RS256` algorithm + + The JWT token must use the `RS256` algorithm Each payload for the JWT token contains: -* [JSON-RPC permissions](#json-rpc-permissions). -* [`exp` (Expiration Time) claim](https://tools.ietf.org/html/rfc7519#section-4.1.4). -* Optional. The tenant's Orion public key using `privacyPublicKey`. Only used -for [multi-tenancy](../../../Concepts/Privacy/Multi-Tenancy.md). +* [JSON-RPC permissions](#json-rpc-permissions) +* [`exp` (Expiration Time) claim](https://tools.ietf.org/html/rfc7519#section-4.1.4) +* Optionally, the tenant's Orion public key using `privacyPublicKey`. Only used for + [multi-tenancy](../../../Concepts/Privacy/Multi-Tenancy.md). -The following example uses the [JWT.io](https://jwt.io/) website to create a JWT token for testing purposes. +The following example uses the [JWT.io](https://jwt.io/) website to create a JWT token for +testing purposes. ![Create a JWT token](../../../images/JWT.png) -### 3. Enable Authentication +### 3. Enable authentication + +To require authentication for the JSON-RPC API, use the +[`--rpc-http-authentication-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-authentication-enabled) +or [`--rpc-ws-authentication-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-authentication-enabled) +options. + +To specify the public key to use with the externally created JWT token, use the +[`--rpc-http-authentication-jwt-public-key-file`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-authentication-jwt-public-key-file) +and [`--rpc-ws-authentication-jwt-public-key-file`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-authentication-jwt-public-key-file) +options. -Use the [` --rpc-http-authentication-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-authentication-enabled) or - [`--rpc-ws-authentication-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-authentication-enabled) - options to require authentication for the JSON-RPC API. - -Use the [`--rpc-http-authentication-jwt-public-key-file`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-authentication-jwt-public-key-file) and [`--rpc-ws-authentication-jwt-public-key-file`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-authentication-jwt-public-key-file) options to specify the public key to use with the externally created JWT token. - -## JSON-RPC Permissions +## JSON-RPC permissions -Each user has a list of permissions strings defining the methods they can access. To give access to: +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:*"]`. +* 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. +With authentication 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. -## Using an Authentication Token to Make Requests +## Using an authentication token to make requests -Specify the authentication token as a `Bearer` token in the JSON-RPC request header. +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. The token is generated [externally](#2-create-the-jwt-token), or by the [`login` request](#3-obtain-an-authentication-token). +In the _Authorization_ tab in the _TYPE_ drop-down list, select *Bearer Token* and specify the +token (generated either [externally](#2-create-the-jwt-token) or by the +[`login` request](#3-generate-an-authentication-token)). -### Curl +### cURL -Specify the `Bearer` in the header. +Specify the `Bearer` in the header. !!! example - ```bash tab="curl Request with Authentication Placeholders" + + ```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" + + ```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}' http://localhost:8545 ``` \ No newline at end of file diff --git a/docs/HowTo/Interact/APIs/GraphQL.md b/docs/HowTo/Interact/APIs/GraphQL.md index 17d186f8320..2f2e77b9b7d 100644 --- a/docs/HowTo/Interact/APIs/GraphQL.md +++ b/docs/HowTo/Interact/APIs/GraphQL.md @@ -1,51 +1,61 @@ +--- description: How to access the Hyperledger Besu API using GraphQL - +--- # GraphQL over HTTP GraphQL can reduce the overhead needed for common queries. For example, instead of querying each receipt in a -block, GraphQL can obtain the same result with a single query for the entire block. +block, GraphQL can get the same result with a single query for the entire block. -The GraphQL implementation for Ethereum is described in the [schema](https://github.com/hyperledger/besu/blob/master/ethereum/api/src/main/resources/schema.graphqls). -The GraphQL service is enabled using the [command line options](API.md#enabling-api-access). +The [Besu GraphQL schema] describes the GraphQL implementation for Ethereum. Enable the GraphQL +service using [command line options](API.md#enabling-api-access). !!! note + GraphQL is not supported over WebSockets. - -Access the GraphQL endpoint at `http://:/graphql` where `` and `` can be configured using [`graphql-http-host`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-host) and [`graphql-http-port`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-port). The default endpoint is `http://127.0.0.1:8547/graphql`. +Access the GraphQL endpoint at `http://:/graphql`. Configure `` and `` +using [`graphql-http-host`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-host) and +[`graphql-http-port`](../../../Reference/CLI/CLI-Syntax.md#graphql-http-port). The default endpoint +is `http://127.0.0.1:8547/graphql`. -## GraphQL Requests with Curl +## GraphQL requests with cURL -[Hyperledger Besu JSON-RPC API methods](../../../Reference/API-Methods.md) with an equivalent [GraphQL](GraphQL.md) -query include a GraphQL request and result in the method example. +[Hyperledger Besu JSON-RPC API methods](../../../Reference/API-Methods.md) with an equivalent +[GraphQL](GraphQL.md) query include a GraphQL request and result in the method example. !!! example - The following [`syncing`](../../../Reference/API-Methods.md#eth_syncing) request returns data about the synchronization status. + + The following [`syncing`](../../../Reference/API-Methods.md#eth_syncing) request returns data + about the synchronization status. + ```bash curl -X POST -H "Content-Type: application/json" --data '{ "query": "{syncing{startingBlock currentBlock highestBlock}}"}' http://localhost:8547/graphql ``` -## GraphQL Requests with GraphiQL App +## GraphQL requests with GraphiQL App -The third-party tool [GraphiQL](https://github.com/skevy/graphiql-app) provides a tabbed interface for editing and testing GraphQL -queries and mutations. GraphiQL also provides access the Besu GraphQL schema from within the app. +The third-party tool, [GraphiQL](https://github.com/skevy/graphiql-app), provides a tabbed +interface for editing and testing GraphQL queries and mutations. GraphiQL also provides access the +[Besu GraphQL schema] from within the app. -![GraphiQL](../../../images/GraphiQL.png) +![GraphiQL](../../../images/GraphiQL.png) -## Pending +## Pending -The Pending query is supported for `transactionCount` and `transactions`. +`transactionCount` and `transactions` supports the Pending query. -!!! important - Besu doesn't execute pending transactions so result from `account`, `call`, and `estimateGas` for Pending - do not reflect pending transactions. +!!! important + + Besu does not execute pending transactions so results from `account`, `call`, and `estimateGas` + for Pending do not reflect pending transactions. !!! example + ```bash tab="Pending Transaction Count" curl -X POST -H "Content-Type: application/json" --data '{ "query": "{pending {transactionCount}}"}' http://localhost:8547/graphql ``` - + ```bash tab="Result" { "data" : { @@ -55,12 +65,13 @@ The Pending query is supported for `transactionCount` and `transactions`. } } ``` - + !!! example + ```bash tab="Pending Transactions" curl -X POST -H "Content-Type: application/json" --data '{ "query": "{pending {transactions{hash}}}"}' http://localhost:8547/graphql ``` - + ```bash tab="Result" { "data" : { @@ -73,4 +84,7 @@ The Pending query is supported for `transactionCount` and `transactions`. } } } - ``` \ No newline at end of file + ``` + + +[Besu GraphQL schema]: https://github.com/hyperledger/besu/blob/master/ethereum/api/src/main/resources/schema.graphqls diff --git a/docs/HowTo/Interact/APIs/RPC-PubSub.md b/docs/HowTo/Interact/APIs/RPC-PubSub.md index 0ac5e2d5edc..843adb95e58 100644 --- a/docs/HowTo/Interact/APIs/RPC-PubSub.md +++ b/docs/HowTo/Interact/APIs/RPC-PubSub.md @@ -1,59 +1,72 @@ +--- description: Using RPC Pub/Sub with Hyperledger Besu WebSockets - +--- # RPC Pub/Sub over WebSockets ## Introduction -Subscribe to events by using either RPC Pub/Sub over WebSockets or [filters over HTTP](../Filters/Accessing-Logs-Using-JSON-RPC.md). +Subscribe to events by using either RPC Pub/Sub over WebSockets or +[filters over HTTP](../Filters/Accessing-Logs-Using-JSON-RPC.md). -Use RPC Pub/Sub over WebSockets 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. +Use RPC Pub/Sub over WebSockets to wait for events instead of polling for them. For example, a Dapp +can subscribe to logs and receive notification when a specific event occurs. -Methods specific to RPC Pub/Sub are: +Methods specific to RPC Pub/Sub are: -* `eth_subscribe` - create a subscription for specific events. +* `eth_subscribe` - create a subscription for specific events * `eth_unsubscribe` - cancel a subscription. !!!important - Unlike other [Hyperledger Besu API methods](../../../Reference/API-Methods.md), - the RPC Pub/Sub methods cannot be called over HTTP. Use the [`--rpc-ws-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-enabled) option to enable - the WebSockets JSON-RPC service. - + + Unlike other [Hyperledger Besu API methods](../../../Reference/API-Methods.md), you cannot call + the RPC Pub/Sub methods over HTTP. Use the + [`--rpc-ws-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-enabled) option to enable the + WebSockets JSON-RPC service. + ### Using RPC Pub/Sub -The RPC Pub/Sub API is supported on [WebSockets](Using-JSON-RPC-API.md#http-and-websocket-requests). +[WebSockets](Using-JSON-RPC-API.md#http-and-websocket-requests) supports the RPC Pub/Sub API. -Use `eth_subscribe` to create subscriptions. Once subscribed, notifications are published by the API using `eth_subscription`. +To create subscriptions, use `eth_subscribe`. Once subscribed, the API publishes notifications +using `eth_subscription`. -!!!note - Notifications are published by `eth_subscription`; you do not need to call `eth_subscription`. +!!!note -Subscriptions are coupled to a connection. If the connection is closed, all subscriptions created over this connection are removed. + `eth_subscription` publishes notifications; you do not need to call `eth_subscription`. -### Subscription ID +Subscriptions couple with connections. If a connection is closes, this removes all subscriptions +created over the connection. -`eth_subscribe` returns a subscription ID for each subscription created. Notifications include the subscription ID. +### Subscription ID +`eth_subscribe` returns a subscription ID for each subscription created. Notifications include the +subscription ID. !!!example - For example, to create a synchonizing subscription - + + For example, to create a synchronizing subscription: + ```json {"id": 1, "method": "eth_subscribe", "params": ["syncing"]} ``` - The result includes the subscription ID of `"0x1"`: + + The result includes the subscription ID of `"0x1"`: + ```json {"jsonrpc":"2.0","id":1,"result":"0x1"} ``` - The notifications also include the subscription ID of `"0x1"`: + + The notifications also include the subscription ID of `"0x1"`: + ```json {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x1","result":{"startingBlock":"0x0","currentBlock":"0x50","highestBlock":"0x343c19"}}} ``` -### Notifications when Synchronizing +### Notifications when synchronizing -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. ## Subscribing @@ -63,32 +76,39 @@ Use `eth_subscribe` to create subscriptions for the following event types: * [Logs](#logs) * [Pending transactions](#pending-transactions) * [Dropped transactions](#dropped-transactions) -* [Synchronizng](#synchronizing) +* [Synchronizng](#synchronizing) -### New Headers +### New headers -Use the `newHeads` parameter with `eth_subscribe` to be notified each time a block is added to the blockchain. +To notify you about each block added to the blockchain, use the `newHeads` parameter with +`eth_subscribe`. -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. +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](../../../Reference/API-Objects.md#block-object). The -second parameter is optional. If specified, whole [transaction objects](../../../Reference/API-Objects.md#transaction-object) -are included in the notifications. Otherwise, the transaction hashes are included. +The new headers notification returns +[block objects](../../../Reference/API-Objects.md#block-object). The second parameter is optional. +If specified, the notifications include whole +[transaction objects](../../../Reference/API-Objects.md#transaction-object), Otherwise, the +notifications include transaction hashes. !!!example + To subscribe to new header notifications: - + ```json {"id": 1, "method": "eth_subscribe", "params": ["newHeads", {"includeTransactions": true}]} ``` - + Example result: + ```json {"jsonrpc":"2.0","id":2,"result":"0x1"} ``` - + Example notification without the `{"includeTransactions": true}` parameter included: + ```json { "jsonrpc": "2.0", @@ -119,8 +139,9 @@ are included in the notifications. Otherwise, the transaction hashes are include } } ``` - - Example notification with the `{"includeTransactions": true}` parameter included: + + Example notification with the `{"includeTransactions": true}` parameter included: + ```json { "jsonrpc": "2.0", @@ -154,35 +175,46 @@ are included in the notifications. Otherwise, the transaction hashes are include ### Logs -Use the `logs` parameter with `eth_subscribe` to be notified of [logs](../../../Concepts/Events-and-Logs.md) included in new blocks. You can -specify a filter object to receive notifications only for logs matching your filter. +To notify you about [logs](../../../Concepts/Events-and-Logs.md) included in new blocks, use the +`logs` parameter with `eth_subscribe`. You can specify a filter object to receive notifications +only for logs matching your filter. 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](../../../Concepts/Events-and-Logs.md#topic-filters). +* `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](../../../Concepts/Events-and-Logs.md#topic-filters). -If a chain reorganization occurs, the subscription publishes notifications for logs from the old chain -with the `removed` property in the [log object](../../../Reference/API-Objects.md#log-object) set to `true`. -This means the subscription can publish notifications for multiple logs for the same transaction. +If a chain reorganization occurs, the subscription publishes notifications for logs from the old +chain with the `removed` property in the [log object](../../../Reference/API-Objects.md#log-object) +set to `true`. This means the subscription can publish notifications for multiple logs for the same +transaction. -The logs subscription returns [log objects](../../../Reference/API-Objects.md#log-object). +The logs subscription returns [log objects](../../../Reference/API-Objects.md#log-object). !!!example + To subscribe to all logs notifications: + ```json {"id": 1, "method": "eth_subscribe", "params": ["logs",{}]} ``` - To subscribe to logs for a specific address and topic: + + To subscribe to logs for a specific address and topic: + ```json {"id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd", "topics": ["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"]}]} ``` - + Example result: + ```json {"jsonrpc":"2.0","id":1,"result":"0x2"} ``` - Example notification: + + Example notification: + ```json { "jsonrpc":"2.0", @@ -204,31 +236,35 @@ The logs subscription returns [log objects](../../../Reference/API-Objects.md#lo } ``` -### Pending Transactions +### Pending transactions -Use the `newPendingTransactions` parameter with `eth_subscribe` to be notified of pending transactions -added to the transaction pool for the node. +To notify you about pending transactions added to the transaction pool for the node, use the +`newPendingTransactions` parameter with `eth_subscribe`. -The pending transactions subscription returns the transaction hashes or transaction details of the pending transactions. -If the `includeTransactions` parameter is not included, the default is transaction hashes only. +The pending transactions subscription returns the transaction hashes or transaction details of the +pending transactions. If the `includeTransactions` parameter is not included, the default is +transaction hashes only. -If a chain reorganization occurs, transactions are resubmitted to be included in the new canonical chain. -This means the subscription can publish notifications for the same pending transaction more than once. +If a chain reorganization occurs, Besu resubmits transactions for inclusion in the new canonical +chain. This means the subscription can publish notifications for the same pending transaction more +than once. !!!example "Transaction Hashes" + To subscribe to pending transaction notifications and receive transaction hashes only: - + ```json {"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions", {"includeTransactions":false}]} ``` - + Example result: + ```json {"jsonrpc":"2.0","id":1,"result":"0x1"} ``` - - - Example notification: + + Example notification: + ```json { "jsonrpc":"2.0", @@ -241,18 +277,21 @@ This means the subscription can publish notifications for the same pending trans ``` !!!example "Transaction Details" + To subscribe to pending transaction notifications and receive transaction details: - + ```json {"id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions", {"includeTransactions":true}]} ``` - + Example result: + ```json {"jsonrpc":"2.0","id":1,"result":"0x2"} - ``` - - Example notification: + ``` + + Example notification: + ```json { "jsonrpc":"2.0", @@ -275,32 +314,35 @@ This means the subscription can publish notifications for the same pending trans } } ``` - -### Dropped Transactions -Use the `droppedPendingTransactions` parameter with `eth_subscribe` to be notified of transactions -dropped from the transaction pool for the node. +### Dropped transactions -The dropped transactions subscription returns the transaction hashes of the dropped transactions. +To notify you about transactions dropped from the transaction pool for the node, use the +`droppedPendingTransactions` parameter with `eth_subscribe`. -Transactions can be re-added to the transaction pool from a variety of sources after being dropped. For example, -receiving a previously dropped transaction from a peer. As a result it's possible to receive multiple dropped -transaction notifications for the same transaction. +The dropped transactions subscription returns the transaction hashes of the dropped transactions. + +Dropped transactions can be re-added to the transaction pool from a variety of sources. For +example, receiving a previously dropped transaction from a peer. As a result, it's possible to +receive multiple dropped transaction notifications for the same transaction. !!!example + To subscribe to dropped transaction notifications: - + ```json {"id": 1, "method": "eth_subscribe", "params": ["droppedPendingTransactions"]} ``` - + Example result: + ```json {"jsonrpc":"2.0","id":1,"result":"0x1"} ``` - - - Example notification: + + + Example notification: + ```json { "jsonrpc":"2.0", @@ -314,24 +356,27 @@ transaction notifications for the same transaction. ### Synchronizing -Use the `syncing` parameter with `eth_subscribe` to be notified about synchronization progress. +To notify you about synchronization progress, use the `syncing` parameter with `eth_subscribe`. -When behind the chain head, the synchronizing subscription returns an object indicating the synchronization -progress. When fully synchronized, returns false. +When behind the chain head, the synchronizing subscription returns an object indicating the +synchronization progress. When fully synchronized, returns `false`. !!!example + To subscribe to synchronizing notifications: + ```json {"id": 1, "method": "eth_subscribe", "params": ["syncing"]} ``` - + Example result: + ```json {"jsonrpc":"2.0","id":1,"result":"0x4"} ``` - - Example notification while synchronizing: - + + Example notification while synchronizing: + ```json { "jsonrpc":"2.0", @@ -346,9 +391,9 @@ progress. When fully synchronized, returns false. } } ``` - + Example notification when synchronized with chain head: - + ```json { "jsonrpc":"2.0", @@ -359,21 +404,25 @@ progress. When fully synchronized, returns false. } } ``` - + ## Unsubscribing -Use the [subscription ID](#subscription-id) with `eth_unsubscribe` to cancel a subscription. Only the -connection that created a subscription can unsubscribe from it. +To cancel a subscription, use the [subscription ID](#subscription-id) with `eth_unsubscribe`. Only +the connection that created a subscription can unsubscribe from it. -`eth_unsubscribe` returns `true` if subscription succuessfully unsubscribed; otherwise, an error is returned. +`eth_unsubscribe` returns `true` if subscription succuessfully unsubscribed; otherwise, returns an +error. !!!example + To unsubscribe from a subsciption with subscription ID of `0x1`: + ```json {"id": 1, "method": "eth_unsubscribe", "params": ["0x1"]} ``` - - Example result: + + Example result: + ```json {"jsonrpc":"2.0","id":1,"result":true} - ``` \ No newline at end of file + ``` diff --git a/docs/HowTo/Interact/APIs/Using-JSON-RPC-API.md b/docs/HowTo/Interact/APIs/Using-JSON-RPC-API.md index f8a9f13a633..c9e72dfdc4e 100644 --- a/docs/HowTo/Interact/APIs/Using-JSON-RPC-API.md +++ b/docs/HowTo/Interact/APIs/Using-JSON-RPC-API.md @@ -1,41 +1,46 @@ +--- description: How to access the Hyperledger Besu API using JSON-RPC - +--- # JSON-RPC over HTTP and WebSockets -To enable JSON-RPC over HTTP or WebSockets, use the [`--rpc-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled) -and [`--rpc-ws-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-enabled) options. +To enable JSON-RPC over HTTP or WebSockets, use the +[`--rpc-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled) and +[`--rpc-ws-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-enabled) options. {!global/Postman.md!} -## Geth Console +## Geth console -The geth console is a REPL (Read, Evaluate, & Print Loop) Javascript console. Use JSON-RPC APIs supported by geth and -Hyperledger Besu directly in the console. +The geth console is a REPL (Read, Evaluate, & Print Loop) JavaScript console. Use JSON-RPC APIs +supported by geth and Hyperledger Besu directly in the console. -To use the geth console with Besu: +To use the geth console with Besu: -1. Start Besu with the [`--rpc-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled) option. +1. Start Besu with the + [`--rpc-http-enabled`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-enabled) option. +1. Specify which APIs to enable using the + [`--rpc-http-api`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-api) option. +1. Start the geth console specifying the JSON-RPC endpoint: -1. Specify which APIs to enable using the [`--rpc-http-api`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-api) option. - -1. Start the geth console specifying the JSON-RPC endpoint: ```bash geth attach http://localhost:8545 - ``` - -Use the geth console to call [JSON-RPC API methods](../../../Reference/API-Methods.md) that geth and Besu share. + ``` + +Use the geth console to call [JSON-RPC API methods](../../../Reference/API-Methods.md) that geth +and Besu share. + +!!! example -!!! example ```bash eth.syncing ``` - -## JSON-RPC Authentication -[Authentication](Authentication.md) is disabled by default. +## JSON-RPC authentication -## HTTP and WebSocket Requests +Besu disables [Authentication](Authentication.md) by default. + +## HTTP and WebSocket requests ### HTTP @@ -47,7 +52,8 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"web3_clientVersion","params":[], ### WebSockets -To make RPC requests over WebSockets, you can use [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): @@ -55,32 +61,36 @@ First connect to the WebSockets server using `wscat` (you only need to connect o wscat -c ws:// ``` -After the connection is established, the terminal displays a '>' prompt. -Send individual requests as a JSON data package at each prompt: +After you establish a connection, the terminal displays a '>' prompt. Send individual requests as a +JSON data package at each prompt: ```bash {"jsonrpc":"2.0","method":"web3_clientVersion","params":[],"id":53} ``` -!!! 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. +!!! note + + `wscat` does not support headers. [Authentication](Authentication.md) requires you to pass an + authentication token in the request header. To use authentication with WebSockets, you require + an app that supports headers. -## Readiness and Liveness Endpoints +## Readiness and liveness endpoints Besu provides readiness and liveness endpoints to confirm the Besu node status. Both return a -`200 OK` status when ready or live and a `503 Service Unavailable` status if not ready or live. - -By default, the readiness check requires a peer to be connected and the node to be within 2 blocks of the best -known block. If [p2p communication is disabled](../../../Reference/CLI/CLI-Syntax.md#p2p-enabled), -no peers are required. A live node with p2p disabled is always ready. +`200 OK` status when ready or live and a `503 Service Unavailable` status if not ready or live. -Use the query parameters `minPeers` and `maxBlocksBehind` to adjust the number of peers required and number of blocks tolerance. +By default, the readiness check requires a connected peer and the node to be within two blocks of +the best known block. If you have +[disabled p2p communication](../../../Reference/CLI/CLI-Syntax.md#p2p-enabled), you do not need +peers. A live node with p2p disabled is always ready. + +Use the query parameters `minPeers` and `maxBlocksBehind` to adjust the number of peers required +and the number of blocks tolerance. ```bash tab="Readiness Endpoint" http:///readiness ``` - + ```bash tab="curl Request Example" curl -v 'http://localhost:8545/readiness' ``` @@ -89,37 +99,43 @@ curl -v 'http://localhost:8545/readiness' curl -v 'http://localhost:8545/readiness?minPeers=0&maxBlocksBehind=10' ``` -The liveness check requires the JSON RPC server to be up. +The liveness check requires the JSON RPC server to be up. ```bash tab="Liveness Endpoint" http:///liveness ``` - + ```bash tab="curl Request Example" curl -v 'http://localhost:8545/liveness' ``` -## API Methods Enabled by Default +## API methods enabled by default -The `ETH`, `NET`, and `WEB3` API methods are enabled by default. +Besu enables the `ETH`, `NET`, and `WEB3` API methods by default. -Use the [`--rpc-http-api`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-api) or [`--rpc-ws-api`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-api) -options to enable the `ADMIN`, `CLIQUE`, `DEBUG`, `EEA`, `IBFT`, `MINER`, `PERM`, `PLUGINS`, `PRIV`, -and `TXPOOL` API methods. +To enable the `ADMIN`, `CLIQUE`, `DEBUG`, `EEA`, `IBFT`, `MINER`, `PERM`, `PLUGINS`, `PRIV`, and +`TXPOOL` API methods, use the [`--rpc-http-api`](../../../Reference/CLI/CLI-Syntax.md#rpc-http-api) +or [`--rpc-ws-api`](../../../Reference/CLI/CLI-Syntax.md#rpc-ws-api) options. -## 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](../../../Reference/API-Methods.md#eth_gettransactionbyblocknumberandindex), have a block parameter. +When you make requests that might have different results depending on the block accessed, the block +parameter specifies the block. Methods such as +[`eth_getTransactionByBlockNumberAndIndex`](../../../Reference/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](../../../Reference/API-Methods.md#eth_gettransactioncount). +* `blockNumber` : `quantity` - The block number, specified in hexadecimal or decimal. 0 represents + the genesis block. +* `earliest` : `tag` - The earliest (genesis) block. +* `latest` : `tag` - The last block mined. +* `pending` : `tag` - The last block mined plus pending transactions. Use only with + [eth_getTransactionCount](../../../Reference/API-Methods.md#eth_gettransactioncount). !!! note - If [synchronizing in FAST mode](../../../Reference/CLI/CLI-Syntax.md#sync-mode), most historical - world state data is unavailable. Any methods attempting to access unavailable world state data return `null`. \ No newline at end of file + + If [synchronizing in FAST mode](../../../Reference/CLI/CLI-Syntax.md#sync-mode), most + historical world state data is unavailable. Any methods attempting to access unavailable world + state data return `null`. +