Contract-Deployment-Change-Notifications

[Habibah371]

PR: Contract Deployment Change Notifications (Registry → Clients)

Summary

This PR introduces contract deployment change notifications and registry version tracking to improve upgrade visibility, reduce client outage risk, and enable dynamic configuration refreshes without requiring redeployments.

The implementation provides registry change events, version-aware client polling, optional webhook notifications, and comprehensive audit logging for deployment lifecycle management.

Changes Implemented

Contract Registry Change Events

• Added internal domain events emitted whenever contract registry entries are created, updated, or removed

• Events include:

  • Contract identifier
  • Previous deployment reference
  • New deployment reference
  • Registry version
  • Timestamp
  • Actor information

Registry Version Endpoint

• Added endpoint for clients to retrieve the current registry version

Example:

GET /contracts/registry/version

Features:

• Returns current registry version
• Supports ETag-based change detection
• Enables lightweight polling
• Allows clients to refresh configuration only when changes occur

Deployment Change Webhooks

• Added optional admin-managed webhook notifications
• Webhooks are triggered when contract deployments change
• Includes deployment metadata and registry version information
• Supports secure operator integrations and monitoring systems

Audit Logging

• Added audit records for all registry modification actions:

  • Contract registration
  • Contract updates
  • Contract replacement
  • Contract removal
  • Webhook configuration changes

Audit entries capture:

• User/admin responsible for the action
• Previous and new values
• Timestamp
• Request metadata

Rate Limiting & Safety

• Applied rate limiting to polling and notification endpoints
• Added validation and authorization checks for webhook management
• Prevented duplicate notifications for unchanged deployments

Testing

Added comprehensive test coverage for:

• Registry version generation and updates
• ETag response handling
• Contract change event emission
• Webhook delivery workflow
• Audit log creation
• Authorization and access controls
• Rate limiting behavior
• Registry update edge cases

Acceptance Criteria

• Internal events emitted when contract registry entries change
• Clients can poll current registry version using ETag support
• Optional admin-only webhook notifications implemented
• Audit logs created for all deployment changes
• Rate limiting applied to relevant endpoints
• Automated tests added for notification and versioning flows

Benefits

• Clients automatically detect contract deployment changes
• Configuration refreshes occur without application redeployment
• Operators gain visibility into upgrade activity
• Deployment history becomes fully auditable
• Reduced outage risk during contract upgrades and migrations
  Closes BE-40: Contract Deployment Change Notifications (Registry → Clients) #426

[drips-wave]

@Habibah371 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]

Please resolve conflicts