Qlight docs

docs/concepts/qlight-node.md

@@ -0,0 +1,55 @@
+# GoQuorum qlight node
+
+A standard GoQuorum node will process all blocks and associated transactions; It also requires a local Private Transaction Manager to handle private data.
+This can require significant resources and may make it more difficult to scale networks.
+Additionally, since the node processes all transactions, privacy concerns could be raised by business partners.
+
+A Quorum qlight node can be deployed to reduce the amount of data that is available and that is shared by the full nodes with external parties.
+
+You can also use a qlight node for anything that could thrash the API, such as monitoring, debugging, state querying etc. This can alleviate any concerns around impact to the performance of a main node, or having to deal with network throttling due to third party network limits, or multiple clients all hitting the same main node.
+
+Qlight nodes have specific differences from standard quorum nodes, they:
+
+- 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.
+- Only receive blocks from the server node, processing them locally to build up the public and private state.
+- Do not require a transaction manager. Instead, private data is sent directly by the server node via the qlight P2P protocol.
+- 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.
+- Have the same RPC APIs that are required for dApps, delegating calls to the server node if needed.
+- Do not partake in the consensus mechanism.
+
+If the qlight node is halted, then on restart it will resync with any blocks that were missed whilst it was not running.
+
+It is worth noting that the server node would normally be set up as a multi-tenant (MT) 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.
+
+## Terminology
+
+- "qlight client": This refers to the qlight node.
+- "qlight server": This 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
+
+A peer-to-peer protocol is implemented for communication between the qlight client and server.
+
+### 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 (PTM), but relies on the qlight server to supply private data.
+This is implemented by means of a local cache which simulates a local PTM. Therefore private transactions can be executed locally, with the private data being fetched from the PTM 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.

docs/configure-and-manage/manage/qlight-node.md

@@ -0,0 +1,71 @@
+# Setting up a GoQuorum qlight node
+
+A qlight client node requires a full node configured to act as a qlight server.
+The server node is usually set up to support Multiple Private States (MPS), with the qlight client set up to use a Private State Identifier (PSI) which is managed by the server node.
+
+## Configure qlight client
+
+The qlight client is configured 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.
+
+Additionally, 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.
+
+## Configure server node
+
+The qlight server is configured 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).
+The network mask is specified on the qlight server using the command line option `--qlight.server.p2p.netrestrict`.
+
+### File based permissioning
+
+File based permissioning allows qlight clients to be checked against a permissioned list and a disallowed list.
+It is enabled on the server node using `--qlight.server.p2p.permissioning`.
+
+The default files are `permissioned-nodes.json` and `disallowed-nodes.json`.
+However, a file prefix can be specified using `--qlight.server.p2p.permissioning.prefix`, in which case the filename will be: 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) an access token must be provided to communicate to the qlight server. How the token is obtained and refreshed is down to the node operator.
+
+To enable auth tokens in the qlight client one must use the flag `--qlight.client.token.enabled`.
+
+Once enabled one may specify an initial value using the flag `--qlight.client.token.value <token>`.
+
+In addition to the above a refresh mechanism for the token should be specified using the flag `--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
+
+An encryption layer can be used on the qlight client-server communication.
+This is configured 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.

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