Incremental commits off-chain

docs/docs/dev/protocol.md

@@ -2,42 +2,100 @@
 
 Additional implementation-specific documentation for the Hydra Head protocol and extensions like incremental decommits.
 
+### Incremental Commits
+
+#### Deposit flow
+
+```mermaid
+sequenceDiagram
+    Alice->>+Node A: POST /commit UTxO
+    Node A-->>-Alice: depositTx
+
+    Alice ->> Alice: sign depositTx
+    Alice ->> Chain: submit depositTx
+
+    Chain ->>+ Node A: OnDepositTx utxo
+    Chain ->>+ Node B: OnDepositTx utxo
+
+    Node A -->> Alice: DepositDetected
+
+    par Alice isLeader
+        Node A->>Node A: ReqSn utxoToCommit
+    and
+        Node A->>Node B: ReqSn utxoToCommit
+    end
+
+    Node A -->> Alice: CommitRequested
+
+    Node A->>Node A: sig = sign snapshot incl. utxoToCommit
+
+    par broadcast
+        Node A->>Node A: AckSn sig
+    and
+        Node A->>Node B: AckSn sig
+    end
+    Node B->>Node A: AckSn sig
+    Node A -->> Alice: SnapshotConfirmed
+
+    Node A -->> Alice: CommitApproved
+
+    Node A ->> Chain: IncrementTx snapshot sig
+    Chain ->> Node A: OnIncrementTx
+    Node A -->> Alice: CommitFinalized
+```
+
+#### Recover flow
+
+```mermaid
+sequenceDiagram
+    Alice->>+Node A: DELETE /commits/<tx-in>
+    Node A->>Chain: recoverTx
+    Chain ->>+ Node A: OnRecoverTx utxo
+    Chain ->>+ Node B: OnRecoverTx utxo
+    Node A -->>- Alice: CommitRecovered
+    Node B -->>- Bob: CommitRecovered
+    Node A-->>-Alice: OK
+
+```
+
 ### Incremental Decommits
 
 ```mermaid
 sequenceDiagram
-    Alice->>HeadLogic: Decommit (decTx)
-    HeadLogic->>HeadLogic: canApply decTx
+    Alice->>+Node A: POST /decommit (decTx)
+    Node A-->>-Alice: OK
+
+    Node A->>Node A: canApply decTx
 
     par broadcast
-        HeadLogic->>HeadLogic: ReqDec decTx
+        Node A->>Node A: ReqDec decTx
     and
-        HeadLogic->>Node B: ReqDec decTx
+        Node A->>Node B: ReqDec decTx
     end
 
-    HeadLogic -->> Alice: DecommitRequested
+    Node A -->> Alice: DecommitRequested
 
     par Alice isLeader
-        HeadLogic->>HeadLogic: ReqSn decTx
+        Node A->>Node A: ReqSn decTx
     and
-        HeadLogic->>Node B: ReqSn decTx
+        Node A->>Node B: ReqSn decTx
     end
 
-    HeadLogic->>HeadLogic: canApply decTx, decUTxO =  outputs(decTx)
-    HeadLogic->>HeadLogic: sig = sign snapshot incl. decUTxO
+    Node A->>Node A: canApply decTx, decUTxO =  outputs(decTx)
+    Node A->>Node A: sig = sign snapshot incl. decUTxO
 
     par broadcast
-        HeadLogic->>HeadLogic: AckSn sig
+        Node A->>Node A: AckSn sig
     and
-        HeadLogic->>Node B: AckSn sig
+        Node A->>Node B: AckSn sig
     end
 
-    Node B->>HeadLogic: AckSn sig
+    Node B->>Node A: AckSn sig
 
-    HeadLogic -->> Alice: SnapshotConfirmed
-    HeadLogic -->> Alice: DecommitApproved
+    Node A -->> Alice: SnapshotConfirmed
+    Node A -->> Alice: DecommitApproved
 
-    HeadLogic ->> Chain: DecrementTx snapshot sig
-    Chain ->> HeadLogic: OnDecrementTx
-    HeadLogic -->> Alice: DecommitFinalized
+    Node A ->> Chain: DecrementTx snapshot sig
+    Chain ->> Node A: OnDecrementTx
+    Node A -->> Alice: DecommitFinalized
 ```

