Ouroboros-Network

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

Loading

• network-mux - implementation of a general network multiplexer.
• ouroboros-network-api - shared API between network and consensus components.
• 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-node and node-to-client API. It contains the implementation of outbound governor.
• ouroboros-network-mock & ouroboros-network-testing - shared testing code.
• ntp-client - an ntp client (used by cardano-wallet).
• cardano-ping - a library which implements the core functionality of cardano-cli ping command.
• cardano-client - a subscription for node-to-client which want to connect to a cardano-node.

Libraries:

• monoidal-synchronisation - a small standalone package which contains synchronisation primitives.

Ouroboros-Network Documentation

We have two documents which describe various levels of the networking layer of the Cardano Shelley implementation:

• Introduction to the design of Data Diffusion and Networking of Cardano Shelley

  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.

• The Shelley Networking Protocol

  This document is a technical specification of the networking protocol. It includes serialisation formats, necessary details of multiplexer and technical specifications of mini-protocols used by either node-to-node and node-to-client flavours of the protocol.

• Haddock documentation

• Official Cardano Documentation

  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.

Ouroboros-Network API

The API consists of three layers:

• mini-protocol API's, 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 typed Peer type when one is using runPeer or runPeerPipelined function and each protocol exposes a function to create it (e.g. Ouroboros.Network.Protocol.ChainSync.Client.chainSyncClientPeer)

• callback ptcl -> channel -> m () where ptcl is enumeration for each mini-protocol, this is either NodeToNodeProtocols or NodeToClientProtocols. 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.NodeToNode and Ouroboros.Network.NodeToClient expose V1 api which hides versioning from the caller.

Demo applications

• demo-chain-sync
• cardano-ping
• mux-demo
• demo-ping-pong
• demo-ntp-client

Instructions

To run a demo type:

cabal run <DEMO_NAME> --

After -- you will need to pass arguments, when a demo is run without arguments it will specify what arguments it needs.