Merge branch 'master' into dependabot/github_actions/cachix/install-n…

…ix-action-27

CHANGELOG.md

@@ -8,34 +8,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 As a minor extension, we also keep a semantic version for the `UNRELEASED`
 changes.
 
-## [0.17.0] - UNRELEASED
+## [0.17.0] - 2024-05-20
 
-- **BREAKING** `hydra-node` `/commit` enpoint now also accepts a _blueprint/draft_
-  transaction together with the `UTxO` which is spent in this transaction. `hydra-node` can
-  still be used like before if the provided `UTxO` is at public key address. In order to spend
-  from a script `UTxO`, and also unlock more involved use-cases, users need to provide additional
-  unsigned transaction that correctly specifies required data (like redeemers, validity ranges etc.)
+- **BREAKING** Change `hydra-node` API `/commit` endpoint for committing from scripts [#1380](https://github.com/input-output-hk/hydra/pull/1380):
+  - Instead of the custom `witness` extension of `UTxO`, the endpoint now accepts a _blueprint_ transaction together with the `UTxO` which is spent in this transaction.
+  - Usage is still the same for commiting "normal" `UTxO` owned by public key addresses.
+  - Spending from a script `UTxO` now needs the `blueprintTx` request type, which also unlocks more involved use-cases, where the commit transaction should also satisfy script spending constraints (like additional signers, validity ranges etc.)
 
-- Update navigation and re-organized documentation website https://hydra.family
+- _DEPRECATED_ the `GetUTxO` client input and `GetUTxOResponse` server output. Use `GET /snapshot/utxo` instead.
+
+- Update navigation and re-organized documentation website https://hydra.family [#1440](https://github.com/input-output-hk/hydra/pull/1440)
   - Updated logos
   - Removed localization as it got outdated and on-demand site translation tools exist.
 
-- Add `GET /snapshot/utxo` API endpoint to query confirmed UTxO set on demand.
+- Add `GET /snapshot/utxo` API endpoint to query confirmed UTxO set on demand. [#1398](https://github.com/input-output-hk/hydra/pull/1398)
   - Always responds with the last confirmed UTxO
 
-- Set [CORS](https://fetch.spec.whatwg.org/#http-cors-protocol) headers on `hydra-node` API to allow requests from any origin `*`.
-
-- _DEPRECATED_ the `GetUTxO` client input and `GetUTxOResponse` server output. Use `GET /snapshot/utxo` instead.
+- Set [CORS](https://fetch.spec.whatwg.org/#http-cors-protocol) headers on `hydra-node` API to allow requests from any origin `*`. [#1434](https://github.com/input-output-hk/hydra/pull/1434)
 
-- `hydra-node` logs will now report `NetworkEvents` to distinguish between `ConnectivityEvent`s and `ReceivedMessage`s on the network.
+- `hydra-node` logs will now report `NetworkEvents` to distinguish between `ConnectivityEvent`s and `ReceivedMessage`s on the network. [#1396](https://github.com/input-output-hk/hydra/pull/1396)
 
 - Hydra now uses a versioned protocol for handshaking. In the event of a node
   attempting to connect using a different version of the networking protocol, a
   `HandshakeFailure` event will be recorded in the logs and sent as a server
-  output on the API.
+  output on the API. [#1381](https://github.com/input-output-hk/hydra/pull/1381)
 
 - Make `hydra-cluster --devnet` more configurable
-  - Now it is idle by default again and a `--busy` will make it busy respending the same UTxO.
+  - Now it is idle by default again and a `--busy` will make it busy respending the same UTxO. [#1420](https://github.com/input-output-hk/hydra/pull/1420)
 
 ## [0.16.0] - 2024-04-03
 

cabal.project

@@ -12,8 +12,8 @@ repository cardano-haskell-packages
 
 -- See CONTRIBUTING.md for information about when and how to update these.
 index-state:
-  , hackage.haskell.org 2024-03-21T15:07:04Z
-  , cardano-haskell-packages 2024-03-21T19:04:02Z
+  , hackage.haskell.org 2024-05-19T19:07:04Z
+  , cardano-haskell-packages 2024-05-19T19:04:02Z
 
 packages:
   cardano-api-classy
@@ -41,3 +41,6 @@ benchmarks: True
 
 -- Always show detailed output for tests
 test-show-details: direct
+
+constraints:
+  io-classes-mtl == 0.1.1.0

demo/docker-compose.yaml

@@ -23,7 +23,7 @@ services:
 
   hydra-node-1:
    # NOTE: Make sure to use the same image in ./seed-devnet.sh
-    image: ghcr.io/input-output-hk/hydra-node:0.16.0
+    image: ghcr.io/input-output-hk/hydra-node:0.17.0
     build:
       context: ../
       target: hydra-node
@@ -58,7 +58,7 @@ services:
 
   hydra-node-2:
     # NOTE: Make sure to use the same image in ./seed-devnet.sh
-    image: ghcr.io/input-output-hk/hydra-node:0.16.0
+    image: ghcr.io/input-output-hk/hydra-node:0.17.0
     build:
       context: ../
       target: hydra-node
@@ -93,7 +93,7 @@ services:
 
   hydra-node-3:
     # NOTE: Make sure to use the same image in ./seed-devnet.sh
-    image: ghcr.io/input-output-hk/hydra-node:0.16.0
+    image: ghcr.io/input-output-hk/hydra-node:0.17.0
     build:
       context: ../
       target: hydra-node
@@ -127,7 +127,7 @@ services:
     restart: always
 
   hydra-tui-1:
-    image: ghcr.io/input-output-hk/hydra-tui:0.16.0
+    image: ghcr.io/input-output-hk/hydra-tui:0.17.0
     build:
        context: ../
        target: hydra-tui
@@ -144,7 +144,7 @@ services:
         ipv4_address: 172.16.238.11
 
   hydra-tui-2:
-    image: ghcr.io/input-output-hk/hydra-tui:0.16.0
+    image: ghcr.io/input-output-hk/hydra-tui:0.17.0
     build:
        context: ../
        target: hydra-tui
@@ -161,7 +161,7 @@ services:
         ipv4_address: 172.16.238.21
 
   hydra-tui-3:
-    image: ghcr.io/input-output-hk/hydra-tui:0.16.0
+    image: ghcr.io/input-output-hk/hydra-tui:0.17.0
     build:
        context: ../
        target: hydra-tui

demo/seed-devnet.sh

@@ -49,7 +49,7 @@ function hnode() {
       docker run --rm -it \
         --pull always \
         -v ${SCRIPT_DIR}/devnet:/devnet \
-        ghcr.io/input-output-hk/hydra-node:0.16.0 -- ${@}
+        ghcr.io/input-output-hk/hydra-node:0.17.0 -- ${@}
   fi
 }
 

docs/docs/configuration.md

@@ -165,4 +165,13 @@ The `hydra-node` is compatible with the Cardano `mainnet` network, and can conse
 
 ## Offline mode
 
-TODO integrate https://github.com/input-output-hk/hydra/pull/1414
+Hydra supports an offline mode, which allows for disabling the Layer 1 interface (that is, the underlying Cardano blockchain which Hydra heads use to seed funds and ultimately funds are withdrawn to). Disabling Layer 1 interactions allows use-cases which would otherwise require running and configuring an entire Layer 1 private devnet. For example, the offline mode can be used to quickly validate a series of transactions against a UTxO, without having to spin up an entire Layer 1 Cardano node.
+
+In this offline mode, only the Layer 2 ledger is run, along with the Hydra API and persistence, to support interacting with the offline Hydra. Therefore, ledger genesis parameters that normally influence things like time-based transaction validation, may be set to defaults that aren't reflective of mainnet. To set this, set --ledger-protocol-parameters to a non-zero file, as described [here](https://hydra.family/head-protocol/unstable/docs/configuration/#ledger-parameters).
+Depending on your use case, you can [configure your node's event source and sinks](./how-to/event-sinks-and-sources.md) to better suite your needs.
+
+To initialize the Layer 2 ledger's UTXO state, offline mode takes an obligatory --initial-utxo parameter, which points to a JSON encoded UTXO file. This UTXO is independent of Event Source loaded events, and the latter are validated against this UTXO. The UTXO follows the following schema `{ txout : {address, value : {asset : quantity}, datum, datumhash, inlinedatum, referenceScript }`
+
+An example UTXO:
+```json
+{"1541287c2598ffc682742c961a96343ac64e9b9030e6b03a476bb18c8c50134d#0":{"address":"addr_test1vqg9ywrpx6e50uam03nlu0ewunh3yrscxmjayurmkp52lfskgkq5k","datum":null,"datumhash":null,"inlineDatum":null,"referenceScript":null,"value":{"lovelace":100000000}},"39786f186d94d8dd0b4fcf05d1458b18cd5fd8c6823364612f4a3c11b77e7cc7#0":{"address":"addr_test1vru2drx33ev6dt8gfq245r5k0tmy7ngqe79va69de9dxkrg09c7d3","datum":null,"datumhash":null,"inlineDatum":null,"referenceScript":null,"value":{"lovelace":100000000}}}```

docs/docs/how-to/event-sinks-and-sources.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 4
+---
+
+# Extend the node with event source and sinks
+
+Some use-cases exist, where many features of the Hydra platform are useful, but interfacing with the entire Hydra node, especially with respect to IO, is impractical. For a use-case which calls for different persistence requirements from the Hydra default, it initially might seem there are two options:
+
+1. One might decide to fork the Hydra code-base, to make any customizations desired. This comes at the cost of maintenance burden, as internal code is inherently more unstable and less documented than external-facing interfaces.
+
+2. The alternative would be to instead make do with running a full Hydra node, and preparing a persistence file before the Hydra runs, or parsing the file as it is written. This comes at the cost of control, code duplication, resource usage, and still relies on interfacing with an unstable external API (the persistence file on-disk).
+
+To better enable these use-cases, Hydra supports the concept of alternate Event Sinks and a single alternate Event Source. These respectively represent ways to persist new transactions processed at run-time (a generalization of appending to the persistence file), and a way to seed the initial transactions a Hydra node loads upon startup (a generalization of restoring from the persistence file).
+
+Multiple Event Sinks may be used simultaneously, but currently only one Event Source may be used at a time. The Event Source is only loaded upon startup. Each Event Sink is run upon each new transaction. Currently, the order must be specified by customizing the order of the Event Sink list in the Hydra node source code, in the eventSinks parameter to hydrate, invoked in Hydra.Node.Run.run [here](https://github.com/SundaeSwap-finance/hydra/blob/4785bd86a03b92ba8fa8fb34c9d485a1e2f4f7d7/hydra-node/src/Hydra/Node/Run.hs#L104)
+
+The default Hydra file-based persistence is implemented as an Event Sink and Source pair. They do not need to be used in tandem; it is possible to use the default Event Source which processes previous transactions from a file on disk, combined with an Event Sink which could, for example, store new transactions on S3, on several machines, or not at all.
+
+To see a basic example of an Event Sink that sends new transactions over UDP please refer to [this fork](https://github.com/ffakenz/hydra/tree/udp-sink).
+For a more complex example using S3 and AWS Kinesis as Event Sources and Sinks, see the doug_hydra_changes branch [here](https://github.com/SundaeSwap-finance/hydra). In particular, see [hydra-node/src/Hydra/Events/AWS/Kinesis.hs](https://github.com/SundaeSwap-finance/hydra/blob/f27e51c001e7b64c3679eab4efd9f17f08db53fe/hydra-node/src/Hydra/Events/AWS/Kinesis.hs)
+
+Currently, there is no CLI API to toggle which sources and sinks are utilized, this must be done by the implementor of the sources and sinks. See the source and sink example, [here](https://github.com/SundaeSwap-finance/hydra/blob/4785bd86a03b92ba8fa8fb34c9d485a1e2f4f7d7/hydra-node/src/Hydra/Node/Run.hs#L97), where the Event Sinks and Source are toggled by added CLI Options.
+
+To construct an Event Sink, construct an EventSink e m object, where m is the monad (like IO), that the Event Sink will run in, and e is the (polymorphic) event type. There is only one field in the EventSink record, corresponding to the monadic action to take upon a new Event. An example that outputs the event to AWS Kinesis is available [here](https://github.com/SundaeSwap-finance/hydra/blob/598b20fcee9669a196781f70e02e13779967e470/hydra-node/src/Hydra/Events/AWS/Kinesis.hs#L85)
+
+To construct an Event Source, construct an EventSource e m object. The monadic action that EventSource e m wraps, should produce a list of events `[e]`. An example that loads events from AWS Kinesis is available [here](https://github.com/SundaeSwap-finance/hydra/blob/598b20fcee9669a196781f70e02e13779967e470/hydra-node/src/Hydra/Events/AWS/Kinesis.hs#L85). Note that it may be necessary to add delays to throttle the event list construction, since the entire list is replayed (and forced) at Hydra node startup time, and it's likely that it will be forced too fast for any sort of API, if it is not throttled.
+
+Hydra also supports an offline mode, which allows for disabling the Layer 1 interface (that is, the underlying Cardano blockchain which Hydra heads use to seed funds and ultimately funds are withdrawn to). This offline mode makes operation only influenced by the HTTP/WebSocket APIs, and the configured Event Sinks and sources. While separate from the Event Sinks and Event Source functionality, disabling Layer 1 interactions allows for further customization, enabling use-cases which would otherwise require running and configuring an entire Layer 1 private devnet. See offline mode documentation [here](../configuration.md#offline-mode)

docs/docs/how-to/operating-hydra.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 3
 ---
 
 # Operate a Hydra Node

docs/docs/tutorial/index.md

@@ -37,7 +37,7 @@ components of the Cardano ecosystem, putting them in a `bin/` directory:
 
 ```shell
 mkdir -p bin
-version=0.16.0
+version=0.17.0
 curl -L -O https://github.com/input-output-hk/hydra/releases/download/${version}/hydra-x86_64-linux-${version}.zip
 unzip -d bin hydra-x86_64-linux-${version}.zip
 curl -L -o - https://github.com/input-output-hk/cardano-node/releases/download/8.9.0/cardano-node-8.9.0-linux.tar.gz \
@@ -52,7 +52,7 @@ chmod +x bin/*
 
 ```shell
 mkdir -p bin
-version=0.16.0
+version=0.17.0
 curl -L -O https://github.com/input-output-hk/hydra/releases/download/${version}/hydra-aarch64-darwin-${version}.zip
 unzip -d bin hydra-aarch64-darwin-${version}.zip
 curl -L -o - https://github.com/input-output-hk/cardano-node/releases/download/8.9.0/cardano-node-8.9.0-macos.tar.gz \
@@ -388,7 +388,7 @@ Let's start the `hydra-node` with all these parameters now:
 <TabItem value="alice" label="Alice">
 
 ```shell
-version=0.16.0
+version=0.17.0
 hydra-node \
   --node-id "alice-node" \
   --persistence-dir persistence-alice \
@@ -411,7 +411,7 @@ hydra-node \
 <TabItem value="bob" label="Bob">
 
 ```shell
-version=0.16.0
+version=0.17.0
 hydra-node \
   --node-id "bob-node" \
   --persistence-dir persistence-bob \