feat: add two-step vault rotation to settlement

[Onyedika3d]

Summary

Replaced the one-step set_vault flow with a safer two-step vault rotation process:

propose_vault (admin-only)
        ↓
accept_vault (pending vault or admin)

This change prevents accidental or incorrect vault updates by requiring explicit acceptance before a vault becomes active.

To improve transparency and auditability, the contract now stores pending vault changes on-chain and emits dedicated events throughout the rotation lifecycle.

Additionally, proposals where new_vault equals the settlement contract address are now rejected to prevent self-referential misconfiguration.

For backwards compatibility, set_vault remains available but now acts as an alias for propose_vault and no longer performs an immediate vault swap.

Changes

contracts/settlement/src/lib.rs

New Storage

Added:

StorageKey::PendingVault

to persist vault rotation proposals until accepted.

New Admin Flow

Added:

propose_vault(caller, new_vault)

• Admin-only
• Stores the proposed vault in PendingVault
• Does not modify the active vault

Added:

accept_vault(caller)

Can be called by:

• The pending vault address
• The admin

Upon acceptance:

• Active vault is updated
• Pending vault is cleared
• Acceptance event is emitted

Safety Validation

Added validation preventing:

new_vault == settlement_contract_address

This avoids accidental self-configuration that could break settlement flows or administrative controls.

Events

Added:

VaultProposedEvent
VaultAcceptedEvent

Emitted as:

vault_proposed
vault_accepted

These events provide a complete on-chain audit trail for vault transitions.

Backwards Compatibility

set_vault(...) remains available but now delegates to:

propose_vault(...)

Behavior change:

• Previous: immediate vault replacement
• Current: create pending proposal only

This preserves interface compatibility while enforcing the safer two-step process.

contracts/settlement/src/test.rs

Added test coverage for:

Vault Rotation Happy Path

• Admin proposes a vault
• Pending vault accepts
• Active vault updates successfully

Unauthorized Acceptance

• Non-admin, non-pending-vault callers cannot accept

Admin-Finalized Acceptance

• Admin can finalize the vault rotation directly

Self-Address Rejection

• Proposals targeting the settlement contract address are rejected

Event Emission

Verifies:

• vault_proposed emitted on proposal
• vault_accepted emitted on acceptance

Closes: #334

[drips-wave]

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