Merge pull request #589 from input-output-hk/olgahryniuk-patch-97

Updating all sections under 'Explore'

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,22 +104,26 @@ 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
 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).
 

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

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/)