feat(soroban, sdk): add per-contract event tracking and event type query (SC-17) (#1169)

Implements SC-17 feature adding:
- Soroban contract: per-contract event counts and event type registry
  with query methods contract_event_count() and contract_event_types()
- Python SDK: get_contract_event_types() method for sync/async clients,
  ContractEventTypeInfo model, CLI event-types subcommand
- TypeScript SDK: getContractEventTypes() method and ContractEventTypeInfo interface

Co-authored-by: TheCreatorNode <basseyu01@gmail.com>

Author: slim856

sdk/python/soroscan/__init__.py

@@ -23,6 +23,7 @@
 from soroscan.webhook_verification import verify_webhook_signature
 from soroscan.models import (
     ContractEvent,
+    ContractEventTypeInfo,
     ContractStats,
     EventEntry,
     PaginatedResponse,
@@ -43,6 +44,7 @@
     "Paginator",
     "AsyncPaginator",
     "ContractEvent",
+    "ContractEventTypeInfo",
     "TrackedContract",
     "WebhookSubscription",
     "ContractStats",

sdk/python/soroscan/cli.py

@@ -104,6 +104,17 @@ def _handle_contracts(args: argparse.Namespace) -> int:
                 )
             return 0
 
+        if args.contract_command == "event-types":
+            types = client.get_contract_event_types(args.contract_id)
+            if args.output == "json":
+                _print_json(types)
+            else:
+                _print_table(
+                    types,
+                    ["event_type", "count", "first_seen", "last_seen"],
+                )
+            return 0
+
         response = client.get_contracts(
             is_active=args.active,
             search=args.search,
@@ -190,6 +201,14 @@ def build_parser() -> argparse.ArgumentParser:
     contracts_get.add_argument("contract_id")
     contracts_get.add_argument("--output", choices=["table", "json"], default="table")
     contracts_get.set_defaults(func=_handle_contracts)
+    contracts_event_types = contract_subcommands.add_parser(
+        "event-types", help="Get event types for a contract (SC-17)"
+    )
+    contracts_event_types.add_argument("contract_id", help="Contract address (C...)")
+    contracts_event_types.add_argument(
+        "--output", choices=["table", "json"], default="table"
+    )
+    contracts_event_types.set_defaults(func=_handle_contracts)
 
     return parser
 

sdk/python/soroscan/client.py

@@ -19,6 +19,7 @@
 )
 from soroscan.models import (
     ContractEvent,
+    ContractEventTypeInfo,
     ContractStats,
     EventEntry,
     PaginatedResponse,
@@ -302,6 +303,21 @@ def get_contract_stats(self, contract_id: str) -> ContractStats:
         data = self._handle_response(response)
         return ContractStats.model_validate(data)
 
+    def get_contract_event_types(self, contract_id: str) -> list[ContractEventTypeInfo]:
+        """
+        Get event types and their counts for a specific contract (SC-17).
+
+        Args:
+            contract_id: Contract address (C...)
+
+        Returns:
+            List of event type info with counts and first/last seen timestamps
+        """
+        url = urljoin(self.base_url, f"/api/contracts/{contract_id}/event-types/")
+        response = self._client.get(url, headers=self._get_headers())
+        data = self._handle_response(response)
+        return [ContractEventTypeInfo.model_validate(item) for item in data]
+
     def get_events(
         self,
         contract_id: str | None = None,
@@ -809,6 +825,21 @@ async def get_contract_stats(self, contract_id: str) -> ContractStats:
         data = self._handle_response(response)
         return ContractStats.model_validate(data)
 
+    async def get_contract_event_types(self, contract_id: str) -> list[ContractEventTypeInfo]:
+        """
+        Get event types and their counts for a specific contract (SC-17).
+
+        Args:
+            contract_id: Contract address (C...)
+
+        Returns:
+            List of event type info with counts and first/last seen timestamps
+        """
+        url = urljoin(self.base_url, f"/api/contracts/{contract_id}/event-types/")
+        response = await self._client.get(url, headers=self._get_headers())
+        data = self._handle_response(response)
+        return [ContractEventTypeInfo.model_validate(item) for item in data]
+
     async def get_events(
         self,
         contract_id: str | None = None,

sdk/python/soroscan/models.py

@@ -91,6 +91,17 @@ class RecordEventResponse(BaseModel):
     error: str | None = Field(None, description="Error message if failed")
 
 
+# ── SC-17: Contract event type info ───────────────────────────────────────────
+
+class ContractEventTypeInfo(BaseModel):
+    """Event type summary for a contract (SC-17)."""
+
+    event_type: str = Field(..., description="Event type name")
+    count: int = Field(..., description="Number of events of this type")
+    first_seen: str = Field(..., description="ISO timestamp of first occurrence")
+    last_seen: str = Field(..., description="ISO timestamp of last occurrence")
+
+
 # ── SC-29: Batch event recording ──────────────────────────────────────────────
 
 class EventEntry(BaseModel):

sdk/typescript/src/client.ts

@@ -1,6 +1,7 @@
 import type {
   SoroScanClientConfig,
   SoroScanApiError,
+  ContractEventTypeInfo,
   GetEventsParams,
   GetEventsResponse,
   GetContractsParams,
@@ -179,6 +180,24 @@ export class SoroScanClient {
     );
   }
 
+  /**
+   * Get event types and their counts for a specific contract (SC-17).
+   *
+   * @example
+   * const types = await client.getContractEventTypes('CCAAA...');
+   * for (const t of types) {
+   *   console.log(t.eventType, t.count);
+   * }
+   */
+  async getContractEventTypes(
+    contractId: string
+  ): Promise<ContractEventTypeInfo[]> {
+    return this.#request<ContractEventTypeInfo[]>(
+      "GET",
+      `/v1/contracts/${encodeURIComponent(contractId)}/event-types`
+    );
+  }
+
   // ─── Transactions ──────────────────────────────────────────────────────────
 
   /**

sdk/typescript/src/index.ts

@@ -47,6 +47,8 @@ export type {
   SubscribeWebhookParams,
   UpdateWebhookParams,
   WebhookListResponse,
+  // SC-17: Contract event type info
+  ContractEventTypeInfo,
   // SC-29: Batch event recording
   EventEntry,
   RecordEventsBatchParams,

sdk/typescript/src/types.ts

@@ -302,6 +302,21 @@ export interface WebhookListResponse {
   totalCount: number;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// SC-17: Contract event type info
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ContractEventTypeInfo {
+  /** Event type name */
+  eventType: string;
+  /** Number of events of this type */
+  count: number;
+  /** ISO timestamp of first occurrence */
+  firstSeen: string;
+  /** ISO timestamp of last occurrence */
+  lastSeen: string;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // SC-29: Batch event recording
 // ─────────────────────────────────────────────────────────────────────────────