feat: contract pause/unpause circuit breaker (SC-28) (#1186)

Adds pause()/unpause()/is_paused() to the SoroScan core contract, letting
the admin temporarily disable record_event()/record_events_batch() in an
emergency. Exposed through both SDKs as get_contract_status()/
getContractStatus().

Also fixes test_event_decoding_and_types, which used tuple-field syntax
(.topics/.value) incompatible with the soroban-sdk version this crate
currently resolves to without a committed Cargo.lock — needed to get the
contract test suite compiling at all.

Closes #1133

Author: esthertitilayo-dev

sdk/python/soroscan/__init__.py

@@ -23,6 +23,7 @@
     ContractEvent,
     ContractHealth,
     ContractStats,
+    ContractStatus,
     EventEntry,
     PaginatedResponse,
     AddIndexerRequest,
@@ -52,6 +53,7 @@
     "TrackedContract",
     "WebhookSubscription",
     "ContractStats",
+    "ContractStatus",
     "GetEventsByContractsRequest",
     "GetEventsByContractsResponse",
     "PaginatedResponse",

sdk/python/soroscan/client.py

@@ -19,6 +19,7 @@
     ContractEvent,
     ContractHealth,
     ContractStats,
+    ContractStatus,
     EventEntry,
     PaginatedResponse,
     RecordEventRequest,
@@ -577,6 +578,18 @@ def record_events_batch(
         data = self._handle_response(response)
         return RecordEventsBatchResponse.model_validate(data)
 
+    def get_contract_status(self) -> ContractStatus:
+        """
+        Get the contract's current pause/health status (SC-28).
+
+        Returns:
+            ContractStatus with paused flag, admin address, and total event count
+        """
+        url = urljoin(self.base_url, "/api/contract-status/")
+        response = self._client.get(url, headers=self._get_headers())
+        data = self._handle_response(response)
+        return ContractStatus.model_validate(data)
+
     def get_webhooks(
         self,
         page: int = 1,
@@ -1178,6 +1191,18 @@ async def record_events_batch(
         data = self._handle_response(response)
         return RecordEventsBatchResponse.model_validate(data)
 
+    async def get_contract_status(self) -> ContractStatus:
+        """
+        Get the contract's current pause/health status (SC-28).
+
+        Returns:
+            ContractStatus with paused flag, admin address, and total event count
+        """
+        url = urljoin(self.base_url, "/api/contract-status/")
+        response = await self._client.get(url, headers=self._get_headers())
+        data = self._handle_response(response)
+        return ContractStatus.model_validate(data)
+
     async def get_webhooks(
         self,
         page: int = 1,

sdk/python/soroscan/models.py

@@ -173,6 +173,14 @@ class RecordEventsBatchResponse(BaseModel):
     error: str | None = Field(None, description="Error message if failed")
 
 
+# ── SC-28: Contract pause status ──────────────────────────────────────────────
+
+class ContractStatus(BaseModel):
+    """Contract pause/health status (SC-28)."""
+
+    paused: bool = Field(..., description="Whether event recording is currently paused")
+    admin: str = Field(..., description="Current admin address")
+    total_events: int = Field(..., description="Total events recorded so far")
 # ── SC-16: Contract health ─────────────────────────────────────────────────────
 
 class ContractHealth(BaseModel):

sdk/python/tests/test_sc28_contract_status.py

@@ -0,0 +1,101 @@
+"""Tests for SC-28: contract pause status."""
+
+import pytest
+from pytest_httpx import HTTPXMock
+
+from soroscan import AsyncSoroScanClient, SoroScanClient
+from soroscan.models import ContractStatus
+
+
+# ── Fixtures ──────────────────────────────────────────────────────────────────
+
+ACTIVE_STATUS_RESPONSE = {
+    "paused": False,
+    "admin": "GAAA111222333444555666777888999AAABBBCCCDDDEEEFFF",
+    "total_events": 42,
+}
+
+PAUSED_STATUS_RESPONSE = {
+    "paused": True,
+    "admin": "GAAA111222333444555666777888999AAABBBCCCDDDEEEFFF",
+    "total_events": 42,
+}
+
+
+# ── Sync client ───────────────────────────────────────────────────────────────
+
+
+def test_get_contract_status_active(base_url: str, httpx_mock: HTTPXMock) -> None:
+    """get_contract_status returns a not-paused status."""
+    httpx_mock.add_response(
+        url=f"{base_url}/api/contract-status/",
+        json=ACTIVE_STATUS_RESPONSE,
+        status_code=200,
+    )
+
+    with SoroScanClient(base_url=base_url) as client:
+        result = client.get_contract_status()
+
+    assert isinstance(result, ContractStatus)
+    assert result.paused is False
+    assert result.admin == "GAAA111222333444555666777888999AAABBBCCCDDDEEEFFF"
+    assert result.total_events == 42
+
+
+def test_get_contract_status_paused(base_url: str, httpx_mock: HTTPXMock) -> None:
+    """get_contract_status returns a paused status."""
+    httpx_mock.add_response(
+        url=f"{base_url}/api/contract-status/",
+        json=PAUSED_STATUS_RESPONSE,
+        status_code=200,
+    )
+
+    with SoroScanClient(base_url=base_url) as client:
+        result = client.get_contract_status()
+
+    assert isinstance(result, ContractStatus)
+    assert result.paused is True
+    assert result.total_events == 42
+
+
+def test_contract_status_payload_validation_missing_admin() -> None:
+    """ContractStatus rejects a payload missing the required admin field."""
+    from pydantic import ValidationError
+
+    with pytest.raises(ValidationError):
+        ContractStatus(paused=False, total_events=1)  # type: ignore[call-arg]
+
+
+# ── Async client ──────────────────────────────────────────────────────────────
+
+
+@pytest.mark.anyio
+async def test_async_get_contract_status(base_url: str, httpx_mock: HTTPXMock) -> None:
+    """Async get_contract_status fetches correctly and returns response."""
+    httpx_mock.add_response(
+        url=f"{base_url}/api/contract-status/",
+        json=ACTIVE_STATUS_RESPONSE,
+        status_code=200,
+    )
+
+    async with AsyncSoroScanClient(base_url=base_url) as client:
+        result = await client.get_contract_status()
+
+    assert isinstance(result, ContractStatus)
+    assert result.paused is False
+    assert result.total_events == 42
+
+
+@pytest.mark.anyio
+async def test_async_get_contract_status_paused(base_url: str, httpx_mock: HTTPXMock) -> None:
+    """Async get_contract_status returns a paused status."""
+    httpx_mock.add_response(
+        url=f"{base_url}/api/contract-status/",
+        json=PAUSED_STATUS_RESPONSE,
+        status_code=200,
+    )
+
+    async with AsyncSoroScanClient(base_url=base_url) as client:
+        result = await client.get_contract_status()
+
+    assert result.paused is True

sdk/typescript/src/client.ts

@@ -25,6 +25,7 @@ import type {
   PaginatedResponse,
   RecordEventsBatchParams,
   RecordEventsBatchResponse,
+  ContractStatus,
   AddIndexerParams,
   AddIndexerResponse,
   GetAdminResponse,
@@ -477,6 +478,17 @@ export class SoroScanClient {
     );
   }
 
+  /**
+   * Get the contract's current pause/health status (SC-28).
+   *
+   * @example
+   * const status = await client.getContractStatus();
+   * console.log('Paused:', status.paused);
+   */
+  async getContractStatus(): Promise<ContractStatus> {
+    return this.#request<ContractStatus>("GET", "/v1/contract-status");
+  }
+
   /**
    * Create a new webhook subscription.
    *

sdk/typescript/src/index.ts

@@ -62,6 +62,8 @@ export type {
   EventEntry,
   RecordEventsBatchParams,
   RecordEventsBatchResponse,
+  // SC-28: Contract pause status
+  ContractStatus,
   // SC-30: Recent contract events
   GetContractRecentEventsParams,
   // WebSocket

sdk/typescript/src/types.ts

@@ -510,6 +510,19 @@ export interface EventFilter {
   topics?: Partial<ContractEventTopic>[];
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// SC-28: Contract pause status
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ContractStatus {
+  /** Whether event recording is currently paused */
+  paused: boolean;
+  /** Current admin address */
+  admin: string;
+  /** Total events recorded so far */
+  totalEvents: number;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Errors
 // ─────────────────────────────────────────────────────────────────────────────

sdk/typescript/test/sc28-contract-status.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { SoroScanClient, SoroScanError } from "../src/client.js";
+import type { ContractStatus } from "../src/types.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+function mockFetch(body: unknown, status = 200): void {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn().mockResolvedValue(
+      new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+      })
+    )
+  );
+}
+
+const BASE_URL = "https://api.soroscan.io";
+const makeClient = () => new SoroScanClient({ baseUrl: BASE_URL, apiKey: "test-key" });
+
+const MOCK_ACTIVE_STATUS: ContractStatus = {
+  paused: false,
+  admin: "GAAA111222333444555666777888999AAABBBCCCDDDEEEFFF",
+  totalEvents: 42,
+};
+
+const MOCK_PAUSED_STATUS: ContractStatus = {
+  paused: true,
+  admin: "GAAA111222333444555666777888999AAABBBCCCDDDEEEFFF",
+  totalEvents: 42,
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SC-28: getContractStatus
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("getContractStatus() — SC-28", () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it("returns a correctly-parsed status when not paused", async () => {
+    mockFetch(MOCK_ACTIVE_STATUS, 200);
+    const result = await makeClient().getContractStatus();
+
+    expect(result.paused).toBe(false);
+    expect(result.admin).toBe(MOCK_ACTIVE_STATUS.admin);
+    expect(result.totalEvents).toBe(42);
+  });
+
+  it("returns a correctly-parsed status when paused", async () => {
+    mockFetch(MOCK_PAUSED_STATUS, 200);
+    const result = await makeClient().getContractStatus();
+
+    expect(result.paused).toBe(true);
+    expect(result.totalEvents).toBe(42);
+  });
+
+  it("calls the correct URL with GET method", async () => {
+    mockFetch(MOCK_ACTIVE_STATUS, 200);
+    await makeClient().getContractStatus();
+
+    const [url, init] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [
+      string,
+      RequestInit,
+    ];
+    expect(url).toContain("/v1/contract-status");
+    expect(init.method).toBe("GET");
+  });
+
+  it("includes Authorization header", async () => {
+    mockFetch(MOCK_ACTIVE_STATUS, 200);
+    await makeClient().getContractStatus();
+
+    const [, init] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0] as [
+      string,
+      RequestInit,
+    ];
+    expect((init.headers as Record<string, string>)["Authorization"]).toBe(
+      "Bearer test-key"
+    );
+  });
+
+  it("throws SoroScanError on 401 unauthorized", async () => {
+    mockFetch({ code: "UNAUTHORIZED", message: "Invalid API key" }, 401);
+    await expect(makeClient().getContractStatus()).rejects.toMatchObject({
+      name: "SoroScanError",
+      statusCode: 401,
+      code: "UNAUTHORIZED",
+    });
+  });
+
+  it("throws SoroScanError on 500 server error", async () => {
+    mockFetch({ code: "SERVER_ERROR", message: "Internal error" }, 500);
+    await expect(makeClient().getContractStatus()).rejects.toBeInstanceOf(
+      SoroScanError
+    );
+  });
+});