From 69a6e98f23b16e8e098cffb2eb3cc270da3f0e13 Mon Sep 17 00:00:00 2001 From: Franco Testagrossa Date: Fri, 17 May 2024 10:56:40 +0200 Subject: [PATCH 1/3] Reorder new docs according to new structure --- docs/docs/configuration.md | 11 ++++++++++- docs/docs/getting-started/offline-mode.md | 9 --------- .../event-sinks-and-sources.md | 13 +++++++++---- docs/docs/how-to/operating-hydra.md | 2 +- 4 files changed, 20 insertions(+), 15 deletions(-) delete mode 100644 docs/docs/getting-started/offline-mode.md rename docs/docs/{getting-started => how-to}/event-sinks-and-sources.md (86%) diff --git a/docs/docs/configuration.md b/docs/docs/configuration.md index 400644a23cf..8a91e26deba 100644 --- a/docs/docs/configuration.md +++ b/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}}}``` diff --git a/docs/docs/getting-started/offline-mode.md b/docs/docs/getting-started/offline-mode.md deleted file mode 100644 index 71a8cd6554f..00000000000 --- a/docs/docs/getting-started/offline-mode.md +++ /dev/null @@ -1,9 +0,0 @@ -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). - -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}}}``` \ No newline at end of file diff --git a/docs/docs/getting-started/event-sinks-and-sources.md b/docs/docs/how-to/event-sinks-and-sources.md similarity index 86% rename from docs/docs/getting-started/event-sinks-and-sources.md rename to docs/docs/how-to/event-sinks-and-sources.md index 54c937de45c..ddacc289358 100644 --- a/docs/docs/getting-started/event-sinks-and-sources.md +++ b/docs/docs/how-to/event-sinks-and-sources.md @@ -1,4 +1,8 @@ -# Overview +--- +sidebar_position: 4 +--- + +# Configure 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: @@ -12,12 +16,13 @@ Multiple Event Sinks may be used simultaneously, but currently only one Event So 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. -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 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](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) -To see an example of S3 and AWS Kinesis Event Sources and Sinks, see the doug_hydra_changes branch [here](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](offline-mode.md) \ No newline at end of file +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) diff --git a/docs/docs/how-to/operating-hydra.md b/docs/docs/how-to/operating-hydra.md index 90c4a5b08c7..d1817e51139 100644 --- a/docs/docs/how-to/operating-hydra.md +++ b/docs/docs/how-to/operating-hydra.md @@ -1,5 +1,5 @@ --- -sidebar_position: 6 +sidebar_position: 3 --- # Operate a Hydra Node From 75d4433d1ef19a3567b19b70f2d21bef8e4570d3 Mon Sep 17 00:00:00 2001 From: Franco Testagrossa Date: Fri, 17 May 2024 13:48:52 +0200 Subject: [PATCH 2/3] Enhance document title Co-authored-by: Sebastian Nagel --- docs/docs/how-to/event-sinks-and-sources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/how-to/event-sinks-and-sources.md b/docs/docs/how-to/event-sinks-and-sources.md index ddacc289358..fbd0f5c5059 100644 --- a/docs/docs/how-to/event-sinks-and-sources.md +++ b/docs/docs/how-to/event-sinks-and-sources.md @@ -2,7 +2,7 @@ sidebar_position: 4 --- -# Configure Event Source and Sinks +# 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: From 2c42a62052acbf41d0bd900ddd55cdd16d98b870 Mon Sep 17 00:00:00 2001 From: Franco Testagrossa Date: Fri, 17 May 2024 13:51:49 +0200 Subject: [PATCH 3/3] Fix external link --- docs/docs/how-to/event-sinks-and-sources.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/how-to/event-sinks-and-sources.md b/docs/docs/how-to/event-sinks-and-sources.md index fbd0f5c5059..ef2217ad887 100644 --- a/docs/docs/how-to/event-sinks-and-sources.md +++ b/docs/docs/how-to/event-sinks-and-sources.md @@ -17,7 +17,7 @@ Multiple Event Sinks may be used simultaneously, but currently only one Event So 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](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) +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.