Update changelog and documentation

CHANGELOG.md

@@ -41,6 +41,10 @@ changes.
   bleeding-edge from `master` branch is available at
   https://hydra.family/head-protocol/unstable.
 
+- API clients can decide if they want to:
+  + Skip observing history of events before they connected
+  + View the transactions in the server output encoded as CBOR
+
 ## [0.9.0] - 2023-03-02
 
 :dragon_face: Renamed the repository from `hydra-poc` to [`hydra`](https://github.com/input-output-hk/hydra)!

docs/core-concepts/behavior.md

@@ -18,4 +18,11 @@ A special case is the `RolledBack` output. This means that the chain rolled back
 
 ## Replay of past server outputs
 
-When a `hydra-node` restarts, it will load it's history from persistence and replay previous server outputs to enable clients to re-establish their state upon re-connection. If that happens, obviously some of these outputs are not relevant anymore. One example of this is the `PeerConnected` and `PeerDisconnected`. To make it possible to determine the end of replayed history, client applications can use the `Greetings`, which will be emitted on every `hydra-node` start. See the `hydra-tui` example client for how this is handled.
+When a `hydra-node` restarts, by default it will load it's history from persistence and replay previous server outputs to enable clients to re-establish their state upon re-connection. If that happens, obviously some of these outputs are not relevant anymore. One example of this is the `PeerConnected` and `PeerDisconnected`. To make it possible to determine the end of replayed history, client applications can use the `Greetings`, which will be emitted on every `hydra-node` start. See the `hydra-tui` example client for how this is handled.
+
+Clients can optionally decide to skip history outputs and receive only the `Greetings` and following ones. In order to do that they can use query param `history=no`.
+
+They can also decide to be served with transactions encoded as CBOR by using query param `tx-output=cbor`.
+
+For example if the client wants to connect to a local `hydra-node` and doesn't want to view the server history but also want to have the
+transactions encoded as CBOR (base16) they would connect using default port `4001` and the full path `ws://localhost:4001/?history=0&tx-output=cbor`.

hydra-node/json-schemas/api.yaml

@@ -6,7 +6,9 @@ info:
     WebSocket API for administrating & interacting with Hydra Heads: multi-party isomorphic state-channels for Cardano.
 
     Once started, a Hydra node provides an API in the forms of JSON messages over WebSocket. An Hydra node is an event-driven application where users (a.k.a you) are one possible source of inputs. Other sources can be mainly other Hydra nodes in the network, or transactions observed on the layer 1 (e.g. a closing transaction).
-    Therefore, once connected, clients receive a stream of outputs as they arrive. They can interact with their node by pushing events to it, some are local, and some will have consequences on the rest of the head.
+    Therefore, once connected, clients receive a stream of outputs as they arrive. Clients get to decide (using query parameters) if they want to observe the history of outputs and the transaction format.
+    For example if client provides a path that looks like this `/?history=0&tx-output=cbor` the server will not serve prior history of server outputs and the transaction fields in the json will be encoded as CBOR.
+    They can interact with their node by pushing events to it, some are local, and some will have consequences on the rest of the head.
     See [the documentation](https://hydra.family/head-protocol/core-concepts/behavior/) for more details on the overall API behavior.
 
     > By default, a Hydra node listens for TCP WebSocket connections on port `tcp/4001` . This can be changed using `--port`.

hydra-node/src/Hydra/API/Server.hs

@@ -142,12 +142,12 @@ runAPIServer host port party tracer history callback responseChannel = do
       traceWith tracer NewAPIConnection
 
       -- api client can decide if they want to see the past history of server outputs
-      serveHistory <- shouldServeHistory queryParams
-      if serveHistory
-        then forwardHistory con
-        else forwardGreetingOnly con
+      dontServeHistory <- shouldNotServeHistory queryParams
+      if dontServeHistory
+        then forwardGreetingOnly con
+        else forwardHistory con
 
-      -- api client can decides if they want tx's to be displayed as CBOR instead of plain json
+      -- api client can decide if they want tx's to be displayed as CBOR instead of plain json
       txDisplay <- decideOnTxDisplay queryParams
 
       withPingThread con 30 (pure ()) $
@@ -171,9 +171,9 @@ runAPIServer host port party tracer history callback responseChannel = do
         True -> TxCBOR
         False -> TxJSON
 
-  shouldServeHistory qp = do
+  shouldNotServeHistory qp = do
     k <- mkQueryKey "history"
-    v <- mkQueryValue "1"
+    v <- mkQueryValue "0"
     pure $ (QueryParam k v) `elem` qp
 
   onIOException ioException =

hydra-node/test/Hydra/API/ServerSpec.hs

@@ -167,9 +167,7 @@ spec = parallel $ do
             -- if client doesn't specify anything they will get tx encoded as JSON
             withClient port defaultPath $ \conn -> do
               sendOutput txValidMessage
-              -- receive greetings + one more message
               received :: [ByteString] <- replicateM 2 (receiveData conn)
-              -- make sure tx output is valid tx cbor
               (received List.!! 1) ^? key "transaction" . nonNull
                 `shouldBe` Just (toJSON tx)