From 4d28d69e9129676e46353fc7798c2fc03cd753dd Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Wed, 3 Apr 2024 14:18:53 +0300 Subject: [PATCH 01/19] Updating all sections under 'Explore' --- docs/04-explore-cardano/_category_.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-explore-cardano/_category_.yml b/docs/04-explore-cardano/_category_.yml index 3105a4a7..d018b820 100644 --- a/docs/04-explore-cardano/_category_.yml +++ b/docs/04-explore-cardano/_category_.yml @@ -1,4 +1,4 @@ position: 4 -label: 'Explore Cardano' +label: 'Explore more' collapsible: true collapsed: true From 30fe3bc82ed6e7c375615c64d91d290d24fbca9f Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Wed, 3 Apr 2024 14:45:16 +0300 Subject: [PATCH 02/19] Update 03-cardano-architecture.mdx --- .../03-cardano-architecture.mdx | 90 +++++++++---------- 1 file changed, 42 insertions(+), 48 deletions(-) diff --git a/docs/04-explore-cardano/03-cardano-architecture.mdx b/docs/04-explore-cardano/03-cardano-architecture.mdx index bbd9f816..638b4ff4 100644 --- a/docs/04-explore-cardano/03-cardano-architecture.mdx +++ b/docs/04-explore-cardano/03-cardano-architecture.mdx @@ -6,69 +6,64 @@ metaTitle: Cardano architecture This section describes the high-level architecture of Cardano, providing details on the core components and their interactions. -### High level architecture of Cardano - The following diagram outlines the interaction between the system components of Cardano: ![cardano_components](https://ucarecdn.com/3756645a-a4a2-4d2f-846a-e454bf7cba60/) -### System components +## System components The _current_ implementation of Cardano is highly modular. It includes the following components (different deployment use cases will use different combinations of components): - [Node](https://github.com/input-output-hk/cardano-node) -- [Command line interface (CLI)](https://github.com/input-output-hk/cardano-node-wiki/blob/main/docs/reference/cardano-node-cli-reference.md) -- [Daedalus wallet](https://github.com/input-output-hk/cardano-wallet) +- [Command line interface (CLI)](https://github.com/IntersectMBO/cardano-cli) +- [Cardano wallet](https://github.com/input-output-hk/cardano-wallet) - [Cardano db-sync](https://github.com/input-output-hk/cardano-db-sync) - [GraphQL](https://github.com/input-output-hk/cardano-graphql) API server (Apollo) -- [SMASH server](https://github.com/input-output-hk/smash) +- [SMASH server](https://github.com/IntersectMBO/cardano-db-sync/tree/master/cardano-smash-server) -### Nodes and remote nodes +## Nodes and remote nodes A blockchain system consists of a set of nodes distributed across a network that -communicate with each other to achieve [consensus](https://docs.cardano.org/learn/consensus-explained) about the system’s state. +communicate with each other to achieve [consensus](/learn/consensus-explained) about the system’s state. Nodes are responsible for: - Executing the - [Ouroboros](https://github.com/input-output-hk/ouroboros-network/#ouroboros-network) + [Ouroboros](https://github.com/IntersectMBO/ouroboros-network?tab=readme-ov-file#ouroboros-network) protocol - Validating and relaying blocks - Producing blocks (some nodes) -- Providing information about the state of the blockchain to other local clients - -You can only trust nodes run by you or your organization. This is why [Daedalus](https://docs.cardano.org/cardano-components/daedalus-wallet) -runs a node in the background. +- Providing information about the state of the blockchain to other local clients. -#### Node process +### Node process -The cardano-node is the top level for the node and consists of the other -subsystems, of which the most significant are consensus, -[ledger](https://github.com/input-output-hk/cardano-ledger-specs#cardano-ledger) -and networking with ancillary configuration, CLI, logging, and monitoring. +The `cardano-node` is the top level Cardano component that consists of the other +subsystems, of which the most significant are [consensus](https://github.com/IntersectMBO/ouroboros-consensus?tab=readme-ov-file#ouroboros-consensus), +[ledger](https://github.com/IntersectMBO/cardano-ledger?tab=readme-ov-file#cardano-ledger) +and [networking](https://github.com/IntersectMBO/ouroboros-network?tab=readme-ov-file#ouroboros-network) with ancillary configuration, CLI, logging, and monitoring. -#### Node-to-Node IPC protocol +### Node-to-node IPC protocol The purpose of the node-to-node Inter-Process Communication (IPC) protocol is to allow for the exchange of blocks and transactions between nodes as part of the Ouroboros consensus algorithm. The node-to-node protocol is a composite protocol, consisting of three -‘mini-protocols’: +mini-protocols: -- **chain-sync**: Used for following the chain and getting block headers. -- **block-fetch**: Used for getting block bodies. -- **tx-submission**: Used for forwarding transactions. +- **chain-sync**: used for following the chain and getting block headers +- **block-fetch**: used for getting block bodies +- **tx-submission**: used for forwarding transactions. These mini-protocols are multiplexed on a single long-running Transmission Control Protocol (TCP) connection between nodes. They can be run in _both_ directions on the same TCP connection to allow for peer-to-peer (P2P) settings. -The overall protocol -and each mini-protocol- is designed for a trustless +The overall protocol – and each mini-protocol – is designed for a trustless setting where both sides need to guard against Denial-of-Service (DoS) attacks. For example, each mini-protocol uses consumer-driven control flow, so a node only requests more work when it is ready, rather than having work _pushed_ upon @@ -78,7 +73,7 @@ The protocol design is modular and evolvable: version negotiation is used to agree on the set of mini-protocols to use, which allows additional or updated mini-protocols to be added over time without causing compatibility issues. -#### Node-to-Client IPC +### Node-to-client IPC The purpose of the node-to-client IPC protocol is to allow local applications to interact with the blockchain via the node. This includes applications such as @@ -87,7 +82,7 @@ these applications to access the raw chain data and to query the current ledger state. It also provides the ability to submit new transactions to the system. The node-to-client protocol uses the same design as the node-to-node protocol, -but with a different set of mini-protocols, and using local pipes rather than +but with a different set of mini-protocols, and local pipes rather than TCP connections. As such, it is a relatively low-level narrow interface that exposes only what the node can provide natively. For example, the node provides access to all the raw chain data but does not provide a way to query data on the @@ -97,9 +92,9 @@ backend. The node-to-client protocol consists of three mini-protocols: -- **chain-sync**: Used for following the chain and getting blocks -- **local-tx-submission**: Used for submitting transactions -- **local-state-query**: Used for querying the ledger state +- **chain-sync**: used for following the chain and getting blocks +- **local-tx-submission**: used for submitting transactions +- **local-state-query**: used for querying the ledger state. The node-to-client version of chain sync uses _full_ blocks, rather than just block headers. This is why no separate block-fetch protocol is needed. The @@ -109,9 +104,13 @@ local state query protocol provides query access to the current ledger state, which contains a lot of interesting data that is _not_ directly reflected on the chain itself. -[Read more about the networking protocol design and Cardano node communication protocols.](/explore-cardano/cardano-network/networking-protocol) +:::info + +Read more about the [networking protocol design here](/explore-cardano/cardano-network/networking-protocol). -### Command line interface (CLI) +::: + +## Command line interface (CLI) The node’s CLI tool is the 'swiss army knife' of the system. It can do almost everything, but it is quite low level and not very convenient because it’s @@ -119,12 +118,12 @@ text-based and lacks a graphical user interface (GUI). The CLI tool can: -- Query the node for information -- Submit transactions -- Build and sign transactions -- Manage cryptographic keys +- query the node for information +- submit transactions +- build and sign transactions +- manage cryptographic keys. -### Daedalus wallet +## Daedalus wallet Daedalus is a full node wallet that helps users to manage their ada, and can send and receive payments on the Cardano blockchain. Daedalus consists of a @@ -135,24 +134,19 @@ selection, transaction construction, and submission. The backend interacts with a local node via the node-to-client IPC protocol, and interacts with the frontend via a HTTP API. The backend also provides a CLI that enables interaction with the wallet. The wallet backend can also be used on its own --without Daedalus- via its API. This is a convenient way for software developers + – without Daedalus – via its API. This is a convenient way for software developers to integrate Cardano with other applications and systems. -We advise that most advanced users intending to use Cardano start with Daedalus. - -### cardano-db-sync +## Cardano DB Sync -The cardano node stores only the blockchain itself and associated information -needed to validate the blockchain. This design principle is about minimising -code complexity, and reducing computational cost and resource use, to keep the +The cardano node stores only the blockchain itself and the associated information +needed to validate the blockchain. This design principle is about minimizing +code complexity (and reducing computational cost and resource use) to keep the node's local interfaces as minimal as possible and to use external clients to provide a variety of convenient interfaces and extra functionality. In particular, the node does not provide a convenient query interface for historical information on the blockchain. This data service is provided by a -separate component using an Structured Query Language (SQL) database. - -Read more about: +separate component using a Structured Query Language (SQL) database. -+ [Cardano DB Sync and its components](https://docs.cardano.org/cardano-components/cardano-db-sync/about-db-sync/) -+ [SMASH](https://docs.cardano.org/cardano-components/smash) +Learn more about [Cardano DB Sync here](https://github.com/IntersectMBO/cardano-db-sync?tab=readme-ov-file#cardano-db-sync). From c10d908dfae21a902ebf9a179c95e20a3e7a3c0b Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Wed, 3 Apr 2024 15:08:19 +0300 Subject: [PATCH 03/19] Update index.mdx --- .../04-cardano-network/index.mdx | 99 ++++++++++--------- 1 file changed, 50 insertions(+), 49 deletions(-) diff --git a/docs/04-explore-cardano/04-cardano-network/index.mdx b/docs/04-explore-cardano/04-cardano-network/index.mdx index c0923c0e..56af2194 100644 --- a/docs/04-explore-cardano/04-cardano-network/index.mdx +++ b/docs/04-explore-cardano/04-cardano-network/index.mdx @@ -7,7 +7,7 @@ collapsed: true --- The Cardano network is a technical infrastructure combining Cardano nodes and -their relative interactions in one unified system. It consists of a collection +their interactions in one unified system. It consists of a collection of nodes that communicate with each other to maintain the distributed ledger. These nodes are the actors on Cardano that validate blocks, add blocks to the chain, and distribute transactions. @@ -17,11 +17,15 @@ requirements, which includes new blocks diffusion and transaction information for establishing a better data flow. Cardano nodes maintain connections with peers that have been chosen via a custom peer selection process. -Follow these links to find detailed specifications of: +:::info + +Read the following specifications for more details: - [The Shelley networking protocol](https://ouroboros-network.cardano.intersectmbo.org/pdfs/network-spec/network-spec.pdf) - [An introduction to the design of data diffusion and networking for Cardano Shelley.](https://ouroboros-network.cardano.intersectmbo.org/pdfs/network-design/network-design.pdf) +::: + ## Data flow between and within nodes To understand how nodes communicate with each other, let’s suppose that node _A_ @@ -30,36 +34,35 @@ generate a new block in a given time slot. Depending on the location of nodes _A_, _B_, and _N_ in the network topology, and whether a new block arrives first at _A_ or _B_, node _A_ can be either upstream or downstream of node _B_. -A set of mini protocols is used to enable communication between different nodes. -Each mini protocol implements a basic information exchange requirement, such as +A set of mini-protocols is used to enable communication between different nodes. +Each mini-protocol implements a basic information exchange requirement, such as informing peers of the latest block, sharing blocks as needed, or sharing new -transactions around the Cardano network. For connection purposes, mini protocols +transactions around the Cardano network. For connection purposes, mini-protocols are determined by the version of the network protocol. For example, there are two protocol suites: node-to-node and node-to-client. The node-to-client protocol suite is used by wallets and chain consumers. Protocol suites use -different sets of mini protocols and the version is negotiated when a new +different sets of mini-protocols and the version is negotiated when a new connection is established using a specific protocol (protocols are described in the following sections). Clients can also choose which node-to-client mini-protocols to use, but it is important to note that the node needs to be able to reply to all of them to support different use cases. For example, to communicate, node A runs its -client-side instance of the _chain-sync mini protocol_ that talks with a server -instance of the _chain-sync mini protocol_ at node _B_. Such a situation is -similar to the functionality of other mini protocols. +client-side instance of the _chain-sync mini-protocol_ that talks with a server +instance of the _chain-sync mini-protocol_ at node _B_. Such a situation is +similar to the functionality of other mini-protocols. The scheme below illustrates how data flows within a node. Circles represent protocol threads and internal threads that are responsible for running the -client and server processes within the respective mini protocols. +client and server processes within the respective mini-protocols. ![node_data_flow](node_data_flow.jpg) Two types of data flow exist: -1. Mini protocols communicate with mini protocols of other nodes by sending and +1. Mini-protocols communicate with mini-protocols of other nodes by sending and receiving messages across a public network (internet); this flow is not - covered within the scheme above but will be potentially designed for better - understanding. + covered within the scheme above. 2. Within a node, mini-protocols communicate with each other by reading from, and writing to, a shared mutable variable, which is represented by boxes in the scheme. Arrows indicate whether a thread has _read_ or _write_ access to @@ -98,11 +101,11 @@ those time slots. Choosing a slot time, however, might cause certain complexities in terms of the slot length, as it should be long enough for a new block to have a good chance to reach the next slot leader in time. Therefore, a chosen value for the slot length was initially set to 20 seconds in the Byron -era. With [Ouroboros Praos](https://eprint.iacr.org/2017/573.pdf) now +era. With [Ouroboros Praos](https://eprint.iacr.org/2017/573.pdf) implemented in the Shelley era, a slot length of 1 second is chosen but, on average, only 0.05 of slots will produce a block (and thus on average, there will be 20-second intervals between blocks). It is assumed that the clock skews -between local clocks of the nodes is small with respect to the slot length. +between the local clocks of the nodes are small with respect to the slot length. Possible clock inaccuracies should still be taken into consideration, especially when dealing with time-stamped incoming blocks. It is important to differentiate whether there is a time difference or whether the node considers an adversarial @@ -110,36 +113,34 @@ behavior of another node. ## Utilizing mini-protocols -Mini protocols are used to communicate between multiple nodes while implementing -information exchange requirements. A mini protocol is a defined modular building -block of the network protocol. Structuring the network protocol around mini -protocols helps to manage the overall complexity of the design while ensuring +Mini-protocols are used to communicate between multiple nodes while implementing +information exchange requirements. A mini-protocol is a defined modular building +block of the network protocol. Structuring the network protocol around mini-protocols helps to manage the overall complexity of the design while ensuring useful flexibility. -Mini protocols describe both the _initiator_ and the _responder_ within the +Mini-protocols describe both the _initiator_ and the _responder_ within the communication stream. The initiator is the dual element of the responder and -vice versa. A node typically runs many instances of mini protocols, which -includes many instances of the same mini protocol. Each mini protocol instance -of the node then communicates with the dual instance of the exact peer. All mini -protocols that communicate with the same peer share a single communication +vice versa. A node typically runs many instances of mini-protocols, which +includes many instances of the same mini-protocol. Each mini-protocol instance +of the node then communicates with the dual instance of the exact peer. All mini-protocols that communicate with the same peer share a single communication channel (pipe or socket). A multiplexer or de-multiplexer is used to multiplex respective protocols over that channel. -The set of mini protocols that is used for connection between two participants +The set of mini-protocols that is used for connection between two participants of the system depends on the role of these participants, for instance, whether the node acts as a full node or a blockchain consumer (for example, a wallet). -It is also worth noting that the implementation of mini protocols uses a generic +It is also worth noting that the implementation of mini-protocols uses a generic framework for **state machines**. This framework uses _correct-by-construction_ techniques to guarantee the implementation of several properties of the protocol. In particular, this technique assures that no deadlocks occur and -communication is cancelled in the following scenarios: +communication is canceled in the following scenarios: - when one side is expected to transmit the next message, and the other side is awaiting the message, and both sides agree that the protocol has been terminated - when either side receives a message that is not expected according to the - protocol + protocol. All mini protocols based on this framework include the following information in their description: @@ -149,27 +150,27 @@ their description: - exchanged messages - a transition graph of the state machine global view - the client’s implementation of the protocol -- the server implementation of the protocol +- the server implementation of the protocol. -## Example mini protocols +## Example mini-protocols -This section outlines some examples of mini protocols. +This section outlines some examples of mini-protocols. -### Ping Pong protocol +### Ping pong protocol This is a simple protocol for testing that a client can use to check that the -server is responsive. The Ping-Pong protocol is very simple because the messages -do not carry any data and the Ping-Pong client, as well as the Ping-Pong server, +server is responsive. The ping pong protocol is very simple because the messages +do not carry any data and the ping pong client, as well as the ping pong server, do not access the internal state of the node. -### Request Response protocol +### Request response protocol -The request response protocol is polymorphic in the request and response data +The request esponse protocol is polymorphic in the request and response data that is being transmitted. This means that there are different possible applications of this protocol and the application of the protocol determines the types of requests sent and responses received. -### Chain Synchronisation protocol +### Chain synchronization protocol The chain synchronization protocol is used by a blockchain consumer to replicate the producer’s blockchain locally. A node communicates with several upstream and @@ -181,44 +182,44 @@ uses an instance of the chain synchronization protocol that transfers full blocks, while the node-to-node instance only transfers block headers. In the node-to-node scenario, the block fetch protocol is used to transfer full blocks. -### Block Fetch protocol +### Block fetch protocol The block-fetching protocol enables a node to download a range of blocks. -### Local Transaction Submission mini protocol +### Local transaction submission mini-protocol -The local transaction submission mini protocol is used by local clients, for +The local transaction submission mini-protocol is used by local clients, for example, wallets or CLI tools, to submit transactions to a local node. The protocol is not used to forward transactions from one core node to another. The protocol follows a simple request-response pattern: -1. the client sends a request with a single transaction. +1. the client sends a request with a single transaction 2. the server either accepts the transaction (returning a confirmation), or rejects it (returning the reason). -### Node-to-Node Transaction Submission protocol +### Node-to-node transaction submission protocol The node-to-node transaction submission protocol is used to transfer transactions between full nodes. The protocol follows a pull-based strategy where the initiator asks for new transactions and the responder replies with transactions. It is suitable for a trustless setting where both sides need to guard against resource consumption attacks from the other side. The -implementation of the node-to-node transaction mini protocol is based on a -generic mini protocol framework (the same as for all other mini protocols). For +implementation of the node-to-node transaction mini-protocol is based on a +generic mini-protocol framework (the same as for all other mini-protocols). For technical reasons, the roles of the initiator and the responder are reversed in -this case compared to the way other mini protocols are implemented in the +this case compared to the way other mini-protocols are implemented in the framework. In other words, the server is the initiator who requests new transactions, and the client is the responder who replies with transactions. -### Handshake mini protocol +### Handshake mini-protocol -The handshake mini protocol is used to negotiate the protocol version and the +The handshake mini-protocol is used to negotiate the protocol version and the protocol parameters that are used by the client and the server. It is used first when a new connection is initialized and consists of a single request from the -client and a single reply from the server. The handshake mini protocol is a +client and a single reply from the server. The handshake mini-protocol is a generic protocol that can negotiate any kind of protocol parameters. It assumes that protocol parameters can be encoded to, and decoded from Concise Binary Object Representation (CBOR) terms. A node that runs the handshake protocol must instantiate it with the set of supported protocol versions and callback functions for handling the protocol parameters. These callback functions are -specific for the supported protocol versions. +specific to the supported protocol versions. From 09f0225a03cafe176b517e2c36f8d374bea48d9b Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Wed, 3 Apr 2024 15:27:22 +0300 Subject: [PATCH 04/19] Update 02-networking-protocol.mdx --- .../02-networking-protocol.mdx | 44 ++++++++++--------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/docs/04-explore-cardano/04-cardano-network/02-networking-protocol.mdx b/docs/04-explore-cardano/04-cardano-network/02-networking-protocol.mdx index 6706d62d..314f5d25 100644 --- a/docs/04-explore-cardano/04-cardano-network/02-networking-protocol.mdx +++ b/docs/04-explore-cardano/04-cardano-network/02-networking-protocol.mdx @@ -15,7 +15,7 @@ for example, can open 1,024 connections per process, whereas macOS limits this number to 256. To avoid excessive use of resources and enable reliable means for connection establishment, Cardano uses a _multiplexer_. -### Connection management +## Connection management The network layer handles a range of specific tasks besides the exchange of block and transaction information required by the Ouroboros protocol. @@ -32,13 +32,13 @@ following tasks: - shutting down the connection in case of an error - handling a shutdown request from the peer - shutting down the threads that run mini-protocols -- closing a socket +- closing a socket. -### Multiplexing +## Multiplexing The multiplexing layer acts as a central crossing between mini-protocols and the network channel. It runs several -[mini-protocols](/explore-cardano/cardano-network#utilizingmini-protocols) in +[mini-protocols](/explore-cardano/cardano-network/#utilizing-mini-protocols) in parallel in a single channel ‒ TCP connection, for example. Figure 1 reflects how data flows between two nodes, each running three @@ -61,36 +61,40 @@ reassemble byte streams for the mini-protocols on its side. The multiplexing protocol (see the note below) itself is completely agnostic to the structure of the multiplexed data. -> Note: This is not a generic, but specialized, use of multiplexing. Individual -> mini-protocols have strict constraints on unacknowledged messages that can be -> in flight. The design avoids the conditions in which the use of general TCP -> over TCP multiplexing creates chaotic performance. +:::note -### Data segments of the multiplexing protocol +This is not a generic, but specialized, use of multiplexing. Individual +mini-protocols have strict constraints on unacknowledged messages that can be +in flight. The design avoids the conditions in which the use of general TCP +over TCP multiplexing creates chaotic performance. + +::: + +## Data segments of the multiplexing protocol Multiplexing data segments include the following details: - **Transmission time** ‒ a timestamp based on the lower 32 bits of the sender’s - monotonic clock with a resolution of one microsecond. -- **Mini-protocol ID** ‒ the unique ID of the mini-protocol. -- **Payload length** ‒ the size of the segment payload in bytes. The maximum + monotonic clock with a resolution of one microsecond +- **Mini-protocol ID** ‒ the unique ID of the mini-protocol +- **Payload length** ‒ the size of the segment payload in bytes; the maximum payload length supported by the multiplexing wire format is 216 − 1. Note that an instance of the protocol can choose a smaller limit for the size of - segments it transmits. + segments it transmits - **Mode** ‒ the single bit M (the mode) is used to distinguish the dual instances of a mini-protocol. The mode is set to 0 in segments from the initiator (the side that initially has agency), and it is set to 1 in segments from the responder. -### Cardano node communication protocols +## Cardano node communication protocols Cardano uses inter-process communication (IPC) protocols to allow for the exchange of blocks and transactions between nodes, and to allow local applications to interact with the blockchain via the node. -#### Node-to-Node IPC overview +### Node-to-node IPC overview -The Node-to-Node (NtN) protocol transfers transactions between full nodes. NtN +The Node-to-node (NtN) protocol transfers transactions between full nodes. NtN includes three mini-protocols (chain-sync, block-fetch, and tx-submission), which are multiplexed over a single TCP channel using a network-mux package. @@ -124,9 +128,9 @@ additional protocol: - **keep-alive**: a protocol that ensures continuous connection between nodes and minimizes performance faults. -#### Node-to-Client IPC overview +### Node-to-client IPC overview -Node-to-Client (NtC) is a connection between a full node and a client that +Node-to-client (NtC) is a connection between a full node and a client that consumes data but does not take part in the Ouroboros protocol (a wallet, for example.) @@ -136,7 +140,7 @@ backends or blockchain explorers. The NtC protocol enables these applications to access the raw chain data and to query the current ledger state, and it also provides the ability to submit new transactions to the system. -The NtC protocol uses the same design as the Node-to-Node (NtN) protocol, but +The NtC protocol uses the same design as the node-to-node (NtN) protocol, but with a different set of mini-protocols, and using local pipes rather than TCP connections. As such, it is a relatively low-level and narrow interface that exposes only what the node can provide natively. For example, the node provides @@ -151,7 +155,7 @@ The NtC protocol consists of three mini-protocols: - **chain-sync** - used for following the chain and getting blocks - **local-tx-submission** - used for submitting transactions -- **local-state-query** - used for querying the ledger state +- **local-state-query** - used for querying the ledger state. The NtC version of chain-sync uses full blocks, rather than just block headers. This is why no separate block-fetch protocol is needed. The local-tx-submission From 8b0f605b9078e8533901a5cc651e04f4116f52f6 Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Wed, 3 Apr 2024 15:39:31 +0300 Subject: [PATCH 05/19] Update 03-p2p-networking.mdx --- .../04-cardano-network/03-p2p-networking.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/04-explore-cardano/04-cardano-network/03-p2p-networking.mdx b/docs/04-explore-cardano/04-cardano-network/03-p2p-networking.mdx index 917ec0c5..ceab43a0 100644 --- a/docs/04-explore-cardano/04-cardano-network/03-p2p-networking.mdx +++ b/docs/04-explore-cardano/04-cardano-network/03-p2p-networking.mdx @@ -15,11 +15,11 @@ that was defined in a topology file. Since the introduction of Shelley, the system has been functioning in a hybrid mode. Moving from the federated state of network connectivity to the hybrid one, the teams delivered a manually constructed P2P network of SPO relay nodes. This means that SPO block-producing -nodes can connect to both trusted\* relay nodes and other SPO-run relay nodes. +nodes can connect to both trusted relay nodes and other SPO-run relay nodes. Hybrid connectivity is not automated, however, it enables the exchange of block and transaction information without relying on trusted relays only. -\*A trusted relay is the one that the SPO, wallet, or exchange accessing the +A trusted relay is the one that the SPO, wallet, or exchange accessing the network ‘trusts’. Though this role has mostly been performed by IOG, other entities, such as the Cardano Foundation, a wallet, or exchanges can also run trusted relays. Block-producing nodes can connect to any relays they deem @@ -46,17 +46,17 @@ trustable. To ensure efficient communication between nodes, it is desirable to enable automated connections of SPO relays to each other, so that less static -configuration is needed. Dynamic P2P is gradually enabled with the node +configuration is needed. Dynamic P2P has been gradually enabled since the node [v.1.35.6](https://github.com/input-output-hk/cardano-node/releases/tag/1.35.6) release. For more details, see [this blog post](https://iohk.io/en/blog/posts/2023/03/16/dynamic-p2p-is-coming-to-cardano/). -After Dynamic P2P is deployed, networking will keep evolving with future +With the deployment of Dynamic P2P, networking keeps evolving with additions such as Ouroboros Genesis and peer sharing: 4. Ouroboros Genesis: in development. Anyone running their own node or Daedalus wallet will connect to a fully decentralized and self-organized network. - Genesis enables secure node bootstrapping and the removal of trusted relays. + Genesis enables secure node bootstrapping and the removal of trusted relays. Read this blog post to learn more about [the transition to Genesis](https://iohk.io/en/blog/posts/2024/03/14/approaching-full-p2p-node-operations/). ![genesis](https://ucarecdn.com/9ce084f4-28d6-4557-919e-d60a18ded168/) @@ -106,7 +106,7 @@ maintains a set of peers mapped into three categories: for network measurements without implementing any of the node-to-node mini-protocols - hot peers ‒ peers that have a connection, which is being used by all three - node-to-node mini-protocols + node-to-node mini-protocols. Newly discovered peers are initially added to the cold peer set. The outbound governor is then responsible for peer connection management: it defines which @@ -124,7 +124,7 @@ following activities: - promotion of cold peers to warm peers - demotion of warm peers to cold peers - promotion of warm peers to hot peers -- demotion of hot peers to warm peers +- demotion of hot peers to warm peers. The outbound governor needs to establish and maintain: @@ -135,7 +135,7 @@ The outbound governor needs to establish and maintain: geographic locations - a target churn frequency for hot or warm changes - a target churn frequency for warm or cold changes -- a target churn frequency for cold or unknown changes +- a target churn frequency for cold or unknown changes. ![peer-discovery](https://ucarecdn.com/b6bae79e-5960-4d4e-9f6c-993a100b01c3/) From 67857f2a2b07f1118958e25c87d4e8410083e488 Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Wed, 3 Apr 2024 16:01:57 +0300 Subject: [PATCH 06/19] Update 05-cardano-entropy.mdx and merge with nonce explainer --- .../04-explore-cardano/05-cardano-entropy.mdx | 105 +++++++++++++++--- 1 file changed, 92 insertions(+), 13 deletions(-) diff --git a/docs/04-explore-cardano/05-cardano-entropy.mdx b/docs/04-explore-cardano/05-cardano-entropy.mdx index 2b39ea4f..e52c7a56 100644 --- a/docs/04-explore-cardano/05-cardano-entropy.mdx +++ b/docs/04-explore-cardano/05-cardano-entropy.mdx @@ -3,37 +3,116 @@ title: Cardano entropy metaTitle: Cardano entropy --- -## Cardano's evolution towards a fully decentralized entity +**Cardano's evolution towards a fully decentralized entity** The Cardano blockchain has transitioned from a federated system run only by 8 nodes in July 2020, to its present state where block production is fully decentralized. The final part of this transition happened on March 31st, 2021 (D=0 Day), a major milestone in Cardano's journey. As of that date, 100% of block production is the responsibility of stake pool operators (SPOs). -### The entropy parameter +## The entropy parameter -A truly decentralized state means that we can neither predict nor influence blockchain events going forward. In other words, all future on-chain events must be completely unpredictable. To ensure this, Cardano provides an additional entropy mechanism that can be used to ensure the true randomness of the system. True randomness lies at the core of any complex cryptographic system. For a cryptographic environment such as the Cardano blockchain to work, and to be trusted by the community as truly decentralized and fair, there needs to exist a source of true, unpredictable randomness that ensures that the chain's future direction cannot be manipulated by anyone with knowledge of the past. +A truly decentralized state means that no one can neither predict nor influence blockchain events going forward. In other words, all future on-chain events must be completely unpredictable. To ensure this, Cardano provides an additional entropy mechanism that can be used to ensure the true randomness of the system. True randomness lies at the core of any complex cryptographic system. For a cryptographic environment such as the Cardano blockchain to work, and to be trusted by the community as truly decentralized and fair, there needs to exist a source of true, unpredictable randomness that ensures that the chain's future direction cannot be manipulated by anyone with knowledge of the past. -Cardano's source of randomness is given through the entropy parameter. This represents something unpredictable outside the Cardano ecosystem and ensures that nobody could “rig” the randomness of the blockchain. The value of this parameter was calculated based on events that could not have been known in advance, or that anyone could have had insider information about. +Cardano's source of randomness is given through the entropy parameter. This represents something unpredictable outside the Cardano ecosystem and ensures that nobody could 'rig' the randomness of the blockchain. The value of this parameter was calculated based on events that could not have been known in advance, or that anyone could have had insider information about. -The parameter will be updated during the epoch starting on April 5, 2021, and determined by the hash of the last block prior to **Wednesday, April 7, 15:44:51 UTC = slot 151200 of epoch 258;** with this hash value appearing in the first block of slot 151200 or later. +The parameter was updated during the epoch starting on April 5, 2021, and determined by the hash of the last block before **Wednesday, April 7, 15:44:51 UTC = slot 151200 of epoch 258;** with this hash value appearing in the first block of slot 151200 or later. -### Cardano's entropy addition mechanism +## Cardano's entropy addition mechanism To understand how the entropy addition mechanism works it is vital to first understand how fully decentralized block production works and how the new transition nonce will affect this process. -The Ouroboros protocol determines which pools are elected as block producers via an evolving sequence of leadership nonces (cryptographic seeds used to generate a sequence of values using a repeatable random number generation algorithm). These nonces set the schedule for block production. Each leader nonce determines this schedule for a complete 120-hour epoch, during which the nonce governs the choice of stake pools to lead the creation of each block. The leadership nonces and stake distributions evolve in unison to provide the fundamental ledger properties required. +The Ouroboros protocol determines which pools are elected as block producers via an evolving sequence of leadership nonces (cryptographic seeds used to generate a sequence of values using a repeatable random number generation algorithm). These nonces set the schedule for block production. Each leader nonce determines this schedule for a complete 120-hour epoch, during which the nonce governs the choice of stake pools to lead the creation of each block. The leadership nonces and stake distributions evolve in unison to provide the fundamental ledger properties required. -### The transition nonce +## The transition nonce -Just after March 31st, we added a transition nonce to the running leadership nonce. The transition nonce must rely on random values (which are introduced via on-chain transactions) that cannot be accurately predicted when the stake distribution for the April 10 epoch is settled. This places special emphasis on transactions appearing in the blockchain between the 12-hour mark — when the stake distribution is firmly settled — and the 42-hour mark, when the hash value will be lifted. +Just after March 31, 2021 a transition nonce was added to the running leadership nonce. The transition nonce must rely on random values (which are introduced via on-chain transactions) that cannot be accurately predicted when the stake distribution for the April 10 epoch is settled. This places special emphasis on transactions appearing in the blockchain between the 12-hour mark — when the stake distribution is firmly settled — and the 42-hour mark, when the hash value will be lifted. -The transition nonce reflects entropy from a variety of external, unpredictable sources. Specifically, all transactions posted to the blockchain before **Wednesday, April 7 at 15:44:51 UTC (slot 151200 of epoch 258)** will play a notable and privileged role in Cardano's history: the transactions' accumulated hash value (reflected in the ‘previous-block hash’ from the first block created on-chain on or after this point in time) will determine the transition nonce, and hence contribute directly to Ouroboros’ perpetual cycle of randomness generation. +The transition nonce reflects entropy from a variety of external, unpredictable sources. Specifically, all transactions posted to the blockchain before **Wednesday, April 7 at 15:44:51 UTC (slot 151200 of epoch 258)** play a notable and privileged role in Cardano's history: the transactions' accumulated hash value (reflected in the ‘previous-block hash’ from the first block created on-chain on or after this point in time) determines the transition nonce, and hence contribute directly to Ouroboros’ perpetual cycle of randomness generation. -### The entropy addition mechanism +## The entropy addition mechanism In Cardano, the entropy addition mechanism works as follows: the system adds specific bitstrings on the blockchain to subsequent leadership nonces (which are the intended targets of the transition nonce). This requires public declaration of the bitstring, and explicit, cryptographically secure approval. More specifically, only a handful of digitally signed votes from genesis delegates can complete the process, and have a specific time limit to do so: votes must appear before the 48-hour mark in the epoch. -The epoch beginning on **Monday, April 5 at 21:44:51 UTC (epoch 258)** invoked the mechanism: in particular, the previous block hash appearing in the first block on or after **Wednesday, April 7 at 15:44:51 UTC (slot 151200 of epoch 258)** will determine the transition nonce; this will take place roughly 42 hours after the epoch has begun and thus leave six hours for the genesis delegates to cast their votes. Recalling the hash chain structure of the Ouroboros blockchain, this hash value depends on the entire blockchain up to that point. +The epoch beginning on **Monday, April 5 at 21:44:51 UTC (epoch 258)** invoked the mechanism: in particular, the previous block hash appearing in the first block on or after **Wednesday, April 7 at 15:44:51 UTC (slot 151200 of epoch 258)** determined the transition nonce; this took place roughly 42 hours after the epoch had begun and thus left six hours for the genesis delegates to cast their votes. Recalling the hash chain structure of the Ouroboros blockchain, this hash value depended on the entire blockchain up to that point. -The --extra-entropy argument looks different from the _extraEntropy field displayed after a transaction is created. This difference is explained in the [nonce explanation page](https://docs.cardano.org/explore-cardano/explain-nonce/). +The --extra-entropy argument looks different from the _extraEntropy field displayed after a transaction is created. This difference is explained below. + +## Explanation of the nonce value + +When using the Cardano command line interface (cardano-CLI), a user supplies a nonce for a transaction, but when they view the contents of the transaction, the nonce returned is different. + +### Steps to reproduce + +The cardano-cli governance create-update-proposal command creates an update proposal: + +``` +cardano-cli governance create-update-proposal --epoch 258 --extra-entropy d8b0ee71c3eab43750882bdc0880cf0b46a488d82e5bc9fd5b2fb3e7297bdbd4 --out-file mainnet-258-entropy.proposal $(for i in {1..7}; do echo "--genesis-verification-key-file genesis-keys/genesis$i.vkey "; done) + ``` + +The cardano-cli transaction build-raw command creates a transaction: + +``` +cardano-cli transaction build-raw --tx-in b2bdbe07d5cd4da8b8dbef9eee67ff6fb1877055d0b8309fbd4718591389eac5#0 --tx-out addr1q9jytwcggewzdn6rtfp8fwx6mlm48vae4pl5428cs3u5x82wkertsmcc7m6zve5y7dlmeaqz03jsw37ug5nc4v9l3j8q54uy5u+$((5000000 - 217553)) --fee 217553 --ttl $(cardano-cli query tip --mainnet | jq '.slot + 5000') --update-proposal-file mainnet-258-entropy.proposal --out-file tx-entropy.txbody +``` + +The cardano-cli transaction view command displays the transaction contents: + +``` +cardano-cli transaction view --tx-body-file tx-entropy.txbody +``` + +In the output, the nonce is different: + +``` +{ + "auxiliary_data": null, + "auxiliary_data_hash": null, + "certificates": [], + "era": "Mary", + "fee": 217553, + "inputs": [ + "b2bdbe07d5cd4da8b8dbef9eee67ff6fb1877055d0b8309fbd4718591389eac5#0" + ], + "mint": { + "lovelace": 0, + "policies": {} + }, + "outputs": [ + { + "address": "016445bb08465c26cf435a4274b8dadff753b3b9a87f4aa8f88479431d4eb646b86f18f6f4266684f37fbcf4027c650747dc45278ab0bf8c8e", + "amount": { + "lovelace": 4782447, + "policies": {} + } + } + ], + "update": "Update (ProposedPPUpdates (fromList [(KeyHash \"162f94554ac8c225383a2248c245659eda870eaa82d0ef25fc7dcd82\",PParams + {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"2075a095b3c844a29c24317a94a643ab8e22d54a3a3a72a420260af6\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"268cfc0b89e910ead22e0ade91493d8212f53f3e2164b2e4bef0819b\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"60baee25cbc90047e83fd01e1e57dc0b06d3d0cb150d0ab40bbfead1\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"ad5463153dc3d24b9ff133e46136028bdc1edbb897f5a7cf1b37950c\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"b9547b8a57656539a8d9bc42c008e38d9c8bd9c8adbb1e73ad529497\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"f7b341c14cd58fca4195a9b278cce1ef402dc0e06deb77e543cd1757\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing})])) (EpochNo 258)", + "validity_interval": { + "invalid_before": null, + "invalid_hereafter": 26253029 + }, + "withdrawals": [] +} +``` +The fields being compared are: + +`--extra-entropy d8b0ee71c3eab43750882bdc0880cf0b46a488d82e5bc9fd5b2fb3e7297bdbd4` + +And + +`_extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\")` + + +### Explanation + +Internally, the --extra-entropy argument is hashed using Blake2b-256 before it is placed in the update proposal transaction. This hash is applied to the binary representation, rather than the base16 representation supplied. This additional hash does not affect the quality of the entropy provided. For instance, the above example’s output can be replicated in Python with the following sequence of commands: + +``` +>>> import hashlib +>>> hashlib.blake2b(bytes.fromhex( +... "d8b0ee71c3eab43750882bdc0880cf0b46a488d82e5bc9fd5b2fb3e7297bdbd4"), +... digest_size=32).hexdigest() +'d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa' +``` From 0792fd66df8f155999e6e90c57aa3d713debe60a Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Wed, 3 Apr 2024 16:02:28 +0300 Subject: [PATCH 07/19] Delete docs/04-explore-cardano/08-explain-nonce.mdx --- docs/04-explore-cardano/08-explain-nonce.mdx | 82 -------------------- 1 file changed, 82 deletions(-) delete mode 100644 docs/04-explore-cardano/08-explain-nonce.mdx diff --git a/docs/04-explore-cardano/08-explain-nonce.mdx b/docs/04-explore-cardano/08-explain-nonce.mdx deleted file mode 100644 index bb394323..00000000 --- a/docs/04-explore-cardano/08-explain-nonce.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Explanation of the nonce value -metaTitle: Explanation of the nonce value ---- - -## Issue: -When using the Cardano command line interface (cardano-CLI), a user supplies a nonce for a transaction, but when they view the contents of the transaction, the nonce returned is different. - -## Steps to reproduce - -The cardano-cli governance create-update-proposal command creates an update proposal: - -``` -cardano-cli governance create-update-proposal --epoch 258 --extra-entropy d8b0ee71c3eab43750882bdc0880cf0b46a488d82e5bc9fd5b2fb3e7297bdbd4 --out-file mainnet-258-entropy.proposal $(for i in {1..7}; do echo "--genesis-verification-key-file genesis-keys/genesis$i.vkey "; done) - ``` - -The cardano-cli transaction build-raw command creates a transaction: - -``` -cardano-cli transaction build-raw --tx-in b2bdbe07d5cd4da8b8dbef9eee67ff6fb1877055d0b8309fbd4718591389eac5#0 --tx-out addr1q9jytwcggewzdn6rtfp8fwx6mlm48vae4pl5428cs3u5x82wkertsmcc7m6zve5y7dlmeaqz03jsw37ug5nc4v9l3j8q54uy5u+$((5000000 - 217553)) --fee 217553 --ttl $(cardano-cli query tip --mainnet | jq '.slot + 5000') --update-proposal-file mainnet-258-entropy.proposal --out-file tx-entropy.txbody -``` - -The cardano-cli transaction view command displays the transaction contents: - -``` -cardano-cli transaction view --tx-body-file tx-entropy.txbody -``` - -In the output, the nonce is different: - -``` -{ - "auxiliary_data": null, - "auxiliary_data_hash": null, - "certificates": [], - "era": "Mary", - "fee": 217553, - "inputs": [ - "b2bdbe07d5cd4da8b8dbef9eee67ff6fb1877055d0b8309fbd4718591389eac5#0" - ], - "mint": { - "lovelace": 0, - "policies": {} - }, - "outputs": [ - { - "address": "016445bb08465c26cf435a4274b8dadff753b3b9a87f4aa8f88479431d4eb646b86f18f6f4266684f37fbcf4027c650747dc45278ab0bf8c8e", - "amount": { - "lovelace": 4782447, - "policies": {} - } - } - ], - "update": "Update (ProposedPPUpdates (fromList [(KeyHash \"162f94554ac8c225383a2248c245659eda870eaa82d0ef25fc7dcd82\",PParams - {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"2075a095b3c844a29c24317a94a643ab8e22d54a3a3a72a420260af6\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"268cfc0b89e910ead22e0ade91493d8212f53f3e2164b2e4bef0819b\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"60baee25cbc90047e83fd01e1e57dc0b06d3d0cb150d0ab40bbfead1\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"ad5463153dc3d24b9ff133e46136028bdc1edbb897f5a7cf1b37950c\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"b9547b8a57656539a8d9bc42c008e38d9c8bd9c8adbb1e73ad529497\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"f7b341c14cd58fca4195a9b278cce1ef402dc0e06deb77e543cd1757\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing})])) (EpochNo 258)", - "validity_interval": { - "invalid_before": null, - "invalid_hereafter": 26253029 - }, - "withdrawals": [] -} -``` -The fields being compared are: - -`--extra-entropy d8b0ee71c3eab43750882bdc0880cf0b46a488d82e5bc9fd5b2fb3e7297bdbd4` - -And - -`_extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\")` - - -## Explanation - -Internally, the --extra-entropy argument is hashed using Blake2b-256 before it is placed in the update proposal transaction. This hash is applied to the binary representation, rather than the base16 representation supplied. This additional hash does not affect the quality of the entropy provided. For instance, the above example’s output can be replicated in Python with the following sequence of commands: - -``` ->>> import hashlib ->>> hashlib.blake2b(bytes.fromhex( -... "d8b0ee71c3eab43750882bdc0880cf0b46a488d82e5bc9fd5b2fb3e7297bdbd4"), -... digest_size=32).hexdigest() -'d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa' -``` From ce90508b9b78d972eb47e5f7f092a34c43862f29 Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Wed, 3 Apr 2024 17:28:32 +0300 Subject: [PATCH 08/19] Delete docs/04-explore-cardano/05-cardano-entropy.mdx This information is historic. The extra entropy parameter is now set to null. --- .../04-explore-cardano/05-cardano-entropy.mdx | 118 ------------------ 1 file changed, 118 deletions(-) delete mode 100644 docs/04-explore-cardano/05-cardano-entropy.mdx diff --git a/docs/04-explore-cardano/05-cardano-entropy.mdx b/docs/04-explore-cardano/05-cardano-entropy.mdx deleted file mode 100644 index e52c7a56..00000000 --- a/docs/04-explore-cardano/05-cardano-entropy.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Cardano entropy -metaTitle: Cardano entropy ---- - -**Cardano's evolution towards a fully decentralized entity** - -The Cardano blockchain has transitioned from a federated system run only by 8 nodes in July 2020, to its present state where block production is fully decentralized. The final part of this transition happened on March 31st, 2021 (D=0 Day), a major milestone in Cardano's journey. As of that date, 100% of block production is the responsibility of stake pool operators (SPOs). - -## The entropy parameter - -A truly decentralized state means that no one can neither predict nor influence blockchain events going forward. In other words, all future on-chain events must be completely unpredictable. To ensure this, Cardano provides an additional entropy mechanism that can be used to ensure the true randomness of the system. True randomness lies at the core of any complex cryptographic system. For a cryptographic environment such as the Cardano blockchain to work, and to be trusted by the community as truly decentralized and fair, there needs to exist a source of true, unpredictable randomness that ensures that the chain's future direction cannot be manipulated by anyone with knowledge of the past. - -Cardano's source of randomness is given through the entropy parameter. This represents something unpredictable outside the Cardano ecosystem and ensures that nobody could 'rig' the randomness of the blockchain. The value of this parameter was calculated based on events that could not have been known in advance, or that anyone could have had insider information about. - -The parameter was updated during the epoch starting on April 5, 2021, and determined by the hash of the last block before **Wednesday, April 7, 15:44:51 UTC = slot 151200 of epoch 258;** with this hash value appearing in the first block of slot 151200 or later. - -## Cardano's entropy addition mechanism - -To understand how the entropy addition mechanism works it is vital to first understand how fully decentralized block production works and how the new transition nonce will affect this process. - -The Ouroboros protocol determines which pools are elected as block producers via an evolving sequence of leadership nonces (cryptographic seeds used to generate a sequence of values using a repeatable random number generation algorithm). These nonces set the schedule for block production. Each leader nonce determines this schedule for a complete 120-hour epoch, during which the nonce governs the choice of stake pools to lead the creation of each block. The leadership nonces and stake distributions evolve in unison to provide the fundamental ledger properties required. - -## The transition nonce - -Just after March 31, 2021 a transition nonce was added to the running leadership nonce. The transition nonce must rely on random values (which are introduced via on-chain transactions) that cannot be accurately predicted when the stake distribution for the April 10 epoch is settled. This places special emphasis on transactions appearing in the blockchain between the 12-hour mark — when the stake distribution is firmly settled — and the 42-hour mark, when the hash value will be lifted. - -The transition nonce reflects entropy from a variety of external, unpredictable sources. Specifically, all transactions posted to the blockchain before **Wednesday, April 7 at 15:44:51 UTC (slot 151200 of epoch 258)** play a notable and privileged role in Cardano's history: the transactions' accumulated hash value (reflected in the ‘previous-block hash’ from the first block created on-chain on or after this point in time) determines the transition nonce, and hence contribute directly to Ouroboros’ perpetual cycle of randomness generation. - -## The entropy addition mechanism - -In Cardano, the entropy addition mechanism works as follows: the system adds specific bitstrings on the blockchain to subsequent leadership nonces (which are the intended targets of the transition nonce). This requires public declaration of the bitstring, and explicit, cryptographically secure approval. More specifically, only a handful of digitally signed votes from genesis delegates can complete the process, and have a specific time limit to do so: votes must appear before the 48-hour mark in the epoch. - -The epoch beginning on **Monday, April 5 at 21:44:51 UTC (epoch 258)** invoked the mechanism: in particular, the previous block hash appearing in the first block on or after **Wednesday, April 7 at 15:44:51 UTC (slot 151200 of epoch 258)** determined the transition nonce; this took place roughly 42 hours after the epoch had begun and thus left six hours for the genesis delegates to cast their votes. Recalling the hash chain structure of the Ouroboros blockchain, this hash value depended on the entire blockchain up to that point. - -The --extra-entropy argument looks different from the _extraEntropy field displayed after a transaction is created. This difference is explained below. - -## Explanation of the nonce value - -When using the Cardano command line interface (cardano-CLI), a user supplies a nonce for a transaction, but when they view the contents of the transaction, the nonce returned is different. - -### Steps to reproduce - -The cardano-cli governance create-update-proposal command creates an update proposal: - -``` -cardano-cli governance create-update-proposal --epoch 258 --extra-entropy d8b0ee71c3eab43750882bdc0880cf0b46a488d82e5bc9fd5b2fb3e7297bdbd4 --out-file mainnet-258-entropy.proposal $(for i in {1..7}; do echo "--genesis-verification-key-file genesis-keys/genesis$i.vkey "; done) - ``` - -The cardano-cli transaction build-raw command creates a transaction: - -``` -cardano-cli transaction build-raw --tx-in b2bdbe07d5cd4da8b8dbef9eee67ff6fb1877055d0b8309fbd4718591389eac5#0 --tx-out addr1q9jytwcggewzdn6rtfp8fwx6mlm48vae4pl5428cs3u5x82wkertsmcc7m6zve5y7dlmeaqz03jsw37ug5nc4v9l3j8q54uy5u+$((5000000 - 217553)) --fee 217553 --ttl $(cardano-cli query tip --mainnet | jq '.slot + 5000') --update-proposal-file mainnet-258-entropy.proposal --out-file tx-entropy.txbody -``` - -The cardano-cli transaction view command displays the transaction contents: - -``` -cardano-cli transaction view --tx-body-file tx-entropy.txbody -``` - -In the output, the nonce is different: - -``` -{ - "auxiliary_data": null, - "auxiliary_data_hash": null, - "certificates": [], - "era": "Mary", - "fee": 217553, - "inputs": [ - "b2bdbe07d5cd4da8b8dbef9eee67ff6fb1877055d0b8309fbd4718591389eac5#0" - ], - "mint": { - "lovelace": 0, - "policies": {} - }, - "outputs": [ - { - "address": "016445bb08465c26cf435a4274b8dadff753b3b9a87f4aa8f88479431d4eb646b86f18f6f4266684f37fbcf4027c650747dc45278ab0bf8c8e", - "amount": { - "lovelace": 4782447, - "policies": {} - } - } - ], - "update": "Update (ProposedPPUpdates (fromList [(KeyHash \"162f94554ac8c225383a2248c245659eda870eaa82d0ef25fc7dcd82\",PParams - {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"2075a095b3c844a29c24317a94a643ab8e22d54a3a3a72a420260af6\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"268cfc0b89e910ead22e0ade91493d8212f53f3e2164b2e4bef0819b\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"60baee25cbc90047e83fd01e1e57dc0b06d3d0cb150d0ab40bbfead1\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"ad5463153dc3d24b9ff133e46136028bdc1edbb897f5a7cf1b37950c\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"b9547b8a57656539a8d9bc42c008e38d9c8bd9c8adbb1e73ad529497\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing}),(KeyHash \"f7b341c14cd58fca4195a9b278cce1ef402dc0e06deb77e543cd1757\",PParams {_minfeeA = SNothing, _minfeeB = SNothing, _maxBBSize = SNothing, _maxTxSize = SNothing, _maxBHSize = SNothing, _keyDeposit = SNothing, _poolDeposit = SNothing, _eMax = SNothing, _nOpt = SNothing, _a0 = SNothing, _rho = SNothing, _tau = SNothing, _d = SNothing, _extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\"), _protocolVersion = SNothing, _minUTxOValue = SNothing, _minPoolCost = SNothing})])) (EpochNo 258)", - "validity_interval": { - "invalid_before": null, - "invalid_hereafter": 26253029 - }, - "withdrawals": [] -} -``` -The fields being compared are: - -`--extra-entropy d8b0ee71c3eab43750882bdc0880cf0b46a488d82e5bc9fd5b2fb3e7297bdbd4` - -And - -`_extraEntropy = SJust (Nonce \"d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa\")` - - -### Explanation - -Internally, the --extra-entropy argument is hashed using Blake2b-256 before it is placed in the update proposal transaction. This hash is applied to the binary representation, rather than the base16 representation supplied. This additional hash does not affect the quality of the entropy provided. For instance, the above example’s output can be replicated in Python with the following sequence of commands: - -``` ->>> import hashlib ->>> hashlib.blake2b(bytes.fromhex( -... "d8b0ee71c3eab43750882bdc0880cf0b46a488d82e5bc9fd5b2fb3e7297bdbd4"), -... digest_size=32).hexdigest() -'d982e06fd33e7440b43cefad529b7ecafbaa255e38178ad4189a37e4ce9bf1fa' -``` - - - From 3f4375ab9b30b54ddedd631a528d12e60c2b2d0e Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 11:25:25 +0300 Subject: [PATCH 09/19] Update 06-fee-structure.mdx --- docs/04-explore-cardano/06-fee-structure.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-explore-cardano/06-fee-structure.mdx b/docs/04-explore-cardano/06-fee-structure.mdx index 28005bc4..40de5707 100644 --- a/docs/04-explore-cardano/06-fee-structure.mdx +++ b/docs/04-explore-cardano/06-fee-structure.mdx @@ -34,7 +34,7 @@ Fees are constructed around two constants (a and b). The formula for calculating minimal fees for a transaction (tx) is a \* size(tx) + b, where: - a/b are protocol parameters -- size(tx) is the transaction size in bytes +- size(tx) is the transaction size in bytes. ## Protocol parameters (a and b) From c2cb4c8279cca1af82e3310bbdca2df24c8323b9 Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 11:33:40 +0300 Subject: [PATCH 10/19] Update 07-monetary-policy.mdx --- .../04-explore-cardano/07-monetary-policy.mdx | 27 +++++++++---------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/04-explore-cardano/07-monetary-policy.mdx b/docs/04-explore-cardano/07-monetary-policy.mdx index 8b1833fc..e835cada 100644 --- a/docs/04-explore-cardano/07-monetary-policy.mdx +++ b/docs/04-explore-cardano/07-monetary-policy.mdx @@ -3,25 +3,24 @@ title: Cardano monetary policy metaTitle: Cardano monetary policy --- -Cardano aims to achieve true decentralization with the introduction of -Voltaire. Voltaire includes decentralized voting and +Cardano achieves true decentralization with the Voltaire development phase, which includes decentralized voting and treasury systems to empower the community to influence Cardano's evolution, and provide a funding mechanism to transform Cardano into a self-funded, self-sustainable environment. -True decentralization does come with its own set of challenges, as factors such +Decentralization does come with its own set of challenges, as factors such as security, performance, stability, sustainability, fairness, and crucially, economic viability come into play. Maintaining, developing, and improving a blockchain project requires ongoing -monetary support. When Voltaire is implemented, the Treasury will perform this -function, and funding for new features, improvements, etc. will be allocated +monetary support. With Voltaire, the treasury performs this +function, and funding for new features, improvements, etc. is allocated through a decentralized voting system. ## Stake pools The principles of decentralization and fairness drive Cardano's development. -Cardano wants to offer equal opportunities to anyone who wishes to become part +Cardano offers equal opportunities to anyone who wishes to become part of the network by running a stake pool. But the very freedom to participate opens up the possibility of unfair advantage posed by larger stake pool operators. This presents the challenge of maintaining the integrity of the chain @@ -44,8 +43,8 @@ delegated uniformly to the k most attractive pools. Cardano's monetary policy addresses two issues: -- The necessity to offer rewards for people who participate in the network -- Funding the treasury +- the necessity to offer rewards for people who participate in the network +- funding the treasury. **Rewards** @@ -62,7 +61,7 @@ Staking rewards for delegators and stake pool operators come from two sources: treasury, and the rest is used as epoch rewards. This system is designed to ensure that the portion of rewards taken from the -reserves is high at the beginning, when transaction numbers are still relatively +reserves is high at the beginning when transaction numbers are still relatively low. This incentivizes early adopters to move quickly to benefit from high initial rewards. Over time, and as the number of transactions increases, additional fees will compensate for smaller reserves. @@ -71,20 +70,20 @@ This mechanism also ensures that available rewards are predictable and do not vary dramatically. Instead, rewards change gradually. The fixed percentage taken from remaining reserves every epoch guarantees a smooth exponential decline. -**Funding the Treasury** +**Funding the treasury** -The Treasury's goal is the provision of funds to develop Cardano activities +The treasury's goal is the provision of funds to develop Cardano activities through a voting process. This necessitates a process whereby funds are -regularly sent to the Treasury to ensure that funds are always available. +regularly sent to the treasury to ensure that funds are always available. ## Policy rationale for the ρ and τ values A lot of thought was put into determining what the values for ρ (fixed -percentage) and τ (funds going into the Treasury) should be. +percentage) and τ (funds going into the treasury) should be. **Calculating ρ** -While searching for the right ρ value, the team faced a quandary: A higher value would mean higher rewards for everybody initially, and the Treasury would fill faster. But higher values of ρ would also mean that the reserves would deplete faster. Paying high rewards and incentivizing early adopters is a crucial consideration, but so is to offer a long term perspective for all stakeholders. Therefore, the solution to this quandary requires a tradeoff between these two issues. +While searching for the right ρ value, the team faced a quandary: A higher value would mean higher rewards for everybody initially, and the treasury would fill faster. But higher values of ρ would also mean that the reserves would deplete faster. Paying high rewards and incentivizing early adopters is a crucial consideration, but so is to offer a long-term perspective for all stakeholders. Therefore, the solution to this quandary requires a tradeoff between these two issues. Adopting an exponential decay approach to prevent Cardano’s reserve from running out makes sense in this situation. From c62dd1c40582a54735657a60ceca65568cf614ea Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 11:52:46 +0300 Subject: [PATCH 11/19] Update 09-time.mdx --- docs/04-explore-cardano/09-time.mdx | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/04-explore-cardano/09-time.mdx b/docs/04-explore-cardano/09-time.mdx index 5c57baec..8772e50d 100644 --- a/docs/04-explore-cardano/09-time.mdx +++ b/docs/04-explore-cardano/09-time.mdx @@ -40,7 +40,7 @@ In the current context, determinism means that a given transaction has a 'fixed Blockchains are based on the principle of replicating a fixed sequence of transactions (grouped in blocks) to reach a consensus about the state of the world. All blockchains have *historical* determinism, meaning that transactions in the chain have a fixed effect, else the results of validating the chain would be non-deterministic, which would break consensus. -But few blockchains have *prospective* determinism, meaning that a transaction that has not yet been added to the chain does have a fixed effect (or won't apply). Cardano does feature prospective determinism (with the current exception of pointer addresses, which are proposed to be removed in this [CIP](https://github.com/cardano-foundation/CIPs/pull/374)). You can also find out more about [Cardano's transaction cost determinism here](https://docs.cardano.org/smart-contracts/plutus/transaction-costs-determinism/). +But few blockchains have *prospective* determinism, meaning that a transaction that has not yet been added to the chain does have a fixed effect (or won't apply). Cardano does feature prospective determinism. You can also find out more about [Cardano's transaction cost determinism here](https://docs.cardano.org/smart-contracts/plutus/transaction-costs-determinism/). On blockchains that do not have prospective determinism users cannot know how much gas fees they need to pay for transactions which then results in such users overpaying for transactions. The lack of prospective determinism is also why a risk exists that a transaction on such blockchains can fail while also consuming lots of gas. @@ -49,11 +49,10 @@ On blockchains that do not have prospective determinism users cannot know how mu Prospective determinism is a very powerful feature of Cardano, for multiple reasons: * Users know, ahead of time, what a transaction will do, so there are no surprises. This is particularly relevant for scripts because users know exactly: - * how the scripts will behave, and * how much execution budget is needed. * Proposed transactions can safely be processed in parallel. This parallelism is one of the reasons for Hydra's speed. -* Because users know in advance whether a transaction will fail or not, script failures can be punished harshly (because they will never happen to non-malicious users) +* Because users know in advance whether a transaction will fail or not, script failures can be punished harshly (because they will never happen to non-malicious users). * Broadly, it makes interacting with, and evolving the blockchain easier and more predictable. Prospective determinism of transactions requires that every part of transaction validation, including script execution, is completely deterministic. This is ultimately why Cardano cannot have non-deterministic operations in scripts. @@ -66,7 +65,7 @@ Plutus scripts get access to the transaction validity range, defined by its crea The script can assume that the actual time of validation is in this range. Otherwise, the transaction will fail in [phase 1](https://iohk.io/en/blog/posts/2021/09/07/no-surprises-transaction-validation-part-2/) before script execution. This ensures determinism since the script will _always_ see the same piece of information (the validity range) regardless of when the script is validated, so the behavior will be the same. -The limits of the validity interval are expressed in real time (POSIXTime), rather than slots, and the conversion from slots to real time is done by consensus, as discussed in the previous post. Using real time rather than slots is important because slot lengths can change at a hard fork, so assumptions based on counting slots are generally unreliable. The fact that scripts see the validity range allows the scripts to make assertions like 'the current time is before/after some given time', but it does not enable a script to make any other kind of assertion ('the second in which this transaction is validated is even', for example.) +The limits of the validity interval are expressed in real time (POSIXTime), rather than slots, and the conversion from slots to real time is done by consensus. Using real time rather than slots is important because slot lengths can change at a hard fork, so assumptions based on counting slots are generally unreliable. The fact that scripts see the validity range allows the scripts to make assertions like 'the current time is before/after some given time', but it does not enable a script to make any other kind of assertion ('the second in which this transaction is validated is even', for example.) In Alonzo's original design, the validity range covered all known uses of time, while also fitting neatly with the existing time-to-live (TTL) field. In theory, it is possible to apply the same principles to other kinds of assertions, for example – let the script rely on assertions checked in phase 1. However, this would not be easy as it implies deep structural changes to various parts of the Cardano network. And because phase 1 checks need to be valid for every node across the network, this precludes any kind of assertion that depends on some local condition, like 'Current Time'. @@ -102,8 +101,6 @@ Finally, layer 2 networks such as Hydra, can provide increased accuracy through ## Conclusion -Time _is_ a complex topic, especially in a decentralized blockchain setting. These blog posts show that there is a clear notion of on-chain time on Cardano with specific constraints and available improvement options in the longer term. +Time _is_ a complex topic, especially in a decentralized blockchain setting. There is a clear notion of on-chain time on Cardano with specific constraints and available improvement options in the longer term. On-chain time behaves in a somewhat different way from the time in traditional software. This divergence is defined in a consistent way to address system constraints while ensuring security and usability for end-users and stake pool operators. Moreover, Cardano's measure of time appears to be good enough to cover multiple use cases, even when compared to traditional finance uses. - -Join [Discord community channels](https://discord.com/channels/826816523368005654/826816523964383263) for further discussions of time handling on Cardano and potential use cases that are not mentioned here. From 9f3cb1c5cb7bc66144494aaa2a57fb35903b85f8 Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 12:26:22 +0300 Subject: [PATCH 12/19] Update 10-concurrency.mdx --- docs/04-explore-cardano/10-concurrency.mdx | 55 +++++++--------------- 1 file changed, 17 insertions(+), 38 deletions(-) diff --git a/docs/04-explore-cardano/10-concurrency.mdx b/docs/04-explore-cardano/10-concurrency.mdx index 31107562..1331ea33 100644 --- a/docs/04-explore-cardano/10-concurrency.mdx +++ b/docs/04-explore-cardano/10-concurrency.mdx @@ -3,41 +3,20 @@ title: Understanding concurrency metaTitle: Understanding concurrency --- -Concurrency may or may not improve a system’s performance, throughput, or -responsiveness. The amount of concurrency limits the maximum number of -simultaneous operations that can be performed. - -To obtain _actual_ performance improvements in a UTXO-based blockchain, -processors or other actors should be able to perform multiple actions -simultaneously. The higher the level of concurrency, the higher the maximum -possible parallelism. Such an approach then translates to performance -improvements and throughput. It also provides significant advantages over -account based systems (like Ethereum). - -## Deploying DApps on UTXO ledgers is different - -Cardano’s approach to DApp deployment is different and thus it requires a -learning curve and a different approach. This is like working with different -programming languages: there is one goal – to deploy a solution, but so many -programming languages to use for this purpose. - -Maximizing concurrency is a skill that needs to be learned: developers need to -write code in a way that severely restricts the opportunities for contention -(e.g., by avoiding shared states and accidental dependencies). The system must -then translate this concurrency into parallelism. A number of developers have -already identified ways to approach this, while others are still developing -solutions. Simply transplanting lessons learned on one blockchain will not work; -while the learning curve is a little steeper, the results make this worthwhile. - -Either way, it is important to understand that to deploy a scalable DApp on -Cardano, a developer can’t just use an adapted Ethereum contract. Cardano is -based on the UTXO model; it is not account-based which means that a single -on-chain state will not meet the concurrency property of Cardano. Instead, DApps -should split up their on-chain state across many UTXOs. This will increase the -concurrency in their application, thereby allowing higher throughput. - -To learn more about scalability, you can read -[how to design a scalable Plutus application](https://plutus-apps.readthedocs.io/en/stable/plutus/howtos/writing-a-scalable-app.html) -and to learn more about how to organise DApps on Cardano using patterns, read -the -[order book pattern](https://plutus-apps.readthedocs.io/en/stable/plutus/explanations/order-book-pattern.html). +Concurrency refers to the ability of different actors to perform work simultaneously without interfering with each other. In Cardano's Extended Unspent Transaction Output (EUTXO) model, transactions can be processed in parallel, enabling multiple operations without causing system failures. This approach enhances system throughput while maintaining the performance of individual operations. + +The EUTXO model, employed by Cardano, allows for secure and predictable execution of smart contracts. By splitting logic across different branches and utilizing multiple UTXOs, Cardano achieves greater parallelism, leading to improved scalability. + +The level of concurrency sets the limit for simultaneous operations. Developers should adopt strategies to minimize contention and translate concurrency into parallelism, which may involve a learning curve but yields significant benefits. + +:::info + +Learn more: + +- [Concurrency: Cardano smart contracts and the EUTXO model](https://www.essentialcardano.io/article/concurrency-and-all-that-cardano-smart-contracts-and-the-eutxo-model) +- [How to design a scalable Plutus application](https://plutus-apps.readthedocs.io/en/stable/plutus/howtos/writing-a-scalable-app.html) +- [About the order book pattern](https://plutus-apps.readthedocs.io/en/stable/plutus/explanations/order-book-pattern.html). + +::: + + From e9e45572f82f6e73cb596cdd916cb9311efe335c Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 12:29:49 +0300 Subject: [PATCH 13/19] Rename 12-parameter-guide.mdx to 11-parameter-guide.mdx --- .../{12-parameter-guide.mdx => 11-parameter-guide.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/04-explore-cardano/{12-parameter-guide.mdx => 11-parameter-guide.mdx} (100%) diff --git a/docs/04-explore-cardano/12-parameter-guide.mdx b/docs/04-explore-cardano/11-parameter-guide.mdx similarity index 100% rename from docs/04-explore-cardano/12-parameter-guide.mdx rename to docs/04-explore-cardano/11-parameter-guide.mdx From dc2311d47b5fdbd4398e1448f927dc9b487b5133 Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 12:30:39 +0300 Subject: [PATCH 14/19] Update and rename 11-relevant-research-papers.mdx to 12-relevant-research-papers.mdx --- ...arch-papers.mdx => 12-relevant-research-papers.mdx} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename docs/04-explore-cardano/{11-relevant-research-papers.mdx => 12-relevant-research-papers.mdx} (99%) diff --git a/docs/04-explore-cardano/11-relevant-research-papers.mdx b/docs/04-explore-cardano/12-relevant-research-papers.mdx similarity index 99% rename from docs/04-explore-cardano/11-relevant-research-papers.mdx rename to docs/04-explore-cardano/12-relevant-research-papers.mdx index 892830a4..2dd57659 100644 --- a/docs/04-explore-cardano/11-relevant-research-papers.mdx +++ b/docs/04-explore-cardano/12-relevant-research-papers.mdx @@ -22,7 +22,7 @@ scalability, and governance of a pioneering blockchain environment. Relevant research papers and specifications according to the Cardano development roadmap are outlined below. -### Byron +## Byron A period dedicated to building a foundational federated network that enabled the purchase and sale of ada. The network ran the proof-of-stake Ouroboros consensus @@ -44,7 +44,7 @@ protocol. [Small Step Semantics for Cardano](https://github.com/input-output-hk/cardano-ledger/releases/latest/download/small-step-semantics.pdf) -### Shelley +## Shelley A period of growth and development for the network focused on ensuring greater decentralization, which will lead to enhanced security and a more robust @@ -72,7 +72,7 @@ environment once the majority of nodes are run by network participants. [A Specification of the Non-Integral Calculations in the Shelley Ledger](https://github.com/input-output-hk/cardano-ledger/releases/latest/download/non-integer-calculations.pdf) -### Goguen +## Goguen The Goguen era will introduce smart-contract functionality to build decentralized applications while supporting multi-functional assets, fungible, @@ -107,7 +107,7 @@ Multi-Asset Implementation](https://github.com/input-output-hk/cardano-ledger/re [A Formal Specification of the Cardano Ledger integrating Plutus Core](https://github.com/input-output-hk/cardano-ledger/releases/latest/download/alonzo-ledger.pdf "A Formal Specification of the Cardano Ledger integrating Plutus Core") -### Basho +## Basho An era of optimization, improving the scalability and interoperability of the network. Enhancing the network performance, Basho will introduce _sidechains_, @@ -132,7 +132,7 @@ potential to extend the network’s capabilities. [Formal Specification of the Cardano Ledger for the Babbage era](https://github.com/input-output-hk/cardano-ledger/releases/latest/download/babbage-ledger.pdf "Formal Specification of the Cardano Ledger for the Babbage era") -### Voltaire +## Voltaire A development era enabling the Cardano network to become a self-sustaining system. Voltaire will introduce a voting and treasury system that will enable From e65ff3c6552c1e1fe9d97e8c38db004761984da9 Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 14:29:22 +0300 Subject: [PATCH 15/19] Update docs/04-explore-cardano/03-cardano-architecture.mdx Co-authored-by: NeilBurgess42 --- docs/04-explore-cardano/03-cardano-architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-explore-cardano/03-cardano-architecture.mdx b/docs/04-explore-cardano/03-cardano-architecture.mdx index 638b4ff4..db810d85 100644 --- a/docs/04-explore-cardano/03-cardano-architecture.mdx +++ b/docs/04-explore-cardano/03-cardano-architecture.mdx @@ -43,7 +43,7 @@ Nodes are responsible for: The `cardano-node` is the top level Cardano component that consists of the other subsystems, of which the most significant are [consensus](https://github.com/IntersectMBO/ouroboros-consensus?tab=readme-ov-file#ouroboros-consensus), -[ledger](https://github.com/IntersectMBO/cardano-ledger?tab=readme-ov-file#cardano-ledger) +[ledger](https://github.com/IntersectMBO/cardano-ledger?tab=readme-ov-file#cardano-ledger), and [networking](https://github.com/IntersectMBO/ouroboros-network?tab=readme-ov-file#ouroboros-network) with ancillary configuration, CLI, logging, and monitoring. ### Node-to-node IPC protocol From 9b9fd9dac77e8b4ad8ea6eeefee598ff1dae802b Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 14:29:31 +0300 Subject: [PATCH 16/19] Update docs/04-explore-cardano/03-cardano-architecture.mdx Co-authored-by: NeilBurgess42 --- docs/04-explore-cardano/03-cardano-architecture.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-explore-cardano/03-cardano-architecture.mdx b/docs/04-explore-cardano/03-cardano-architecture.mdx index db810d85..53cacfba 100644 --- a/docs/04-explore-cardano/03-cardano-architecture.mdx +++ b/docs/04-explore-cardano/03-cardano-architecture.mdx @@ -139,7 +139,7 @@ to integrate Cardano with other applications and systems. ## Cardano DB Sync -The cardano node stores only the blockchain itself and the associated information +The Cardano node stores only the blockchain itself and the associated information needed to validate the blockchain. This design principle is about minimizing code complexity (and reducing computational cost and resource use) to keep the node's local interfaces as minimal as possible and to use external clients to From 48d26d8834196c6de2869e974b443c66eb4de3eb Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 14:29:49 +0300 Subject: [PATCH 17/19] Update docs/04-explore-cardano/04-cardano-network/index.mdx Co-authored-by: NeilBurgess42 --- docs/04-explore-cardano/04-cardano-network/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-explore-cardano/04-cardano-network/index.mdx b/docs/04-explore-cardano/04-cardano-network/index.mdx index 56af2194..c27e9a73 100644 --- a/docs/04-explore-cardano/04-cardano-network/index.mdx +++ b/docs/04-explore-cardano/04-cardano-network/index.mdx @@ -142,7 +142,7 @@ communication is canceled in the following scenarios: - when either side receives a message that is not expected according to the protocol. -All mini protocols based on this framework include the following information in +All mini-protocols based on this framework include the following information in their description: - an informal description of the protocol From 731c79f046d3fda7c28475b1e270ec732567048c Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 14:29:56 +0300 Subject: [PATCH 18/19] Update docs/04-explore-cardano/04-cardano-network/index.mdx Co-authored-by: NeilBurgess42 --- docs/04-explore-cardano/04-cardano-network/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-explore-cardano/04-cardano-network/index.mdx b/docs/04-explore-cardano/04-cardano-network/index.mdx index c27e9a73..4d2aca55 100644 --- a/docs/04-explore-cardano/04-cardano-network/index.mdx +++ b/docs/04-explore-cardano/04-cardano-network/index.mdx @@ -165,7 +165,7 @@ do not access the internal state of the node. ### Request response protocol -The request esponse protocol is polymorphic in the request and response data +The request response protocol is polymorphic in the request and response data that is being transmitted. This means that there are different possible applications of this protocol and the application of the protocol determines the types of requests sent and responses received. From a8c3dea324acf5194e5040da1048a0a3f36c1933 Mon Sep 17 00:00:00 2001 From: olgahryniuk <67585499+olgahryniuk@users.noreply.github.com> Date: Thu, 4 Apr 2024 15:07:46 +0300 Subject: [PATCH 19/19] Update 09-time.mdx --- docs/04-explore-cardano/09-time.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/04-explore-cardano/09-time.mdx b/docs/04-explore-cardano/09-time.mdx index 8772e50d..4ad69397 100644 --- a/docs/04-explore-cardano/09-time.mdx +++ b/docs/04-explore-cardano/09-time.mdx @@ -40,7 +40,7 @@ In the current context, determinism means that a given transaction has a 'fixed Blockchains are based on the principle of replicating a fixed sequence of transactions (grouped in blocks) to reach a consensus about the state of the world. All blockchains have *historical* determinism, meaning that transactions in the chain have a fixed effect, else the results of validating the chain would be non-deterministic, which would break consensus. -But few blockchains have *prospective* determinism, meaning that a transaction that has not yet been added to the chain does have a fixed effect (or won't apply). Cardano does feature prospective determinism. You can also find out more about [Cardano's transaction cost determinism here](https://docs.cardano.org/smart-contracts/plutus/transaction-costs-determinism/). +But few blockchains have *prospective* determinism, meaning that a transaction that has not yet been added to the chain does have a fixed effect (or won't apply). Cardano does feature prospective determinism. On blockchains that do not have prospective determinism users cannot know how much gas fees they need to pay for transactions which then results in such users overpaying for transactions. The lack of prospective determinism is also why a risk exists that a transaction on such blockchains can fail while also consuming lots of gas.