feat: add SC-38 structured event support (#1188)

Author: She-ge

django-backend/soroscan/ingest/serializers.py

@@ -567,6 +567,17 @@ class RecordEventRequestSerializer(serializers.Serializer):
     )
 
 
+class StructuredEventRequestSerializer(RecordEventRequestSerializer):
+    """SC-38 request payload for versioned, idempotent contract events."""
+
+    schema_version = serializers.IntegerField(min_value=1, help_text="Payload schema version")
+    correlation_id = serializers.CharField(
+        max_length=64,
+        min_length=64,
+        help_text="64-character hexadecimal id used to deduplicate retries",
+    )
+
+
 class APIKeySerializer(serializers.ModelSerializer):
     """
     Serializer for APIKey model.

django-backend/soroscan/ingest/stellar_client.py

@@ -240,6 +240,61 @@ def record_event(
                 error=str(e),
             )
 
+    def record_structured_event(
+        self,
+        target_contract_id: str,
+        event_type: str,
+        payload_hash_hex: str,
+        schema_version: int,
+        correlation_id_hex: str,
+    ) -> TransactionResult:
+        """Submit the SC-38 versioned and correlation-safe event invocation."""
+        if not self.keypair:
+            return TransactionResult(False, "", "error", error="No keypair configured")
+
+        try:
+            payload_hash = bytes.fromhex(payload_hash_hex)
+            correlation_id = bytes.fromhex(correlation_id_hex)
+            if len(payload_hash) != 32 or len(correlation_id) != 32:
+                raise ValueError("Payload hash and correlation ID must be 32 bytes")
+            account = self.server.load_account(self.keypair.public_key)
+            tx = (
+                TransactionBuilder(
+                    source_account=account,
+                    network_passphrase=self.network_passphrase,
+                    base_fee=100000,
+                )
+                .append_invoke_contract_function_op(
+                    contract_id=self.contract_id,
+                    function_name="record_structured_event",
+                    parameters=[
+                        self._address_to_sc_val(self.keypair.public_key),
+                        self._address_to_sc_val(target_contract_id),
+                        self._symbol_to_sc_val(event_type),
+                        self._bytes_to_sc_val(payload_hash),
+                        SCVal(type=SCValType.SCV_U32, u32=schema_version),
+                        self._bytes_to_sc_val(correlation_id),
+                    ],
+                )
+                .set_timeout(30)
+                .build()
+            )
+            simulation = self.server.simulate_transaction(tx)
+            if simulation.error:
+                return TransactionResult(False, "", "simulation_failed", error=simulation.error)
+            prepared = self.server.prepare_transaction(tx, simulation)
+            prepared.sign(self.keypair)
+            response = self.server.send_transaction(prepared)
+            return TransactionResult(
+                success=response.status == "PENDING",
+                tx_hash=response.hash,
+                status=response.status,
+                result_xdr=getattr(response, "result_xdr", None),
+            )
+        except Exception as e:
+            logger.exception("Failed to record SC-38 structured event")
+            return TransactionResult(False, "", "error", error=str(e))
+
     def get_total_events(self) -> Optional[int]:
         """
         Query the total_events function on the contract.

django-backend/soroscan/ingest/urls.py

@@ -28,6 +28,7 @@
     health_check,
     networks_view,
     record_event_view,
+    record_structured_event_view,
     restore_archived_events,
     transaction_events_view,
     vulnerability_impact_view,
@@ -84,6 +85,7 @@
     ),
     path("", include(router.urls)),
     path("record/", record_event_view, name="record-event"),
+    path("record/structured/", record_structured_event_view, name="record-structured-event"),
     path("health/", health_check, name="health-check"),
     path("events/type-statistics/", event_type_statistics_view, name="event-type-statistics"),
     path("events/restore-archive/", restore_archived_events, name="restore-archive"),

django-backend/soroscan/ingest/views.py

@@ -67,6 +67,7 @@
     OrganizationCorsSerializer,
     OrganizationCostSnapshotSerializer,
     RecordEventRequestSerializer,
+    StructuredEventRequestSerializer,
     TeamMemberAddSerializer,
     TeamSerializer,
     TrackedContractSerializer,
