From fe3b72cfe69707ea95fd387dce165c54c95db37c Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 25 Oct 2022 16:06:26 +0200 Subject: [PATCH 1/5] doc: proofread user/proxy.rst --- docs/user/proxy.rst | 53 +++++++++++++++++++++++++-------------------- 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/docs/user/proxy.rst b/docs/user/proxy.rst index 3c4909f5edc5..579e3edfc199 100644 --- a/docs/user/proxy.rst +++ b/docs/user/proxy.rst @@ -1,17 +1,16 @@ Proxy mode ---------- -The ``octez-client`` described -:ref:`here ` forwards all RPCs to a node. -This page describes the *proxy* mode, a mode where the client +The ``octez-client``, described in +:ref:`its own tutorial `, forwards all RPCs to a node. +The current page describes the *proxy* mode, a mode where the client performs protocol RPCs locally. For the computations to be correct, -the proxy client requests the data it needs from the node, and uses -this data locally to perform its own computations -(see the :doc:`mockup mode ` for an entirely local mode). +the proxy client only requests the data it needs from the node, and uses +this data locally to perform its own computations. +For an entirely local mode, see the :doc:`mockup mode `. -This mode's purpose is to relieve the node -from some long computations when estimating gas or asking for baking rights -for instance. +The purpose of the proxy mode is to relieve the node +from some long computations, necessary for instance when estimating gas or when asking for baking rights. Executing commands in proxy mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -20,11 +19,12 @@ The CLI interface of the client in proxy mode (the *proxy client* in short) is the same as the default client. To turn proxy mode ON, pass ``--mode proxy`` to ``octez-client``. -Because computations done locally are protocol dependent, the proxy mode does not support all protocols. +Because some computations usually done by the node are protocol-dependent, the proxy mode has to be configured for a specific protocol. +However, the proxy mode does not support all protocols. +Execute ``octez-client list proxy protocols`` to see the supported protocols. It is expected that, at any given time, the proxy mode supports ``Alpha``, the current protocol of Mainnet and the current protocol proposal on Mainnet at the time of release. -In doubt, execute ``octez-client list proxy protocols`` to see the supported protocols. If ``--protocol`` is omitted when calling the proxy client, it tries to match the node's protocol. On the one hand, this is handy when @@ -35,9 +35,9 @@ RPC at **every** call ``octez-client --mode proxy ...`` Examples with the sandbox ~~~~~~~~~~~~~~~~~~~~~~~~~ -In this section, we show examples of usage of the proxy mode when using -the :doc:`sandboxed node `. For convenience we repeat -instructions for the sandboxed mode here, but refer the reader to the +In this section, we show examples of using the proxy mode with +a :doc:`sandboxed node `. For convenience, we repeat +instructions for the sandboxed mode here, but we refer the reader to the sandboxed mode page for further details. In a terminal, start a sandboxed node: @@ -45,7 +45,7 @@ start a sandboxed node: $ ./src/bin_node/octez-sandboxed-node.sh 1 --connections 1 -Leave that terminal running, in another terminal, prepare the appropriate +Leave that terminal running and, in another terminal, prepare the appropriate environment for using the proxy client: :: @@ -56,7 +56,7 @@ Then upgrade the node to protocol alpha: :: - $ tezos-activate-alpha + $ octez-activate-alpha $ octez-client bake for bootstrap1 To avoid warnings being printed in upcoming commands (optional): @@ -82,14 +82,16 @@ You're now ready to use the proxy client. For example, request baking rights: { "level": 3, "delegate": "tz1ddb9NMYHZi5UzPdzTZMYQQZoMub195zgv", "priority": 10, "estimated_time": "2020-07-01T08:47:21Z" } ] -Well that doesn't seem very different from what the default client would return. +Well, that doesn't seem very different from what the default client would return. Indeed, it's the same; that was the point! To see what the proxy client -is doing differently, you may use three debug variables: +is doing differently, you may set up debugging on the following event sections +(see :doc:`./logging`): * ``proxy_rpc_ctxt`` shows whether the proxy client is delegating RPCs - to the node or doing them locally. This is the main debug variable. + to the node or doing them locally. This is the main debug section. * ``proxy_rpc`` shows the RPCs that the proxy client is performing to retrieve - up-to-date data from the node. This debug variable is useful to understand + up-to-date data from the node. + This debug section is useful to understand if the proxy is performing slowly. It might be because it is performing a lot of such RPCs. * ``proxy_context`` shows low-level detail implementations of the client, @@ -130,6 +132,11 @@ And redo the same RPC as before: In this case, the bulk of the computation is done locally. +If you also want to see the data requests to the node, do the following before running your commands:: + + $ export TEZOS_LOG="proxy_rpc_ctxt->debug; alpha.proxy_rpc->debug" + + How to deploy to relieve nodes from some RPCs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -153,7 +160,7 @@ deployment should be done as follows (we suppose there's a single node for simplicity): * Deploy the node as usual -* In front of the node, put multiple HTTP caches (I'm not using the +* In front of the node, put multiple HTTP caches (let's avoid the term proxy here, to disambiguate with the proxy client) that cache the following RPCs: @@ -174,13 +181,13 @@ for simplicity): when it starts performing a computation that would happen on the node with a regular client. - It is safe to cache these three RPCs, because the corresponding data + Note that it is safe to cache these three RPCs, because the corresponding data is immutable (if it's there it won't change in the future). Regarding clients, either: * Use proxy clients -* Or intercept request of regular clients, and honor them by spawning +* Or intercept requests of regular clients, and honor them by spawning proxy clients on the fly, in front of the setup described in the previous list. -- GitLab From 59e750ce95feac9ed6e57aa3aa1a210ca77bc08a Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 17 Nov 2022 16:55:18 +0100 Subject: [PATCH 2/5] doc: update logs with the new behaviour of the proxy --- docs/user/proxy.rst | 51 +++++++++++++++++++++++++++------------------ 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/docs/user/proxy.rst b/docs/user/proxy.rst index 579e3edfc199..a909ae8a4093 100644 --- a/docs/user/proxy.rst +++ b/docs/user/proxy.rst @@ -71,16 +71,21 @@ You're now ready to use the proxy client. For example, request baking rights: $ octez-client --mode proxy rpc get /chains/main/blocks/head/helpers/baking_rights protocol of proxy unspecified, using the node's protocol: ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK - [ { "level": 3, "delegate": "tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx", - "priority": 0, "estimated_time": "2020-07-01T08:47:21Z" }, - { "level": 3, "delegate": "tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv", - "priority": 2, "estimated_time": "2020-07-01T08:47:21Z" }, - { "level": 3, "delegate": "tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU", - "priority": 5, "estimated_time": "2020-07-01T08:47:21Z" }, + [ { "level": 3, "delegate": "tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv", + "round": 0, "estimated_time": "2022-11-17T14:20:17Z", + "consensus_key": "tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv" }, { "level": 3, "delegate": "tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN", - "priority": 7, "estimated_time": "2020-07-01T08:47:21Z" }, + "round": 1, "estimated_time": "2022-11-17T14:20:18Z", + "consensus_key": "tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" }, { "level": 3, "delegate": "tz1ddb9NMYHZi5UzPdzTZMYQQZoMub195zgv", - "priority": 10, "estimated_time": "2020-07-01T08:47:21Z" } ] + "round": 2, "estimated_time": "2022-11-17T14:20:20Z", + "consensus_key": "tz1ddb9NMYHZi5UzPdzTZMYQQZoMub195zgv" }, + { "level": 3, "delegate": "tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU", + "round": 3, "estimated_time": "2022-11-17T14:20:23Z", + "consensus_key": "tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU" }, + { "level": 3, "delegate": "tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx", + "round": 4, "estimated_time": "2022-11-17T14:20:27Z", + "consensus_key": "tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" } ] Well, that doesn't seem very different from what the default client would return. Indeed, it's the same; that was the point! To see what the proxy client @@ -115,20 +120,26 @@ And redo the same RPC as before: :: $ proxy-client rpc get /chains/main/blocks/head/helpers/baking_rights - Aug 18 12:05:29.624 - proxy_rpc_ctxt: Delegating call_service GET version to http - Aug 18 12:05:29.625 - proxy_rpc_ctxt: Delegating call_service GET chains//blocks//protocols to http - Aug 18 12:05:29.629 - proxy_rpc_ctxt: Done call_service GET describe/ locally - Aug 18 12:05:29.841 - proxy_rpc_ctxt: Done generic_json_call GET /chains/main/blocks/head/helpers/baking_rights locally - [ { "level": 3, "delegate": "tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx", - "priority": 0, "estimated_time": "2020-08-18T09:58:20Z" }, - { "level": 3, "delegate": "tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv", - "priority ": 2, "estimated_time": "2020-08-18T09:58:20Z" }, - { "level": 3, "delegate": "tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU", - "priority": 5, "estimated_time": "2020-08-18T09:58:20Z" }, + Nov 17 15:21:19.959 - proxy_rpc_ctxt: delegating to http: GET call_service version + Nov 17 15:21:19.967 - proxy_rpc_ctxt: locally done: GET call_service chains//blocks//protocols + Nov 17 15:21:19.969 - proxy_rpc_ctxt: locally done: GET call_service describe/ + Nov 17 15:21:19.976 - proxy_rpc_ctxt: locally done generic media type call: GET + Nov 17 15:21:19.976 - proxy_rpc_ctxt: /chains/main/blocks/head/helpers/baking_rights + [ { "level": 3, "delegate": "tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv", + "round": 0, "estimated_time": "2022-11-17T14:20:17Z", + "consensus_key": "tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv" }, { "level": 3, "delegate": "tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN", - "priority": 7, "estimated_time": "2020-08-18T09:58:20Z" }, + "round": 1, "estimated_time": "2022-11-17T14:20:18Z", + "consensus_key": "tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN" }, { "level": 3, "delegate": "tz1ddb9NMYHZi5UzPdzTZMYQQZoMub195zgv", - "priority": 10, "estimated_time": "2020-08-18T09:58:20Z" } ] + "round": 2, "estimated_time": "2022-11-17T14:20:20Z", + "consensus_key": "tz1ddb9NMYHZi5UzPdzTZMYQQZoMub195zgv" }, + { "level": 3, "delegate": "tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU", + "round": 3, "estimated_time": "2022-11-17T14:20:23Z", + "consensus_key": "tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU" }, + { "level": 3, "delegate": "tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx", + "round": 4, "estimated_time": "2022-11-17T14:20:27Z", + "consensus_key": "tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx" } ] In this case, the bulk of the computation is done locally. -- GitLab From 7413760e70ea2d546dbb31d330473c78a5532f65 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 21 Nov 2022 14:36:30 +0100 Subject: [PATCH 3/5] doc: remove advice to intercept RPC ../protocols --- docs/user/proxy.rst | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/docs/user/proxy.rst b/docs/user/proxy.rst index a909ae8a4093..a490d5e19402 100644 --- a/docs/user/proxy.rst +++ b/docs/user/proxy.rst @@ -9,8 +9,9 @@ the proxy client only requests the data it needs from the node, and uses this data locally to perform its own computations. For an entirely local mode, see the :doc:`mockup mode `. -The purpose of the proxy mode is to relieve the node -from some long computations, necessary for instance when estimating gas or when asking for baking rights. +Estimating gas required by a smart contract call or asking for baking rights +are typical examples of potentially long computation the proxy mode relieves +the node of. Executing commands in proxy mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -70,7 +71,6 @@ You're now ready to use the proxy client. For example, request baking rights: :: $ octez-client --mode proxy rpc get /chains/main/blocks/head/helpers/baking_rights - protocol of proxy unspecified, using the node's protocol: ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK [ { "level": 3, "delegate": "tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv", "round": 0, "estimated_time": "2022-11-17T14:20:17Z", "consensus_key": "tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv" }, @@ -99,8 +99,6 @@ is doing differently, you may set up debugging on the following event sections This debug section is useful to understand if the proxy is performing slowly. It might be because it is performing a lot of such RPCs. -* ``proxy_context`` shows low-level detail implementations of the client, - you likely do not need it. For convenience, let's define an alias before continuing, to save keystrokes and the ``protocol of proxy unspecified`` warning: @@ -145,7 +143,7 @@ In this case, the bulk of the computation is done locally. If you also want to see the data requests to the node, do the following before running your commands:: - $ export TEZOS_LOG="proxy_rpc_ctxt->debug; alpha.proxy_rpc->debug" + $ export TEZOS_LOG="proxy_rpc_ctxt->debug; proxy_rpc->debug" How to deploy to relieve nodes from some RPCs @@ -182,17 +180,12 @@ for simplicity): Intercepting ``../raw/bytes`` is required because proxy clients call it a lot, as described above. - Intercepting ``../protocols`` is recommended, because the - proxy client calls this RPC when it starts, to check the protocol - it uses matches the node's protocol - (recall that proxy clients are protocol-specific). - - Finally, intercepting ``../header`` is recommended, because the proxy client + Intercepting ``../header`` is recommended, because the proxy client calls this RPC when it starts honoring a request locally, i.e. when it starts performing a computation that would happen on the node with a regular client. - Note that it is safe to cache these three RPCs, because the corresponding data + Note that it is safe to cache these RPCs, because the corresponding data is immutable (if it's there it won't change in the future). Regarding clients, either: -- GitLab From 6cb6c1699989af0da316b11cb754d58d4c89ba85 Mon Sep 17 00:00:00 2001 From: Pierre Boutillier Date: Mon, 21 Nov 2022 13:54:15 +0000 Subject: [PATCH 4/5] doc: remove advice to specify --protocol --- docs/user/proxy.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/user/proxy.rst b/docs/user/proxy.rst index a490d5e19402..c7d6caef6999 100644 --- a/docs/user/proxy.rst +++ b/docs/user/proxy.rst @@ -27,12 +27,6 @@ It is expected that, at any given time, the proxy mode supports ``Alpha``, the current protocol of Mainnet and the current protocol proposal on Mainnet at the time of release. -If ``--protocol`` is omitted when calling the proxy client, it -tries to match the node's protocol. On the one hand, this is handy when -testing. On the other hand, in a production environment, it is recommended -to specify ``--protocol`` if the protocol is known, to avoid an extra -RPC at **every** call ``octez-client --mode proxy ...`` - Examples with the sandbox ~~~~~~~~~~~~~~~~~~~~~~~~~ -- GitLab From 5b7631c7c0adfeaf68bbfd6f8ceb38ea4a849244 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 29 Nov 2022 15:00:07 +0100 Subject: [PATCH 5/5] doc: rephrase proxy mode intro for more generality --- docs/user/proxy.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/user/proxy.rst b/docs/user/proxy.rst index c7d6caef6999..a6afe34f7ae3 100644 --- a/docs/user/proxy.rst +++ b/docs/user/proxy.rst @@ -2,30 +2,32 @@ Proxy mode ---------- The ``octez-client``, described in -:ref:`its own tutorial `, forwards all RPCs to a node. -The current page describes the *proxy* mode, a mode where the client -performs protocol RPCs locally. For the computations to be correct, -the proxy client only requests the data it needs from the node, and uses -this data locally to perform its own computations. -For an entirely local mode, see the :doc:`mockup mode `. +:ref:`a dedicated tutorial `, heavily relies on node RPCs to implement its features. Thus, when a client need to perform some computation which cannot be done entirely locally, but which is implemented by a node RPC, it will simply call the corresponding RPC. -Estimating gas required by a smart contract call or asking for baking rights -are typical examples of potentially long computation the proxy mode relieves -the node of. +The current page describes the *proxy* mode, an execution mode where the client +avoids some RPC calls to the node, especially computation-intensive RPCs. +Thus, for computations that cannot be done entirely locally, +the proxy client only requests the data it needs from the node using RPCs (that are not computation-intensive), and uses +this data locally to perform computations by itself, whenever possible. + +For an entirely local mode, which never calls node RPCs, see the :doc:`mockup mode `. + +Typical examples of potentially long computations the proxy mode relieves +the node of include estimating gas required by a smart contract call or asking for baking rights. Executing commands in proxy mode ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The CLI interface of the client in proxy mode (the *proxy client* in short) is the same as the default client. To turn proxy mode ON, -pass ``--mode proxy`` to ``octez-client``. +simply pass option ``--mode proxy`` to ``octez-client``. Because some computations usually done by the node are protocol-dependent, the proxy mode has to be configured for a specific protocol. However, the proxy mode does not support all protocols. Execute ``octez-client list proxy protocols`` to see the supported protocols. It is expected that, at any given time, the proxy mode supports ``Alpha``, -the current protocol of Mainnet and the current protocol proposal on Mainnet -at the time of release. +the current protocol of Mainnet, and the current protocol proposal on Mainnet +at the time of release, if any. Examples with the sandbox ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -139,7 +141,6 @@ If you also want to see the data requests to the node, do the following before r $ export TEZOS_LOG="proxy_rpc_ctxt->debug; proxy_rpc->debug" - How to deploy to relieve nodes from some RPCs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- GitLab