Implement submit tx api endpoint (#2124)

Resolves #2107 
Implementation and tests are added.

---

<!-- 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: vrom911

CHANGELOG.md

@@ -18,6 +18,8 @@ changes.
 
 - Hydra node now rejects requests for incremental commits if provided UTxO is below the limit.
 
+- Add API endpoint `POST /transaction` to submit transaction to the head.
+
 ## [0.22.2] - 2025.06.30
 
 * Fix wrong hydra-script-tx-ids in networks.json

docs/docs/dev/architecture/hydra-components.svg

@@ -639,6 +639,23 @@ Submit the transaction through the already open WebSocket connection. Generate t
 cat tx-signed.json | jq -c '{tag: "NewTx", transaction: .}'
 ```
 
+<details>
+<summary>Alternative: use the HTTP API endpoint</summary>
+
+Alternatively, you can submit the transaction using the HTTP API endpoint:
+
+```shell
+curl -X POST 127.0.0.1:4001/transaction \
+  --data @tx-signed.json
+```
+
+The HTTP endpoint provides a synchronous response with different status codes:
+- **200 OK**: Transaction was included in a confirmed snapshot (includes `snapshotNumber`)
+- **202 Accepted**: Transaction was accepted but not yet confirmed
+- **400 Bad Request**: Transaction was rejected due to validation errors (includes `validationError`)
+
+</details>
+
 The transaction will be validated by both `hydra-node`s and either result in a
 `TxInvalid` message with a reason, or a `TxValid` message and a
 `SnapshotConfirmed` with the new UTXO available in the head shortly after.

docs/docs/tutorial/index.md

@@ -413,6 +413,7 @@ prepareHydraNode chainConfig workDir hydraNodeId hydraSKey hydraVKeys allNodeIds
           CardanoLedgerConfig
             { cardanoLedgerProtocolParametersFile
             }
+      , apiTransactionTimeout = 100000
       }
  where
   port = fromIntegral $ 5_000 + hydraNodeId

hydra-cluster/src/HydraNode.hs

@@ -0,0 +1,23 @@
+{
+    "samples": [
+        {
+            "tag": "SubmitTxSubmitted"
+        },
+        {
+            "tag": "SubmitTxInvalid",
+            "validationError": ""
+        },
+        {
+            "tag": "SubmitTxInvalid",
+            "validationError": "\u0001)e"
+        },
+        {
+            "tag": "SubmitTxInvalid",
+            "validationError": "=\u000e􂨤p"
+        },
+        {
+            "tag": "SubmitTxSubmitted"
+        }
+    ],
+    "seed": -1369626537
+}

hydra-node/golden/ReasonablySized (SubmitL2TxRequest (Tx ConwayEra)).json

@@ -10,6 +10,7 @@
                 "tag": "IPv4"
             },
             "apiPort": 18036,
+            "apiTransactionTimeout": 0,
             "chainConfig": {
                 "cardanoSigningKey": "a/c/b/c.sk",
                 "cardanoVerificationKeys": [
@@ -85,6 +86,7 @@
                 "tag": "IPv4"
             },
             "apiPort": 32191,
+            "apiTransactionTimeout": 27,
             "chainConfig": {
                 "initialUTxOFile": "b/b/c/a.json",
                 "ledgerGenesisFile": null,
@@ -143,6 +145,7 @@
                 "tag": "IPv4"
             },
             "apiPort": 20019,
+            "apiTransactionTimeout": 26,
             "chainConfig": {
                 "cardanoSigningKey": "c/b/a/b/c/b.sk",
                 "cardanoVerificationKeys": [
@@ -223,6 +226,7 @@
                 "tag": "IPv4"
             },
             "apiPort": 9965,
+            "apiTransactionTimeout": 17,
             "chainConfig": {
                 "initialUTxOFile": "b/c/b/a/a/c.json",
                 "ledgerGenesisFile": "b/c/a.json",
@@ -263,6 +267,7 @@
                 "tag": "IPv4"
             },
             "apiPort": 8054,
+            "apiTransactionTimeout": 23,
             "chainConfig": {
                 "cardanoSigningKey": "a/c/a.sk",
                 "cardanoVerificationKeys": [

hydra-node/golden/ReasonablySized SubmitL2TxResponse.json

@@ -90,6 +90,7 @@ library
     Hydra.Network.Message
     Hydra.NetworkVersions
     Hydra.Node
+    Hydra.Node.ApiTransactionTimeout
     Hydra.Node.DepositPeriod
     Hydra.Node.EmbedTH
     Hydra.Node.Environment
@@ -395,6 +396,7 @@ test-suite tests
     , req
     , resourcet
     , silently
+    , stm
     , temporary
     , text
     , time

hydra-node/golden/RunOptions.json

@@ -367,7 +367,7 @@ channels:
           $ref: "api.yaml#/components/schemas/Transaction"
       bindings:
         http:
-          type: response
+          type: request
           method: POST
           bindingVersion: '0.1.0'
     subscribe:
@@ -388,11 +388,73 @@ channels:
           summary: 400 Bad Request
           payload:
             $ref: "api.yaml#/components/schemas/PostTxError"
+      bindings:
+        http:
+          type: response
+          method: POST
+          bindingVersion: '0.1.0'
+
+  /transaction:
+    servers:
+      - localhost-http
+    publish:
+      operationId: submitL2TxRequest
+      message:
+        summary: |
+          A transaction to be submitted to the head.
+          Accepts transactions encoded as Base16 CBOR string, TextEnvelope type or JSON.
+        payload:
+          $ref: "api.yaml#/components/schemas/Transaction"
       bindings:
         http:
           type: request
           method: POST
           bindingVersion: '0.1.0'
+    subscribe:
+      operationId: submitL2TxResponse
+      message:
+        oneOf:
+        - name: SubmitTxConfirmed
+          summary: 200 OK
+          description: Transaction was included in a confirmed snapshot.
+          payload:
+            type: object
+            additionalProperties: false
+            properties:
+              tag:
+                type: string
+                enum: ["SubmitTxConfirmed"]
+              snapshotNumber:
+                type: integer
+                minimum: 0
+        - name: SubmitTxInvalid
+          summary: 400 Bad Request
+          description: Transaction was rejected due to validation errors.
+          payload:
+            type: object
+            additionalProperties: false
+            properties:
+              tag:
+                type: string
+                enum: ["SubmitTxInvalid"]
+              validationError:
+                type: string
+        - name: SubmitTxSubmitted
+          summary: 202 Accepted
+          description: Transaction was accepted but not yet confirmed.
+          payload:
+            type: object
+            additionalProperties: false
+            properties:
+              tag:
+                type: string
+                enum: ["SubmitTxSubmitted"]
+      bindings:
+        http:
+          type: response
+          method: POST
+          bindingVersion: '0.1.0'
+
 components:
   messages:
 
@@ -3262,6 +3324,43 @@ components:
         status:
           $ref: "api.yaml#/components/schemas/DepositStatus"
 
+    SubmitL2TxResponse:
+      oneOf:
+        - title: SubmitTxConfirmed
+          type: object
+          additionalProperties: false
+          required:
+            - tag
+            - snapshotNumber
+          properties:
+            tag:
+              type: string
+              enum: ["SubmitTxConfirmed"]
+            snapshotNumber:
+              type: integer
+              minimum: 0
+        - title: SubmitTxInvalid
+          type: object
+          additionalProperties: false
+          required:
+            - tag
+            - validationError
+          properties:
+            tag:
+              type: string
+              enum: ["SubmitTxInvalid"]
+            validationError:
+              type: string
+        - title: SubmitTxSubmitted
+          type: object
+          additionalProperties: false
+          required:
+            - tag
+          properties:
+            tag:
+              type: string
+              enum: ["SubmitTxSubmitted"]
+
     DepositStatus:
       oneOf:
         - title: Unknown

hydra-node/hydra-node.cabal

@@ -16,6 +16,7 @@ data APIServerLog
       { method :: Method
       , path :: PathInfo
       }
+  | APITransactionSubmitted {submittedTxId :: String}
   deriving stock (Eq, Show, Generic)
   deriving anyclass (ToJSON)