Merge pull request #419 from input-output-hk/KtorZ/use-cases

Write-up bits about Hydra use cases.

docs/docusaurus.config.js

@@ -70,6 +70,16 @@ const config = {
         editUrl
       })
     ],
+    [
+      'content-docs',
+      /** @type {import('@docusaurus/plugin-content-docs').Options} */
+      ({
+        id: 'use-cases',
+        path: 'use-cases',
+        routeBasePath: 'use-cases',
+        editUrl
+      })
+    ],
     [
       'content-docs',
       /** @type {import('@docusaurus/plugin-content-docs').Options} */
@@ -108,6 +118,11 @@ const config = {
             label: 'User Manual',
             position: 'left',
           },
+          {
+            to: '/use-cases',
+            label: 'Use Cases',
+            position: 'left',
+          },
           {
             to: '/core-concepts',
             label: 'Core Concepts',

docs/i18n/fr/docusaurus-theme-classic/navbar.json

@@ -26,5 +26,9 @@
   "item.label.GitHub": {
     "message": "GitHub",
     "description": "Navbar item with label GitHub"
+  },
+  "item.label.Use Cases": {
+    "message": "Cas d'usages",
+    "description": "Navbar item with label Use Cases"
   }
 }

docs/topologies/star-shaped/index.md

@@ -18,7 +18,7 @@ A _Star-shaped Hydra Network_ or more precisely a Star-shaped Heads Network is c
 
 ![Star-shaped Heads Network](./star-shaped-general.jpg)
 
-Client nodes want to be able to interact with each other efficiently, at a low cost, using L2 solution, with all the Hydra safety guarantees, but without bearing the operational burden of operating an always online "full" Hydra node (eg. using an embedded version of the node, or a lighweight version). There might be a lot of them, say in the 100s or even 1000s but they are not always all live and up at the same time.
+Client nodes want to be able to interact with each other efficiently, at a low cost, using L2 solution, with all the Hydra safety guarantees, but without bearing the operational burden of operating an always online "full" Hydra node (eg. using an embedded version of the node, or a lightweight version). There might be a lot of them, say in the 100s or even 1000s but they are not always all live and up at the same time.
 
 Client nodes establish pairwise Heads (eg. _channels_) with the server: This setup is simpler than with a normal multiparty head because the server has as a well-known identity and the client can always provide the needed parameters (keys, IP) to the server when setting up the Head using some specific service whose definition is outside of the scope of this document.
 

docs/use-cases/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Overview",
+  "position": 1
+}

docs/use-cases/index.md

@@ -0,0 +1,15 @@
+---
+sidebar_label: 'Overview'
+sidebar_position: 1
+---
+
+# Use Cases
+
+In this section, you'll find example use cases and user-stories about Hydra heads. At this stage, this is mostly how we envision people using Hydra or what we think can be valid use cases. We hope that this not only helps readers understand a bit more the pros and cons of using Hydra heads as a layer 2 solution, but we hope it may also inspire projects and new use cases!
+
+```mdx-code-block
+import DocCardList from '@theme/DocCardList';
+import {useDocsSidebar} from '@docusaurus/theme-common';
+
+<DocCardList items={useDocsSidebar().filter(({ docId }) => docId != "index")}/>
+```

docs/use-cases/inter-wallet-payments/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Inter-Wallet Payments",
+  "position": 4
+}

docs/use-cases/inter-wallet-payments/index.md

