packages feed

haskoin-node-2.6.1: src/Haskoin/Node.hs

-- |
-- Module      : Haskoin.Node
-- Copyright   : (c) Haskoin Developers
-- License     : MIT
-- Maintainer  : jprupp@protonmail.ch
-- Stability   : experimental
-- Portability : POSIX
--
-- A peer-to-peer node for Bitcoin (BTC) and Bitcoin Cash (BCH).
--
-- The node connects to other peers on the network, keeps a number of them
-- online, and synchronises the block chain headers, which it stores in a
-- RocksDB database. It does not download or validate full blocks or
-- transactions by itself: it publishes events and lets the application request
-- whatever data it needs from the connected peers.
--
-- A node is made of two main components, which run in their own threads:
--
-- * The peer manager ("Haskoin.Node.PeerMgr") discovers and connects to peers,
--   performs the version handshake, pings peers to measure latency, and
--   disconnects peers that misbehave, are too slow or have been connected for
--   too long.
--
-- * The chain ("Haskoin.Node.Chain") downloads block headers from peers,
--   connects them to the best chain, and stores them in the database. It
--   follows the announcements of new blocks, whether they come as headers or
--   as inventory, and polls peers when it has heard nothing for a while.
--
-- Everything that happens is published as a 'NodeEvent' to the 'Publisher'
-- given in 'NodeConfig'. Subscribe to it to learn about new best blocks, peers
-- connecting and disconnecting, and every message received from an online
-- peer, such as inventory announcements, blocks and transactions. A
-- subscription is an unbounded queue: the node does not wait for a slow
-- subscriber, so a subscriber that falls behind holds every event it has not
-- read in memory.
--
-- = Purpose
--
-- Talking to the Bitcoin network well is a job of its own, independent of what
-- a program does with the data. Peers have to be found, kept, measured and
-- dropped; messages have to be parsed defensively, because anyone can connect;
-- and the header chain, the backbone that tells which blocks are real, has to
-- be followed through reorganisations. This library does that job and nothing
-- else, so that wallets, indexers and monitors can be built on it without each
-- reimplementing it.
--
-- = Design
--
-- * __Headers only.__ The node syncs block headers, which are small and enough
--   to know the best chain, and leaves blocks and transactions to the
--   application. Applications differ wildly in what they need: an indexer wants
--   every block, a wallet a few transactions, a monitor nothing but
--   announcements. Fetching on request serves all of them.
--
-- * __Events, not callbacks.__ Everything the node learns is published. The
--   node does not know who listens or how many listeners there are, and a slow
--   listener cannot reach into the node's own state.
--
-- * __Processes with one job each.__ The peer manager, the chain and every
--   peer connection are separate NQE processes. Each owns its state and is fed
--   by messages, which keeps the concurrency easy to reason about and lets a
--   failing peer die without disturbing the rest.
--
-- * __Plain 'IO'.__ Every function runs in 'IO', without monad transformers
--   or @MonadIO@ and @MonadUnliftIO@ constraints. The types say exactly what
--   runs, GHC has nothing to specialise, and the long-running loops of the node
--   cannot leak memory through an unspecialised dictionary (see
--   "Haskoin.Node.Loop"). Programs that work in their own monad call the node
--   with @liftIO@.
--
-- * __Trust nothing from the network.__ Peers are strangers. Every message is
--   checked against size limits before it is read, invalid input disconnects
--   the peer, every block must hold the transactions its header commits to
--   ("Haskoin.Node.Block"), and a peer cannot make the node allocate memory
--   faster than it can work. The node's subscribers are another matter: the
--   node does not wait for them, so a subscriber must keep up with what it
--   asked for.
--
-- = Example
--
-- @
-- main :: IO ()
-- main =
--   'withLogger' 'LevelInfo' $ \\logger ->
--   withDB "\/tmp\/node" def{createIfMissing = True} $ \\db ->
--   'withPublisher' $ \\pub ->
--   'withSubscription' pub $ \\events -> do
--     let cfg =
--           'NodeConfig'
--             { maxPeers = 8,
--               db = db,
--               cf = Nothing,
--               peers = [],
--               discover = True,
--               address = NetworkAddress 0 (sockToHostAddress (SockAddrInet 0 0)),
--               net = btc,
--               pub = pub,
--               timeout = 120,
--               maxPeerLife = 48 * 3600,
--               connect = 'withConnection',
--               logger = logger
--             }
--     'withNode' cfg $ \\node -> forever $
--       'receive' events >>= \\case
--         'ChainEvent' ('ChainBestBlock' bn) -> print bn.height
--         _ -> return ()
-- @
--
-- = Requesting data
--
-- Use 'getPeers' to list the peers that are online, then 'getBlocks',
-- 'getTxs' or 'getData' to request data from one of them. Use
-- 'chainGetBlock', 'chainGetBest' and related functions to query the headers
-- that the node has stored.
module Haskoin.Node
  ( -- * Node
    NodeConfig (..),
    NodeEvent (..),
    Node (..),
    withNode,
    withConnection,

    -- * Peers
    module Haskoin.Node.Peer,

    -- * Blocks
    module Haskoin.Node.Block,

    -- * Peer manager
    module Haskoin.Node.PeerMgr,

    -- * Chain
    module Haskoin.Node.Chain,

    -- * Logging
    module Haskoin.Node.Logger,
  )
