Deposit funds to an open Head
Assuming we already have an open Head and some funds on the L1 we would like to deposit.
The /commit
endpoint supports two ways of specifying what to deposit, 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 transaction as a recipe on what to deposit.
Blueprint transactions work differently in deposits (incremental commits) compared to commits (committing before the Head is in the open state).
When it comes to depositing our users have four ways of using the blueprint transaction so it should work for even more involved scenarios:
- Only provide the UTxO to deposit - simple deposit where whole of the UTxO is deposited to the Head.
- Provide UTxO and a bluerprint transaction without any outputs - whole of the UTxO will be deposited but users get to specify additional transaction context needed for dApps.
- Provide UTxO, blueprint transaction with specified outputs but NO change address is provided - In this case we expect to see fully balanced blueprint transaction where it's outputs will be deposited completely.
- Provide UTxO, blueprint transaction with specified outputs AND a change address - hydra-node will balance the deposit transaction and give back any change to the provided change address. Provided outputs will be deposited.
Hydra node assumes that the blueprint transaction does not contain any stake pool or DRep registration or delegation certificates since these don't make too much sense on L2 network.
The last option is most flexible one for dApp builders since they can just specify which UTxO assets they want to deposit (providing the appropriate outputs in the blueprint tx) while the hydra-node will make sure to return any change to the specified address. Using script UTxO as a reference inputs is also possible for optimising the dApp workflow.
Partial deposit example:
If there exists a user UTxO that looks like this
{
"98ce7d553c87837735ce99d0452d6c78c14499a35a2ebe78a61653da422ba06b#0":
{ "address":"addr_test1vznxtg0ljhlqghzr9sdw3stfffna97l6xuaradgdk8jnhegyza948",
"datum":null,
"datumhash":null,
"inlineDatum":null,
"inlineDatumRaw":null,
"referenceScript":null,
"value":
{ "dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75":
{ "32":6459586778467727683,
"38":4726846541838542289,
"58cfd525f109":2,
"60c477033b55e1":6560058562233977644,
"768b8dfd46f4d5b14873b4c3851f2c82d0301f61661347":4661096764720222855,
"ab5f4e6486d24ad6744e54f95dd1bc4dbbe721":3250906605877226653,
"d47f9b":1,
"d6cc1ed8ac3cda":2,
"f26fe54468b98902751e8d54553c1878b5f952d486":1
},
"lovelace":30000000
}
}
}
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
providing the blueprint transaction with specified outputs, UTxO and a change address:
{
"blueprintTx": {
"cborHex": "84a300d901028182582098ce7d553c87837735ce99d0452d6c78c14499a35a2ebe78a61653da422ba06b00018182581d60a665a1ff95fe045c432c1ae8c1694a67d2fbfa373a3eb50db1e53be5821a00e4e1c0a1581cdcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75a44658cfd525f109024760c477033b55e11b5b0a028173b74b2c53ab5f4e6486d24ad6744e54f95dd1bc4dbbe7211b2d1d8a5581486c9d55f26fe54468b98902751e8d54553c1878b5f952d486010200a0f5f6",
"description": "",
"txId": "8451c42d1a1b48fdb1b1d2b014dc700cbba15b3c20addb2076feeceeeb3d22a4",
"type": "Tx ConwayEra"
},
"changeAddress": "addr_test1vznxtg0ljhlqghzr9sdw3stfffna97l6xuaradgdk8jnhegyza948",
"utxo": {
"98ce7d553c87837735ce99d0452d6c78c14499a35a2ebe78a61653da422ba06b#0": {
"address": "addr_test1vznxtg0ljhlqghzr9sdw3stfffna97l6xuaradgdk8jnhegyza948",
"datum": null,
"datumhash": null,
"inlineDatum": null,
"inlineDatumRaw": null,
"referenceScript": null,
"value": {
"dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75": {
"32": 6459586778467727000,
"38": 4726846541838542000,
"58cfd525f109": 2,
"60c477033b55e1": 6560058562233978000,
"768b8dfd46f4d5b14873b4c3851f2c82d0301f61661347": 4661096764720223000,
"ab5f4e6486d24ad6744e54f95dd1bc4dbbe721": 3250906605877226500,
"d47f9b": 1,
"d6cc1ed8ac3cda": 2,
"f26fe54468b98902751e8d54553c1878b5f952d486": 1
},
"lovelace": 30000000
}
}
}
}
In the provided blueprint tx we specified the outputs we want to deposit. Rendered blueprint tx looks like this:
"8451c42d1a1b48fdb1b1d2b014dc700cbba15b3c20addb2076feeceeeb3d22a4"
== INPUTS (1)
- 98ce7d553c87837735ce99d0452d6c78c14499a35a2ebe78a61653da422ba06b#0
ShelleyAddress Testnet (KeyHashObj (KeyHash {unKeyHash = "a665a1ff95fe045c432c1ae8c1694a67d2fbfa373a3eb50db1e53be5"})) StakeRefNull
30000000 lovelace
6459586778467727683 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.32
4726846541838542289 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.38
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.58cfd525f109
6560058562233977644 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.60c477033b55e1
4661096764720222855 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.768b8dfd46f4d5b14873b4c3851f2c82d0301f61661347
3250906605877226653 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.ab5f4e6486d24ad6744e54f95dd1bc4dbbe721
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.d47f9b
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.d6cc1ed8ac3cda
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.f26fe54468b98902751e8d54553c1878b5f952d486
TxOutDatumNone
ReferenceScriptNone
== COLLATERAL INPUTS (0)
== REFERENCE INPUTS (0)
== OUTPUTS (1)
Total number of assets: 5
- ShelleyAddress Testnet (KeyHashObj (KeyHash {unKeyHash = "a665a1ff95fe045c432c1ae8c1694a67d2fbfa373a3eb50db1e53be5"})) StakeRefNull
15000000 lovelace
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.58cfd525f109
6560058562233977644 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.60c477033b55e1
3250906605877226653 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.ab5f4e6486d24ad6744e54f95dd1bc4dbbe721
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.f26fe54468b98902751e8d54553c1878b5f952d486
TxOutDatumNone
== TOTAL COLLATERAL
TxTotalCollateralNone
== RETURN COLLATERAL
TxReturnCollateralNone
== FEE
TxFeeExplicit ShelleyBasedEraConway (Coin 0)
== VALIDITY
TxValidityNoLowerBound
TxValidityUpperBound ShelleyBasedEraConway Nothing
== MINT/BURN
0 lovelace
== SCRIPTS (0)
Total size (bytes): 0
== DATUMS (0)
== REDEEMERS (0)
== REQUIRED SIGNERS
[]
== METADATA
TxMetadataNone
You can see that the UTxO contains the following assets present in the blueprint input:
30000000 lovelace
6459586778467727683 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.32
4726846541838542289 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.38
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.58cfd525f109
6560058562233977644 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.60c477033b55e1
4661096764720222855 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.768b8dfd46f4d5b14873b4c3851f2c82d0301f61661347
3250906605877226653 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.ab5f4e6486d24ad6744e54f95dd1bc4dbbe721
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.d47f9b
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.d6cc1ed8ac3cda
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.f26fe54468b98902751e8d54553c1878b5f952d486
But we decided to deposit some of them which we specified in the single blueprint output:
15000000 lovelace
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.58cfd525f109
6560058562233977644 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.60c477033b55e1
3250906605877226653 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.ab5f4e6486d24ad6744e54f95dd1bc4dbbe721
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.f26fe54468b98902751e8d54553c1878b5f952d486
Hydra node returns a deposit transaction which then needs to be signed and submitted to the network. Deposit looks like this:
"ab4adce53699015ca8fd112689906338278f435d436516290c68c679921de8a4"
== INPUTS (2)
- 04e36b0eeb5d97be19e543583e3b736640b45ceaf5ece1d37f5db9ac88143f20#1
- 98ce7d553c87837735ce99d0452d6c78c14499a35a2ebe78a61653da422ba06b#0
ShelleyAddress Testnet (KeyHashObj (KeyHash {unKeyHash = "a665a1ff95fe045c432c1ae8c1694a67d2fbfa373a3eb50db1e53be5"})) StakeRefNull
30000000 lovelace
6459586778467727683 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.32
4726846541838542289 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.38
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.58cfd525f109
6560058562233977644 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.60c477033b55e1
4661096764720222855 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.768b8dfd46f4d5b14873b4c3851f2c82d0301f61661347
3250906605877226653 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.ab5f4e6486d24ad6744e54f95dd1bc4dbbe721
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.d47f9b
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.d6cc1ed8ac3cda
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.f26fe54468b98902751e8d54553c1878b5f952d486
TxOutDatumNone
ReferenceScriptNone
== COLLATERAL INPUTS (1)
- 04e36b0eeb5d97be19e543583e3b736640b45ceaf5ece1d37f5db9ac88143f20#1
== REFERENCE INPUTS (0)
== OUTPUTS (3)
Total number of assets: 10
- ShelleyAddress Testnet (ScriptHashObj (ScriptHash "ae01dade3a9c346d5c93ae3ce339412b90a0b8f83f94ec6baa24e30c")) StakeRefNull
15000000 lovelace
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.58cfd525f109
6560058562233977644 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.60c477033b55e1
3250906605877226653 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.ab5f4e6486d24ad6744e54f95dd1bc4dbbe721
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.f26fe54468b98902751e8d54553c1878b5f952d486
TxOutDatumInline [0,["0xe9e21b6e4f59b3c62721c99109e76abb46e018e4fc184b16e58d650a",1759768581709,[[0,[[0,["0x8451c42d1a1b48fdb1b1d2b014dc700cbba15b3c20addb2076feeceeeb3d22a4",0]],"0xd8799fd8799fd8799f581ca665a1ff95fe045c432c1ae8c1694a67d2fbfa373a3eb50db1e53be5ffd87a80ffa240a1401a00e4e1c0581cdcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75a44658cfd525f109024760c477033b55e11b5b0a028173b74b2c53ab5f4e6486d24ad6744e54f95dd1bc4dbbe7211b2d1d8a5581486c9d55f26fe54468b98902751e8d54553c1878b5f9
52d48601d87980d87a80ff"]]]]]
- ShelleyAddress Testnet (KeyHashObj (KeyHash {unKeyHash = "a665a1ff95fe045c432c1ae8c1694a67d2fbfa373a3eb50db1e53be5"})) StakeRefNull
15000000 lovelace
6459586778467727683 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.32
4726846541838542289 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.38
4661096764720222855 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.768b8dfd46f4d5b14873b4c3851f2c82d0301f61661347
1 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.d47f9b
2 dcf5fdd1d01c04b0e6262bba173a89c4b81b6570211f08bc059c8a75.d6cc1ed8ac3cda
TxOutDatumNone
- ShelleyAddress Testnet (KeyHashObj (KeyHash {unKeyHash = "f8a68cd18e59a6ace848155a0e967af64f4d00cf8acee8adc95a6b0d"})) StakeRefNull
21583379 lovelace
TxOutDatumNone
== TOTAL COLLATERAL
TxTotalCollateralNone
== RETURN COLLATERAL
TxReturnCollateralNone
== FEE
TxFeeExplicit ShelleyBasedEraConway (Coin 203737)
== VALIDITY
TxValidityNoLowerBound
TxValidityUpperBound ShelleyBasedEraConway (Just (SlotNo 37))
== 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 of this deposit tx you will see that we only locked specified ADA amount + tokens at the deposit address and gave back leftover ADA and assets the provided change address.
This will result in a deposit being detected by the hydra-node
and consequently the funds to be deposited to the Head.
Recover a deposit
Once we deposited funds we should not see the corresponding UTxO on L1.
To inspect the pending deposits you can use curl
:
curl -X GET localhost:4001/commits
You should see the tx-id of the deposit transaction in case it wasn't picked up by the hydra-node already. (e.g.["ab4adce53699015ca8fd112689906338278f435d436516290c68c679921de8a4"]
To recover, we can use the /commits
endpoint again using the transaction id of the deposit:
curl -X DELETE localhost:4001/commits/$(printf "\"ab4adce53699015ca8fd112689906338278f435d436516290c68c679921de8a4"\" | jq -sRr '@uri')
If we inspect the address funds again we will see that the locked deposit is now recovered. It is important to mention that recovering works even if the Head is closed already.