feat: standardize Soroban contract errors and events

[OsejiFabian]

Summary

Closes #191

This PR standardizes the Soroban contract error and event interfaces across the escrow and dispute contracts, and updates the application-side event synchronization layer so frontend/backend consumers can reliably interpret on-chain operations.

Problem

The contracts previously exposed generic error enums with only implicit numeric semantics and emitted short, ad hoc topics such as init, fund, submit, and release. The dispute contract did not emit lifecycle events at all. This made it difficult for consumers to:

• Reliably identify the operation represented by an event.
• Correlate an event with a contract, milestone, dispute, or actor.
• Handle failures without parsing unstable human-readable panic text.
• Keep the Soroban event indexer and database enum in sync with deployed contracts.

What changed

Standardized contract errors

• Added explicit #[repr(u32)] to both contract error enums.
• Preserved existing numeric error values for ABI compatibility.
• Added descriptive integration-code documentation for each error, including:
  • ERR_ALREADY_INITIALIZED
  • ERR_NOT_INITIALIZED
  • ERR_INVALID_STATE
  • ERR_UNAUTHORIZED
  • ERR_INVALID_AMOUNT
  • ERR_MILESTONE_NOT_FOUND
  • ERR_INSUFFICIENT_APPROVALS
  • ERR_VOTING_ENDED
  • ERR_VOTING_NOT_ENDED
  • ERR_ALREADY_VOTED
  • ERR_NO_STAKE
• Documented the append-only rule for future error codes.
• Added authorization enforcement for escrow initialization and dispute resolution.

Standardized escrow events

Replaced untyped one-word event topics with typed Soroban #[contractevent] definitions:

• EscrowCreated
• EscrowFunded
• MilestoneSubmitted
• MilestoneApproved
• MilestoneConfirmed
• PaymentReleased
• DisputeRaised
• RefundIssued
• DisputeResolved
• MilestoneExpired

Each event includes the relevant contract identifier and actor, with milestone identifiers indexed where applicable. Payment/refund/resolution events also include recipient and amount data.

Standardized dispute events

Added typed lifecycle events for the dispute contract:

• DisputeCreated
• VoteCast
• DisputeResolved
• StakeClaimed

These events include contract_id, dispute_id, and actor topics, plus structured amount, recipient, voting, and outcome data.

Event synchronization compatibility

• Added canonical snake_case event names for the indexer and Postgres layer.
• Added normalization for PascalCase typed Soroban event names.
• Retained support for legacy short event topics from already deployed contracts.
• Added structured listener fields for:
  • milestoneId
  • disputeId
  • actor
  • recipient
  • amount
  • support
  • releaseToFreelancer
• Updated event-to-state mapping to use canonical names.
• Added canonical dispute-only event types without incorrectly mutating escrow state.

Database and documentation

• Added migration 009_contract_event_standardization.sql.
• Existing event enum values remain valid for historical records.
• Added docs/soroban-contract-events.md documenting:
  • Error codes and meanings.
  • Canonical event names.
  • Indexed topics.
  • Event data payload schemas.
  • Legacy compatibility behavior.

Tests

• Added normalization tests for canonical, PascalCase, and legacy topics.
• Added listener coverage for canonical typed events and indexed identifiers.
• Existing mapper behavior remains covered while now accepting both canonical and legacy event names.

Compatibility and rollout notes

• Existing deployed contracts continue to be ingestible because legacy short topics are normalized to canonical names.
• Historical contract_sync_log.event_type values are not rewritten.
• New deployments emit typed standardized events.
• Existing consumers should migrate to canonical snake_case event names and use structured fields rather than relying on raw topic positions.
• Error numeric values are preserved; future variants must be appended rather than renumbered.

Verification

The following checks were run locally:

• pnpm lint — passed with four pre-existing warnings.
• Targeted ESLint for changed TypeScript files — passed.
• git diff --check — passed.

The following checks were attempted but are blocked by the current workspace/environment:

• pnpm test and targeted Vitest — blocked before test collection by a missing @rolldown native optional dependency.
• pnpm build — blocked by a missing @tailwindcss/oxide native optional dependency.
• pnpm exec tsc --noEmit — reports numerous pre-existing repository-wide type errors outside this change.
• Rust contract checks — rustc, cargo, rustfmt, and stellar are not installed in the workspace.

Checklist

• References issue [Feature]: Soroban Contract Error & Event Standardization #191 with Closes #191.
• Preserves existing contract error numeric values.
• Adds standardized typed contract events.
• Includes identifiers and actor information in event schemas.
• Adds dispute contract lifecycle events.
• Keeps legacy event ingestion compatible.
• Documents event payloads and error codes.
• Adds focused event normalization/listener tests.
• Runs available lint and diff checks.

[drips-wave]

@OsejiFabian 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