where

import Control.Concurrent.Async (link, withAsync)
import Control.Concurrent.STM (atomically)
import Data.Functor ((<&>))
import Data.Time.Clock (NominalDiffTime)
import Database.RocksDB (ColumnFamily, DB)
import Haskoin
import Haskoin.Node.Address (withConnection)
import Haskoin.Node.Block
import Haskoin.Node.Chain
import Haskoin.Node.Logger
import Haskoin.Node.Loop (loopForever)
import Haskoin.Node.Peer
import Haskoin.Node.PeerMgr
import NQE
import Network.Socket (SockAddr)

-- | General node configuration. Passed to 'withNode'.
--
-- Connecting is a parameter ('connect') rather than hard-wired so that tests can
-- plug in simulated peers, and deployments can route through a proxy.
data NodeConfig = NodeConfig
  { -- | maximum number of connected peers allowed
    maxPeers :: !Int,
    -- | database handler
    db :: !DB,
    -- | database column family
    cf :: !(Maybe ColumnFamily),
    -- | static list of peers to connect to
    peers :: ![String],
    -- | activate peer discovery
    discover :: !Bool,
    -- | network address for the local host
    address :: !NetworkAddress,
    -- | network constants
    net :: !Network,
    -- | node events are sent to this publisher
    pub :: !(Publisher NodeEvent),
    -- | seconds without a response before a peer is considered unresponsive
    -- and disconnected; also used as timeout for handshakes and for syncing
    -- headers
    timeout :: !NominalDiffTime,
    -- | disconnect a peer after it has been connected for this many seconds,
    -- so that connections rotate over time
    maxPeerLife :: !NominalDiffTime,
    -- | how to open a connection to a peer address; normally
    -- 'withConnection', but can be replaced to use a proxy or for testing
    connect :: !(SockAddr -> WithConnection),
    -- | log messages here
    logger :: !Logger
  }

-- | A running node, as given by 'withNode'. Use its fields to query and
-- control the peer manager and the chain.
data Node = Node
  { -- | the peer manager
    peerMgr :: !PeerMgr,
    -- | the block header chain
    chain :: !Chain
  }

-- | Events published by the node to the 'Publisher' in 'NodeConfig'.
data NodeEvent
  = -- | something happened to the header chain, such as a new best block
    ChainEvent !ChainEvent
  | -- | a peer connected, disconnected or sent a message
    PeerEvent !PeerEvent
  deriving stock (Eq)

-- | Forward events from the chain to the node publisher, telling the peer
-- manager about every new best block height so that it can tell peers apart
-- that are behind.
chainEvents ::
  PeerMgr -> Inbox ChainEvent -> Publisher NodeEvent -> IO ()
chainEvents mgr input output = loopForever $ do
  event <- receive input
  case event of
    ChainBestBlock bb -> peerMgrBest mgr bb.height
    _ -> return ()
  publish (ChainEvent event) output

