This repository contains the core components of the network code for the Cardano node. It is a dependency when building the node from the cardano-node repository.
The following graph shows the dependency tree. The top-level package is
ouroboros-consensus-diffusion which is part of ouroboros-consensus
flowchart TD A[network-mux] --> B[network / Win32-network] M[cardano-ping] --> A D[ouroboros-network-framework] --> A D --> E[ouroboros-network-api] E --> H[typed-protocols] G --> H[typed-protocols] G --> E F[ouroboros-network] --> D F --> G[ouroboros-network-protocols] I[ouroboros-consensus-diffusion] --> F J[cardano-client] --> F K[ntp-client] --> B click A "https://input-output-hk.github.io/ouroboros-network/network-mux/" _blank click M "https://input-output-hk.github.io/ouroboros-network/cardano-ping/" _blank click D "https://input-output-hk.github.io/ouroboros-network/ouroboros-network-framework/" _blank click E "https://input-output-hk.github.io/ouroboros-network/ouroboros-network-api/" _blank click F "https://input-output-hk.github.io/ouroboros-network/ouroboros-network/" _blank click G "https://input-output-hk.github.io/ouroboros-network/ouroboros-network-protocols/" _blank click I "https://github.com/input-output-hk/ouroboros-consensus/" _blank click J "https://input-output-hk.github.io/ouroboros-network/cardano-client/" _blank click K "https://input-output-hk.github.io/ouroboros-network/ntp-client/" _blank click H "https://github.com/input-output-hk/typed-protocols/" _blank
network-mux- implementation of a general network multiplexer.
ouroboros-network-api- shared API between
ouroboros-network-framework- low-level network components, e.g. snockets, connection manager, inbound governor, handshake mini-protocol, network simulator.
ouroboros-network-protocols- implementation of all /node-to-node/ & /node-to-client/ protocols. Also contains a testing library which is implementing various applications for testing purposes.
ouroboros-network- top-level integration of all network components also defines
node-to-clientAPI. It contains the implementation of the outbound governor.
ouroboros-network-testing- shared testing code.
ntpclient (used by
cardano-ping- a library which implements the core functionality of
cardano-client- a subscription for
node-to-clientwhich wants to connect to a
monoidal-synchronisation- a small standalone package which contains synchronisation primitives.
We have two documents which describe various levels of the networking layer of the Cardano Shelley implementation:
This document explains the technical requirements and key constraints for the networking layer of the Cardano Shelley implementation of Ouroboros Praos. This is a design document.
This document is a technical specification of the networking protocol. It includes serialisation formats, necessary details of the multiplexer and technical specifications of mini-protocols used by either node-to-node and node-to-client flavours of the protocol.
Specifically the section "Explore Cardano" is helpful, since it talks about the Cardano Architecture, Cardano Design Rationale, the Cardano Network, etc. Although the Cardano documentation is less detailed, it is a good place to start and refresh some more basic concepts about Cardano.
On a biweekly basis, we publish updates on cardano-updates. We are also tracking our current work in the Ouroboros Network Project. Our quarterly goals are published in the [Cardano Node Product Backlog][cardano-node-backlog].
The API consists of three layers:
• mini-protocol APIs, which are GADTs for each mini-protocol under
Ouroboros.Network.Protocol (defined in
ouroboros-network-protocols package); this hides heavy type machinery of session types. One only needs the
Peer or [
PeerPipelined] type when one is using
runPeer or [
runPeerPipelined] function and each protocol exposes a function to create it (e.g.
chainSyncClientPeer. There is also API which allows to run a
Peer or [
PipelinedPeer] with limits (i.e. per state timeouts & per message size limits).
MiniProtocolCb. The callback is wrapped in
OuroborosApplication GADT which allows to differentiate the initiator/responder (or client/server) callbacks.
• versioning which is a map from version numbers to the above callbacks and version data (the tricky part here is that version data type can be different between different versions; there is a simple way of building this map using a semigroup). You can use
simpleSingletonVersion if your application does not depend on negotiated version data. However,
Ouroboros.Network.NodeToClient expose API which hides versioning from the caller.
InstructionsTo run a demo type:
cabal run <DEMO_NAME> --
-- you will need to pass arguments, when a demo is run without
arguments it will specify what arguments it needs.