Add upgradeability pattern to vesting_escrow contract

[Wilfred007]

What

Vesting_escrow has no upgrade mechanism. If a bug is found, all vesting schedules must be migrated manually. Vesting schedules span months/years.

Why

An unfixable bug could lock funds permanently. Upgradeability with timelock is a security best practice.

Scope

In scope: Proxy pattern or WASM hash upgrade, admin can upgrade with 48h timelock, storage preserved
Out of scope: Governance-controlled upgrades

Acceptance Criteria

• Admin can propose upgrade with new WASM hash
• Timelock (48h) before upgrade executes
• Storage preserved across upgrades
• Upgrade event emitted

Technical Context

• contracts/vesting_escrow/src/lib.rs — no upgrade mechanism
• contracts/common/src/lib.rs — shared admin auth

[balisdev]

Hi, I’d like to contribute to this issue by implementing a secure, admin-controlled upgrade mechanism for Vesting_escrow with a mandatory 48-hour timelock.

Since vesting schedules can remain active for months or years, I agree that requiring manual migration to fix a critical contract bug creates unnecessary risk. The upgrade mechanism should therefore make it possible to patch the contract while preserving all existing vesting state and giving administrators enough time to review or cancel a proposed upgrade.

Proposed approach

I’d first inspect the existing contract architecture and the shared admin authorization in contracts/common/src/lib.rs, then implement the upgrade flow in contracts/vesting_escrow/src/lib.rs using the upgrade mechanism that best fits the current WASM contract architecture.

The core flow would be:

1. Propose upgrade

   • Admin submits a new WASM hash.
   • Store the proposed hash and the timestamp at which the upgrade becomes executable.
   • Record enough state to prevent ambiguous or partially completed upgrades.

2. 48-hour timelock

   • The proposed upgrade cannot execute immediately.
   • Execution should require the current timestamp to be at least proposed_at + 48 hours.
   • The contract should reject attempts to execute before the timelock expires.

3. Execute upgrade

   • After the timelock expires, the authorized admin can execute the upgrade.
   • Ensure the contract's existing storage/state is preserved across the upgrade.
   • Clear or finalize the pending upgrade state appropriately after successful execution.

4. Upgrade event

   • Emit a dedicated upgrade event containing useful information such as the previous/new WASM hash and relevant timing information.
   • Keep the event consistent with the project's existing event conventions.

5. Admin authorization

   • Reuse the existing authorization patterns from contracts/common/src/lib.rs.
   • Ensure unauthorized accounts cannot propose or execute upgrades.

Storage safety

Storage preservation would be one of my main focuses because existing vesting schedules must continue working after an upgrade.

I’d review the current storage layout and serialization types before implementing the upgrade path, and avoid unnecessary changes to existing storage keys/types. I’d also add tests specifically covering an upgrade with pre-existing vesting schedules to verify that balances, schedules, beneficiaries, timestamps, and other persistent state remain intact.

Testing

I would add tests covering at least:

• Admin can propose an upgrade.
• Non-admin cannot propose or execute an upgrade.
• Proposed WASM hash is persisted correctly.
• Upgrade cannot execute before 48 hours.
• Upgrade executes successfully after the timelock.
• Existing vesting storage survives the upgrade.
• Correct upgrade event is emitted.
• Pending upgrade state is handled correctly after execution.
• Invalid upgrade attempts are rejected safely.

I’d also pay particular attention to timestamp arithmetic and boundary conditions around the 48-hour delay.

Implementation philosophy

I’d aim to keep the change narrowly scoped: no governance layer, no changes to the existing vesting behavior, and no unnecessary migration of existing schedules. The upgrade mechanism should be deliberately simple and auditable, with the timelock acting as an important safety boundary rather than adding unnecessary complexity.

I’m happy to start by reviewing the existing contract/storage architecture and test conventions, then implement the smallest upgrade mechanism that satisfies the acceptance criteria while maintaining backward compatibility with existing vesting schedules.

[grantfox-oss]

🦊 GrantFox — @balisdev has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #552)
2. Your PR will be reviewed by the Protocol-Guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@balisdev's PR #602 was approved and merged by @Wilfred007.

🏆 @balisdev: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (783 total points). Track your full progress on GrantFox.

👏 Great work, @balisdev! Keep contributing to Protocol-Guild.