diff --git a/docs/concepts/qlight-node.md b/docs/concepts/qlight-node.md new file mode 100644 index 00000000..4157acba --- /dev/null +++ b/docs/concepts/qlight-node.md @@ -0,0 +1,73 @@ +# GoQuorum qlight node + +A qlight node is a lightweight replica of a full node that proxies transactions to the full node. +You can deploy a qlight node to reduce the amount of data that is shared with external parties by the full nodes. + +The qlight node can be used to: + +- Avoid impacting main nodes which are processing transactions with anything that could thrash the API (such as monitoring, state querying, or other intensive processes). +- Prevent security concerns where the main node is handling multiple private parties [(multi-tenancy)](multi-tenancy.md). + The qlight client deals with a private state for one party only, and only that user has access to the qlight client. + +## Qlight nodes and standard nodes + +A standard GoQuorum node processes all blocks and associated transactions. +It also requires a local [private transaction manager](privacy/index.md#private-transaction-manager) to handle private data. +This can require significant resources and can make it more difficult to scale networks. +Additionally, since the node processes all transactions, privacy concerns could be raised by business partners. + +Using a qlight node for process-intensive tasks can help lessen impact to the performance of a main node. +Qlight nodes help prevent network throttling due to third party network limits, +or multiple clients all hitting the same main node. + +Qlight nodes differ from standard quorum nodes in the following ways: + +- Qlight nodes depend on a server full node for receiving data and will only connect to the server node. + There is no communication with any other node. + +- They only receive blocks from the server node, processing them locally to build up the public and private state. + +- They do not require a transaction manager. Instead, private data is sent directly by the server node via the qlight P2P protocol. + +- They act as a proxy for locally submitted transactions, performing minimal validation. + API calls like `SendTansaction`/`SendRawTransaction`/`StoreRaw` are forwarded to the server node for processing. + +- They use the same RPC APIs that are required for dapps, delegating calls to the server node if needed. + +- They do not partake in the consensus mechanism. + +## Client and server + +- *qlight client* refers to the qlight node. + +- *qlight server* refers to a full node that is configured to supply data to the qlight client. + It also handles API requests that are delegated from the qlight client. + +## Architecture + +![Qlight](../images/qlight_diagram_1.jpeg) + +## Communication protocol + +The qlight client and server communicate through a peer-to-peer protocol. + +### Security + +A number of security features are available for the qlight client-server connection: + +- Native transport layer security (TLS): this can be used to encrypt communications and ensure the security of private transaction data. +- Network restriction: restricts communication to specified IP networks (CIDR masks). +- File based permissioning: allows qlight peers to be checked against a permissioned list and a disallowed list. +- Enterprise authorization protocol integration: this allows qlight clients to be authenticated using an OAuth2 server. + +## Private transaction manager cache + +The qlight client does not have a local [private transaction manager](../concepts/privacy/index.md#private-transaction-manager), +but relies on the qlight server to supply private data. +This is implemented by means of a local cache which simulates a local private transaction manager. +Therefore, private transactions can be executed locally, with the private data being fetched from the private transaction manager cache. + +## New API methods (on qlight server) + +- `admin.qnodeInfo`: Returns details of the qlight configuration. +- `admin.qpeers`: Returns details of the qlight clients that are connected. diff --git a/docs/configure-and-manage/manage/qlight-node.md b/docs/configure-and-manage/manage/qlight-node.md new file mode 100644 index 00000000..a4da8927 --- /dev/null +++ b/docs/configure-and-manage/manage/qlight-node.md @@ -0,0 +1,82 @@ +# Using a GoQuorum qlight node + +A [qlight client node](../../concepts/qlight-node.md) requires a full node configured to act as a qlight server. +The server node is usually set up to support [multiple private states](../../concepts/multi-tenancy.md#multiple-private-states) +(MPS), with the qlight client set up to use a [private state identifier](../../concepts/multi-tenancy.md#private-state-identifier) +(PSI) which is managed by the server node. + +!!! note + + A server node is normally be set up as a multi-tenant node with Multiple Private States (MPS). + However this is not essential, for example when setting up a qlight client for the purpose of offloading processing from a full node. + +## Configure qlight client + +Configure the qlight client using the following command line options: + +- `--qlight.client`: This marks the node as a qlight client. +- `--qlight.client.psi`: This specifies the PSI which this client will support (default = "private"). +- `--qlight.client.serverNode`: The Node ID of the server node. +- `--qlight.client.serverNodeRPC`: The RPC URL of the server node. + +If the server node has the RPC API secured using TLS, then the qlight client requires the following: + +- `--qlight.client.rpc.tls`: Use TLS when forwarding RPC API calls. +- `--qlight.client.rpc.tls.insecureskipverify`: Skip TLS verification. +- `--qlight.client.rpc.tls.cacert`: The qlight client certificate authority. +- `--qlight.client.rpc.tls.cert`: The qlight client certificate. +- `--qlight.client.rpc.tls.key`: The qlight client certificate private key. + +If the qlight client node is halted, on restart it resyncs with any blocks that were missed when it was not running. + +## Configure server node + +Configure the qlight server using the following command line options: + +- `--qlight.server`: This marks the node as a qlight server. +- `--qlight.server.p2p.port`: The RPC listening port. +- `--qlight.server.p2p.maxpeers`: The maximum number of qlight clients that are supported. + +### Network IP restriction + +This restricts communication to specified IP networks (CIDR masks). +Specify the network mask on the qlight server using `--qlight.server.p2p.netrestrict`. + +### File based permissioning + +File based permissioning allows qlight clients to be checked against a permissioned list and a disallowed list. +Enable file based permissioning on the server node using `--qlight.server.p2p.permissioning`. + +The default files are `permissioned-nodes.json` and `disallowed-nodes.json`. +However, you can specify a file prefix using `--qlight.server.p2p.permissioning.prefix`, in which case the filename is: the prefix, followed by a hyphen, followed by the default file name. + +## Using the enterprise authorization protocol integration + +This leverages the security model described under [JSON-RPC security](json-rpc-api-security.md#enterprise-authorization-protocol-integration) to only allow authenticated clients to connect to the server. + +When using [JSON-RPC security](json-rpc-api-security.md#enterprise-authorization-protocol-integration) +you must provide an access token to communicate to the qlight server. + +Enable auth tokens in the qlight client using `--qlight.client.token.enabled`. + +Once enabled, specify an initial value using `--qlight.client.token.value `. + +Specify a refresh mechanism for the token using `--qlight.client.token.management`. +The valid values are: + +- `none` - the token is not refreshed (this mechanism is for development/testing purposes only). +- `external` - the refreshed token must be updated in the running qlight client process by invoking the `qlight.setCurrentToken` RPC API. +- `client-security-plugin` (default) - the client security plugin is used to periodically refresh the access token. Please see the client-security-plugin documentation for further details. + +## Native transport layer security (TLS) for P2P communication + +You can add an encryption layer on the qlight client-server communication. +Configure the encryption layer using the following options: + +- `--qlight.tls`: Enable TLS on the P2P connection. +- `--qlight.tls.cert`: The certificate file to use. +- `--qlight.tls.key`: The key file to use. +- `--qlight.tls.clientcacerts`: The certificate authorities file to use for validating the connection (server configuration parameter). +- `--qlight.tls.cacerts`: The certificate authorities file to use for validating the connection (client configuration parameter). +- `--qlight.tls.clientauth`: The way the client is authenticated. Possible values: 0=NoClientCert(default) 1=RequestClientCert 2=RequireAnyClientCert 3=VerifyClientCertIfGiven 4=RequireAndVerifyClientCert (default: 0). +- `--qlight.tls.ciphersuites`: The cipher suites to use for the connection. diff --git a/docs/images/qlight_diagram_1.jpeg b/docs/images/qlight_diagram_1.jpeg new file mode 100644 index 00000000..28b082d1 Binary files /dev/null and b/docs/images/qlight_diagram_1.jpeg differ diff --git a/mkdocs.navigation.yml b/mkdocs.navigation.yml index 1854bd1e..a3ec6233 100644 --- a/mkdocs.navigation.yml +++ b/mkdocs.navigation.yml @@ -23,7 +23,7 @@ nav: - Docker and Docker Compose: deploy/install/docker-and-compose.md - Kubernetes: deploy/install/kubernetes.md - Upgrade GoQuorum: deploy/upgrade/migration.md - - Quorum deployment examples: deploy/deployment-overview.md + - GoQuorum deployment examples: deploy/deployment-overview.md - Configure and manage: - Configure: - Consensus protocols: @@ -51,16 +51,17 @@ nav: - Multi-tenancy: - Use multi-tenancy: configure-and-manage/manage/multi-tenancy/multi-tenancy.md - Multiple private states migration: configure-and-manage/manage/multi-tenancy/migration.md + - GoQuorum qlight client: configure-and-manage/manage/qlight-node.md - Include revert reason: configure-and-manage/manage/revert-reason.md - GraphQL: configure-and-manage/manage/graphql.md - Backup and restore: configure-and-manage/manage/import-export.md - Monitor nodes: - Use metrics: configure-and-manage/monitor/metrics.md - Use Elastic Stack: configure-and-manage/monitor/elastic-stack.md - - Use Quorum Hibernate: configure-and-manage/monitor/quorum-hibernate.md + - Use GoQuorum Hibernate: configure-and-manage/monitor/quorum-hibernate.md - Use Splunk: configure-and-manage/monitor/splunk.md - Use Cakeshop: configure-and-manage/monitor/cakeshop.md - - Use Quorum Reporting: configure-and-manage/monitor/quorum-reporting.md + - Use GoQuorum Reporting: configure-and-manage/monitor/quorum-reporting.md - Develop applications: - Connect to a node: develop/connecting-to-a-node.md - JSON-RPC APIs: develop/json-rpc-apis.md @@ -92,10 +93,11 @@ nav: - Plugins: concepts/plugins.md - Security framework: concepts/security-framework.md - Multi-tenancy: concepts/multi-tenancy.md - - Quorum profiling: concepts/profiling.md + - GoQuorum qlight client: concepts/qlight-node.md + - GoQuorum profiling: concepts/profiling.md - Network and chain ID: concepts/network-and-chain-id.md - Try the tutorials: - - Quorum Developer Quickstart: + - GoQuorum Developer Quickstart: - tutorials/quorum-dev-quickstart/index.md - Use the quickstart: tutorials/quorum-dev-quickstart/using-the-quickstart.md - Remix: tutorials/quorum-dev-quickstart/remix.md