feat: add on-chain event correlation service (#546)

[CHKM001]

PR #546 : Add On-Chain Event Correlation Service

Summary

Implements a service that correlates Soroban on-chain events to internal records using package_id/claim_id and stores the mapping (tx hash, ledger, event topic). This enables full auditability between blockchain activity and internal claim/package state.

Changes

New Files

File	Description
src/onchain/soroban-event-correlation.service.ts	Core service that fetches Soroban events via RPC, extracts package_id/claim_id from payloads, and stores correlation records in SorobanEventCorrelation table
src/onchain/soroban-event-correlation.scheduler.ts	Cron-based scheduler (every 5 min) + on-demand trigger via BullMQ queue
src/onchain/soroban-event-correlation.service.spec.ts	16 unit tests for the extractIdentifiers mapper logic

Modified Files

File	Change
prisma/schema.prisma	Added reverse relation fields sorobanEventCorrelations to Claim and AidPackage models (required by Prisma)
src/onchain/interfaces/onchain-job.interface.ts	Added EVENT_CORRELATION and EVENT_CORRELATION_TRANSACTION to OnchainOperationType enum
src/onchain/onchain.processor.ts	Injected SorobanEventCorrelationService; added handlers for the two new job types
src/onchain/onchain.module.ts	Registered SorobanEventCorrelationService, SorobanEventCorrelationScheduler; exported service; added ScheduleModule
src/onchain/aid-escrow.module.ts	Added SorobanEventCorrelationService to exports
src/onchain/aid-escrow.controller.ts	Added 3 new endpoints (see below)
src/claims/claims.controller.ts	Added 1 new endpoint (see below)
test/transaction-status.spec.ts	Added mock SorobanEventCorrelationService provider
test/aid-escrow.integration.spec.ts	Added mock SorobanEventCorrelationService provider

New API Endpoints

Package Events

GET /onchain/aid-escrow/packages/:id/events

Returns all Soroban on-chain events correlated to a specific aid package.

Claim Events

GET /claims/:id/events

Returns all Soroban on-chain events correlated to a specific claim.

On-Demand Correlation

POST /onchain/aid-escrow/correlate/:txHash

Triggers immediate event correlation for a specific transaction hash.

All Events (Filtered)

GET /onchain/aid-escrow/events?page=1&limit=20&eventTopic=package_created&claimId=...&packageId=...&startLedger=1000&endLedger=2000

Returns all event correlations with filtering by topic, claim, package, or ledger range.

How It Works

1. Scheduled Job (SorobanEventCorrelationScheduler): Runs every 5 minutes, queries Soroban RPC for new events since the last processed ledger, and queues correlation jobs via BullMQ.

2. On-Demand Trigger: Admin/operator can trigger correlation for a specific transaction hash via the POST /correlate/:txHash endpoint.

3. Correlation Logic (SorobanEventCorrelationService):

   • Fetches events from Soroban RPC for the configured contract
   • Filters to known event topics (package_created, claim_disbursed, etc.)
   • Extracts package_id/claim_id from event payloads using flexible path resolution
   • Stores correlation records with idempotency (deduplicates by txHash + eventIndex)

4. Read Endpoints: Claim and package read endpoints now include correlated on-chain event data.

Mapper Logic (extractIdentifiers)

The mapper resolves identifiers from event payloads using a prioritized path search:

package_id paths: package_id, packageId, id, package, data.package_id, data.id
claim_id paths:   claim_id, claimId, claim, data.claim_id, data.claimId, metadata.claim_ref

• Returns { packageId } if found (takes priority)
• Returns { claimId } if no package ID found
• Returns {} if neither found
• Handles nested payloads, numeric/bigint coercion

Testing

• 16 unit tests for extractIdentifiers covering all payload structures, edge cases, and type coercion
• 449 total tests passing (all pre-existing tests unchanged)
• Test files updated with mock providers for DI compatibility

Environment Variables

Variable	Default	Description
AID_ESCROW_CONTRACT_ID	''	Soroban contract ID to fetch events for
STELLAR_RPC_URL	https://soroban-testnet.stellar.org	Soroban RPC endpoint
STELLAR_NETWORK_PASSPHRASE	Test SDF Network ; September 2015	Network passphrase

Acceptance Criteria

• Correlation runs on-demand and/or scheduled job
• Correlated data is exposed in claim/package read endpoints
• Includes unit tests for mapper logic

Closes #546

[vercel]

@CHKM001 is attempting to deploy a commit to the Cedarich's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@CHKM001 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Cedarich]

@CHKM001 please fix workflow

[CHKM001]

okay