Submit a transaction

This section describes how to submit a transaction to an already open head using the NewTx command of the WebSocket API.

This example assumes zero L2 fees and an ADA-only input. Replace the sample input reference, destination address, and signing-key path with your own.

First, query the UTxO available in the head:

curl --fail-with-body -sS http://127.0.0.1:4001/snapshot/utxo | jq

Below is an example response:

Example response of GET /snapshot/utxo
{
  "8690d7618bb88825d6ec7cfbe2676779b8f4633cb137a1c12cd31b4c53f90f32#0": {
    "address": "addr_test1vrdhewmpp96gv6az4vymy80hlw9082sjz6rylt2srpntsdq6njxxu",
    "datum": null,
    "datumhash": null,
    "inlineDatum": null,
    "referenceScript": null,
    "value": {
      "lovelace": 100000000
    }
  }
}

Assuming the single UTXO is owned by some-payment-key.sk and you want to send all of it to another address, you can use cardano-cli (or your preferred transaction builder) to construct and sign a transaction:

Transaction building
cardano-cli conway transaction build-raw \
  --tx-in 8690d7618bb88825d6ec7cfbe2676779b8f4633cb137a1c12cd31b4c53f90f32#0 \
  --tx-out addr_test1vp5cxztpc6hep9ds7fjgmle3l225tk8ske3rmwr9adu0m6qchmx5z+100000000 \
  --fee 0 \
  --out-file tx.json

cardano-cli conway transaction sign \
  --tx-body-file tx.json \
  --signing-key-file some-payment-key.sk \
  --out-file tx-signed.json

cat tx-signed.json | jq -c '{tag: "NewTx", transaction: .}'

This command generates a message suitable for submission to the hydra-node via a WebSocket connection. If hydra-node operates on the default port 4001, the message can be submitted using websocat:

cat tx-signed.json | jq -c '{tag: "NewTx", transaction: .}' | websocat "ws://127.0.0.1:4001?history=no"

Greetings message will be displayed as always when calling the web socket api and the transaction will be validated by all connected hydra-node instances. It will result in either a TxInvalid message, providing a reason for rejection, or a TxValid message followed by a SnapshotConfirmed, updating the UTXO available in the head shortly after that.

Transactions executing Plutus scripts

Transactions executing Plutus scripts inside a head require at least one collateral input, even when transaction fees are zero. Hydra uses Cardano's ledger validation, which checks that collateral inputs are present separately from checking the required collateral amount. Omitting them results in TxInvalid with a validation error containing NoCollateralInputs.

Select an ADA-only, key-controlled UTxO from the head as collateral. If the transaction already spends a suitable input, the same input can also serve as collateral; a separate UTxO is unnecessary. With cardano-cli, pass its reference using --tx-in-collateral, then sign the transaction with the key controlling that input. Rebuild and re-sign any existing transaction after adding collateral.

The withdraw-zero example demonstrates using the same input for spending and collateral. This collateral must exist inside the head; the node's layer 1 fuel does not provide it.

Transactions executing Plutus scripts​

Transactions executing Plutus scripts