Skip to content

Technical Architecture

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

Technical Architecture

NOTE: This document should be superseded by embedded documentation in the repository once PR #13 is merged

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.

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