Skip to content

Technical Architecture

Jump to bottom
Arnaud Bailly edited this page Jun 7, 2021 · 7 revisions

Technical Architecture

This document is constant work-in-progress which serves as raw material for more formal documents that would be published as part of the release lifecycle of Hydra node.

Principles

TODO: This should really be ADRs?

With-pattern for Duplex Channels

  • With pattern or bracket pattern is a functional programming idiom, a particular instance of Continuation-Passing Style, whereby one component that controls some resource that is consumed by another component of the system, is created via a function that takes as argument a function consuming the resource, instead of returning it.
  • We use this pattern to provide implementations of various interfaces to components of the system with which the Node exchanges messages:

Broadcast Network

  • Hydra nodes always broadcast messages over a Hydra network, expecting each message to reach every node without having explicit addressing
  • While unicast or multicast appear to be a better fit and less wasteful of network resources, systematic broadcasting has several advantages:
    • It does not seem to save much messages as broadcasting AckTx messages removes the need to send a ConfTx: Each node can confirm transactions on its own
    • Coupled with a fully-connected network topology, it simplifies messages handling and routing: Simply send everything to everyone and handle any message received
    • It makes it simpler to build non-fully connected networks, and more generally accomodate for various network topologies: Nodes act both as destinary of messages and relays to propagate messages over the network until they reach all interested parties.

      NOTE: This is directly inspired by how transactions are propagated between cardano-node using ouroboros TxSubmission protocol

Hydra Node

The following diagram represents the internal structure of the HydraNode and the interactions between its components.

Legend:

  • Grayed boxes represent components which are not developed yet
  • Black boxes represent components which are expected to be used as black box, eg. without any knowledge of their inner workings.
  • Arrows depict the flow of data (Requests, messages, responses...)
  • We represent some components that are not part of the Hydra node proper for legibility's sake

Hydra Node

  • The HydraNode is a handle to all other components' handles
  • This handle is used by the main loop to processNextEvent and processEffect

Head Logic

  • This component implements the Head Protocol's state machine as a pure function.
  • The protocol is described in two parts in the Hydra paper:
    • One part detailing how the Head deals with clients input, eg. ClientRequest:
    • Another part detailing how the Head reacts to peers input provided by the network, eg. HydraMessage:

OnChain Client

  • The OnChain client implements the Head-Chain Interaction part of the protocol:
  • Incoming and outgoing on-chain transactions are modelled as an OnChainTx data type that abstracts away the details of the structure of the transaction.
  • The ChainEffect produced by the Head Logic's state machine represents a transaction to be posted on-chain. The node delegates the actual posting of the transaction to a OnChain handle wrapping a single postTx function.
  • Incoming transactions from the chain are handled using a similar Callback function which is passed to the actual chain client upon initialisation of the node.
    • This function wraps incoming OnChainTx as ChainEvent and put them into the Event queue for later processing by the Node's Reactive loop

Mock Chain Client

  • In order to ease the development process, we provide an idealised version of a blockchain client, implemented using 0MQ.
  • The server is implemented as a standalone executable which simply stores and forwards all transactions received to all connected clients using Pub/Sub connections.
  • As clients can come and go at any time, the server also provides a Rep type socket for clients to request past transactions

PAB Chain Client

Note: This client is not currently implemented, see the Chain Client and Smart Contracts section for more details.

Network

  • The Network component provides the Node an asynchronous messaging interface to the Hydra Network, e.g to other Hydra nodes
  • Similar to the On-chain client:
    • Incoming and outgoing messages are modelled as HydraMessage data type
    • A NetworkEffect is produced by the HeadLogic to request posting of a transaction by the actual network implementation, while the latter enqueues a NetworkEvent when it receives a message from the a peer,
  • The HydraNetwork's only interface is broadcast which means all messages are sent to all Hydra peers

    NOTE: This is a departure from the protocol's description in the original paper but it's hinted at as a possible alternative to unicast on p.21's footnote.

  • We provide 2 implementations of the network, one based on the ouroboros-network framework and one based on 0MQ

    NOTE: While it is more work to maintain two implementations for the same interface, we think this cost is more than offset by the benefits this provides: Interfaces must not leak implementation details and it provides options for deployment and configuration.

Ouroboros Network

  • The Ouroboros based network layer implements a dumb FireForget protocol
  • Contrary to other protocols implemented in Ouroboros, this is a push-based protocol

ZeroMQ Network

  • The 0MQ based network

Head State

  • The main component of the Head is an interface to the Ledger which allows the head to maintain and update the state of Seen or Confirmed transactions and UTxOs according to its protocol.

Logging

  • Structured logging is implemented using IOHK monitoring framework which provides backend for contra-tracer generic logging
  • Each component defines its own tracing messages as a datatype and they are aggregated in the HydraLog datatype. Specialized Tracers can be passed around from the top-level one using contramap to peel one layer of the onion
  • Configuration of the main tracer is done via the withTracer wrapper function

Monitoring

  • Metrics and monitoring are piggy-backed on tracing events:
    • Monitoring collection is configured at start of the hydra-node
    • Traced events can be interpreted as contributing to some specific metric value without trace producers needing to be aware of how this process happens
  • Metrics are exposed using Prometheus format over URI /metrics from an HTTP server started on a configurable port.

Chain Client & Smart Contracts

Hydra Plutus Smart Contracts

  • This article provides a detailed walkthrough of the design and implementation of Hydra head protocol on-chain smart contracts
  • Those smart contracts will be embedded with a dedicated Plutus Application Backend
Clone this wiki locally