feat: add cancelled vault state handling (#521)

[Amas-01]

Closes #521

Summary

What changed

• backend/src/services/indexer.ts:

  • Added parseCancelFundingEvent() function to parse fund_cxl events from the cancel_funding contract function
  • Added handleCancelFunding() private method to process cancel_funding events and update vault state to "Cancelled"
  • Integrated cancel_funding event dispatch into processEvent() method with notification support

• backend/src/services/indexer.test.ts:

  • Added 3 test cases for parseCancelFundingEvent() covering successful parsing, malformed event handling, and event name format recognition

• backend/src/api/controllers/vaults.test.ts (new file):

  • Added 5 comprehensive test cases for GET /api/v1/vaults endpoint with state filtering
  • Tests verify correct filtering, empty results, unfiltered behavior, and README documentation presence

• backend/README.md:

  • Added "Vault States" documentation section with complete lifecycle table
  • Documented all 5 vault states: Funding, Active, Matured, Cancelled, Closed
  • Included API usage example for retrieving cancelled vaults

State value used

"Cancelled" — casing confirmed from backend/src/types/index.ts which defines VaultState union type including "Cancelled" (capital C). All existing state values use PascalCase convention (Funding, Active, Matured, Closed).

Migration required

No — The vaults.state column is TEXT NOT NULL DEFAULT 'Funding' with no enum constraint or check condition (verified in backend/src/db/migrations/001_vaults.sql). The column accepts any string value, so "Cancelled" requires no schema changes.

How to verify

1. Event Handler Processing

# The cancel_funding event is now indexed and processed:
# - Check database: vault.state should be "Cancelled" after cancel_funding event
# - Check logs: should see "Processing cancel_funding event" info logs
# - Verify idempotency: calling handler again should not error

[drips-wave]

@Amas-01 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