Add GetTransactionsStream RPC (#345)

* RPC GetPaymentsStream

This introduces a new feature to the ArkService API that allows clients to subscribe to payment events. Here's a breakdown of the changes:

1. **OpenAPI Specification (`service.swagger.json`):**
   - A new endpoint `/v1/payments` is added to the API, supporting a `GET` operation for streaming payment events.
   - New definitions `v1GetPaymentsStreamResponse`, `v1RoundPayment`, and `v1AsyncPayment` are added to describe the structure of the streaming responses.

2. **Protobuf Definition (`service.proto`):**
   - Added a new RPC method `GetPaymentsStream` that streams `GetPaymentsStreamResponse` messages.
   - Defined new message types: `GetPaymentsStreamRequest`, `GetPaymentsStreamResponse`, `RoundPayment`, and `AsyncPayment`.

3. **Generated Protobuf Code (`service.pb.go`, `service.pb.gw.go`, `service_grpc.pb.go`):**
   - The generated code is updated to include the new RPC method and message types.
   - The gateway code includes functions to handle HTTP requests and responses for the new streaming endpoint.

4. **Application Logic (`covenant.go`, `covenantless.go`):**
   - New payment events channels are introduced (`paymentEventsCh`).
   - Payment events are propagated to these channels when a round is finalized or an async payment is completed.
   - New event types `RoundPaymentEvent` and `AsyncPaymentEvent` are defined, implementing a `PaymentEvent` interface.

5. **gRPC Handlers (`arkservice.go`):**
   - Added logic to handle `GetPaymentsStream` requests and manage payment listeners.
   - A new goroutine is started to listen to payment events and forward them to active listeners.

Overall, this patch extends the ArkService to support real-time streaming of payment events, allowing clients to receive updates on both round payments and async payments as they occur.

* Move emit events in updateVtxoSet & Use generics and parsers (#1)

* Move sending event to updateVtxoSet

* Use generics and parsers

* pr review refactor

* pr review refactor

* fix

---------

Co-authored-by: Pietralberto Mazza <[email protected]>

Author: sekulicd

api-spec/openapi/swagger/ark/v1/service.swagger.json

@@ -415,6 +415,37 @@
         ]
       }
     },
+    "/v1/transactions": {
+      "get": {
+        "operationId": "ArkService_GetTransactionsStream",
+        "responses": {
+          "200": {
+            "description": "A successful response.(streaming responses)",
+            "schema": {
+              "type": "object",
+              "properties": {
+                "result": {
+                  "$ref": "#/definitions/v1GetTransactionsStreamResponse"
+                },
+                "error": {
+                  "$ref": "#/definitions/rpcStatus"
+                }
+              },
+              "title": "Stream result of v1GetTransactionsStreamResponse"
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "schema": {
+              "$ref": "#/definitions/rpcStatus"
+            }
+          }
+        },
+        "tags": [
+          "ArkService"
+        ]
+      }
+    },
     "/v1/vtxos/{address}": {
       "get": {
         "operationId": "ArkService_ListVtxos",
@@ -620,6 +651,17 @@
         }
       }
     },
+    "v1GetTransactionsStreamResponse": {
+      "type": "object",
+      "properties": {
+        "round": {
+          "$ref": "#/definitions/v1RoundTransaction"
+        },
+        "redeem": {
+          "$ref": "#/definitions/v1RedeemTransaction"
+        }
+      }
+    },
     "v1Input": {
       "type": "object",
       "properties": {
@@ -727,6 +769,28 @@
         }
       }
     },
+    "v1RedeemTransaction": {
+      "type": "object",
+      "properties": {
+        "txid": {
+          "type": "string"
+        },
+        "spentVtxos": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Outpoint"
+          }
+        },
+        "spendableVtxos": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Vtxo"
+          }
+        }
+      }
+    },
     "v1RegisterInputsForNextRoundRequest": {
       "type": "object",
       "properties": {
@@ -896,6 +960,35 @@
       ],
       "default": "ROUND_STAGE_UNSPECIFIED"
     },
+    "v1RoundTransaction": {
+      "type": "object",
+      "properties": {
+        "txid": {
+          "type": "string"
+        },
+        "spentVtxos": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Outpoint"
+          }
+        },
+        "spendableVtxos": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Vtxo"
+          }
+        },
+        "claimedBoardingUtxos": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/v1Outpoint"
+          }
+        }
+      }
+    },
     "v1SubmitSignedForfeitTxsRequest": {
       "type": "object",
       "properties": {

api-spec/protobuf/ark/v1/service.proto

@@ -92,6 +92,11 @@ service ArkService {
       get: "/v1/vtxos/{address}"
     };
   }
+  rpc GetTransactionsStream(GetTransactionsStreamRequest) returns (stream GetTransactionsStreamResponse) {
+    option (google.api.http) = {
+      get: "/v1/transactions"
+    };
+  }
 }
 
 message GetInfoRequest {}
@@ -321,3 +326,24 @@ message PendingPayment {
   string redeem_tx = 1;
   repeated string unconditional_forfeit_txs =2;
 }
+
+message GetTransactionsStreamRequest {}
+message GetTransactionsStreamResponse {
+  oneof tx {
+    RoundTransaction round = 1;
+    RedeemTransaction redeem = 2;
+  }
+}
+
+message RoundTransaction {
+  string txid = 1;
+  repeated Outpoint spent_vtxos = 2;
+  repeated Vtxo spendable_vtxos = 3;
+  repeated Outpoint claimed_boarding_utxos = 4;
+}
+
+message RedeemTransaction {
+  string txid = 1;
+  repeated Outpoint spent_vtxos = 2;
+  repeated Vtxo spendable_vtxos = 3;
+}