Merge pull request #861 from input-output-hk/abailly-iohk/mainnet-dis…

…claimers

Mainnet disclaimers

README.md

@@ -19,12 +19,30 @@ we've put together, marching towards a production ready solution. It contains a
 connects to other hydra-nodes, interfaces the Cardano blockchain and provides an
 API to clients such as the included example terminal user interface `hydra-tui`.
 
-> :warning: :warning: :warning:
->
-> This is still prototypical and exploratory work shared here for your
-interest.
->
-> It is NOT ready for production (yet).
+:rotating_light: Mainnet Availability :rotating_light:
+
+The Hydra Head protocol version 0.10.0 is compatible with the Cardano mainnet,
+which means it is possible to run a hydra-node on mainnet for testing purposes.
+
+Before running a `hydra-node` to take part in the Hydra Head protocol,
+developers are strongly encouraged to review the [known issues][known-issues] in
+the documentation in order to understand the current limitations and the
+possible consequences.
+
+By using Hydra Head protocol version 0.10.0, you understand the protocol is in
+development and that use of the hydra-node on mainnet is entirely at your own
+risk.
+
+You also acknowledge and agree to have an adequate understanding of the risks
+associated with use of the Hydra Head protocol version 0.10.0 and that all
+information and materials published, distributed or otherwise made available on
+Hydra.Family and Hydra Github Repository is available on an ‘AS IS’ and ‘AS
+AVAILABLE’ basis, without any representations or warranties of any kind. All
+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].
+
+[known-issues]: https://hydra.family/head-protocol/getting-started/known-issues
+[license]: ./LICENSE
 
 ## :rocket: Getting started
 

docs/docs/getting-started/index.md

@@ -4,6 +4,44 @@ sidebar_position: 1
 
 # Getting Started
 
