Partial tokens regression test and fix (#2221)

fix #2180 

- This PR is the outcome of user reported issue where in their use case
it is required to be able to partially commit some assets from the
provided UTxO. My opinion is that we should mark this feature as
**experimental** until we get confirmations from more users that it is
actually working nicely for them which should be tracked in the
documentation.

- In order to successfully test the fix I had to add the option to mint
some tokens in our e2e tests so this adds on to the number of altered
files.

NOTE: This PR changes our Head script since I had to use `==` from
Plinth instead of our own strict equality `===`. This leads to smaller
script size so it seems like Plinth equality check is now improved
therefore we drop our own strict equality everywhere.


---

<!-- Consider each and tick it off one way or the other -->
* [x] CHANGELOG updated or not needed
* [x] Documentation updated or not needed
* [x] Haddocks updated or not needed
* [x] No new TODOs introduced or explained herafter

Author: v0d1ch

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

@@ -50,10 +50,153 @@ cardano-cli query utxo \
 ```
 
 :::info
-You can also specify `amount` of lovelace you want to commit together with the `UTxO` and hydra-node would
-commit only the specified amount and return any leftover to the user address.
+You can also specify `amount` of lovelace you want to commit as well as `assets` together with the `UTxO` and hydra-node would
+commit only the specified amount of lovelace or any potential non ADA assets and return any leftover to the user address.
 :::
 
+:::danger
+This functionality should be treated as **experimental** for the time being until we see some user reports that this API is
+working well and is easy to use.
+:::
+
+<details>
+ <summary>Partial commit example: </summary>
+
+   If there exists a user UTxO that looks like this
+
+   ```json
+   {"0bdf069df8fa1084989a7bda419c900810fd5d5a72a95f7ab487f96df9052fb8#0":
+     { "address":"addr_test1vq7j5vf74jw779y6ssxk2rwart5mltr2r7ju4gtfc3kcawcy0v2v8",
+       "datum":null,
+       "datumhash":null,
+       "inlineDatum":null,
+       "inlineDatumRaw":null,
+       "referenceScript":null,
+       "value":
+          { "dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75":
+              { "34":2007797983096461947,
+                "7041ef64f4476c6f6d8a3c74b7":4866145859671050979,
+                "b7a7b64d585f973e82be6ca36ae948":2,
+                "beb7e61cb67dd301":2
+              },
+            "lovelace":5000000
+          }
+     }
+   }
+
+   ```
+   Then the user can decide to commit some amount of lovelace and assets while the _change_ would be given back to the origin address.
+   In order to do that they can send a http POST request to the `/commit` endpoint
+   specifying the _amount_ of ADA and map of _tokens_ with quantities to commit:
+
+   ```json
+
+   {
+     "amount":3000000,
+     "tokens":
+        [
+          [ "dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75",
+               { "34":2007797983096461947,
+                 "7041ef64f4476c6f6d8a3c74b7":4866145859671050979
+               }
+          ]
+        ],
+     "utxoToCommit":
+        { "0bdf069df8fa1084989a7bda419c900810fd5d5a72a95f7ab487f96df9052fb8#0":
+             { "address":"addr_test1vq7j5vf74jw779y6ssxk2rwart5mltr2r7ju4gtfc3kcawcy0v2v8",
+               "datum":null,
+               "datumhash":null,
+               "inlineDatum":null,
+               "inlineDatumRaw":null,
+               "referenceScript":null,
+               "value":
+                   { "dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75":
+                        { "34":2007797983096461947,
+                          "7041ef64f4476c6f6d8a3c74b7":4866145859671050979,
+                          "b7a7b64d585f973e82be6ca36ae948":2,
+                          "beb7e61cb67dd301":2
+                        },
+                     "lovelace":5000000
+                   }
+             }
+        }
+   }
+
+   ```
+   Hydra node returns a deposit transaction which then needs to be signed and submitted to the network:
+
+   ```
+
+   "d22e92621c1b66d947eff97887feb19c1fb5751ecb7440cd6749ac8d734af04f"
+
+   == INPUTS (2)
+   - 0bdf069df8fa1084989a7bda419c900810fd5d5a72a95f7ab487f96df9052fb8#0
+         ShelleyAddress Testnet (KeyHashObj (KeyHash {unKeyHash = "3d2a313eac9def149a840d650ddd1ae9bfac6a1fa5caa169c46d8ebb"})) StakeRefNull
+         5000000 lovelace
+         2007797983096461947 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.34
+         4866145859671050979 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.7041ef64f4476c6f6d8a3c74b7
+         2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.b7a7b64d585f973e82be6ca36ae948
+         2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.beb7e61cb67dd301
+         TxOutDatumNone
+         ReferenceScriptNone
+   - 799028d0132ec355d6870704e040b73dbab67dba40313cb4f5dbc42d0e66bd40#1
+
+   == COLLATERAL INPUTS (1)
+   - 799028d0132ec355d6870704e040b73dbab67dba40313cb4f5dbc42d0e66bd40#1
+
+   == REFERENCE INPUTS (0)
+
+   == OUTPUTS (3)
+   Total number of assets: 5
+   - ShelleyAddress Testnet (ScriptHashObj (ScriptHash "ae01dade3a9c346d5c93ae3ce339412b90a0b8f83f94ec6baa24e30c")) StakeRefNull
+         3000000 lovelace
+         2007797983096461947 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.34
+         4866145859671050979 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.7041ef64f4476c6f6d8a3c74b7
+         TxOutDatumInline [0,["0x3fbb97e02ed6f34def7b87d9aaff67b4fe707f338d72bc2a7f93a409",1757516160812,[[0,[[0,["0x0bdf069df8fa1084989a7bda419c900810fd5d5a72a95f7ab487f96df9052fb8",0]],"0xd8799fd8799fd8799f581c3d2a313eac9def149a840d650ddd1ae9bfac6a1fa5caa169c46d8ebbffd87a80ffa240a1401a002dc6c0581cdcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75a241341b1bdd21a0bb35da7b4d7041ef64f4476c6f6d8a3c74b71b438805e09eee4ae3d87980d87a80ff"]]]]]
+   - ShelleyAddress Testnet (KeyHashObj (KeyHash {unKeyHash = "3d2a313eac9def149a840d650ddd1ae9bfac6a1fa5caa169c46d8ebb"})) StakeRefNull
+         2000000 lovelace
+         2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.b7a7b64d585f973e82be6ca36ae948
+         2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.beb7e61cb67dd301
+         TxOutDatumNone
+   - ShelleyAddress Testnet (KeyHashObj (KeyHash {unKeyHash = "f8a68cd18e59a6ace848155a0e967af64f4d00cf8acee8adc95a6b0d"})) StakeRefNull
+         19625359 lovelace
+         TxOutDatumNone
+
+   == TOTAL COLLATERAL
+   TxTotalCollateralNone
+
+   == RETURN COLLATERAL
+   TxReturnCollateralNone
+
+   == FEE
+   TxFeeExplicit ShelleyBasedEraConway (Coin 197973)
+
+   == VALIDITY
+   TxValidityNoLowerBound
+   TxValidityUpperBound ShelleyBasedEraConway (Just (SlotNo 38))
+
+   == MINT/BURN
+   0 lovelace
+
+   == SCRIPTS (0)
+   Total size (bytes):  0
+
+   == DATUMS (0)
+
+   == REDEEMERS (0)
+
+   == REQUIRED SIGNERS
+   []
+
+   == METADATA
+   TxMetadataInEra ShelleyBasedEraConway (TxMetadata {unTxMetadata = fromList [(55555,TxMetaText "HydraV1/DepositTx")]})
+   ```
+
+   If you take a look at the outputs you will see that we only locked specified ADA amount + tokens at the deposit address and gave back any leftover to the
+   user address.
+
+</details>
+
 Then a request to the `/commit` endpoint provides us with a transaction:
 
 ```shell

hydra-cluster/bench/Bench/EndToEnd.hs

@@ -28,7 +28,7 @@ import Data.Set ((\\))
 import Data.Set qualified as Set
 import Data.Text (pack)
 import Data.Time (UTCTime (UTCTime), utctDayTime)
-import Hydra.Cardano.Api (NetworkId, SocketPath, Tx, TxId, UTxO, getVerificationKey, signTx)
+import Hydra.Cardano.Api (NetworkId, SocketPath, Tx, TxId, UTxO, getVerificationKey, lovelaceToValue, signTx)
 import Hydra.Chain.Backend (ChainBackend)
 import Hydra.Chain.Backend qualified as Backend
 import Hydra.Cluster.Faucet (FaucetLog (..), publishHydraScriptsAs, returnFundsToFaucet', seedFromFaucet)
@@ -352,7 +352,7 @@ seedNetwork backend Dataset{fundingTransaction, hydraNodeKeys} tracer = do
   fuelWith100Ada signingKey = do
     let vk = getVerificationKey signingKey
     putTextLn $ "Fuel node key " <> show vk
-    seedFromFaucet backend vk 100_000_000 tracer
+    seedFromFaucet backend vk (lovelaceToValue 100_000_000) tracer
 
 -- | Commit all (expected to exit) 'initialUTxO' from the dataset using the
 -- (assumed same sequence) of clients.

hydra-cluster/src/Hydra/Cluster/Faucet.hs

@@ -44,29 +44,29 @@ data FaucetLog
   deriving stock (Eq, Show, Generic)
   deriving anyclass (ToJSON)
 
--- | Create a specially marked "seed" UTXO containing requested 'Lovelace' by
+-- | Create a specially marked "seed" UTXO containing requested 'Value' by
 -- redeeming funds available to the well-known faucet.
 seedFromFaucet ::
   ChainBackend backend =>
   backend ->
   -- | Recipient of the funds
   VerificationKey PaymentKey ->
-  -- | Amount to get from faucet
-  Coin ->
+  -- | Value to get from faucet
+  Value ->
   Tracer IO FaucetLog ->
   IO UTxO
-seedFromFaucet backend receivingVerificationKey lovelace tracer = do
+seedFromFaucet backend receivingVerificationKey val tracer = do
   (faucetVk, faucetSk) <- keysFor Faucet
   networkId <- Backend.queryNetworkId backend
   seedTx <- retryOnExceptions tracer $ submitSeedTx faucetVk faucetSk networkId
   producedUTxO <- Backend.awaitTransaction backend seedTx receivingVerificationKey
   pure $ UTxO.filter (== toCtxUTxOTxOut (theOutput networkId)) producedUTxO
  where
   submitSeedTx faucetVk faucetSk networkId = do
-    faucetUTxO <- findFaucetUTxO networkId backend lovelace
+    faucetUTxO <- findFaucetUTxO networkId backend (selectLovelace val)
     let changeAddress = mkVkAddress networkId faucetVk
 
-    buildTransaction backend changeAddress faucetUTxO [] [theOutput networkId] >>= \case
+    buildTransaction backend changeAddress faucetUTxO (toList $ UTxO.inputSet faucetUTxO) [theOutput networkId] >>= \case
       Left e -> throwIO $ FaucetFailedToBuildTx{reason = e}
       Right tx -> do
         let signedTx = sign faucetSk $ getTxBody tx
@@ -78,7 +78,7 @@ seedFromFaucet backend receivingVerificationKey lovelace tracer = do
   theOutput networkId =
     TxOut
       (shelleyAddressInEra shelleyBasedEra (receivingAddress networkId))
-      (lovelaceToValue lovelace)
+      val
       TxOutDatumNone
       ReferenceScriptNone
 
@@ -152,7 +152,7 @@ seedFromFaucet_ ::
   Tracer IO FaucetLog ->
   IO ()
 seedFromFaucet_ backend vk ll tracer =
-  void $ seedFromFaucet backend vk ll tracer
+  void $ seedFromFaucet backend vk (lovelaceToValue ll) tracer
 
 -- | Return the remaining funds to the faucet
 returnFundsToFaucet ::