Revise `POST /commit` endpoint interface

[ch1bo]

Discussed in https://github.com/input-output-hk/hydra/discussions/1337

Why

Currently POST /commit endpoint accepts utxos with witnesses as request payload and supports spending from script addresses. However, it does not provide any means to tweak transaction context, making it impractical for many real-world cases that often involve checking transaction validity range, required signers, etc. as part of the validator logic.

What

• The /commit endpoint can accept a "Blueprint" Tx (CBOR-encoded) + a UTxO (as JSON) to resolve inputs for higher configurability

  • This transactions is used by the hydra-node as as starting point to draftCommitTx

  • Anything that does not conflict with the requirements of a valid head commit transaction should be kept. For example:

    • A Hydra commitTx does not need to have some specific validity range, so any lower or upper bound is also present on the resulting commit tx draft
    • Any inputs, already present are also present on the resulting commit tx draft

  • The drafted commit tx is balanced (hydra-node estimates and pays fees) and signed by the --cardano-signing-key (as before)

• Tests covering a transaction with additional required signers and lower/upper validity set which assert that the resulting commitTx has the same things present as the blueprint has.

• The existing UTxOWithWitnesses is still supported as a request body on /commit

• API reference and documentation is updated (explain how to use this with cardano-cli as an example)

How

• New signature of draftCommitTx :: HeadId -> UTxOType tx -> tx -> m tx (roughly)
• commitTx basically starts with the TxBody instead of emptyTxBody
• The UTxOWithWitnesses is implemented in terms of the now more capable tx-based draftCommitTx by building the blueprint transaction from the UTxOWithWitnesses
• Support both request types by making the request a sum-type, e.g.

data DraftCommitTxRequest
  = SimpleCommitRequest {utxoToCommit :: UTxO' TxOutWithWitness}
  | FullCommitRequest {blueprintTx :: Tx}

TBD

• Mix CBOR and JSON on the request body?