diff --git a/docs/user/proxy.rst b/docs/user/proxy.rst index 3c4909f5edc538537441d4d31a13bc4b2c51e928..a6afe34f7ae3ea57abbf9dc724b841ecf9993909 100644 --- a/docs/user/proxy.rst +++ b/docs/user/proxy.rst @@ -1,43 +1,40 @@ 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 -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). - -This mode's purpose is to relieve the node -from some long computations when estimating gas or asking for baking rights -for instance. +The ``octez-client``, described in +: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. + +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 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 -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 ...`` +the current protocol of Mainnet, and the current protocol proposal on Mainnet +at the time of release, if any. 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 +42,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 +53,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): @@ -70,30 +67,34 @@ 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. +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, - 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: @@ -113,23 +114,33 @@ 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. +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; proxy_rpc->debug" + How to deploy to relieve nodes from some RPCs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -153,7 +164,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: @@ -164,23 +175,18 @@ 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. - 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: * 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.