diff --git a/docs/009/glossary.rst b/docs/009/glossary.rst index df1e907acc1f1e306e14802292b3fd2af72a0605..7a62950f1dbe98ce7c79cdbd95f7043cf06b814b 100644 --- a/docs/009/glossary.rst +++ b/docs/009/glossary.rst @@ -10,8 +10,8 @@ Tezos .. include:: ../shell/glossary.rst.h -Protocol Alpha --------------- +Protocol +-------- _`Accuser` When a node_ attempts to inject several incompatible blocks (or when it tries @@ -25,7 +25,7 @@ _`Accuser` separate binary. _`Account` - An account is a unique identifier within protocol Alpha. There are different + An account is a unique identifier within the protocol. There are different kinds of accounts (see `Originated account`_ and `Implicit account`_). In the Context_, each account is associated with a balance (an amount of @@ -118,7 +118,7 @@ Michelson The built-in language used by a `smart contract`_. _`Operations` - In protocol Alpha, the main operations are transactions (to transfer funds + The main operations in the protocol are transactions (to transfer funds or to execute smart contracts), accusations, activations, delegations, endorsements and originations. diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index 74dd7c33f6bb15a582a56c2aa45ff0db5eae50e9..230e96b14635ad203b704ef367cbb3d53e4565b9 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -174,6 +174,8 @@ While working on your branch to prepare a Merge Request, make sure you respect t - If you add new functions to an interface, don’t forget to document the function in the interface (in the corresponding .mli file; or, if there is no .mli file, directly in the .ml file) +- If you add a new RPC endpoint or modify an existing one, be sure to take + into account the impact on :ref:`RPC security `. - If you modify the user API (e.g. add or change a configuration parameter or a command-line option), update the corresponding documentation. In particular, for configuration parameters of the Tezos node, update the node diff --git a/docs/developer/gadt.rst b/docs/developer/gadt.rst index 1de111caa0b0f5127d86d6cb078b226e194f6911..836830d516ec666181b59f7227ed642a7df71ea4 100644 --- a/docs/developer/gadt.rst +++ b/docs/developer/gadt.rst @@ -1,3 +1,4 @@ +======================================== Generalized Algebraic Data Types (GADTs) ======================================== diff --git a/docs/developer/guidelines.rst b/docs/developer/guidelines.rst index ea89add050e711efbdc4c285a436daf90d2b3a11..23b6742ade6483a67caed474d02a28b3d99162e6 100644 --- a/docs/developer/guidelines.rst +++ b/docs/developer/guidelines.rst @@ -319,6 +319,8 @@ The ``Lwtreslib`` and the ``Error_monad`` libraries provide functions that can help you follow these guidelines. Notably, ``traces`` allow callers to contextualise the errors produced by its callees. +.. _rpc_security: + RPC security ------------ @@ -331,11 +333,10 @@ configuration or debugging purposes or to facilitate development of smart contracts. In order to mitigate risks related to exposing these endpoints, Access Control -Lists (ACL for short) were introduced to limit the scope of API exposed to +Lists (ACL for short) were introduced to limit the scope of the API exposed to public networks (see also :ref:`configure_rpc`). While node administrators are -free to configure these ACLs however they like, there is the default ACL -hard-coded in ``src/lib_rpc_http/RPC_server.ml``, which lists all the endpoints -that are **exposed by default**. +free to configure these ACLs however they like, there is :ref:`the default ACL +`, which lists all the endpoints that are **exposed by default**. When adding a new RPC endpoint, please consider whether or not there is a reason to call it over a public network. If the answer is yes, you should probably diff --git a/docs/developer/protocol_environment.rst b/docs/developer/protocol_environment.rst index f986f1ff91c9bbeeed4dc7113e2986ee7ea26755..5597879b5d2fdd104b878bd00e7b4227a9794af9 100644 --- a/docs/developer/protocol_environment.rst +++ b/docs/developer/protocol_environment.rst @@ -45,7 +45,7 @@ Here is a quick description of each file in this environment, all located under Environment versions -==================== +-------------------- The environment interfaces are frozen, providing forever an immutable interface to the protocol. And so when a protocol needs new functions, types, or values, diff --git a/docs/introduction/howtorun.rst b/docs/introduction/howtorun.rst index 4f2a3caa7653549c5f8323c27b46deb0367924c8..9d4692065b06f20e395871a90731aad09eb0a67a 100644 --- a/docs/introduction/howtorun.rst +++ b/docs/introduction/howtorun.rst @@ -12,6 +12,9 @@ The second way allows to participate more actively in the protocol, by baking bl To learn more about the protocol refer to :doc:`this page <../active/proof_of_stake>`. +No matter how you decide to run Tezos, your node must have an accurate time source and be properly synchronized to it, e.g. by configuring an NTP daemon. +This is especially important for bakers, as baking nodes desynchronized from the correct time of day have caused operational problems in the past by "baking in the future". + .. _delegating_coins: Delegating your coins @@ -105,9 +108,8 @@ When a delegator spends their tokens, the delegated balance of their delegate de If a delegate runs out of funds to deposit it won't be able to bake or endorse. Other than being a missed opportunity for them, this has also negative consequences on the network. -Missing baking slots slows the network, as it is necessary to wait for one -minute for the baker at priority 2 to bake, while missing endorsements -reduce the fitness of the chain, making it more susceptible to forks. +Missing baking or endorsing slots slows down the network, as it is necessary to wait some time for the baker at the next priority to bake, and also some other time for each missed endorsing slot. +Besides, missed endorsements also makes the chain more susceptible to forks. Running out of funds can happen if a delegate is *over-delegated*, that is if the amount of rolls it was delegate is disproportionate with respect to its available funds. @@ -193,9 +195,7 @@ won't miss any opportunity we should have around ~3kꜩ for deposits, on the other hand, the expected returns will probably be around ~10ꜩ per cycle. After ``preserved_cycles``, not only does the delegate take back control of -its frozen deposits, but it also receives the rewards for its hard work -which amount to 16ꜩ to bake a block and ``2ꜩ / `` for -endorsing a block. +its frozen deposits, but it also receives its rewards for baking and endorsing. Additionally, a baker also receives the fees of the operations it included in its blocks. While fees are unfrozen after ``preserved_cycles`` like deposits and diff --git a/docs/introduction/howtouse.rst b/docs/introduction/howtouse.rst index 5ddc1f715d726434951a97ce8b2c2a8b51650c92..ed0308c54114cc6df85b9d1a05f662006aadf5f4 100644 --- a/docs/introduction/howtouse.rst +++ b/docs/introduction/howtouse.rst @@ -17,7 +17,7 @@ After a successful compilation, you should have the following binaries: - ``tezos-node``: the tezos daemon itself (see `Node`_); - ``tezos-client``: a command-line client and basic wallet (see `Client`_); -- ``tezos-admin-client``: administration tool for the node; +- ``tezos-admin-client``: administration tool for the node (see :ref:`tezos-admin-client`); - ``tezos-{baker,endorser,accuser}-*``: daemons to bake, endorse and accuse on the Tezos network (see :doc:`howtorun`); - ``tezos-validator``: a daemon for validating and applying operations in blocks (see `Validator`_) diff --git a/docs/introduction/test_networks.rst b/docs/introduction/test_networks.rst index 775818c8afcdfd3918f0503adcb46c721f8e1aca..c1d599d5429ee722951c463844f8fe58b5e6c030 100644 --- a/docs/introduction/test_networks.rst +++ b/docs/introduction/test_networks.rst @@ -2,6 +2,7 @@ .. _test-networks: +============= Test Networks ============= @@ -23,7 +24,7 @@ a new test network is spawned. This also makes synchronization much faster than with a long-lived network. Get Free Funds --------------- +============== Test networks have a list of built-in accounts with some funds. You can obtain the key to these accounts from a faucet to claim the funds. @@ -31,7 +32,7 @@ All networks share the same faucet: https://faucet.tzalpha.net/. The keys obtained from this faucet can be used in all test networks. Granadanet ----------- +========== - Built-in network alias: ``granadanet`` (see :ref:`builtin_networks`) @@ -57,7 +58,7 @@ This results in a faster chain than Mainnet: - a voting period lasts half a cycle and should thus last about 8 hours. Florencenet ------------ +=========== - Built-in network alias: ``florencenet`` (see :ref:`builtin_networks`) @@ -84,7 +85,7 @@ This results in a faster chain than Mainnet: - a voting period lasts half a cycle and should thus last about 8 hours. Future Networks ---------------- +=============== At some point, there will be a proposal for a successor to the current protocol (let's call this new protocol P). After P is injected, a new test network diff --git a/docs/user/node-configuration.rst b/docs/user/node-configuration.rst index 08fb67fb3c1103ae1104fd9fbe4a177ba2acf380..78da0ad2ae8882f18dc3686ef8fc9141f3fd2aad 100644 --- a/docs/user/node-configuration.rst +++ b/docs/user/node-configuration.rst @@ -128,7 +128,7 @@ with other characters in a path segment). A ``**`` stands for any possible path suffix. .. warning:: - The policy is always searched from the beginning of the list to the end and + Rules are always searched from the beginning of the list to the end and the first matching address is returned. Therefore if one wants to put one rule on a specific port on a given host and another rule for all other ports on the same host, then more specific rules should always be written *first* @@ -140,9 +140,10 @@ Default ACL for RPC ------------------- The default ACL for RPC depends on the listening address that the node is using. + If the listening address resolves to the loopback network interface, then full -access to all endpoints is granted. Note, that it does not matter, from which -machine the client is really making his request, but only what the listening +access to all endpoints is granted. Note that it does not matter from which +machine the client is really making a request, but only what the listening address is. This guarantees that insecure endpoints can only be accessed from ``localhost``. @@ -158,14 +159,15 @@ relaxed or tightened by modifying the configuration file. It's worth noting that this default policy among other things disallows baking and endorsing by bakers and endorsers running on remote servers. -This is the default ACL policy for the node (remember to replace +The following is the default ACL policy for the node, +hard-coded in :src:`src/lib_rpc_http/RPC_server.ml` (remember to replace ``any.public.address`` with an IP address or a domain name that you'll be actually listening on): .. literalinclude:: default-acl.json The endpoints specifically required for baking can be found in -``vendors/flextesa-lib/tezos-node.ml``. +:src:`vendors/flextesa-lib/tezos_node.ml`. .. _configure_p2p: diff --git a/src/proto_001_PtCJ7pwo/lib_client_commands/client_proto_context_commands.ml b/src/proto_001_PtCJ7pwo/lib_client_commands/client_proto_context_commands.ml index abc9b7b6b15954ca0208f0a7245430872ea42d1d..3abbd9bc3fff1840abd74c9bf29bf98a46456f75 100644 --- a/src/proto_001_PtCJ7pwo/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_001_PtCJ7pwo/lib_client_commands/client_proto_context_commands.ml @@ -186,7 +186,7 @@ let commands () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Alpha_client_context.full) -> diff --git a/src/proto_002_PsYLVpVv/lib_client_commands/client_proto_context_commands.ml b/src/proto_002_PsYLVpVv/lib_client_commands/client_proto_context_commands.ml index e7ac3984957a58f40dc1369a5cfa0598f267bb26..ab40a32d9d26e7020708e7bcee78ae6c712d9f16 100644 --- a/src/proto_002_PsYLVpVv/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_002_PsYLVpVv/lib_client_commands/client_proto_context_commands.ml @@ -249,7 +249,7 @@ let commands () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Alpha_client_context.full) -> diff --git a/src/proto_003_PsddFKi3/lib_client_commands/client_proto_context_commands.ml b/src/proto_003_PsddFKi3/lib_client_commands/client_proto_context_commands.ml index 62ff2c4c08f0030ab6ea6e4e2488be81a8881a91..60416b4beb21acde7260a44ee2b62618317b3afe 100644 --- a/src/proto_003_PsddFKi3/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_003_PsddFKi3/lib_client_commands/client_proto_context_commands.ml @@ -255,7 +255,7 @@ let commands () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Alpha_client_context.full) -> diff --git a/src/proto_004_Pt24m4xi/lib_client_commands/client_proto_context_commands.ml b/src/proto_004_Pt24m4xi/lib_client_commands/client_proto_context_commands.ml index 62ff2c4c08f0030ab6ea6e4e2488be81a8881a91..60416b4beb21acde7260a44ee2b62618317b3afe 100644 --- a/src/proto_004_Pt24m4xi/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_004_Pt24m4xi/lib_client_commands/client_proto_context_commands.ml @@ -255,7 +255,7 @@ let commands () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Alpha_client_context.full) -> diff --git a/src/proto_005_PsBabyM1/lib_client_commands/client_proto_context_commands.ml b/src/proto_005_PsBabyM1/lib_client_commands/client_proto_context_commands.ml index 9d612cfe9748c4892e64cd7317764d5216844959..f83ca0ebc010298ef73bb6402408fa2e2a857b4d 100644 --- a/src/proto_005_PsBabyM1/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_005_PsBabyM1/lib_client_commands/client_proto_context_commands.ml @@ -319,7 +319,7 @@ let commands () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Protocol_client_context.full) -> diff --git a/src/proto_006_PsCARTHA/lib_client_commands/client_proto_context_commands.ml b/src/proto_006_PsCARTHA/lib_client_commands/client_proto_context_commands.ml index cf469d8cfff0f8f313e0ead820befcb2836b485c..fdd8324f2bc905be9eebf5b99df3f25c2ef0a932 100644 --- a/src/proto_006_PsCARTHA/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_006_PsCARTHA/lib_client_commands/client_proto_context_commands.ml @@ -1079,7 +1079,7 @@ let commands network () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Protocol_client_context.full) -> diff --git a/src/proto_008_PtEdo2Zk/lib_client_commands/client_proto_context_commands.ml b/src/proto_008_PtEdo2Zk/lib_client_commands/client_proto_context_commands.ml index 4fa86059eb7f42027d2fd97a393be326255e4647..467fb57759fa46a227fd09ecd4adeb536bc40dd6 100644 --- a/src/proto_008_PtEdo2Zk/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_008_PtEdo2Zk/lib_client_commands/client_proto_context_commands.ml @@ -1334,7 +1334,7 @@ let commands network () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Protocol_client_context.full) -> diff --git a/src/proto_009_PsFLoren/lib_client_commands/client_proto_context_commands.ml b/src/proto_009_PsFLoren/lib_client_commands/client_proto_context_commands.ml index 9c542fa564697c2a312d65fb0b8be140def63f05..d8a142d5346fb157c58af66b5902962b3ae11f23 100644 --- a/src/proto_009_PsFLoren/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_009_PsFLoren/lib_client_commands/client_proto_context_commands.ml @@ -1327,7 +1327,7 @@ let commands network () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Protocol_client_context.full) -> diff --git a/src/proto_010_PtGRANAD/lib_client_commands/client_proto_context_commands.ml b/src/proto_010_PtGRANAD/lib_client_commands/client_proto_context_commands.ml index 0448215ad5da6e12e54a09ec4b5be6083208abe4..dbb22bf08f5d2917015dea250e83156a8f921e9d 100644 --- a/src/proto_010_PtGRANAD/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_010_PtGRANAD/lib_client_commands/client_proto_context_commands.ml @@ -1321,7 +1321,7 @@ let commands network () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Protocol_client_context.full) -> diff --git a/src/proto_alpha/lib_client_commands/client_proto_context_commands.ml b/src/proto_alpha/lib_client_commands/client_proto_context_commands.ml index 9b9bd1db56cf232f9aff2d0d3f6d61aa2b96dcf8..6dcf0acd7f88977795fb4cd7e071e718e4af1ebc 100644 --- a/src/proto_alpha/lib_client_commands/client_proto_context_commands.ml +++ b/src/proto_alpha/lib_client_commands/client_proto_context_commands.ml @@ -1315,7 +1315,7 @@ let commands network () = >>= fun () -> return_unit); command ~group:binary_description - ~desc:"Describe unsigned block header" + ~desc:"Describe unsigned operation" no_options (fixed ["describe"; "unsigned"; "operation"]) (fun () (cctxt : Protocol_client_context.full) ->