+Hydra is the layer-two scalability solution for Cardano, which aims to increase
+the speed of transactions (low latency, high throughput) and minimize
+transaction cost.
+
+This repository contains the proof-of-concept implementation for the Hydra [Head
+protocol](https://eprint.iacr.org/2020/299.pdf). It is a developer preview that
+we've put together, marching towards a production ready solution. It contains a
+`hydra-node`, which runs a simplified (coordinated) Hydra Head protocol,
+connects to other hydra-nodes, interfaces the Cardano blockchain and provides an
+API to clients such as the included example terminal user interface `hydra-tui`.
+
+:::warning Mainnet Availability
+
+The Hydra Head protocol version 0.10.0 is compatible with the Cardano mainnet,
+which means it is possible to run a hydra-node on mainnet for testing purposes.
+
+Before running a `hydra-node` to take part in the Hydra Head protocol,
+developers are strongly encouraged to review the [known issues][known-issues] in
+the documentation in order to understand the current limitations and the
+possible consequences.
+
+By using Hydra Head protocol version 0.10.0, you understand the protocol is in
+development and that use of the hydra-node on mainnet is entirely at your own
+risk.
+
+You also acknowledge and agree to have an adequate understanding of the risks
+associated with use of the Hydra Head protocol version 0.10.0 and that all
+information and materials published, distributed or otherwise made available on
+Hydra.Family and Hydra Github Repository is available on an ‘AS IS’ and ‘AS
+AVAILABLE’ basis, without any representations or warranties of any kind. All
+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].
+
+:::
+
+[known-issues]: ../known-issues
+[license]: https://github.com/input-output-hk/hydra/blob/master/LICENSE
+
 ```mdx-code-block
 import DocCardList from '@theme/DocCardList';
 import {useCurrentSidebarCategory} from '@docusaurus/theme-common';

docs/docs/getting-started/quickstart.md

@@ -282,5 +282,5 @@ We provide sample node configurations that will help you get started hosting a H
 ## Running on Mainnet
 
 Hydra node is compatible with the mainnet network. To choose this network you need to specify `--mainnet` flag for the network id in the hydra-node arguments. We publish the hydra scripts on each new release and you can find them on the [release page](https://github.com/input-output-hk/hydra/releases) (look for section _Hydra Scripts_).
-You would need to match the hydra-node version with the appropriate scripts published for this release and make sure to choose the correct network.
-Currently there is a hard-coded limit on mainnet network where you can only commit up to 100 ADA into the Hydra head which is meant to prevent the users from _shooting themselves in the foot_ until we have more experiments on the mainnet.
+
+Please be sure to read the [relevant section](/docs/known-issues) section to fully understand the limitations and consequences of running Hydra nodes on mainnet.

docs/docs/known-issues.md

@@ -0,0 +1,86 @@
+# Known issues & limitations
+
+Please be aware of the following limitations before running hydra-node
+on the Cardano `--mainnet`; as an incredibly technical project, Hydra
+in its current form requires an elevated level of understanding of the
+underlying infrastructure. Without the expertise required to operate a
+hydra-node, users may put their funds at risk if they are unfamiliar
+with the implementation and usage process.
+
+### Head protocol
+
+#### Layer-1/Layer-2
+
+The current transaction size on mainnet is limited to 16KB, a limitation which has the following consequences:
+  - The protocol can only handle a maximum number of participants in a
+    Head (see [cost of collectcom
+    transaction](/benchmarks/transaction-cost/#cost-of-collectcom-transaction)). Upon
+    startup, the `hydra-node` will inform you of the current
+    configured maximum when trying to configure too many peers.
+  - Each party can only commit zero or one UTxO into a Head.
+
+It's currently possible to be denied access to funds by other protocol
+participants at various stages in a Hydra Head because of the
+complexity or size of the UTxO being committed or created while the
+Head is open:
+  - The head cannot be _finalized_ if holding more than ~60 assets
+    (see [cost of fanout
+    transaction](https://hydra.family/head-protocol/benchmarks/transaction-cost/#cost-of-fanout-transaction)
+    for latest numbers), although it can be _closed_
+  - If one or more participants commit UTxO too large to be processed
+    together in a `CollectCom` or `Abort` transaction, the Head will
+    be stuck in the _initialising_ stage
+  - Tokens minted and not burnt in an _open_ head will prevent it from being _finalized_
+  - Committing reference scripts from L1 to a Head is problematic and
+    the hydra-node will prevent this should a client try to do
+    so. Note that a `Commit` transaction could perfectly be crafted
+    outside of the hydra-node and would therefore put the Head in an
+    uncloseable state
+  - Using reference scripts on the L2 is non problematic as they will
+    be committed back on the L1 along with all the other UTxO
+
+There are couple of items in the roadmap around reducing the risk of loosing funds in a Hydra Head:
+  - [Always abortable Head](https://github.com/input-output-hk/hydra/issues/699)
+  - [Limit size/complexity of UTxOs in the Head](https://github.com/input-output-hk/hydra/issues/698)
+  - [Only sign closable snapshots](https://github.com/input-output-hk/hydra/issues/370)
+
+#### Networking
+
+The messages exchanged through the _Hydra Network_ layer between
+participants are neither authenticated, authorized, nor encrypted
+which means communications between Hydra nodes are not protected. It's
+advised that operators requiring confidentiality and/or identification
+of participants run hydra-node connected through some kind of VPN or
+on top of encrypted channels until this is addressed in the software
+(see [#727](https://github.com/input-output-hk/hydra/issues/727))
+
+Also, while the Hydra Head protocol guarantees safety of a
+participant's funds, it does not guarantee liveness, so all parties
+involved in a Hydra Head must be online and reactive for the protocol
+to make progress. This means that, should one or several participants'
+Hydra node crash, become unreachable from other Hydra nodes, or is
+disconnected from the Cardano network, no more transactions can happen
+in the Head and it must be closed.
+
+### hydra-node
+
+Independently from the Head protocol itself, the way the hydra-node is
+implemented has the following consequences:
+
+- There is a hard-coded limit on **mainnet** network where you can
+  only commit up to 100 ADA into the Hydra head. This is only a safety
+  precaution and is going to be increased as we gain more experience
+  in running Hydra heads on the mainnet.
+- The internal wallet of `hydra-node` which is used to drive Hydra
+  protocol transactions requires a UTXO to be marked as "fuel" (see
+  [user
+  manual](/docs/getting-started/demo/with-docker/#seeding-the-network)
+
+### hydra-tui
+
+- TUI crashes when user tries to post a new transaction wihout any UTXO remaining.
+
+- Recipient addresses to send money to in the TUI are inferred from
+  the current UTXO set. If a party does not commit a UTXO or consumes
+  all its UTXO in a Head, it won't be able to send or receive anything
+  anymore.