@@ -0,0 +1,11 @@
+# Inter-Wallet Payments
+
+> A (semi-)custodial p2p payment service through wallet providers.
+
+A Hydra head is limited in terms of the number of participants. Because of this, building a large-scale peer-to-peer payment solution can't be done naively where each peer is itself a member of the Head. While the long-term roadmap already envisions routing solutions and networks of heads (see also [Interhead Hydra: Two Heads Are Better Than One](https://eprint.iacr.org/2021/1188) by Jourenko & al), intermediate approaches may involve trusted parties such as light wallet providers. Plus, one can rely on additional on-chain smart contracts to reduce the trust assumption as much as possible.
+
+In this scenario, we imagine a Hydra Head formed by a few major light wallet providers of the network who all have a common interest in providing their users with cheap and fast inter-wallet payments. Therefore, each wallet provider is a Head member and processes transactions inside the Head on behalf of their users. To transact inside the Head, users must first lock funds they want to move on layer 2 inside a particular contract. This contract authorizes any wallet provider to redeem funds from it, provided they have proof of payment issued by the corresponding user. 
+
+Through their interface, wallet providers can show the _virtual balance_ held in each account based on the traffic on layer two. The _effective balance_ (i.e. the value locked on the layer one) remains unchanged. Users may ask any wallet provider to unlock funds in the contract at any time if any are left. This is done by collecting the funds at one or more of those contracts. Then funds are re-distributed accordingly: some back in locked accounts and some back to the user who requested his money back.
+
+We assume in this scenario that the traffic between wallet providers is somewhat symmetrical (that is, users of wallet X spend/receive roughly as much as users of wallet Y) so that there isn't too much imbalance in the system. Furthermore, it can be enforced by wallet providers who can reject specific payments if their processing invalidates the assumption.

docs/use-cases/nft-auction/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "NFT Auction",
+  "position": 5
+}

docs/use-cases/nft-auction/index.md

@@ -0,0 +1,28 @@
+# NFT Auction
+
+> Layer 1 redeemable vouchers negotiated on layer 2.
+
+NFT drops can be a real problem when run on L1, generating a lot of UTxO and transactions in a short amount of time, clogging the network and leading to congestion and general slowdowns. The problem seems to come not much from the NFTs themselves but from the large of number of bidding transactions people post to grab some.
+
+We sketch a way to run NFT auctions inside Hydra Head that would alleviate that problem. Here is an outline of the sequence of transactions involved, both on-chain and off-chain:
+
+![](./diagram.png)
+
+- The auctioneer forges some "auction tokens" (a.k.a VT) representing participation in an auction for some NFT;
+- The auctioneer commits the ATs in a Head;
+- The Auction ATs can be "grabbed" by bidders to bid some amounts for a given NFT auction;
+- The bidders do not have to be Head parties<sup>1</sup>, they just do "normal" cardano transactions to grab a bid token and then possibly keep bidding until the auction ends;
+- The auctioneer posts a settlement transaction that consumes all current bids at some point, producing a voucher for the NFT to be sent to Bob if he pays V2'. The voucher is only valid if produced by this script, and there might be some reserve price to ensure price does not fall below some threshold;
+- Then Head is closed and the voucher is posted on-chain;
+- Bob can redeem his NFT, paying V2' to the auctioneer.
+
+The auctioneer runs the risk of opening/closing a Head with the winner not reclaiming his NFT. If it does not run the head itself, it runs the risk of the Head parties rigging the auction but in the worst case, the Head is closed with someone having a voucher to claim the NFT at a reserved price, or the NFTs themselves are paid back to auctioneer.
+
+The bidders run the same risk of bidding in a rigged auction but in the worst case, they can refuse to pay for the NFT. Anyhow, this setup would offer already a much better security story than all the fully custodial NFT drops done on Cardano today
+
+:::info NOTES 
+
+1. In this scenario, the Head is initialised by the auctioneer. It could be a "Managed Head" or "Head-as-a-Service", e.g. The auctioneer does not run a Hydra node but uses some third-party provider to run the node. A single-party head might not seem to make much sense but in this case it's just a way to do Cardano transactions with smart-contracts faster than on the mainchain.
+
+2. This use case is _extracted_ from a [conversation that happened on Github](https://github.com/input-output-hk/hydra-poc/discussions/116). Have a look at the conversation for details and/or to comment.
+:::

docs/use-cases/pay-per-use-api/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Pay-Per-Use API",
+  "position": 3
+}

docs/use-cases/pay-per-use-api/index.md