docs/docs/how-to/incremental-commit.md

@@ -0,0 +1,92 @@
+# Commit funds to an open Head
+
+Assuming we already have an open Head and some funds on the L1 we would like to commit.
+
+### Demo setup
+
+For example a demo setup could use our `hydra-cluster` binary:
+
+:::caution TODO
+Could also copy the faucet keys for more convenience.
+:::
+
+```shell
+cabal run hydra-cluster -- \
+  --devnet \
+  --publish-hydra-scripts \
+  --state-directory incremental-demo
+```
+
+The following commands expect these environment variables:
+
+```shell
+export CARDANO_NODE_SOCKET_PATH=${PWD}/incremental-demo/node.socket
+export CARDANO_NODE_NETWORK_ID=42
+```
+
+We can inspect the L1 utxo with:
+
+```shell
+cardano-cli query utxo --whole-utxo
+```
+and
+
+```shell
+cardano-cli query utxo \
+  --address $(cardano-cli address build --payment-verification-key-file hydra-cluster/config/credentials/faucet.vk)
+```
+
+
+In this setup, we would be using the `faucet` keys to commit everything into the head.
+
+```shell
+export WALLET_SK=${PWD}/hydra-cluster/config/credentials/faucet.sk
+export WALLET_VK=${PWD}/hydra-cluster/config/credentials/faucet.vk
+cd incremental-demo
+```
+
+### Deposit UTxO to commit
+
+To observe funds owned on L2 we can use `hydra-tui`
+
+```shell
+cabal run hydra-tui -- --cardano-signing-key ${WALLET_SK}
+```
+
+The `/commit` endpoint supports two ways of specifying what to commit, one is just by showing the UTxO (which is assumed to be owned by public keys), while the more advanced way would be using [blueprint transactions](./commit-blueprint).
+
+We are using the simple request here and want to commit everything owned by `${WALLET_SK}`. So we can just query the L1 for all UTxO owned by it:
+```shell
+cardano-cli query utxo \
+  --address $(cardano-cli address build --payment-verification-key-file ${WALLET_VK}) \
+  --out-file commit-utxo.json
+```
+
+Then a request to the `/commit` endpoint provides us with a transaction:
+
+:::danger FIXME
+Should be able to do just this:
+```shell
+curl -X POST localhost:4001/commit \
+  --data @commit-utxo.json
+```
+:::
+
+```shell
+jq '{utxo: .}' commit-utxo.json | \
+  curl -X POST localhost:4001/commit --data @- \
+  > deposit-tx.json
+```
+
+Which we can submit to the cardano network:
+```shell
+cardano-cli transaction sign \
+  --tx-file deposit-tx.json \
+  --signing-key-file ${WALLET_SK} \
+  --out-file deposit-tx.signed.json
+
+cardano-cli transaction submit \
+  --tx-file deposit-tx.signed.json
+```
+
+This will result in a deposit being detected by the `hydra-node` and consequently the funds to be committed to the head.

hydra-cardano-api/src/Hydra/Cardano/Api.hs

@@ -114,6 +114,7 @@ import Cardano.Api.UTxO (
   UTxO' (..),
  )
 import Cardano.Ledger.Coin as X (Coin (..))
