Skip to content

Commit

Permalink
input-output-hk -> cardano-scaling
Browse files Browse the repository at this point in the history
  • Loading branch information
noonio committed Dec 20, 2024
1 parent a6429a4 commit 1d68e33
Show file tree
Hide file tree
Showing 17 changed files with 23 additions and 23 deletions.
2 changes: 1 addition & 1 deletion docs/adr/2021-06-09_005-use-io-sim-classes.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Although we try to contain the use of IO at the outskirt of the Hydra node using

Testing asynchronous and concurrent code is notoriously painful

The ouroboros consensus test suite and [hydra-sim](https://github.com/input-output-hk/hydra-sim) simulation have demonstrated the effectiveness of abstracting concurrent primitives through the use of typeclasses (MTL-style pattern) and being able to run these as pure code, harvesting and analysing produced execution traces.
The ouroboros consensus test suite and [hydra-sim](https://github.com/cardano-scaling/hydra-sim) simulation have demonstrated the effectiveness of abstracting concurrent primitives through the use of typeclasses (MTL-style pattern) and being able to run these as pure code, harvesting and analysing produced execution traces.

There are other such libraries, e.g. [concurrency](https://hackage.haskell.org/package/concurrency) and [dejafu](https://hackage.haskell.org/package/dejafu), as well as the venerable [exceptions](https://hackage.haskell.org/package/exceptions) (for abstracting exception throwing).

Expand Down
4 changes: 2 additions & 2 deletions docs/adr/2022-03-17_015-admin-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Proposed
* Having static network configuration is probably not sustainable in the long run, even if we don't add any fancy multihead capabilities to the node, as it would make it significantly harder to have automated creation of Heads.
* There's been an [attempt](https://github.com/cardano-scaling/hydra/pull/222) at providing a file-based network configuration but this was deemed unconvincing
* [Hydra paper (sec. 4, p. 13)](https://eprint.iacr.org/2020/299.pdf) explicitly assumes the existence of a _setup_ phase
* This _setup_ is currently left aside, e.g. exchange of keys for setting up multisig and identifying peers. The [hydra-node](https://github.com/input-output-hk/hydra/blob/abailly-iohk/admin-api-adr/hydra-node/exe/hydra-node/Main.hs#L41) executable is statically configured and those things are assumed to be known beforehand
* This _setup_ is currently left aside, e.g. exchange of keys for setting up multisig and identifying peers. The [hydra-node](https://github.com/cardano-scaling/hydra/blob/abailly-iohk/admin-api-adr/hydra-node/exe/hydra-node/Main.hs#L41) executable is statically configured and those things are assumed to be known beforehand

## Decision

Expand All @@ -41,7 +41,7 @@ The following picture sketches the proposed architectural change:
* This API is an interface over a specific _resource_ controlled by the Hydra node, namely its knowledge of other peers with which new _Head_s can be opened. As such a proper REST interface (_not_ RPC-in-disguise) seems to make sense here, rather than stream/event-based [duplex communication channels](/adr/3)
* We can easily extend such an API with WebSockets to provide notifications (e.g. peers connectivity, setup events...)
* *Why a separate component?*
* We could imagine extending the existing [APIServer](https://github.com/input-output-hk/hydra/blob/9129c7c013fe2cdc77db048a54981e1ace0843b8/hydra-node/src/Hydra/API/Server.hs) interface with new messages related to this network configuration, however this seems to conflate different responsibilities in a single place: Configuring and managing the Hydra node itself, and configuring, managing, and interacting with the Head itself
* We could imagine extending the existing [APIServer](https://github.com/cardano-scaling/hydra/blob/9129c7c013fe2cdc77db048a54981e1ace0843b8/hydra-node/src/Hydra/API/Server.hs) interface with new messages related to this network configuration, however this seems to conflate different responsibilities in a single place: Configuring and managing the Hydra node itself, and configuring, managing, and interacting with the Head itself
* "Physical" separation of endpoints makes it easier to secure a very sensitive part of the node, namely its administration, e.g by ensuring this can only be accessed through a specific network interface, without relying on application level authentication mechanisms

## Consequences
Expand Down
2 changes: 1 addition & 1 deletion docs/adr/2022-03-23_016-keep-rejected-adr.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Accepted

We have started using _Architecture Decision Records_ as our primary way to document the most important design decisions we take while developing Hydra Node, and this has proved effective in fostering fruitful discussions about major architecture changes.

During the course of this project, we have sometimes had debates on various topics leading to rejection of [some ADRs](https://github.com/input-output-hk/hydra/pull/230). It could be the case that a previously rejected proposal turns out to be interesting, either because the context and situation have changed enough to reevaluate a proposal, or as background for some new proposal.
During the course of this project, we have sometimes had debates on various topics leading to rejection of [some ADRs](https://github.com/cardano-scaling/hydra/pull/230). It could be the case that a previously rejected proposal turns out to be interesting, either because the context and situation have changed enough to reevaluate a proposal, or as background for some new proposal.

## Decision

Expand Down
4 changes: 2 additions & 2 deletions docs/adr/2022-04-13_018-single-state.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Superseded by [ADR 23](/adr/23) and [ADR 26](/adr/26)
1. A `HeadState tx` provided by the `HydraHead tx m` handle interface and part of the `Hydra.Node` module. It provides the basis for the main `hydra-node` business logic in `Hydra.Node.processNextEvent` and `Hydra.HeadLogic.update`
[Creation](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Node.hs#L256-L257), [Usage](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Node.hs#L174)
2. `SomeOnChainHeadState` is kept in the `Hydra.Chain.Direct` to keep track of the latest known head state, including notable transaction outputs and information how to spend it (e.g. scripts and datums)
[Code](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L156-L162), [Usage 1](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L449), [Usage 2](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L414), [Usage 3](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L349-L352)
[Code](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L156-L162), [Usage 1](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L449), [Usage 2](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L414), [Usage 3](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L349-L352)
(There are other unrelated things kept in memory like the event history in the API server or a peer map in the network heartbeat component.)
* The interface between the `Hydra.Node` and a `Hydra.Chain` component consists of
- constructing certain Head protocol transactions given a description of it (`PostChainTx tx`):
Expand All @@ -27,7 +27,7 @@ Superseded by [ADR 23](/adr/23) and [ADR 26](/adr/26)
```hs
type ChainCallback tx m = OnChainTx tx -> m ()
```
* Given by the usage sites above, the `Hydra.Chain.Direct` module requires additional info to do both, construct protocol transactions with `postTx` as well as observe potential `OnChainTx` ([here](https://github.com/input-output-hk/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L333-L336)). Hence we see that, operation of the `Hydra.Chain.Direct` component (and likely any implementing the interface fully) is **inherently stateful**.
* Given by the usage sites above, the `Hydra.Chain.Direct` module requires additional info to do both, construct protocol transactions with `postTx` as well as observe potential `OnChainTx` ([here](https://github.com/cardano-scaling/hydra/blob/a98e2907c4e425de2736782793383aad63132c14/hydra-node/src/Hydra/Chain/Direct.hs#L333-L336)). Hence we see that, operation of the `Hydra.Chain.Direct` component (and likely any implementing the interface fully) is **inherently stateful**.
* We are looking at upcoming features to [handle rollbacks](https://github.com/cardano-scaling/hydra/issues/185) and dealing with [persisting the head state](https://github.com/cardano-scaling/hydra/issues/187).
- Both could benefit from the idea, that the `HeadState` is just a result of pure `Event` processing (a.k.a event sourcing).
- Right now the `HeadState` kept in `Hydra.Node` alone, is not enough to fully describe the state of the `hydra-node`. Hence it would not be enough to just persist all the `Event`s and replaying them to achieve persistence, nor resetting to some previous `HeadState` in the presence of a rollback.
Expand Down
2 changes: 1 addition & 1 deletion docs/adr/2022-12-06_022-model-based-testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Accepted
## Context

- We have been experimenting with [quickcheck-dynamic](https://hackage.org/packages/quickcheck-dynamic) for a while, leading to the implementation of basic [Model-Based tests](https://github.com/cardano-scaling/hydra/blob/master/hydra-node/test/Hydra/ModelSpec.hs) for the Hydra Head Protocol
- These tests fill a gap in our testing strategy, between [BehaviorSpec](https://github.com/input-output-hk/hydra/blob/master/hydra-node/test/Hydra/BehaviorSpec.hs) tests which test a "network" of nodes but only at the level of the off-chain Head logic, and [EndToEndSpec](https://github.com/input-output-hk/hydra/blob/master/hydra-cluster/test/Test/EndToEndSpec.hs) tests which test a full blown network of nodes interconnected through real network connections and to a real cardano-node:
- These tests fill a gap in our testing strategy, between [BehaviorSpec](https://github.com/cardano-scaling/hydra/blob/master/hydra-node/test/Hydra/BehaviorSpec.hs) tests which test a "network" of nodes but only at the level of the off-chain Head logic, and [EndToEndSpec](https://github.com/cardano-scaling/hydra/blob/master/hydra-cluster/test/Test/EndToEndSpec.hs) tests which test a full blown network of nodes interconnected through real network connections and to a real cardano-node:
- The former are fast but do not test the complete lifecycle of a Head. Furthermore, they are only unit tests so do not provide coverage into various corner cases that could arise in practice
- The latter exercise the full lifecycle but are very slow and brittle
- Because they run in [io-sim](https://github.com/input-output-hk/io-sim), those Model-based tests are fast and robust as they don't depend on system interactions. Moreover, decoupling the _System-under-Test_ from `IO` makes it easy to simulate an environment that deviates from the "happy path" such as delays from the network, filesystem errors, or even adversarial behaviour from the node, or the chain.
Expand Down
4 changes: 2 additions & 2 deletions docs/adr/2023-06-19_024-event-sourced-persistence.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Accepted
## Context

- The state of a Hydra Head is currently persisted as a whole upon each `NewState` _outcome_ from the `update` function: The new state is serialised and the `state` file is overwritten with the corresponding bytes. While this is a straightforward strategy to implement, it has a huge impact on the performance of a Hydra Head as serialising a large data structure like the `HeadState` and completely overwriting a file is costly
- We revisited our benchmarks and [found](https://github.com/input-output-hk/hydra/issues/186#issuecomment-1584292265) that persistence was the major bottleneck when measuring roundtrip confirmation time,e g. the time it takes from a client's perspective to submit a transaction and observe in a `ConfirmedSnapshot`
- We revisited our benchmarks and [found](https://github.com/cardano-scaling/hydra/issues/186#issuecomment-1584292265) that persistence was the major bottleneck when measuring roundtrip confirmation time,e g. the time it takes from a client's perspective to submit a transaction and observe in a `ConfirmedSnapshot`
- Furthermore, the way we currently handle changes to the `HeadState` in the hydra-node, while conceptually being an `Effect` is handled differently from other `Effect`s: The state is updated transactionally through a dedicated `modifyHeadState` function in the core loop of processing events, and _then_ effects are processed.

## Decision
Expand Down Expand Up @@ -55,4 +55,4 @@ sequenceDiagram
- Instead of having the `HeadLogic` emits directly a `ClientEffect`, the latter could be the result of a client-centric _interpretation_ of a `StateChanged`.
- Pushing this a little further, we could maintain a _Query Model_ for clients with a dedicated [Query API](https://github.com/cardano-scaling/hydra/discussions/686) to ease implementation of stateless clients.

- Calling `StateChanged` an _event_ while treating it in the code alongside _effects_ might introduce some confusion as we already use the word [Event](https://github.com/input-output-hk/hydra/blob/45913954eb18ef550a31017daa443cee6720a00c/hydra-node/src/Hydra/HeadLogic.hs#L64) to designate the inputs (a.k.a. commands) to the Head logic state machine. We might want at some later point to unify the terminology.
- Calling `StateChanged` an _event_ while treating it in the code alongside _effects_ might introduce some confusion as we already use the word [Event](https://github.com/cardano-scaling/hydra/blob/45913954eb18ef550a31017daa443cee6720a00c/hydra-node/src/Hydra/HeadLogic.hs#L64) to designate the inputs (a.k.a. commands) to the Head logic state machine. We might want at some later point to unify the terminology.
2 changes: 1 addition & 1 deletion docs/adr/2023-09-09_027-network-resilience.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Therefore, the scope of this ADR is to address only point 1. above: Ensure broad
withOuroborosNetwork (contramap Network tracer) localhost peers
```
* This has the nice property that we can basically swap the lower layers should we need to, for example to use [UDP](https://github.com/input-output-hk/hydra/blob/abailly-iohk/multi-node-udp/hydra-node/src/Hydra/Network/UDP.hs), or add other layers for example to address specific head instances in presence of [multiple heads](https://github.com/input-output-hk/hydra/blob/abailly-iohk/multi-node-udp/hydra-node/src/Hydra/Network/MultiHead.hs#L26)
* This has the nice property that we can basically swap the lower layers should we need to, for example to use [UDP](https://github.com/cardano-scaling/hydra/blob/abailly-iohk/multi-node-udp/hydra-node/src/Hydra/Network/UDP.hs), or add other layers for example to address specific head instances in presence of [multiple heads](https://github.com/cardano-scaling/hydra/blob/abailly-iohk/multi-node-udp/hydra-node/src/Hydra/Network/MultiHead.hs#L26)
## Decision
Expand Down
4 changes: 2 additions & 2 deletions docs/adr/2023-12-06_030-use-cbor-for-tx.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Accepted

## Context

* The [Hydra.Ledger.Cardano](https://github.com/input-output-hk/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano.hs#L127) module provides `ToJSON/FromJSON` instances for `Tx` and [AlonzoTx](https://github.com/input-output-hk/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano/Json.hs#L361)
* The [Hydra.Ledger.Cardano](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano.hs#L127) module provides `ToJSON/FromJSON` instances for `Tx` and [AlonzoTx](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano/Json.hs#L361)
* We have specified this format as part of [Hydra API](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/json-schemas/api.yaml#L1473)
* These instances appear in a few places as part of Hydra API:
* In the [ServerOutput](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/API/ServerOutput.hs#L51) sent by the node to clients
Expand All @@ -22,7 +22,7 @@ Accepted
* In the [Network.Message](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Network/Message.hs#L20) exchanged between the nodes
* In the [ClientInput](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/API/ClientInput.hs#L9) from clients submitting `NewTx` commands
* In the [HTTPServer](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/API/HTTPServer.hs#L297) API
* Note that in the latter 2 cases, the hydra-node _accepts_ a hex-CBOR-encoded _JSON string_ to represent a transaction and this particular case is handled directly in the [FromJSON](https://github.com/input-output-hk/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano/Json.hs#L388) instance for transactions where 3 different representations are even accepted:
* Note that in the latter 2 cases, the hydra-node _accepts_ a hex-CBOR-encoded _JSON string_ to represent a transaction and this particular case is handled directly in the [FromJSON](https://github.com/cardano-scaling/hydra/blob/b2dc5a0da4988631bd2c1e94b66ba6217d5db595/hydra-node/src/Hydra/Ledger/Cardano/Json.hs#L388) instance for transactions where 3 different representations are even accepted:
* JSON object detailing the transaction
* A JSON string representing CBOR-encoding of a transaction
* Or a `TextEnvelope` which wraps the CBOR transaction in a simple JSON object
Expand Down
2 changes: 1 addition & 1 deletion docs/benchmarks/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,4 @@ sidebar_position: 1

This section provides up-to-date data regarding the known limitations of the Hydra Head on-chain protocol. Cardano transactions and blocks are subject to constraints on transaction size, execution cost, and the number of inputs and outputs. These constraints are determined by network parameters and significantly influence the capabilities of the Hydra Head protocol, such as the maximum number of parties that can participate, the amount of UTXOs that can be committed, and the extent to which these UTXOs can be fanned out. As on-chain scripts and transactions are further optimized, and as the underlying Cardano blockchain evolves with expanded parameters and enhanced script execution efficiency, these limitations are expected to evolve.

The data in this section is _generated_ through Hydra's [continuous integration (CI)](https://github.com/input-output-hk/hydra/actions/workflows/ci-nix.yaml) process, ensuring that it accurately reflects the current state of the code.
The data in this section is _generated_ through Hydra's [continuous integration (CI)](https://github.com/cardano-scaling/hydra/actions/workflows/ci-nix.yaml) process, ensuring that it accurately reflects the current state of the code.
Loading

0 comments on commit 1d68e33

Please sign in to comment.