[Smart Contract] Add contract version tracking and define upgrade migration path

[gregemax]

Summary

The Soroban escrow contract exposes a version() read-only entrypoint (added 2026-08-01) that returns the current version string. However there is no defined process for what happens when the contract needs to change — e.g. adding a new entrypoint, changing storage layout, or patching a bug.

Soroban contracts can be upgraded in-place via update_current_contract_wasm(). Without a migration path defined, any future change risks breaking existing open escrows.

What's needed

1. Document the upgrade strategy in stellance/Contracts/README.md:

   • When in-place upgrade (update_current_contract_wasm) is safe vs. when a new contract must be deployed
   • Who is authorized to call the upgrade (admin address only)
   • What storage migrations are needed if data layout changes

2. Add an upgrade() entrypoint (admin-only):

   pub fn upgrade(env: Env, admin: Address, new_wasm_hash: BytesN<32>) {
       admin.require_auth();
       // assert admin matches stored admin
       env.deployer().update_current_contract_wasm(new_wasm_hash);
   }

3. Add a test that verifies the upgrade is admin-gated:

   #[test]
   fn test_non_admin_cannot_upgrade() { ... }

Notes

• Open escrow state must survive an upgrade — test that get_escrow returns the same data after an upgrade
• The version() entrypoint should be incremented in every upgrade

Related

• stellance/Contracts/src/lib.rs — version() and get_admin() already implemented
• Roadmap Week 4 — contract hardening