Merge pull request #513 from input-output-hk/ch1bo/docs-api-behavior

Add a page for API Behavior
input-output-hk · Sep 28, 2022 · 23af129 · 23af129
2 parents 7b58957 + 3e11846
commit 23af129
Show file tree

Hide file tree

Showing 19 changed files with 53 additions and 35 deletions.
diff --git a/docs/core-concepts/behavior.md b/docs/core-concepts/behavior.md
@@ -0,0 +1,18 @@
+---
+sidebar_position: 3
+---
+
+# API Behavior
+
+This page documents the behavior of a `hydra-node` at the API layer. That is, how the system behaves given [ClientInputs](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-API-ClientInput.html#t:ClientInput) and what [ServerOutputs](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-API-ServerOutput.html#t:ServerOutput) are produced in response to it. See also the [API reference](https://hydra.family/head-protocol/api-reference/) for more details about individual API messages.
+
+The formalism uses [UML statechart](https://en.wikipedia.org/wiki/UML_state_machine) language where transitions are labeled: `input [condition] / output`. When two outputs (e.g. `A` and `B`) are expected we write `A,B`, while `{A,B}` denotes mutual exclusiveness of outputs.
+
+![](https://www.plantuml.com/plantuml/png/ZP6zJWCn383tF8Ldr8gz0oggG7G112UMgaEANMefSKw92zSYtftaKbrBOM3pp_UTVSuqgOswzSvi60d8jxe3fFGQkLKEOipYOWdZyHNCXPMjuptB6qpw52xXYIpkcZ0BthCQymFwBLKiQpLGmZCZAxSircNsUXLYGU_8uZoLx4_yeIM1oS2Lr9Y-U6pUqqVJPUIpwLwoYwEccylx8RhfMew4NwDdiMtQ19q5MNFqXFKpPSZCXKG8aneCmshPc4Fx51oG84f92GUe_AALiDN7a1Al76LweUm9MfiI9R1hfGYOTST2o-EHgsRCcJvsjDQJmzNsi45VvdtPinAL_z-3Jabmwzqt)
+
+[Edit this diagram](https://www.plantuml.com/plantuml/uml/ZP6zJWCn383tF8Ldr8gz0oggG7G112UMgaEANMefSKw92zSYtftaKbrBOM3pp_UTVSuqgOswzSvi60d8jxe3fFGQkLKEOipYOWdZyHNCXPMjuptB6qpw52xXYIpkcZ0BthCQymFwBLKiQpLGmZCZAxSircNsUXLYGU_8uZoLx4_yeIM1oS2Lr9Y-U6pUqqVJPUIpwLwoYwEccylx8RhfMew4NwDdiMtQ19q5MNFqXFKpPSZCXKG8aneCmshPc4Fx51oG84f92GUe_AALiDN7a1Al76LweUm9MfiI9R1hfGYOTST2o-EHgsRCcJvsjDQJmzNsi45VvdtPinAL_z-3Jabmwzqt)
+
+Not pictured is the `CommandFailed` output, which is implicit emitted whenever an input is used when no transition below applies. Also non-state-changing or life-cycle relevant inputs like `GetUTxO` are not mentioned, as well as outputs like `Greetings`, `InvalidInput`, `PeerConnected`, `PeerDisconnected` and `GetUTxOResponse`.
+
+A special case is the `RolledBack` output. This means that the chain rolled back, but it includes no particular information in which state the Hydra Head is now. Frankly, this is quite hard to use - we will improve on this!, but should not invalidate any of the behavioral rules.
+
diff --git a/hydra-node/hydra-node.cabal b/hydra-node/hydra-node.cabal
@@ -86,7 +86,7 @@ library
     Hydra.Chain.Direct.Tx
     Hydra.Chain.Direct.Util
     Hydra.Chain.Direct.Wallet
-    Hydra.ClientInput
+    Hydra.API.ClientInput
     Hydra.ContestationPeriod
     Hydra.Crypto
     Hydra.HeadLogic
@@ -111,7 +111,7 @@ library
     Hydra.Node.Version
     Hydra.Options
     Hydra.Party
-    Hydra.ServerOutput
+    Hydra.API.ServerOutput
     Hydra.Snapshot
 
   other-modules:   Paths_hydra_node
@@ -271,7 +271,7 @@ test-suite tests
     Hydra.Chain.Direct.TimeHandleSpec
     Hydra.Chain.Direct.TxSpec
     Hydra.Chain.Direct.WalletSpec
-    Hydra.ClientInputSpec
+    Hydra.API.ClientInputSpec
     Hydra.CryptoSpec
     Hydra.FireForgetSpec
     Hydra.HeadLogicSpec
@@ -287,7 +287,7 @@ test-suite tests
     Hydra.NodeSpec
     Hydra.OptionsSpec
     Hydra.PartySpec
-    Hydra.ServerOutputSpec
+    Hydra.API.ServerOutputSpec
     Hydra.SnapshotStrategySpec
     Paths_hydra_node
     Spec

diff --git a/hydra-node/src/Hydra/ClientInput.hs → hydra-node/src/Hydra/API/ClientInput.hs b/hydra-node/src/Hydra/ClientInput.hs → hydra-node/src/Hydra/API/ClientInput.hs
@@ -1,6 +1,6 @@
 {-# LANGUAGE UndecidableInstances #-}
 
-module Hydra.ClientInput where
+module Hydra.API.ClientInput where
 
 import Hydra.Prelude
 

diff --git a/hydra-node/src/Hydra/API/Server.hs b/hydra-node/src/Hydra/API/Server.hs
@@ -17,12 +17,12 @@ import Control.Concurrent.STM.TChan (newBroadcastTChanIO, writeTChan)
 import Control.Concurrent.STM.TVar (TVar, modifyTVar', newTVarIO, readTVar)
 import Control.Exception (IOException)
 import qualified Data.Aeson as Aeson
-import Hydra.ClientInput (ClientInput)
+import Hydra.API.ClientInput (ClientInput)
 import Hydra.Ledger (IsTx (..))
 import Hydra.Logging (Tracer, traceWith)
 import Hydra.Network (IP, PortNumber)
 import Hydra.Party (Party)
-import Hydra.ServerOutput (ServerOutput (Greetings, InvalidInput))
+import Hydra.API.ServerOutput (ServerOutput (Greetings, InvalidInput))
 import Network.WebSockets (
   acceptRequest,
   receiveData,

diff --git a/hydra-node/src/Hydra/ServerOutput.hs → hydra-node/src/Hydra/API/ServerOutput.hs b/hydra-node/src/Hydra/ServerOutput.hs → hydra-node/src/Hydra/API/ServerOutput.hs
@@ -1,9 +1,9 @@
 {-# LANGUAGE UndecidableInstances #-}
 
-module Hydra.ServerOutput where
+module Hydra.API.ServerOutput where
 
+import Hydra.API.ClientInput (ClientInput (..))
 import Hydra.Chain (PostChainTx, PostTxError)
-import Hydra.ClientInput (ClientInput (..))
 import Hydra.Crypto (MultiSignature)
 import Hydra.Ledger (IsTx, UTxOType, ValidationError)
 import Hydra.Network (Host)

diff --git a/hydra-node/src/Hydra/HeadLogic.hs b/hydra-node/src/Hydra/HeadLogic.hs
@@ -27,7 +27,7 @@ import Hydra.Chain (
   PostChainTx (..),
   PostTxError,
  )
-import Hydra.ClientInput (ClientInput (..))
+import Hydra.API.ClientInput (ClientInput (..))
 import Hydra.ContestationPeriod
 import Hydra.Crypto (HydraKey, Signature, SigningKey, aggregateInOrder, sign, verify)
 import Hydra.Ledger (
@@ -41,7 +41,7 @@ import Hydra.Ledger (
  )
 import Hydra.Network.Message (Message (..))
 import Hydra.Party (Party (vkey))
-import Hydra.ServerOutput (ServerOutput (..))
+import Hydra.API.ServerOutput (ServerOutput (..))
 import Hydra.Snapshot (ConfirmedSnapshot (..), Snapshot (..), SnapshotNumber, getSnapshot)
 
 -- * Types

diff --git a/hydra-node/src/Hydra/Logging/Monitoring.hs b/hydra-node/src/Hydra/Logging/Monitoring.hs
@@ -26,7 +26,7 @@ import Hydra.Logging.Messages (HydraLog (..))
 import Hydra.Network (PortNumber)
 import Hydra.Network.Message (Message (ReqTx))
 import Hydra.Node (HydraNodeLog (BeginEvent, EndEffect, EndEvent))
-import Hydra.ServerOutput (ServerOutput (..))
+import Hydra.API.ServerOutput (ServerOutput (..))
 import Hydra.Snapshot (Snapshot (confirmed))
 import System.Metrics.Prometheus.Http.Scrape (serveMetrics)
 import System.Metrics.Prometheus.Metric (Metric (CounterMetric, HistogramMetric))

diff --git a/hydra-node/test/Hydra/ClientInputSpec.hs → hydra-node/test/Hydra/API/ClientInputSpec.hs b/hydra-node/test/Hydra/ClientInputSpec.hs → hydra-node/test/Hydra/API/ClientInputSpec.hs
@@ -1,15 +1,15 @@
 {-# LANGUAGE TypeApplications #-}
 
-module Hydra.ClientInputSpec where
+module Hydra.API.ClientInputSpec where
 
 import Hydra.Prelude
 import Test.Hydra.Prelude
 
 import Cardano.Binary (serialize')
 import Data.Aeson (Result (..), Value (String), fromJSON)
 import qualified Data.ByteString.Base16 as Base16
+import Hydra.API.ClientInput (ClientInput)
 import Hydra.Cardano.Api (serialiseToTextEnvelope, toLedgerTx)
-import Hydra.ClientInput (ClientInput)
 import Hydra.Ledger.Cardano (Tx)
 import Hydra.Ledger.Simple (SimpleTx)
 import Test.Aeson.GenericSpecs (

diff --git a/hydra-node/test/Hydra/ServerOutputSpec.hs → ...a-node/test/Hydra/API/ServerOutputSpec.hs b/hydra-node/test/Hydra/ServerOutputSpec.hs → ...a-node/test/Hydra/API/ServerOutputSpec.hs
@@ -1,13 +1,13 @@
 {-# LANGUAGE TypeApplications #-}
 
-module Hydra.ServerOutputSpec where
+module Hydra.API.ServerOutputSpec where
 
 import Hydra.Prelude
 import Test.Hydra.Prelude
 
+import Hydra.API.ServerOutput (ServerOutput)
 import Hydra.Ledger.Cardano (Tx)
 import Hydra.Ledger.Simple (SimpleTx)
-import Hydra.ServerOutput (ServerOutput)
 import Test.Aeson.GenericSpecs (
   Settings (..),
   defaultSettings,

diff --git a/hydra-node/test/Hydra/API/ServerSpec.hs b/hydra-node/test/Hydra/API/ServerSpec.hs
@@ -19,7 +19,7 @@ import qualified Data.Aeson as Aeson
 import Hydra.API.Server (Server (Server, sendOutput), withAPIServer)
 import Hydra.Ledger.Simple (SimpleTx)
 import Hydra.Logging (nullTracer, showLogsOnFailure)
-import Hydra.ServerOutput (ServerOutput (Greetings, InvalidInput, ReadyToCommit), input)
+import Hydra.API.ServerOutput (ServerOutput (Greetings, InvalidInput, ReadyToCommit), input)
 import Network.WebSockets (Connection, receiveData, runClient, sendBinaryData)
 import Test.Hydra.Fixture (alice)
 import Test.Network.Ports (withFreePort)

diff --git a/hydra-node/test/Hydra/BehaviorSpec.hs b/hydra-node/test/Hydra/BehaviorSpec.hs
@@ -23,7 +23,7 @@ import GHC.Records (getField)
 import Hydra.API.Server (Server (..))
 import Hydra.Cardano.Api (SigningKey)
 import Hydra.Chain (Chain (..), ChainEvent (..), HeadParameters (..), OnChainTx (..), PostChainTx (..))
-import Hydra.ClientInput
+import Hydra.API.ClientInput
 import Hydra.ContestationPeriod (ContestationPeriod (UnsafeContestationPeriod), toNominalDiffTime)
 import Hydra.Crypto (HydraKey, aggregate, sign)
 import Hydra.HeadLogic (
@@ -46,7 +46,7 @@ import Hydra.Node (
   runHydraNode,
  )
 import Hydra.Party (Party, deriveParty)
-import Hydra.ServerOutput (ServerOutput (..))
+import Hydra.API.ServerOutput (ServerOutput (..))
 import Hydra.Snapshot (Snapshot (..), SnapshotNumber, getSnapshot)
 import Test.Aeson.GenericSpecs (roundtripAndGoldenSpecs)
 import Test.Hydra.Fixture (alice, aliceSk, bob, bobSk)

diff --git a/hydra-node/test/Hydra/HeadLogicSpec.hs b/hydra-node/test/Hydra/HeadLogicSpec.hs
@@ -36,7 +36,7 @@ import Hydra.Ledger.Simple (SimpleTx (..), aValidTx, simpleLedger, utxoRef)
 import Hydra.Network (Host (..))
 import Hydra.Network.Message (Message (AckSn, Connected, ReqSn, ReqTx))
 import Hydra.Party (Party (..))
-import Hydra.ServerOutput (ServerOutput (..))
+import Hydra.API.ServerOutput (ServerOutput (..))
 import Hydra.Snapshot (ConfirmedSnapshot (..), Snapshot (..), getSnapshot)
 import Test.Aeson.GenericSpecs (roundtripAndGoldenSpecs)
 import Test.Hydra.Fixture (alice, aliceSk, bob, bobSk, carol, carolSk, cperiod)

diff --git a/hydra-node/test/Hydra/Logging/MonitoringSpec.hs b/hydra-node/test/Hydra/Logging/MonitoringSpec.hs
@@ -17,7 +17,7 @@ import Hydra.Logging.Messages (HydraLog (Node))
 import Hydra.Logging.Monitoring
 import Hydra.Network.Message (Message (ReqTx))
 import Hydra.Node (HydraNodeLog (BeginEvent, EndEffect))
-import Hydra.ServerOutput (ServerOutput (SnapshotConfirmed))
+import Hydra.API.ServerOutput (ServerOutput (SnapshotConfirmed))
 import Hydra.Snapshot (Snapshot (Snapshot))
 import Network.HTTP.Req (GET (..), NoReqBody (..), bsResponse, defaultHttpConfig, http, port, req, responseBody, runReq, (/:))
 import Test.Hydra.Fixture (alice)

diff --git a/hydra-node/test/Hydra/Model.hs b/hydra-node/test/Hydra/Model.hs
@@ -44,17 +44,17 @@ import Hydra.BehaviorSpec (
 import Hydra.Cardano.Api.Prelude (fromShelleyPaymentCredential)
 import Hydra.Chain (HeadParameters (..))
 import Hydra.Chain.Direct.Fixture (defaultGlobals, defaultLedgerEnv, testNetworkId)
-import Hydra.ClientInput (ClientInput (NewTx))
-import qualified Hydra.ClientInput as Input
+import Hydra.API.ClientInput (ClientInput (NewTx))
+import qualified Hydra.API.ClientInput as Input
 import Hydra.Crypto (HydraKey)
 import Hydra.HeadLogic (Committed, PendingCommits)
 import Hydra.Ledger (IsTx (..))
 import Hydra.Ledger.Cardano (cardanoLedger, genAdaValue, genKeyPair, genSigningKey, mkSimpleTx)
 import Hydra.Logging (Tracer)
 import Hydra.Node (HydraNodeLog, runHydraNode)
 import Hydra.Party (Party, deriveParty)
-import Hydra.ServerOutput (ServerOutput (GetUTxOResponse, ReadyToCommit, SnapshotConfirmed))
-import qualified Hydra.ServerOutput as Output
+import Hydra.API.ServerOutput (ServerOutput (GetUTxOResponse, ReadyToCommit, SnapshotConfirmed))
+import qualified Hydra.API.ServerOutput as Output
 import qualified Hydra.Snapshot as Snapshot
 import Test.QuickCheck (elements, frequency, resize, sized, suchThat, tabulate, vectorOf)
 import Test.QuickCheck.DynamicLogic (DynLogicModel)

diff --git a/hydra-node/test/Hydra/ModelSpec.hs b/hydra-node/test/Hydra/ModelSpec.hs
@@ -73,15 +73,15 @@ import qualified Data.Map as Map
 import qualified Data.Set as Set
 import Hydra.BehaviorSpec (TestHydraNode (..))
 import Hydra.Chain.Direct.Fixture (testNetworkId)
-import Hydra.ClientInput (ClientInput (..))
+import Hydra.API.ClientInput (ClientInput (..))
 import Hydra.Model (
   GlobalState (..),
   Nodes (Nodes, nodes),
   OffChainState (..),
   WorldState (..),
  )
 import Hydra.Party (Party (..), deriveParty)
-import Hydra.ServerOutput (ServerOutput (..))
+import Hydra.API.ServerOutput (ServerOutput (..))
 import Test.QuickCheck (Property, counterexample, forAll, property, withMaxSuccess, within)
 import Test.QuickCheck.Gen.Unsafe (Capture (Capture), capture)
 import Test.QuickCheck.Monadic (PropertyM, assert, monadic', monitor, run)

diff --git a/hydra-node/test/Hydra/NodeSpec.hs b/hydra-node/test/Hydra/NodeSpec.hs
@@ -15,7 +15,7 @@ import Hydra.Chain (
   PostChainTx (InitTx),
   PostTxError (NoSeedInput),
  )
-import Hydra.ClientInput (ClientInput (..))
+import Hydra.API.ClientInput (ClientInput (..))
 import Hydra.Crypto (HydraKey, sign)
 import Hydra.HeadLogic (
   Environment (..),
@@ -38,7 +38,7 @@ import Hydra.Node (
   stepHydraNode,
  )
 import Hydra.Party (Party, deriveParty)
-import Hydra.ServerOutput (ServerOutput (PostTxOnChainFailed))
+import Hydra.API.ServerOutput (ServerOutput (PostTxOnChainFailed))
 import Hydra.Snapshot (Snapshot (..))
 import Test.Hydra.Fixture (alice, aliceSk, bob, bobSk, carol, carolSk, cperiod)
 

diff --git a/hydra-tui/src/Hydra/Client.hs b/hydra-tui/src/Hydra/Client.hs
@@ -12,10 +12,10 @@ import Hydra.Cardano.Api (
   SigningKey,
  )
 import Hydra.Chain.Direct.Util (readFileTextEnvelopeThrow)
-import Hydra.ClientInput (ClientInput)
+import Hydra.API.ClientInput (ClientInput)
 import Hydra.Ledger (IsTx)
 import Hydra.Network (Host (Host, hostname, port))
-import Hydra.ServerOutput (ServerOutput)
+import Hydra.API.ServerOutput (ServerOutput)
 import Hydra.TUI.Options (Options (..))
 import Network.WebSockets (ConnectionException, receiveData, runClient, sendBinaryData)
 

diff --git a/hydra-tui/src/Hydra/TUI.hs b/hydra-tui/src/Hydra/TUI.hs
@@ -49,16 +49,16 @@ import Graphics.Vty (
  )
 import qualified Graphics.Vty as Vty
 import Graphics.Vty.Attributes (defAttr)
+import Hydra.API.ClientInput (ClientInput (..))
+import Hydra.API.ServerOutput (ServerOutput (..))
 import Hydra.Chain.CardanoClient (CardanoClient (..), mkCardanoClient)
 import Hydra.Chain.Direct.Util (isMarkedOutput)
 import Hydra.Client (Client (..), HydraEvent (..), withClient)
-import Hydra.ClientInput (ClientInput (..))
 import Hydra.ContestationPeriod (ContestationPeriod (UnsafeContestationPeriod))
 import Hydra.Ledger (IsTx (..))
 import Hydra.Ledger.Cardano (mkSimpleTx)
 import Hydra.Network (Host (..))
 import Hydra.Party (Party (..))
-import Hydra.ServerOutput (ServerOutput (..))
 import Hydra.Snapshot (Snapshot (..))
 import Hydra.TUI.Options (Options (..))
 import Lens.Micro (Lens', lens, (%~), (.~), (?~), (^.), (^?))

diff --git a/hydraw/src/Hydra/Painter.hs b/hydraw/src/Hydra/Painter.hs
@@ -7,11 +7,11 @@ import qualified Data.Aeson as Aeson
 import qualified Data.Map as Map
 import Hydra.Cardano.Api
 import Hydra.Chain.Direct.Util (readFileTextEnvelopeThrow)
-import Hydra.ClientInput (ClientInput (GetUTxO, NewTx))
+import Hydra.API.ClientInput (ClientInput (GetUTxO, NewTx))
 import Hydra.Ledger.Cardano (emptyTxBody)
 import Hydra.Network (Host (..))
 import Hydra.Prelude
-import Hydra.ServerOutput (ServerOutput (GetUTxOResponse))
+import Hydra.API.ServerOutput (ServerOutput (GetUTxOResponse))
 import Network.WebSockets (
   Connection,
   runClient,