diff --git a/docs/architecture.md b/docs/architecture.md index febff8845..47314ec8f 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,109 +2,43 @@ title: Architecture authors: Tim McMackin last_update: - date: 10 June 2024 + date: 30 October 2024 --- -The Tezos blockchain is composed of many Tezos nodes running around the world, complemented by other running daemons, such as bakers and accusers. +The Tezos blockchain is composed of many Tezos nodes running around the world, complemented by other programs such as bakers and accusers. These processes collaborate with the overall goal of maintaining the blockchain data in a decentralized manner. The Tezos nodes are the most important piece in this architecture because they maintain the system and the blockchain data. Users interact with nodes through many different clients, including command-line clients, wallets, and web applications. +For more information about nodes, see [Nodes](./architecture/nodes). This diagram shows a high-level view of the Tezos system: ![A high-level view of the Tezos system, including Tezos nodes, the blockchain data itself, an Indexer, and a few examples of clients](/img/architecture/architecture-overview.png) +## Tezos networks + +When people talk about Tezos, they usually mean the primary Tezos network, which is referred to as Mainnet. +Tezos also has other networks used for testing, referred to as testnets. +Anyone can create new test networks if needed. +For example, before new versions of the Tezos protocol are enabled, users create networks that use that protocol so they can test it. + ## The blockchain data Although people often use the word "blockchain" to mean the entire system, strictly speaking, a Tezos blockchain is a series of blocks of data, each connected to the previous block in the chain, beginning with the genesis block. The blockchain data is maintained by a network of Tezos nodes. Nodes reach consensus on the next block before adding it to the chain. -The primary Tezos network is referred to as Mainnet, and there are several other networks used for testing, referred to as testnets. -Anyone can create new test networks if needed. - As shown in the diagram, the data inside a Tezos block includes the hash of the previous block in the chain and many operations, such as transactions that transfer tez or call smart contracts. Blocks also include operations that are necessary for the management of the chain, including nodes' attestations that blocks are valid, called _consensus operations_, and votes on changes to the protocol, called _voting operations_. For more information on the operations that can be included in blocks, see [Blocks and operations](https://tezos.gitlab.io/alpha/blocks_ops.html) in the Octez documentation. -## Nodes - -A Tezos node has three main roles: - -- It validates blocks and operations -- It broadcasts blocks and operations to other nodes and receives them from other nodes over a peer-to-peer network -- It maintains a copy of the blockchain data and its associated state (also known as the ledger), which includes accounts and their balances, among other things - -Beside these technical roles, nodes must satisfy two other important requirements: - -- Support the governance of the blockchain -- Ensure the extensibility of the blockchain with new clients of different kinds. - -In order to meet these requirements, the software that nodes run is structured according to two major principles: - -- It is separated into a shell and a protocol, to support protocol evolution. -- It implements a client/server architecture, to allow composition with many other tools in a safe way. - -The Octez suite, which is an implementation of the Tezos node and other executables, instantiates these principles in the [Octez software architecture](https://tezos.gitlab.io/shell/the_big_picture.html). - -These two principles are detailed next. - -## Shell & Protocol - -The software that runs Tezos nodes is split into two main parts: - -- The shell, which handles low-level functions like data storage and peer-to-peer network communication -- The economic protocol that interprets the block operations (e.g., transactions) - -The relationship between the shell and the protocol is like the relationship between an operating system and an application. -The operating system stays stable while the application can update itself. -In this way, Tezos can update how it works (its protocol) without requiring nodes to accept major changes to the software that they run (the shell). -For example, nodes can update to a new protocol version without restarting the shell. - -### The Tezos self-amending protocol - -Unlike many other blockchains, Tezos is self-amending. -Its nodes can update the protocol that controls the possible operations and how they are processed; updates are performed via an online governance process. -These updates allow Tezos to adapt to new technologies and respond to user needs. -For example, protocol upgrades have added new features like Smart Rollups and have reduced the amount of time between blocks. - -This protocol is responsible for interpreting the operations in each block. -It also provides the logic that identifies erroneous blocks. - -Updates to the protocol can change this logic through a voting process, using dedicated voting operations such as protocol proposals or protocol upvotes. -For information about the voting process, see [Governance](/architecture/governance). - -The protocol has constants such as the time between blocks and the amount of tez that an account must stake to be a baker. -These constants can be different for different Tezos networks. - -To get the constants for a network, call the `GET /chains/main/blocks/head/context/constants` RPC endpoint. -For example, to get the constants of the network that the Octez client is currently connected to, run this command: - -```bash -octez-client rpc get /chains/main/blocks/head/context/constants -``` - -For more information about constants, see [Protocol constants](https://tezos.gitlab.io/alpha/protocol_overview.html#protocol-constants) in the Octez documentation. - -### The shell - -The shell is responsible for the fundamental functions of a distributed software application, including: - -- Peer-to-peer communication that lets nodes exchange information -- Storage functionality that lets nodes store blocks, operations, and the current state of the chain -- A synchronization heuristic that starts nodes and keeps them in sync with the network -- A validator that checks that blocks are valid with help from the rules in the economic protocol - -In particular, the validator is responsible for resolving the available blocks into a single linear sequence of blocks. -It chooses between the various blocks that baking nodes create, uses the protocol to verify and score them, and selects the tree head with the highest score. -Then it uses that linear chain in all of its work with the protocol, so the protocol is never aware of multiple branches. - ## Tezos clients and servers -In addition to the functions of the protocol and shell, a Tezos node also acts as a server to respond to queries and requests from clients. +In addition to the functions of the [protocol and shell](./architecture/nodes#protocol-and-shell), a Tezos node also acts as a server to respond to queries and requests from clients. A client can query the chain’s state and can inject blocks and operations into a node. +Nodes share operations with each other, so the node that includes an operation in a block may not be the node that the client originally sent the operation to. Tezos uses this client-server architecture for these main reasons: @@ -116,51 +50,40 @@ For example, different bakers may implement different transaction selection stra The node accepts calls from clients through its RPC interface. It has control over which clients to accept calls from, which calls to accept, or whether to accept RPC calls at all. -For more information on the RPC interface, see [The RPC interface](/architecture/rpc). - -### The baker daemon - -The baker daemon is an Octez program that is responsible for creating and proposing new blocks based on the operations proposed by different clients. -The baker daemon is associated with an account, which means that it has access to the account’s private key, which it uses to sign blocks and operations. - -### The accuser daemon - -The accuser daemon is an Octez program that monitors new blocks and looks for problems, such as when bakers try to add more than one block at a time. -When it finds a problem, it submits a denunciation to other nodes to refuse the new blocks and punish the offending node. -### The Octez client +Anyone can run a node and select which clients to run and which requests to accept from clients. +Some typical use cases for nodes are: -The Octez client is a command-line tool that developers can use for many Tezos-related tasks, including: +- A node running by itself, which maintains a copy of the blockchain data and enhances the distribution of the network without actively baking blocks. +Optionally, this node can open its RPC interface to serve different kinds of requests. +- A node along with a baker, an accuser, and a signer can be used to bake new blocks, activity which ensures that the blockchain progresses and yields rewards in tokens. -- Deploying, calling, testing, and interacting with contracts -- Deploying and interacting with Smart Rollups -- Working with accounts -- Calling RPC endpoints directly -- Running Sapling transactions -- Setting up baking operations for testing contracts +Here is a summary of the main Tezos clients: -For more information about the Octez client, see the [Octez documentation](https://tezos.gitlab.io/). +- **Bakers**: The baker is an Octez program that is responsible for creating and proposing new blocks based on the operations proposed by different clients. +For more information, see [Bakers](./architecture/bakers). -### External clients +- **Accusers**: The accuser is an Octez program that monitors new blocks and looks for problems, such as when bakers try to add more than one block at a time. +When it finds a problem, it submits a denunciation to other nodes to refuse the new blocks and punish the offending node. +For more information, see [Accusers](./architecture/accusers). -Many external clients can add operations to the network of nodes or use nodes to inspect the state of the blockchain, including: +- **The Octez client**: The Octez client is a command-line tool that developers can use for many Tezos-related tasks, including: -- Web applications that use SDKs such as Taquito to send and receive information from Tezos -- Indexer websites that monitor the state of the network and allow users to search its history -- Wallet applications + - Deploying, calling, testing, and interacting with contracts + - Deploying and interacting with Smart Rollups + - Working with accounts + - Calling RPC endpoints directly + - Running Sapling transactions + - Setting up baking operations for testing contracts -Nodes share operations with each other, so the node that includes an operation in a block may not be the node that the client originally sent the operation to. + For more information about the Octez client, see [The Octez client](./developing/octez-client). -Anyone can run a node and select which clients to run and which requests to accept from clients. -Some typical use cases for nodes are: - -- A node running with no daemons, which maintains a copy of the blockchain data and enhances the distribution of the network without actively baking blocks. -Optionally, this node can open its RPC interface to serve different kinds of requests. -- A node along with a baker, an accuser, and a signer can be used to bake new blocks, activity which ensures that the blockchain progresses and yields rewards in tokens. +- **External clients**: Many external clients can add operations to the network of nodes or use nodes to inspect the state of the blockchain, including: -### Indexers and block explorers + - Web applications that use SDKs such as Taquito to send and receive information from Tezos + - Wallet applications -Indexers are off-chain applications that retrieve blockchain data, process it, and store it in a way that makes it easier to search and use. +- **Indexers and block explorers**: Indexers are off-chain applications that retrieve blockchain data, process it, and store it in a way that makes it easier to search and use. They are an important part of block explorers, which are applications that provide data about the blockchain. ## References diff --git a/docs/architecture/accusers.md b/docs/architecture/accusers.md new file mode 100644 index 000000000..d58bd8b1b --- /dev/null +++ b/docs/architecture/accusers.md @@ -0,0 +1,19 @@ +--- +title: Accusers +authors: Tim McMackin +last_update: + date: 12 April 2024 +--- + +Accusers are programs that monitor new blocks, look for problems, and denounce bakers that introduce blocks with problems. +Accusers ensure that bakers play by the rules and do not abuse the reward mechanism of the Tezos protocol. + +Accusers look for: + +- Bakers that sign two blocks at the same level +- Bakers that inject more than one attestation for the same baking slot + +When they see one of these problems, they emit a double-baking or double-attesting denunciation operation, which cause the offending baker to lose some of its stake. +Some of the slashed stake goes to the accuser. + +Anyone can run an accuser, and they don't have to stake any tez like bakers must. diff --git a/docs/architecture/baking.md b/docs/architecture/bakers.md similarity index 81% rename from docs/architecture/baking.md rename to docs/architecture/bakers.md index d11d00267..89a33b22b 100644 --- a/docs/architecture/baking.md +++ b/docs/architecture/bakers.md @@ -1,16 +1,17 @@ --- -title: Baking +title: Bakers authors: "Tim McMackin" last_update: - date: 21 February 2024 + date: 12 April 2024 --- Baking is the process of creating new blocks in the Tezos blockchain. -Bakers are daemons complementary to Tezos nodes that cooperate to achieve consensus about the next block to add. +Bakers are programs complementary to Tezos nodes that cooperate to achieve consensus about the next block to add. Bakers validate pending operations, package them into a block, sign the block, propose the new block to other nodes, and verify that the blocks that other bakers propose are valid. -Baker daemons are run on behalf of user accounts which stake tez to guarantee honest participation and receive rewards for their participation. -By extension, bakers also denote the users running baker daemons on behalf of their user accounts. +Bakers are run on behalf of user accounts which stake tez to guarantee honest participation and receive rewards for their participation. +The baker has access to the account's private key, which it uses to sign blocks and operations. +By extension, bakers also denote the users running baker on behalf of their user accounts. ## The baking process @@ -35,8 +36,8 @@ Similarly, when bakers stop baking, their stake is unlocked after a certain numb The delegate must stake at least least 6,000 tez, either from its own account or from tez that delegators delegate to it. The more tez a delegate has, both from its own account and from delegators, the more likely it is to be selected to bake a block and thus receive the rewards. -Bakers must run at least one Tezos node and a baker daemon to go with it. -These daemons must run at all times with a stable internet connection, because inactive bakers are automatically removed from the network. +Bakers must run at least one Tezos node and a baker program to go with it. +These baker programs must run at all times with a stable internet connection, because inactive bakers are automatically removed from the network. ## Delegating to a baker diff --git a/docs/architecture/governance.md b/docs/architecture/governance.md index 6d92288cb..106f9cf5d 100644 --- a/docs/architecture/governance.md +++ b/docs/architecture/governance.md @@ -5,10 +5,9 @@ last_update: --- Tezos incorporates a built-in, on-chain mechanism for proposing, selecting, testing, and activating protocol upgrades without the need to hard fork. -This mechanism makes Tezos a self-amending blockchain and allows any user to propose changes to the [economic protocol](/architecture#the-tezos-self-amending-protocol), which defines the possible blockchain operations and how they are processed. +This mechanism makes Tezos a self-amending blockchain and allows any user to propose changes to the [economic protocol](/architecture/nodes), which defines the possible blockchain operations and how they are processed. - -This self-amendment process is separate from the less formal [Tezos Improvement Process](/architecture/governance/improvement-process). +This self-amendment process is separate from the off-chain and less formal [Tezos Improvement Process](/architecture/governance/improvement-process). ## Amendment periods diff --git a/docs/architecture/nodes.md b/docs/architecture/nodes.md new file mode 100644 index 000000000..c792c633f --- /dev/null +++ b/docs/architecture/nodes.md @@ -0,0 +1,95 @@ +--- +title: Nodes +authors: Tim McMackin +last_update: + date: 16 April 2024 +--- + +Tezos nodes are peer-to-peer programs running the Tezos protocol to participate in the Tezos network. +Anyone can run a Tezos node. + +A Tezos node has three main roles: + +- It validates blocks and operations +- It broadcasts blocks and operations to other nodes and receives them from other nodes over a peer-to-peer network +- It maintains a copy of the blockchain data and its associated state (also known as the ledger), which includes accounts and their balances, among other things + +Beside these technical roles, nodes must satisfy two other important requirements: + +- Support the governance of the blockchain +- Ensure the extensibility of the blockchain with new clients of different kinds + +In order to meet these requirements, the software that nodes run is structured according to two major principles: + +- It is separated into a protocol and a shell to make it easier to upgrade. +- It implements a client/server architecture, to allow composition with many other tools in a safe way. + +Nodes cooperate with clients and with each other through an [RPC interface](#the-rpc-interface). + +The Octez suite, which is an implementation of the Tezos node and other executables, instantiates these principles in the [Octez software architecture](https://tezos.gitlab.io/shell/the_big_picture.html). + +## Protocol and shell + +The software that runs Tezos nodes is split into two main parts: + +- The protocol, which interprets transactions and other operations in each block (also known as the _economic protocol_) +- The shell, which handles low-level functions like data storage and peer-to-peer network communication + +The relationship between the shell and the protocol is like the relationship between an operating system and an application. +The operating system stays stable while the application can update itself. +In this way, Tezos can update how it works (its protocol) without requiring nodes to accept major changes to the software that they run (the shell). +For example, nodes can update to a new protocol version without restarting the shell. + +### The protocol + +The Tezos protocol is responsible for interpreting the operations in each block. +It also provides the logic that identifies erroneous blocks. + +Unlike many other blockchains, Tezos is self-amending. +Its nodes can update the protocol that controls the possible operations and how they are processed; updates are performed via an online governance process. +These updates allow Tezos to adapt to new technologies and respond to user needs. +For example, protocol upgrades have added new features like Smart Rollups and have reduced the amount of time between blocks. + +Users propose updates to the protocol through a voting process, using dedicated voting operations such as protocol proposals and protocol upvotes. +For information about the voting process, see [Governance](governance). + +### The shell + +The shell is responsible for the fundamental functions of a distributed software application, including: + +- Peer-to-peer communication that lets nodes exchange information +- Storage functionality that lets nodes store blocks, operations, and the current state of the chain +- A synchronization heuristic that starts nodes and keeps them in sync with the network +- A validator that checks that blocks are valid with help from the rules in the economic protocol + +In particular, the validator is responsible for resolving the available blocks into a single linear sequence of blocks. +It chooses between the various blocks that baking nodes create, uses the protocol to verify and score them, and selects the tree head with the highest score. +Then it uses that linear chain in all of its work with the protocol, so the protocol is never aware of multiple branches. + +## The RPC interface + +The Tezos RPC (Remote Procedure Call) interface is a specification for a REST API that clients use to interact with Tezos nodes and nodes use to communicate with each other. + +You may want to know this RPC interface if you are developing tools that need to query the Tezos blockchain or to interact with it, such as wallets, indexers, or Web3 libraries. + +Clients use this interface to submit transactions and get information about the state of the blockchain, such as account balances and contract storage. +Tezos nodes act as servers and accept HTTP requests from clients and other nodes via this interface. + +Tezos RPC uses JSON to send and receive data, but it does not adhere to the JSON-RPC specification. + +All the RPCs served by the Tezos node are described as an OpenAPI specification at [Octez Node RPCs](https://tezos.gitlab.io/api/openapi.html#octez-node) in the Octez documentation. + +### Public and private RPC nodes + +All Tezos nodes run RPC servers, but the RPC interface is subject to an access policy. +By default, RPC servers are private and do not accept all requests from every client. + +When you work with a Tezos client, such as the Octez command-line client or the Taquito SDK, you select a public RPC node to send transactions to, or you can use a private RPC node that you have access to. + +If you're using a testnet, you can get a list of public RPC nodes for that network at https://teztnets.com. + +Other sources of public nodes include: + +- [Community RPC Nodes](https://tezostaquito.io/docs/rpc_nodes) listed by ECAD Labs. +- [SmartPy nodes](https://smartpy.io/nodes) +- [RPC nodes](https://tezostaquito.io/docs/rpc_nodes) in the Taquito documentation diff --git a/docs/architecture/rpc.md b/docs/architecture/rpc.md deleted file mode 100644 index ec769fc60..000000000 --- a/docs/architecture/rpc.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: The RPC interface -authors: "Tim McMackin" -last_update: - date: 6 February 2023 ---- - -The Tezos RPC (Remote Procedure Call) interface is a specification for a REST API that clients use to interact with Tezos nodes and nodes use to communicate with each other. - -You may want to know this RPC interface if you are developing tools that need to query the Tezos blockchain or to interact with it, such as wallets, indexers, or Web3 libraries. - -Clients use this interface to submit transactions and get information about the state of the blockchain, such as account balances and contract storage. -Tezos nodes act as servers and accept HTTP requests from clients and other nodes via this interface. - -Tezos RPC uses JSON to send and receive data, but it does not adhere to the JSON-RPC specification. - -All the RPCs served by the Tezos node are described as an OpenAPI specification at [Octez Node RPCs](https://tezos.gitlab.io/api/openapi.html#octez-node) in the Octez documentation. - -## Public and private RPC nodes - -All Tezos nodes run RPC servers, but the RPC interface is subject to an access policy. -By default, RPC servers are private and do not accept all requests from every client. - -When you work with a Tezos client, such as the Octez command-line client or the Taquito SDK, you select a public RPC node to send transactions to, or you can use a private RPC node that you have access to. - -If you're using a testnet, you can get a list of public RPC nodes for that network at https://teztnets.com. - -Other sources of public nodes include: - -- [Community RPC Nodes](https://tezostaquito.io/docs/rpc_nodes) listed by ECAD Labs. -- [SmartPy nodes](https://smartpy.io/nodes) -- [RPC nodes](https://tezostaquito.io/docs/rpc_nodes) in the Taquito documentation diff --git a/docs/developing/information.md b/docs/developing/information.md index 7c5a10530..34b0970b1 100644 --- a/docs/developing/information.md +++ b/docs/developing/information.md @@ -18,7 +18,8 @@ octez-client get balance for tz1QCVQinE8iVj1H2fckqx6oiM85CNJSK9Sx ## The RPC interface -[The RPC interface](/architecture/rpc) provides information about the blockchain that nodes use to communicate with each other. +The [RPC interface](/architecture/nodes#the-rpc-interface) allows nodes to cooperate with each other and with their clients. +In particular, many RPCs provide information about the blockchain. This data is not always in the format that developers and dApps need. For example, the RPC interface does not provide a way to get information about a specific operation by its hash. diff --git a/docs/developing/information/indexers.md b/docs/developing/information/indexers.md index 816534c97..9da204a1b 100644 --- a/docs/developing/information/indexers.md +++ b/docs/developing/information/indexers.md @@ -12,7 +12,7 @@ You can use indexers to provide the data that you need for your dApps. ## Why indexers are needed -Tezos nodes store copies of blocks, but they provide only certain information about those blocks through the [RPC interface](/architecture/rpc). +Tezos nodes store copies of blocks, but they provide only certain information about those blocks through the [RPC interface](/architecture/nodes#the-rpc-interface). For example, assume that you want information about an operation and all you have is its hash. The RPC interface can't provide this information directly, so you would have to search each block until you found the block with this operation, which is very inefficient. diff --git a/docs/unity/quickstart.md b/docs/unity/quickstart.md index b0cad6f10..d48b3cb4f 100644 --- a/docs/unity/quickstart.md +++ b/docs/unity/quickstart.md @@ -342,7 +342,7 @@ private void OnPayloadSigned(SignResult obj) ## Changing the RPC node -As described in [The RPC interface](/architecture/rpc), Tezos clients including the Unity SDK send transactions to RPC nodes. +As described in [The RPC interface](/architecture/nodes#the-rpc-interface), Tezos clients including the Unity SDK send transactions to RPC nodes. By default, the SDK sends requests to a public RPC node that uses the Ghostnet test network, where you can test transactions without spending real tez. For more information about test networks, see [Testing on sandboxes and testnets](/developing/testnets). diff --git a/docs/unity/reference/TezosConfigSO.md b/docs/unity/reference/TezosConfigSO.md index f011e7264..465c3a04f 100644 --- a/docs/unity/reference/TezosConfigSO.md +++ b/docs/unity/reference/TezosConfigSO.md @@ -20,4 +20,4 @@ To use this object, create an instance of it, put your information in its fields - `Pinata Api Key`: The Pinata JWT (not the API key or secret key) to use to upload files and data to IPFS - `Data Provider Config`: The instance of the [DataProviderConfig](/unity/reference/DataProviderConfigSO) scriptable object to use -For more information about RPC nodes, see [The RPC interface](/architecture/rpc). +For more information about RPC nodes, see [The RPC interface](/architecture/nodes#the-rpc-interface). diff --git a/sidebars.js b/sidebars.js index 2f3c27e6d..9d5af4b94 100644 --- a/sidebars.js +++ b/sidebars.js @@ -24,6 +24,9 @@ const sidebars = { type: 'doc', }, items: [ + 'architecture/nodes', + 'architecture/bakers', + 'architecture/accusers', 'architecture/accounts', { type: 'category', @@ -38,8 +41,6 @@ const sidebars = { 'architecture/tokens/FA2.1', ], }, - 'architecture/baking', - 'architecture/rpc', 'architecture/smart-rollups', 'architecture/data-availability-layer', {