-- | Route events from peers to the peer manager and chain, and publish them
-- to the application.
--
-- A message from a peer is handled to completion before the peer may send
-- another one past its small allowance of pending messages (see
-- 'maxPendingMessages'), so that the node's own queues cannot grow faster
-- than it can work. Address, header and inventory messages are only taken
-- from peers that are online: the handshake is complete and the peer is not
-- being disconnected. Inventory with blocks goes to the chain, which asks for
-- headers if it does not know them.
--
-- This loop never waits for the chain. The chain can take seconds over a
-- batch of headers, and a loop that waited for it held up the messages of
-- every peer: blocks and pongs piled up behind the headers, and the
-- application took peers that were delivering for stalled ones. A header or
-- inventory message is instead handed to the chain with the rest of its
-- handling, which runs when the chain is done with it (see 'chainThen'):
-- it is published to the application then, and only then counts as handled
-- for the peer's allowance. The backpressure still holds for the peer that
-- sent it, the chain's mailbox holds at most 'maxPendingMessages' messages of
-- each peer, and the messages of the other peers keep flowing. The chain
-- handles its mailbox in order, so the headers of a peer are imported in the
-- order they came. The application gets a header message only once the
-- chain has its headers, so it can look them up; other messages of the same
-- peer may reach it before.
--
-- Messages for the peer manager, which is quick, are handled the same way,
-- except @version@ and @verack@: the loop waits for those, since whether the
-- next message of that peer is taken depends on them.
--
-- Messages reach the application only from online peers, except @version@
-- and @verack@, which are the handshake itself. Bitcoin Core ignores
-- anything else a peer sends before the handshake is done, and so does the
-- node: a peer whose version may still be refused cannot feed the
-- application blocks and transactions.
peerEvents ::
  Chain -> PeerMgr -> Inbox PeerEvent -> Publisher NodeEvent -> IO ()
peerEvents ch mgr input output = loopForever $ do
  event <- receive input
  case event of
    PeerConnected p -> do
      chainPeerConnected ch p
      atomically (forward event)
    PeerDisconnected p -> do
      chainPeerDisconnected ch p
      atomically (forward event)
    PeerMessage p m -> do
      ticklePeer mgr p
      online <- isOnline p
      let done
            | handshake m || online = forward event >> peerMessageDoneSTM p
            | otherwise = peerMessageDoneSTM p
          now = atomically done
          later f = f done
      case m of
        MVersion v ->
          peerMgrVersion mgr p v >> peerMgrSync mgr >> now
        MVerAck ->
          peerMgrVerAck mgr p >> peerMgrSync mgr >> now
        MPing (Ping n) ->
          peerMgrPing mgr p n >> later (peerMgrThen mgr)
        MPong (Pong n) ->
          peerMgrPong mgr p n >> later (peerMgrThen mgr)
        MAddr (Addr ns)
          | online -> peerMgrAddrs mgr p (map snd ns) >> later (peerMgrThen mgr)
        MHeaders (Headers hs)
          | online -> chainHeaders ch p (map fst hs) >> later (chainThen ch)
        MInv (Inv ivs)
          | online,
            bhs@(_ : _) <- [BlockHash iv.invHash | iv <- ivs, isBlock iv] ->
              chainBlocksAnnounced ch p bhs >> later (chainThen ch)
        _ -> now
  where
    forward event = publishSTM (PeerEvent event) output
    isOnline p =
      getOnlinePeer mgr p <&> \case
        Just o -> o.online
        _ -> False
    isBlock iv = iv.invType `elem` [InvBlock, InvWitnessBlock]
    handshake = \case
      MVersion _ -> True
      MVerAck -> True
      _ -> False

-- | Launch node process in the foreground.
--
-- Start the chain and the peer manager in background threads, pass a 'Node'
-- handle to the given action, and stop everything when the action returns. If
-- any component fails, the exception is re-thrown in the calling thread.
withNode ::
  NodeConfig -> (Node -> IO a) -> IO a
withNode cfg action =
  withPublisher $ \peerPub ->
    withSubscription peerPub $ \peerSub ->
      withPublisher $ \chainPub ->
        withSubscription chainPub $ \chainSub ->
          withChain (chainConfig chainPub) $ \chain ->
            withPeerMgr (peerMgrConfig chain peerPub) $ \peerMgr ->
              withAsync (chainEvents peerMgr chainSub cfg.pub) $ \a1 ->
                withAsync (peerEvents chain peerMgr peerSub cfg.pub) $ \a2 -> do
                  link a1
                  link a2
                  action Node {peerMgr = peerMgr, chain = chain}
  where
    chainConfig pub =
      ChainConfig
        { db = cfg.db,
          cf = cfg.cf,
          net = cfg.net,
          pub = pub,
          timeout = cfg.timeout,
          logger = withSource "Chain" cfg.logger
        }
    peerMgrConfig chain pub =
      PeerMgrConfig
        { maxPeers = cfg.maxPeers,
          peers = cfg.peers,
          discover = cfg.discover,
          address = cfg.address,
          net = cfg.net,
          pub = pub,
          timeout = cfg.timeout,
          maxPeerLife = cfg.maxPeerLife,
          connect = cfg.connect,
          logger = withSource "PeerMgr" cfg.logger,
          lookupBlock = chainGetBlock chain
        }