fix: address #400, #401, #402, #403

[jhayniffy]

Summary

fix: address #400, #401, #402, #403

What was solved

#400 — [High] Add an interface-version handshake between cooperating contracts

Add a semantic interface-version handshake across the four Soroban contracts (intent_settlement, proof_registry, solver_registry, reputation_badge) plus shared helpers in vortex-common. Each contract exports interface_version() -> (name, major, minor); settlement's set_proof_registry/set_solver_registry and directory updates reject incompatible major versions; dependency upgrades emit a version-change event so dependents can re-verify lazily; a compatibility matrix is documented. Pre-handshake contracts that trap on the call are treated as v0 via try_ clients.

Addressed:

• Changed: README.md
• Every contract (intent_settlement, proof_registry, solver_registry, reputation_badge) exports interface_version() -> (name, major, minor)
• set_proof_registry and set_solver_registry reject a dependency whose major version is incompatible
• Directory updates reject incompatible major versions

#401 — [High] Add a contract-spec (ABI) compatibility checker that gates upgrades

Add a new tools/spec-check/ Rust crate that extracts the Soroban contract spec (functions, types, errors, events) from built wasm artifacts, compares it against committed specs/<crate>.json baselines, and fails cargo test on breaking changes (removed/renamed functions, changed arg types, reordered enum variants, changed error codes, removed struct fields). Breaking changes must be explicitly allowlisted with a named issue. Covers all contracts (intent_settlement, proof_registry, reputation_badge, solver_registry).

Addressed:

• Changed: tools/spec-check/Cargo.toml, tools/spec-check/src/lib.rs, tools/spec-check/src/main.rs, tools/spec-check/Cargo.toml
• Create a new Rust crate at tools/spec-check/ that runs as part of cargo test -p spec-check.
• Extract the contract spec from built wasm artifacts by parsing contractspecv0 entries using the soroban-spec crate.
• Commit baseline spec files at specs/<crate>.json generated from the wasm spec entries for every contract in the workspace.

#402 — [High] Implement a generic TimelockController contract that owns protocol admin roles

Add a standalone timelock/ Soroban crate implementing an OpenZeppelin-style TimelockController (proposer/executor/canceller roles, hash-committed operation ids, min-delay self-administration, batch scheduling, and env.invoke_contract replay), plus a deployment runbook doc describing how each protocol contract's admin is transferred to the timelock. Scope is limited to the generic timelock and admin-transfer runbook; voting/Governor is explicitly out of scope, and existing per-contract timelocks are not refactored here.

Addressed:

• Changed: timelock/Cargo.toml, timelock/src/lib.rs, timelock/src/test.rs
• Create a new timelock/ crate with Cargo.toml and src/lib.rs (plus tests) wired into the workspace/CI like the other crates.
• Implement schedule(target, fn, args, salt, delay), execute, cancel, get_operation_state, and batch scheduling.
• Enforce a minimum delay; only the timelock itself may change the delay.

#403 — [High] Implement a stake-weighted Governor contract for protocol parameter changes

Implement a Soroban-native stake-weighted Governor crate that derives voting power from checkpointed solver bond/delegated stake in solver_registry, supports propose/vote/quorum/timelock queue+execute, delegation, and snapshot-based anti-flash-stake protection, plus a governance doc.

Addressed:

• Changed: governor/src/lib.rs, governor/Cargo.toml, docs/governance-design.md
• Create a new governor/ crate implementing propose with a proposal threshold, vote (for/against/abstain), quorum, voting period, queue to TimelockController, and execute
• Derive voting power from solver bond plus delegated stake in solver_registry, snapshotted at proposal creation
• Add historical balance checkpoints to solver_registry/src/lib.rs with binary search over bounded checkpoints

Changes

• tools/spec-check/src/lib.rs (create)
• timelock/src/lib.rs (create)
• governor/Cargo.toml (create)
• tools/spec-check/Cargo.toml (create)
• timelock/Cargo.toml (create)
• governor/src/lib.rs (create)
• README.md (modify)
• tools/spec-check/src/main.rs (create)
• timelock/src/test.rs (create)
• docs/governance-design.md (create)

Approach

1. [High] Add an interface-version handshake between cooperating contracts #400 — [High] Add an interface-version handshake between cooperating contracts (Changed: README.md)
2. [High] Add a contract-spec (ABI) compatibility checker that gates upgrades #401 — [High] Add a contract-spec (ABI) compatibility checker that gates upgrades (Changed: tools/spec-check/Cargo.toml, tools/spec-check/src/lib.rs, tools/spec-check/src/main.rs, tools/spec-check/Cargo.toml)
3. [High] Implement a generic TimelockController contract that owns protocol admin roles #402 — [High] Implement a generic TimelockController contract that owns protocol admin roles (Changed: timelock/Cargo.toml, timelock/src/lib.rs, timelock/src/test.rs)
4. [High] Implement a stake-weighted Governor contract for protocol parameter changes #403 — [High] Implement a stake-weighted Governor contract for protocol parameter changes (Changed: governor/src/lib.rs, governor/Cargo.toml, docs/governance-design.md)

Issues

Closes #400
Closes #401
Closes #402
Closes #403

[drips-wave]

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