@@ -1028,6 +1029,39 @@ def record_event_view(request):
         )
 
 
+@extend_schema(request=StructuredEventRequestSerializer)
+@api_view(["POST"])
+@permission_classes([IsAuthenticated])
+@throttle_classes([IngestRateThrottle, AnonRateThrottle, UserRateThrottle])
+def record_structured_event_view(request):
+    """Relay a versioned, deduplicated SC-38 event to the core contract."""
+    serializer = StructuredEventRequestSerializer(data=request.data)
+    if not serializer.is_valid():
+        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
+
+    data = serializer.validated_data
+    result = SorobanClient().record_structured_event(
+        target_contract_id=data["contract_id"],
+        event_type=data["event_type"],
+        payload_hash_hex=data["payload_hash"],
+        schema_version=data["schema_version"],
+        correlation_id_hex=data["correlation_id"],
+    )
+    if result.success:
+        return Response(
+            {
+                "status": "submitted",
+                "tx_hash": result.tx_hash,
+                "transaction_status": result.status,
+            },
+            status=status.HTTP_202_ACCEPTED,
+        )
+    return Response(
+        {"status": "failed", "error": result.error, "transaction_status": result.status},
+        status=status.HTTP_400_BAD_REQUEST,
+    )
+
+
 @extend_schema(
     responses=inline_serializer(
         name="WebhookSigningPublicKeyResponse",

sdk/README.md

@@ -1,5 +1,20 @@
 # SoroScan SDKs
 
+## SC-38 structured events
+
+SC-38 adds a versioned, retry-safe event submission path. Provide a SHA-256
+payload hash, a non-zero schema version, and a unique 32-byte hexadecimal
+correlation ID. Reusing the correlation ID is rejected by the contract, so a
+network retry cannot create a second event.
+
+```python
+client.record_structured_event(contract_id, "transfer", payload_hash, 1, correlation_id)
+```
+
+```ts
+await client.recordStructuredEvent({ contractId, eventType: "transfer", payloadHash, schemaVersion: 1, correlationId });
+```
+
 Official SDKs for the SoroScan API - Stellar/Soroban event indexing.
 
 ## Strict type verification

sdk/python/tests/test_sc38_structured_event.py

@@ -0,0 +1,45 @@
+"""SC-38 structured-event SDK coverage."""
+
+import json
+
+import pytest
+from pydantic import ValidationError
+from pytest_httpx import HTTPXMock
+
+from soroscan import AsyncSoroScanClient, SoroScanClient
+from soroscan.models import StructuredEventRequest
+
+
+def test_structured_event_request_rejects_zero_schema_version() -> None:
+    with pytest.raises(ValidationError):
+        StructuredEventRequest(
+            contract_id="CABC", event_type="transfer", payload_hash="a" * 64,
+            schema_version=0, correlation_id="b" * 64,
+        )
+
+
+def test_record_structured_event(base_url: str, httpx_mock: HTTPXMock) -> None:
+    httpx_mock.add_response(
+        url=f"{base_url}/api/record/structured/",
+        status_code=202,
+        json={"status": "submitted", "tx_hash": "abc", "transaction_status": "PENDING"},
+    )
+    with SoroScanClient(base_url=base_url) as client:
+        result = client.record_structured_event("CABC", "transfer", "a" * 64, 1, "b" * 64)
+    assert result.status == "submitted"
+    request = httpx_mock.get_requests()[0]
+    assert json.loads(request.content) == {
+        "contract_id": "CABC", "event_type": "transfer", "payload_hash": "a" * 64,
+        "schema_version": 1, "correlation_id": "b" * 64,
+    }
+
+
+@pytest.mark.anyio
+async def test_async_record_structured_event(base_url: str, httpx_mock: HTTPXMock) -> None:
+    httpx_mock.add_response(
+        url=f"{base_url}/api/record/structured/", status_code=202,
+        json={"status": "submitted", "tx_hash": "abc", "transaction_status": "PENDING"},
+    )
+    async with AsyncSoroScanClient(base_url=base_url) as client:
+        result = await client.record_structured_event("CABC", "transfer", "a" * 64, 1, "b" * 64)
+    assert result.tx_hash == "abc"