@@ -0,0 +1,22 @@
+# Pay-per-use API 
+
+> Micro-payments between a service provider and a client.
+
+Let's consider a web service for transaction datum resolution in the form of an HTTP API. Given some datum hash, the API can return, if it exists, the pre-image of that hash digest. On the other end, we have a light-wallet provider with full Cardano smart-contract support and extra care for user experience and security. Part of the transaction workflow of the wallet consists of looking up datums and scripts included in transactions it sees, coming from various DApps its users interact with. Doing so, it can better show how a specific transaction will affect a contract and the data it carries. 
+
+To keep the light-wallet infrastructure setup simple, the implementors decide to rely on that external service for datum resolution. However, their relatively new product makes it hard to estimate appropriately the number of resources they would need and how many users they would eventually serve. Thus, they agree with the service provider to create a Hydra Head and use it to issue short-lived API credentials in exchange for a micro-payment. 
+
+Indeed, the service provider demands 10 lovelace per API lookup. In the final infrastructure, the light-wallet backend server is connected to the service provider with a long-running head. On every request from a user, the light wallet also issues a transaction in the Head. In exchange, the API provider gives a one-time token credential which can be used to authorize a request in the API. The whole dance is resolved in sub-second delays and without any transaction fee. 
+
+![](./diagram.png)
+
+
+Regularly, the light-wallet service refuels its Head via incremental commits (i.e. a Layer 1 transaction locking more value inside the Head). Similarly, every now and then, the service provider redeems its funds back to the Layer 1 using incremental de-commits. These two steps happen without ever closing the Head. 
+
+:::tip Rewards
+If both parties agree, they can also delegate funds locked inside the Head. This delegation may allow, for instance, the light wallet to keep earning rewards on amounts locked in the Head until the service provider redeems it. Said differently, Head participants can still make a passive income through network rewards to cover the cost of running the Head. 
+:::
+
+All-in-all, the light wallet service pay only for what it uses -- in the spirit of _cloud computing_. For the service provider, this is also highly beneficial because they can mutualize their Hydra infrastructure for multiple clients, further spreading their cost and thus, increasing their margin. In addition, they can earn Ada directly and avoid transaction fees on their clients' payments. 
+
+Note also that there are many possible ways this kind of construction can be set up between a client and service provider. For example, one could also imagine API tokens to be fungible tokens, like credits, bought by the client and spent on each request inside the Head. In such a scenario, it would be possible for the server to (a) limit its circulating supply to the number of resources it can handle and (b) create a secondary marketplace for credit surplus that clients have accumulated but won't use.

docs/use-cases/poker-game/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Poker Game",
+  "position": 2
+}

docs/use-cases/poker-game/index.md

@@ -0,0 +1,17 @@
+# Poker Game
+
+> A prototypical example of a multi-party state channel.
+
+We love to explain how Hydra heads work using the analogy of a _poker game_ because it suits pretty well the fundamentals behind the Head protocol. A poker game (or any game in general) is a situation with a clear beginning and an end that evolves around a set of agreed-upon rules. In the case of a poker game, the monetary component is at the centre; players place bids and exchange money at every step of the game. Furthermore, it is comprised of a fixed set of players who have conflicting goals (i.e. win the game), don't fully trust each other but are still willing to collaborate given the agreed set of rules.
+
+:::tip Decentralized randomness & Multi-Party Computation
+For this use case, we assume that there's a way an agreed-upon way to implement a decentralized poker game with pseudo-randomness or multi-party computation (see, for example [ROYALE by David & al](https://eprint.iacr.org/2018/157)). We focus on the state channel aspect of the story for which Hydra heads provide a solution. 
+:::
+
+In a poker game, every player can embody a Hydra Head member, running its own Hydra node. Each participant starts a Head by committing funds to that Head. These represent their chips. Once the Head is established, participants can begin playing the game by leveraging on-head Plutus contracts. Players can instantly process the transfer of funds inside the Head. This is a simple scenario where participants mainly send money to one another, mediated by a script (acting as the game dealer, warrants of the rules and good progress of the game). 
+
+![](./poker.webp)
+
+Eventually, the game reaches an end with a well-defined distribution of funds. Participants can then play another game or close the Head and write the end result onto the Layer 1. The whole game(s) is (are) unknown of the Layer 1. Only the final UTxO distribution is. 
+
+Since the game only involves basic payments and script interactions, it could have been played entirely on the Layer 1, without reaching for a Hydra head. However, a Hydra head provides fast-paced transactions for the course of the game and cheap (or even none) fees -- besides the costs needed to establish the Hydra Head.