+import Hydra.Cardano.Api.Network as X (networkIdToNetwork)
 import Hydra.Cardano.Api.Prelude (
   Era,
   LedgerEra,

hydra-chain-observer/hydra-chain-observer.cabal

@@ -93,6 +93,7 @@ test-suite tests
   type:               exitcode-stdio-1.0
   build-depends:
     , hspec
+    , hydra-cardano-api
     , hydra-chain-observer
     , hydra-node
     , hydra-prelude

hydra-chain-observer/src/Hydra/ChainObserver.hs

@@ -91,6 +91,9 @@ data ChainObserverLog
   | HeadInitTx {headId :: HeadId}
   | HeadCommitTx {headId :: HeadId}
   | HeadCollectComTx {headId :: HeadId}
+  | HeadDepositTx {headId :: HeadId}
+  | HeadRecoverTx {headId :: HeadId}
+  | HeadIncrementTx {headId :: HeadId}
   | HeadDecrementTx {headId :: HeadId}
   | HeadCloseTx {headId :: HeadId}
   | HeadFanoutTx {headId :: HeadId}
@@ -203,6 +206,9 @@ chainSyncClient tracer networkId startingPoint observerHandler =
     OnInitTx{headId} -> HeadInitTx{headId}
     OnCommitTx{headId} -> HeadCommitTx{headId}
     OnCollectComTx{headId} -> HeadCollectComTx{headId}
+    OnIncrementTx{headId} -> HeadIncrementTx{headId}
+    OnDepositTx{headId} -> HeadDepositTx{headId}
+    OnRecoverTx{headId} -> HeadRecoverTx{headId}
     OnDecrementTx{headId} -> HeadDecrementTx{headId}
     OnCloseTx{headId} -> HeadCloseTx{headId}
     OnFanoutTx{headId} -> HeadFanoutTx{headId}

hydra-chain-observer/test/Hydra/ChainObserverSpec.hs

@@ -3,6 +3,7 @@ module Hydra.ChainObserverSpec where
 import Hydra.Prelude
 import Test.Hydra.Prelude
 
+import Hydra.Cardano.Api (utxoFromTx)
 import Hydra.Chain.Direct.State (HasKnownUTxO (getKnownUTxO), genChainStateWithTx)
 import Hydra.Chain.Direct.State qualified as Transition
 import Hydra.Chain.Direct.Tx (HeadObservation (..))
@@ -20,11 +21,13 @@ spec =
         forAllBlind genChainStateWithTx $ \(_ctx, st, tx, transition) ->
           genericCoverTable [transition] $
             counterexample (show transition) $
-              let utxo = getKnownUTxO st
+              let utxo = getKnownUTxO st <> utxoFromTx tx
                in case snd $ observeTx testNetworkId utxo tx of
                     Just (Init{}) -> transition === Transition.Init
                     Just (Commit{}) -> transition === Transition.Commit
                     Just (CollectCom{}) -> transition === Transition.Collect
+                    Just (Deposit{}) -> transition === Transition.Deposit
+                    Just (Increment{}) -> transition === Transition.Increment
                     Just (Decrement{}) -> transition === Transition.Decrement
                     Just (Abort{}) -> transition === Transition.Abort
                     Just (Close{}) -> transition === Transition.Close
@@ -33,9 +36,12 @@ spec =
                     _ -> property False
 
     prop "Updates UTxO state given transaction part of Head lifecycle" $
-      forAllBlind genChainStateWithTx $ \(_ctx, st, tx, _transition) ->
+      forAllBlind genChainStateWithTx $ \(_ctx, st, tx, transition) ->
         let utxo = getKnownUTxO st
-         in fst (observeTx testNetworkId utxo tx) =/= utxo
+         in -- NOTE: deposit doesn't affect the Head UTxO state
+            if transition == Transition.Deposit
+              then property True
+              else fst (observeTx testNetworkId utxo tx) =/= utxo
 
     prop "Does not updates UTxO state given transactions outside of Head lifecycle" $
       forAll genSequenceOfSimplePaymentTransactions $ \(utxo, txs) ->

hydra-cluster/hydra-cluster.cabal

@@ -94,6 +94,7 @@ library
     , directory
     , filepath
     , http-conduit
+    , http-types
     , hydra-cardano-api
     , hydra-node
     , hydra-prelude