Feat/issue 29 upgrade governance#32
Merged
MaryammAli merged 3 commits intoJun 21, 2026
Merged
Conversation
…roof-Stell#30) - Add DocumentInfo contracttype for batch registration input - Add BatchTooLarge (code 7) and BatchEmpty (code 8) error variants - Implement batch_register_documents with 20-doc limit, fail-fast atomicity - Implement batch_revoke_documents with 20-doc limit, fail-fast atomicity - Emit per-document events for each item in successful batch - Fix pre-existing format! macro visibility under #![no_std] with #[macro_use] - Add 10 new tests covering success, partial failure, empty, and oversized batches - Document batch operations and limits in README
…overnance (closes Proof-Stell#29) - Add DataKey::Admin, Version, FeatureFlag(Symbol) to persistent storage - Add CONTRACT_VERSION constant (currently 1) - Add ContractInitialized and ContractUpgraded contract events - Add AlreadyInitialized (9), NotInitialized (10), Unauthorized (11), MigrationNotNeeded (12) error codes - Implement initialize, get_version, get_admin, upgrade, migrate, set_feature_flag, get_feature_flag - migrate handles v0 (pre-versioned) state to bootstrap versioning on existing deployments - Add 13 new tests covering init, double-init, version checks, admin gating, migration, feature flags, and post-migration document compatibility - Add upgrade runbook to README with step-by-step deploy, upgrade, and rollback procedures - Add docs/UPGRADE_GOVERNANCE.md with change classification, governance roles, and emergency upgrade process
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds contract upgrade mechanism, on-chain versioning, data migration path, and feature flag governance to the ProofStell Soroban contract. The admin address (set once at initialize) controls all governance operations. Indexers can detect contract version transitions via ContractInitialized and ContractUpgraded events, and existing document records remain fully accessible after migration.
Type of Change
Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Refactor (code change that neither fixes a bug nor adds a feature)
Documentation update
Related Issues
Closes #29
Changes Made
Add DataKey::Admin, DataKey::Version, DataKey::FeatureFlag(Symbol) to persistent storage
Add CONTRACT_VERSION constant (currently 1)
Add ContractInitialized and ContractUpgraded contract events for indexer version tracking
Add AlreadyInitialized (9), NotInitialized (10), Unauthorized (11), MigrationNotNeeded (12) error codes
Implement initialize(admin) — sets admin + version on first deployment; fails if called again
Implement upgrade(admin, new_wasm_hash) — admin-gated WASM replacement via env.deployer().update_current_contract_wasm
Implement migrate(admin) — detects pre-versioned state (v0) and bootstraps to v1; returns MigrationNotNeeded if already current; extensible for future version transitions
Implement get_version() and get_admin() — read-only accessors
Implement set_feature_flag / get_feature_flag — admin-gated named feature toggles stored per Symbol
Add upgrade runbook to README (build → install → upgrade → migrate → rollback plan)
Add docs/UPGRADE_GOVERNANCE.md with change classification, governance roles, standard and emergency upgrade processes, and storage migration rules
Testing
cargo test passes locally
cargo build --target wasm32-unknown-unknown --release succeeds
New tests added for new functionality (if applicable)
13 new tests: initialize_sets_admin_and_version, double_initialize_fails, get_version_returns_zero_before_init, get_admin_returns_none_before_init, upgrade_requires_initialization, non_admin_cannot_upgrade, migrate_v0_to_v1_sets_versioning, migrate_already_current_fails, documents_still_work_after_migration, get_feature_flag_returns_false_for_unset, admin_can_set_and_get_feature_flag, non_admin_cannot_set_feature_flag, set_feature_flag_requires_initialization. All 87 tests pass.
Checklist
My code follows the project's coding conventions
I have performed a self-review of my code
I have commented my code where necessary
No unused imports or dead code remains
CI checks pass (build + test + wasm)