diff --git a/CHANGELOG.md b/CHANGELOG.md index e1379ed2919..7893660bf4e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,8 @@ changes. - Change `--start-chain-from` to always use the newer point when also a head state is known. +- Moved several pages from "core concepts" into the user manual and developer docs to futher improve user journey. + ## [0.17.0] - 2024-05-20 - **BREAKING** Change `hydra-node` API `/commit` endpoint for committing from scripts [#1380](https://github.com/input-output-hk/hydra/pull/1380): @@ -446,7 +448,7 @@ head again. - Add the [specification](https://github.com/input-output-hk/hydra/tree/master/spec) to the repository and - [website](https://hydra.family/head-protocol/core-concepts/specification). + [website](https://hydra.family/head-protocol/dev/specification). [#693](693) - Disabled `aarch64-darwin` support, until a `cardano-node` for this platform is @@ -611,7 +613,7 @@ Only when this procedure has been applied to all Hydra nodes can you open a new - After restarting `hydra-node`, clients will receive the whole history. [#580](https://github.com/input-output-hk/hydra/issues/580) + This history will be stored in the `server-output` file in `--persistence-dir`. - + Clients should use `Greetings` to identify the end of a [restart/replay of events](https://hydra.family/head-protocol/core-concepts/behavior#replay-of-past-server-outputs). + + Clients should use `Greetings` to identify the end of a [restart/replay of events](https://hydra.family/head-protocol/docs/api-behavior#replay-of-past-server-outputs). - Fixed observing the chain for Hydra L1 transactions after restart. [599](https://github.com/input-output-hk/hydra/issues/599) @@ -733,9 +735,9 @@ Only when this procedure has been applied to all Hydra nodes can you open a new + Not crash anymore on rollbacks + Rewind the internal head state to the point prior to rollback point + Added `RolledBack` server output, see [API reference](https://hydra.family/head-protocol/api-reference) - + See the [user manual](https://hydra.family/head-protocol/core-concepts/rollbacks/) for a detailed explanation on how rollbacks are handled. + + See the [user manual](https://hydra.family/head-protocol/dev/rollbacks/) for a detailed explanation on how rollbacks are handled. -- [Hydra Network](https://hydra.family/head-protocol/core-concepts/networking) section on the website about networking requirements and considerations +- [Hydra Network](https://hydra.family/head-protocol/dev/networking) section on the website about networking requirements and considerations - [Benchmarks](https://hydra.family/head-protocol/benchmarks) section on the website with continuously updated and published results on transaction costs of Hydra protocol transactions + These are also performed and reported now on every PR -> [Example](https://github.com/input-output-hk/hydra/pull/340#issuecomment-1116247611) diff --git a/docs/core-concepts/hydra-head-lifecycle.svg b/docs/core-concepts/hydra-head-lifecycle.svg deleted file mode 100644 index f8b033c68aa..00000000000 --- a/docs/core-concepts/hydra-head-lifecycle.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/core-concepts/index.md b/docs/core-concepts/index.md deleted file mode 100644 index c94866d1aae..00000000000 --- a/docs/core-concepts/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Learn - -```mdx-code-block -import DocCardList from '@theme/DocCardList'; -import {useDocsSidebar} from '@docusaurus/theme-common/internal'; - - docId != "index")}/> -``` diff --git a/docs/core-concepts/behavior.md b/docs/docs/api-behavior.md similarity index 98% rename from docs/core-concepts/behavior.md rename to docs/docs/api-behavior.md index 209acf66903..a76491395e3 100644 --- a/docs/core-concepts/behavior.md +++ b/docs/docs/api-behavior.md @@ -1,8 +1,4 @@ ---- -sidebar_position: 5 ---- - -# API Behavior +# API behavior :::caution Deprecated This page will soon move into the [API reference](/api-reference) itself. diff --git a/docs/docs/dev/architecture/index.md b/docs/docs/dev/architecture/index.md index b78cc08a886..c1bda2c9bd6 100644 --- a/docs/docs/dev/architecture/index.md +++ b/docs/docs/dev/architecture/index.md @@ -1,8 +1,4 @@ ---- -sidebar_position: 4 ---- - -# Hydra Node Architecture +# Architecture This document describes the architecture of the current implementation of a `hydra-node`. The following picture represents the main diff --git a/docs/docs/dev/architecture/networking.md b/docs/docs/dev/architecture/networking.md index 9183fec77c7..37f91b823c6 100644 --- a/docs/docs/dev/architecture/networking.md +++ b/docs/docs/dev/architecture/networking.md @@ -1,8 +1,4 @@ ---- -sidebar_position: 5 ---- - -# Hydra Networking +# Networking This document provides details about the _Hydra Networking Layer_, eg. the network comprised of Hydra nodes upon which Heads can be opened. diff --git a/docs/docs/dev/haskell-packages.md b/docs/docs/dev/haskell-packages.md index 6f8bad79206..354e9a949f1 100644 --- a/docs/docs/dev/haskell-packages.md +++ b/docs/docs/dev/haskell-packages.md @@ -1,8 +1,4 @@ ---- -sidebar_position: 99 ---- - -# Haskell Packages +# Haskell packages The Hydra project is divided into several Haskell packages fulfilling different parts of the protocol. While some packages are internal and specific to the Hydra project, some are quite generic and may be useful to other projects facing similar issues. Regardless, we expose [Haddock](https://www.haskell.org/haddock/) documentation for all of them. diff --git a/docs/core-concepts/horizontal-vertical-scaling.png b/docs/docs/dev/horizontal-vertical-scaling.png similarity index 100% rename from docs/core-concepts/horizontal-vertical-scaling.png rename to docs/docs/dev/horizontal-vertical-scaling.png diff --git a/docs/docs/dev/index.md b/docs/docs/dev/index.md index 05201b70683..a9bd30ddb9f 100644 --- a/docs/docs/dev/index.md +++ b/docs/docs/dev/index.md @@ -1,11 +1,7 @@ ---- -sidebar_position: 1 ---- - # About Hydra So you already read the [User Manual](../index.md) and still want to learn more about the Hydra protocol, its inner workings and how it is implemented? The developer documentation can help you with that. It is a collection of materials expanding on _using_ into _understanding_ Hydra. It is aimed anyone wanting to get a deeper understanding of the Hydra protocol, protocol architects who want to build their own variants and of course developers who contribute to the [reference implementation](https://github.com/input-output-hk/hydra) of Hydra itself. -Consequently, the following sections are more technical and maybe not as cohesive as the user manual, but the [architecture](./architecture) or the [specification](/core-concepts/specification) should be a good starting point. +Consequently, the following sections are more technical and maybe not as cohesive as the user manual, but the [architecture](./architecture) or the [specification](./specification) should be a good starting point. diff --git a/docs/core-concepts/layer-two.md b/docs/docs/dev/layer-two.md similarity index 99% rename from docs/core-concepts/layer-two.md rename to docs/docs/dev/layer-two.md index c00f39da66d..c460cad456a 100644 --- a/docs/core-concepts/layer-two.md +++ b/docs/docs/dev/layer-two.md @@ -1,7 +1,3 @@ ---- -sidebar_position: 3 ---- - # Layer 2 solutions This section provides an overview of various types of layer 2 solutions, along with several examples. diff --git a/docs/docs/dev/rollbacks/index.md b/docs/docs/dev/rollbacks/index.md index fb3071c5164..f49a5cb1528 100644 --- a/docs/docs/dev/rollbacks/index.md +++ b/docs/docs/dev/rollbacks/index.md @@ -1,4 +1,4 @@ -# Handling Rollbacks +# Handling rollbacks Rollbacks are an integral part of the behaviour of the Cardano chain: Any application built on top of Cardano and synchronizing its behaviour with the chain must be prepared to occasionally observe such _rollbacks_ and Hydra is no exception. diff --git a/docs/core-concepts/scalability.md b/docs/docs/dev/scalability.md similarity index 99% rename from docs/core-concepts/scalability.md rename to docs/docs/dev/scalability.md index c8a4ab6c713..523337c5bc1 100644 --- a/docs/core-concepts/scalability.md +++ b/docs/docs/dev/scalability.md @@ -1,7 +1,3 @@ ---- -sidebar_position: 2 ---- - # Scalability Decentralized systems, including blockchains, face fundamental scalability limitations due to their reliance on global transaction replication to ensure security. This constraint is commonly known as the blockchain trilemma, where _decentralization_, _security_, and _scalability_ counteract each other. Although Cardano employs an efficient consensus algorithm, its global distribution among thousands of block-producing nodes results in block creation approximately every twenty seconds. During peak transaction times, this can lead to increased settlement times as transactions may not be included in the immediate next block. diff --git a/docs/core-concepts/specification.md b/docs/docs/dev/specification.md similarity index 80% rename from docs/core-concepts/specification.md rename to docs/docs/dev/specification.md index 1e317cf8530..61d045f3c50 100644 --- a/docs/core-concepts/specification.md +++ b/docs/docs/dev/specification.md @@ -1,8 +1,3 @@ ---- -sidebar_position: 6 -custom_edit_url: https://github.com/input-output-hk/hydra/tree/master/spec ---- - # Specification The specification is currently written in LaTeX and can be [edited](https://github.com/input-output-hk/hydra/tree/master/spec) in the Hydra repository. You can view the rendered version below or download it for fullscreen viewing [here](/hydra-spec.pdf). diff --git a/docs/core-concepts/state-channel.png b/docs/docs/dev/state-channel.png similarity index 100% rename from docs/core-concepts/state-channel.png rename to docs/docs/dev/state-channel.png diff --git a/docs/docs/faqs.md b/docs/docs/faqs.md index 0d8a770ff80..0b40d1409a9 100644 --- a/docs/docs/faqs.md +++ b/docs/docs/faqs.md @@ -1,3 +1,6 @@ +--- +title: FAQs +--- # Frequently asked questions
diff --git a/docs/docs/index.md b/docs/docs/index.md index b9d256b1906..1a7543a9ef3 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -8,8 +8,6 @@ Decentralized applications (DApps), exchanges, and enterprise-level services can The `hydra-node` interfaces with the Cardano blockchain, connects to other `hydra-nodes` on a dedicated overlay network, runs a simplified (coordinated) Hydra Head protocol, and provides an API for clients. -Navigate through tutorials and documentation guides to get started. If you want to learn more about core concepts, see [this section](https://hydra.family/head-protocol/core-concepts). If you're interested in building, see [developer documentation](https://hydra.family/head-protocol/docs/dev). - :::warning Mainnet availability disclaimer The Hydra Head protocol version 0.10.0 or newer is compatible with the Cardano @@ -34,7 +32,7 @@ implied terms are excluded to the fullest extent permitted by law. For details, see also sections 7, 8 and 9 of the [Apache 2.0 License][license]. ::: -Now, without further ado, you can learn more about the protocol by visiting the [protocol overview page](/core-concepts/protocol-overview) or directly dive into [getting started using a local devnet](./getting-started). +Now, without further ado, you can learn more about the protocol by visiting the [protocol overview page](./protocol-overview) or directly dive into [getting started using a local devnet](./getting-started). [known-issues]: ./known-issues.md [license]: https://github.com/input-output-hk/hydra/blob/master/LICENSE diff --git a/docs/core-concepts/protocol-overview.md b/docs/docs/protocol-overview.md similarity index 98% rename from docs/core-concepts/protocol-overview.md rename to docs/docs/protocol-overview.md index 2ac8ce2d044..54099613313 100644 --- a/docs/core-concepts/protocol-overview.md +++ b/docs/docs/protocol-overview.md @@ -1,8 +1,4 @@ ---- -sidebar_position: 4 ---- - -# Hydra Head protocol overview +# Protocol overview Hydra is the layer 2 scalability solution for Cardano, designed to increase transaction speed through low latency and high throughput while minimizing transaction costs. [Hydra Head](https://eprint.iacr.org/2020/299.pdf) is the first protocol of the Hydra family that lays the foundation for more advanced deployment scenarios using isomorphic, multi-party state channels. For an introduction to the protocol, refer to these two blog posts: diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 813cb68d49d..8dd5ca2955e 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -75,17 +75,6 @@ const config = { sidebarPath: false, }), ], - [ - "content-docs", - /** @type {import('@docusaurus/plugin-content-docs').Options} */ - ({ - id: "core-concepts", - path: "core-concepts", - routeBasePath: "core-concepts", - editUrl, - editLocalizedFiles: true, - }), - ], [ "content-docs", /** @type {import('@docusaurus/plugin-content-docs').Options} */ @@ -165,11 +154,6 @@ const config = { label: "Developer Documentation", position: "left", }, - { - to: "/core-concepts", - label: "Core Concepts", - position: "right", - }, { to: "/topologies", label: "Topologies", diff --git a/docs/sidebars.js b/docs/sidebars.js index aeea29e2b85..3ad8d17d427 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,10 +1,7 @@ module.exports = { userDocumentation: [ - { - type: "doc", - label: "Welcome", - id: "index", - }, + "index", + "protocol-overview", "known-issues", { type: "html", @@ -12,32 +9,16 @@ module.exports = { defaultStyle: true, className: "sidebar-header", }, - { - type: "doc", - id: "getting-started", - label: "Getting started", - }, - { - type: "doc", - id: "tutorial/index", - label: "Open a head on testnet", - }, + "getting-started", + "tutorial/index", { type: "html", value: "Documentation", defaultStyle: true, className: "sidebar-header", }, - { - type: "doc", - id: "installation", - label: "Installation", - }, - { - type: "doc", - id: "configuration", - label: "Configuration", - }, + "installation", + "configuration", { type: "category", label: "How to ...", @@ -50,11 +31,7 @@ module.exports = { }, ], }, - { - type: "doc", - id: "faqs", - label: "FAQ", - }, + "faqs", { type: "html", value: "Reference", @@ -71,6 +48,7 @@ module.exports = { href: "/api-reference", label: "API reference", }, + "api-behavior", { type: "link", href: "/benchmarks", @@ -79,10 +57,34 @@ module.exports = { ], developerDocumentation: [ + "dev/index", + { + type: "doc", + id: "dev/specification", + label: "Specification", + }, + { + type: "category", + link: { type: "doc", id: "dev/architecture/index" }, + label: "Architecture", + items: ["dev/architecture/networking"], + }, + "dev/rollbacks/index", + { + type: "html", + value: "Background", + defaultStyle: true, + className: "sidebar-header", + }, + "dev/scalability", + "dev/layer-two", { - type: "autogenerated", - dirName: "dev", + type: "html", + value: "Reference", + defaultStyle: true, + className: "sidebar-header", }, + "dev/haskell-packages", { type: "link", href: "/adr", diff --git a/docs/standalone/audit-guidelines.md b/docs/standalone/audit-guidelines.md index 6d3208d0b64..337f106172a 100644 --- a/docs/standalone/audit-guidelines.md +++ b/docs/standalone/audit-guidelines.md @@ -117,7 +117,7 @@ This sections gives a detailed description of the artifacts mentioned above in t The Hydra Head protocol implementation derives from [Hydra: Fast Isomorphic State Channels](https://eprint.iacr.org/2020/299.pdf) in several ways. Especially some simplifications have been introduced and generalizations removed. -The [Hydra Head specification](/core-concepts/specification) captures these deviations and also includes the "formal notation" of the actual transaction constraints (which are foregone in the original paper). Also, it details the L2 protocol logic for the **Coordinated** Head protocol - which is implemented in V1. +The [Hydra Head specification](/docs/dev/specification) captures these deviations and also includes the "formal notation" of the actual transaction constraints (which are foregone in the original paper). Also, it details the L2 protocol logic for the **Coordinated** Head protocol - which is implemented in V1. ### Artifact 2: Hydra Head Protocol Implementation diff --git a/docs/topologies/index.md b/docs/topologies/index.md index 88990b99ea6..09dfeb2cb37 100644 --- a/docs/topologies/index.md +++ b/docs/topologies/index.md @@ -5,7 +5,7 @@ sidebar_position: 1 # Topologies -Hydra Head is a well-defined Layer 2 consensus protocol as explained in the [Core Concepts](/core-concepts) page, but this is not the end of the story and does not really define _how to use_ this protocol and what _topologies_ are possible. While [example use cases](/use-cases) should help in understanding the former, the _topologies_ below explain some of the various ways in which Hydra Nodes and Hydra Heads could be deployed and interconnected. +Hydra Head is a well-defined Layer 2 consensus protocol as explained in the [Developer documentation](/docs/dev), but this is not the end of the story and does not really define how to use this protocol at large and what _topologies_ are possible. While [example use cases](/use-cases) should help in understanding the former, the _topologies_ below explain some of the various ways in which Hydra Nodes and Hydra Heads could be deployed and interconnected. As more users implement solutions on top of Hydra, this "catalog" of topologies shall expand to help newcomers find and build the deployment model that suits best their use case. @@ -15,4 +15,4 @@ import DocCardList from '@theme/DocCardList'; import {useDocsSidebar} from '@docusaurus/theme-common/internal'; docId != "index")}/> -``` \ No newline at end of file +``` diff --git a/hydra-node/json-schemas/api.yaml b/hydra-node/json-schemas/api.yaml index fb4169b52a1..5d7d76e8284 100644 --- a/hydra-node/json-schemas/api.yaml +++ b/hydra-node/json-schemas/api.yaml @@ -10,7 +10,7 @@ info: For example if client provides a path that looks like this `/?history=no&snapshot-utxo=no` the server will not serve prior history of server outputs, and the utxo field in the json will be omitted. 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. + See [the documentation](https://hydra.family/head-protocol/dev/api-behavior/) for more details on the overall API behavior. Users can also use the HTTP endpoint to draft a commit tx using their own utxo, potentially including a blueprint tx as part of the draft. diff --git a/hydra-node/json-schemas/logs.yaml b/hydra-node/json-schemas/logs.yaml index 15b4859d300..659ad43778b 100644 --- a/hydra-node/json-schemas/logs.yaml +++ b/hydra-node/json-schemas/logs.yaml @@ -950,7 +950,7 @@ definitions: 'contents' field. Please note each possible precondition failure is tied to some specific 'require p' expression in the specification (check - https://hydra.family/head-protocol/core-concepts/specification). + https://hydra.family/head-protocol/dev/specification). additionalProperties: false required: - tag