feat: implement dividend snapshot validation, campaign audit trail, IPFS circuit breaker, and multi-sig validation

[victorisiguzoruzoma874]

Summary

Comprehensive feature implementation addressing 4 backend/contract issues:

• Add dividend snapshot consistency verification #1123: Add dividend snapshot consistency verification to catch ingestion gaps
• Add an audit trail for campaign state-machine persistence #1124: Persist campaign state transitions with full audit trail
• Wrap the IPFS service in a circuit breaker to contain upstream failures #1125: Wrap IPFS service in circuit breaker for resilience
• Enforce comprehensive multi-sig threshold validation at configuration time #1126: Enforce multi-sig threshold validation with duplicate signer checks

Implementation Details

#1123 - Dividend Snapshot Consistency

• New verifySnapshotConsistency() function validates holder balance sum
• Tolerance: 1 unit for rounding differences
• Admin endpoint: GET /api/dividends/pools/:poolId/consistency
• Returns: expected total, actual total, consistency status, holder count

#1124 - Campaign Audit Trail

• New CampaignAuditTrail database model for all state transitions
• Records: from/to status, actor, timestamp, optional txHash
• Service methods: recordStateTransition(), getAuditTrail()
• API endpoint: GET /api/campaigns/:campaignId/audit-trail with pagination

#1125 - IPFS Circuit Breaker

• Circuit breaker configuration:
  • Failure threshold: 5 consecutive failures
  • Success threshold: 2 consecutive successes to close
  • Timeout: 30 seconds before attempting recovery
• Wrapped all IPFS operations (upload image, upload metadata, get metadata)
• Admin metrics: GET /api/admin/operational/circuit-breaker/ipfs
• Admin reset: POST /api/admin/operational/circuit-breaker/ipfs/reset

#1126 - Multi-Sig Validation

• Validates threshold is not zero and not greater than signer count
• Validates no duplicate signers in configuration
• New error code: DuplicateSigners (86)
• Events emitted on successful configuration

Test Plan

• Code compiles without warnings (Rust clippy, TypeScript strict)
• Input validation working at boundaries (Zod schemas, Rust validation)
• Error handling follows conventions (typed AppError, Soroban Error codes)
• Database migrations created and backwards compatible
• API documentation updated with new endpoints
• No breaking changes to existing APIs

Notes

• Token/credit efficiency: Focused implementations without unnecessary abstractions
• All changes preserve existing error-handling conventions
• Migration is non-destructive and can be rolled back
• Circuit breaker metrics useful for monitoring IPFS availability

Closes #1123
Closes #1124
Closes #1125
Closes #1126

[drips-wave]

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