From 36884a37537294236abcf08ab6d74bab9a1c7e08 Mon Sep 17 00:00:00 2001 From: Sasha Bogicevic Date: Wed, 11 Dec 2024 14:25:32 +0100 Subject: [PATCH] Explain de/committing --- .../dev/incremental-commits-and-decommits.md | 121 ++++++++++++++++++ docs/sidebars.js | 1 + 2 files changed, 122 insertions(+) create mode 100644 docs/docs/dev/incremental-commits-and-decommits.md diff --git a/docs/docs/dev/incremental-commits-and-decommits.md b/docs/docs/dev/incremental-commits-and-decommits.md new file mode 100644 index 00000000000..1832337d8ed --- /dev/null +++ b/docs/docs/dev/incremental-commits-and-decommits.md @@ -0,0 +1,121 @@ +# Incremental commits and decommits + +These two new addons to the initial Hydra Head protocol deserve more +explanation so our users are aware of how they work _under the hood_ to bring +more clarity to these processes. + +For now these two new additions run sequentially so we are doing one thing at a +time, at least for now, while we will think about batching certain actions in +the future if the need for that arises. + +It is only possible to either commit or decommit - we don't allow snapshots with both +fields specified for simplicity. This restriction might be lifted later on - once we +are sure this simpler version works nicely. + +## Incremental Commits + +Incremental Commits allow us to take some `UTxO` from L1 and make it available +on L2 for transacting inside of a running Hydra Head. + +The process for incremental commits is pretty much the same as when +_committing_ before the Head is in the `Open` state. In fact we can open a Head +without committing some funds and then _top-up_ our L2 funds by doing incremental +commits. + +The process of incrementally committing a `UTxO` starts by sending a `HTTP` request to +the hydra-node API endpoint: + +```bash + +curl -X POST :/commit --data @commit.json +``` + +:::info + +Note that commit transaction, which is sent to the hydra-node API, only needs +to specify the transaction inputs present in L1 that we want to make available +on L2. It will ignore any specified outputs and instead the owner of +incremented `UTxO` on L2 is the same one that owned the funds on L1. + +::: + +Hydra node will accept a plain `UTxO` encoded as JSON in the `POST` request +body or a _blueprint_ transaction together with the `UTxO` used to resolve it's +inputs. + +_Blueprint_ transaction is just like a recipe that describes which transaction +inputs should be made available on L2 network ignoring any specified outputs. +It goes together with a `UTxO` used to resolve the transaction inputs. It's +purpose is to prove that one can spend specified transaction inputs. + +Successfull API response includes a _deposit_ transaction that needs to be +signed and submitted by the user in order to kick of the deposit process. + +This process just locks the specified `UTxO` at a deposit script address which +will then, later on, after confirmed snapshot, be unlocked by the _increment_ +transaction which will actually make this `UTxO` available on L2. + +The deposit transaction contains a deadline - time window in which we expect +the hydra-node to be able to observe this deposit and issue a _increment_ +transaction that will do the heavy lifting and bring the specified input on L2. + +Currently, _contestation period_ value is used to specify a deposit deadline +but this should be made available as a separate argument to hydra-node since it +heavily depends on the network we are running on. + +Once a hydra-node observes a deposit transaction it will record the deposit as +pending into the local state. There can be many pending deposits but the new +Snapshot will include them one by one. + +When this new Snapshot is ackgnowledged by all parties _increment_ transaction +will be posted by the leader. + +:::info +Note that any node that posts increment transaction will also pay the fees even if +the deposit will not be owned by them on L2. +::: + +Upon observing increment transaction we remove deposit from the local pending deposits +and the process can start again. + +:::note + +Since we can potentially request many deposits, the leader will increment only +one of them. While others are stuck in the pending state any new transaction on +L2 will take next pending deposit and try to include it in a snapshot. + +::: + +## Incremental Decommits + +Incremental decommits allow us to take some L2 `UTxO` and bring it to the L1 +while the Head protocol is running. + +Head participant (or any other user that can send requests to the hydra-node +API endpoint) requests inclusion of some UTxO from L1 by sending a `POST` +`HTTP` request which contains in the request body a decommit transaction +encoded as _TextEnvelope_ JSON value. + +```bash +curl -X POST :/decommit --data @decommit-tx.json +``` + +This transaction needs to be signed by the owner of the funds on L2. + +:::info + +What we call a decommit transaction is the one that user supplies in the API +endpoint. The decrement transaction is the transaction that hydra-node posts +after it checks that decommit transaction applies and the one that actually +makes some UTxO available on L1. + +::: + +Hydra node accepts this transaction and checks if it can be cleanly applied to +the local `UTxO` set. After this check hydra-node will issue a `ReqDec` message +signalling to other parties that we want to produce a new `Snapshot` that +contains the same `UTxO` to decommit. Once a snapshot is signed, hydra-node +posts a _decrement_ transaction that will take specified output and make it +available on L1. + + diff --git a/docs/sidebars.js b/docs/sidebars.js index d9ebee986b5..e584f813d65 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -70,6 +70,7 @@ module.exports = { label: "Specification", }, "dev/protocol", + "dev/incremental-commits-and-decommits", { type: "doc", id: "dev/commit_to_a_Head",