single-connection GetSubscription flow

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

@@ -424,6 +424,60 @@
         }
       }
     },
+    "/v1/indexer/script/subscription": {
+      "get": {
+        "tags": [
+          "IndexerService"
+        ],
+        "description": "GetSubscription is a server-side streaming RPC which allows clients to receive real-time\nnotifications on transactions related to the subscribed vtxo scripts.\nThe subscription can be created or updated by using the SubscribeForScripts and\nUnsubscribeForScripts RPCs.",
+        "operationId": "IndexerService_GetSubscription2",
+        "parameters": [
+          {
+            "name": "subscriptionId",
+            "in": "query",
+            "description": "If empty, server creates a new subscription automatically.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "scripts",
+            "in": "query",
+            "description": "Optional: scripts to subscribe to on stream creation.\nOnly used when subscription_id is empty; ignored otherwise.",
+            "style": "simple",
+            "schema": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "a successful response. (streaming responses)",
+            "content": {
+              "text/event-stream": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetSubscriptionResponse"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Status"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/indexer/script/subscription/{subscription_id}": {
       "get": {
         "tags": [
@@ -435,10 +489,24 @@
           {
             "name": "subscriptionId",
             "in": "path",
+            "description": "If empty, server creates a new subscription automatically.",
             "required": true,
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "name": "scripts",
+            "in": "query",
+            "description": "Optional: scripts to subscribe to on stream creation.\nOnly used when subscription_id is empty; ignored otherwise.",
+            "style": "simple",
+            "schema": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
           }
         ],
         "responses": {
@@ -506,6 +574,47 @@
         }
       }
     },
+    "/v1/indexer/script/updateScripts": {
+      "post": {
+        "tags": [
+          "IndexerService"
+        ],
+        "description": "UpdateSubscriptionScripts allows to modify the scripts of an existing subscription\ncreated via GetSubscription.",
+        "operationId": "IndexerService_UpdateSubscriptionScripts",
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpdateSubscriptionScriptsRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "200": {
+            "description": "a successful response.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UpdateSubscriptionScriptsResponse"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An unexpected error response.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Status"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/indexer/virtualTx/{txids}": {
       "get": {
         "tags": [
@@ -935,8 +1044,16 @@
         "title": "GetSubscriptionRequest",
         "type": "object",
         "properties": {
+          "scripts": {
+            "type": "array",
+            "description": "Optional: scripts to subscribe to on stream creation.\nOnly used when subscription_id is empty; ignored otherwise.",
+            "items": {
+              "type": "string"
+            }
+          },
           "subscriptionId": {
-            "type": "string"
+            "type": "string",
+            "description": "If empty, server creates a new subscription automatically."
           }
         }
       },
@@ -949,6 +1066,9 @@
           },
           "heartbeat": {
             "$ref": "#/components/schemas/IndexerHeartbeat"
+          },
+          "subscriptionStarted": {
+            "$ref": "#/components/schemas/SubscriptionStartedEvent"
           }
         }
       },
@@ -1411,6 +1531,36 @@
           }
         }
       },
+      "ModifyScripts": {
+        "title": "ModifyScripts",
+        "type": "object",
+        "properties": {
+          "addScripts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "removeScripts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "OverwriteScripts": {
+        "title": "OverwriteScripts",
+        "type": "object",
+        "properties": {
+          "scripts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
       "Status": {
         "title": "Status",
         "type": "object",
@@ -1455,6 +1605,15 @@
           }
         }
       },
+      "SubscriptionStartedEvent": {
+        "title": "SubscriptionStartedEvent",
+        "type": "object",
+        "properties": {
+          "subscriptionId": {
+            "type": "string"
+          }
+        }
+      },
       "UnsubscribeForScriptsRequest": {
         "title": "UnsubscribeForScriptsRequest",
         "type": "object",
@@ -1474,6 +1633,45 @@
       "UnsubscribeForScriptsResponse": {
         "title": "UnsubscribeForScriptsResponse",
         "type": "object"
+      },
+      "UpdateSubscriptionScriptsRequest": {
+        "title": "UpdateSubscriptionScriptsRequest",
+        "type": "object",
+        "properties": {
+          "modify": {
+            "$ref": "#/components/schemas/ModifyScripts"
+          },
+          "overwrite": {
+            "$ref": "#/components/schemas/OverwriteScripts"
+          },
+          "subscriptionId": {
+            "type": "string"
+          }
+        }
+      },
+      "UpdateSubscriptionScriptsResponse": {
+        "title": "UpdateSubscriptionScriptsResponse",
+        "type": "object",
+        "properties": {
+          "allScripts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "scriptsAdded": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "scriptsRemoved": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
       }
     }
   },

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

@@ -127,6 +127,25 @@ service IndexerService {
         disable_chunked_transfer: true
         disable_websockets: true
       }
+      additional_bindings: [
+        {
+          get: "/v1/indexer/script/subscription"
+          stream: {
+            disable_chunked_transfer: true
+            disable_websockets: true
+          }
+        }
+      ]
+    };
+  };
+
+  // UpdateSubscriptionScripts allows to modify the scripts of an existing subscription
+  // created via GetSubscription.
+  rpc UpdateSubscriptionScripts(UpdateSubscriptionScriptsRequest)
+      returns (UpdateSubscriptionScriptsResponse) {
+    option (meshapi.gateway.http) = {
+      post: "/v1/indexer/script/updateScripts"
+      body: "*"
     };
   };
 }
@@ -354,16 +373,48 @@ message UnsubscribeForScriptsResponse {}
 
 
 message GetSubscriptionRequest {
+  // If empty, server creates a new subscription automatically.
   string subscription_id = 1;
+  // Optional: scripts to subscribe to on stream creation.
+  // Only used when subscription_id is empty; ignored otherwise.
+  repeated string scripts = 2;
 }
 
 message GetSubscriptionResponse {
   oneof data {
     IndexerHeartbeat heartbeat = 1;
     IndexerSubscriptionEvent event = 2;
+    SubscriptionStartedEvent subscription_started = 3;
+  }
+}
+
+message SubscriptionStartedEvent {
+  string subscription_id = 1;
+}
+
+message ModifyScripts {
+  repeated string add_scripts = 1;
+  repeated string remove_scripts = 2;
+}
+
+message OverwriteScripts {
+  repeated string scripts = 1;
+}
+
+message UpdateSubscriptionScriptsRequest {
+  string subscription_id = 1;
+  oneof scripts_change {
+    ModifyScripts modify = 2;
+    OverwriteScripts overwrite = 3;
   }
 }
 
+message UpdateSubscriptionScriptsResponse {
+  repeated string scripts_added = 1;
+  repeated string scripts_removed = 2;
+  repeated string all_scripts = 3;
+}
+
 message IndexerTxData {
   string txid = 1;
   string tx = 2;