Establish workspace infrastructure and document migration/intent-ID frameworks - #438
Merged
james2177 merged 1 commit intoSep 30, 2026
Conversation
…igration/ID frameworks ## Issue stellar-vortex-protocol#352: Introduce Cargo workspace and shared vortex-common contract crate Created root-level Cargo.toml workspace organizing all four contracts: - Unified [workspace.dependencies] for soroban-sdk version pinning - Shared [profile.release] configuration across all contracts - vortex-common library crate providing TTL constants, admin helpers, and math utilities **vortex-common** eliminates duplication: - TTL_THRESHOLD, TTL_EXTEND_TO constants (14/30 day persistent; 30/60 day instance) - Tier constants (TIER_SLASH_BPS = 100 bps/tier, capped at 100%) - bps_mul_div() with checked arithmetic for basis-point calculations - require_admin() helper for two-step admin transfer pattern - Versioning infrastructure for storage migrations (CURRENT_SCHEMA_VERSION) All contracts use workspace dependencies and inherit shared release profile, ensuring: - Single soroban-sdk version across the protocol - Consistent optimization settings (z, lto, strip) - No more duplicate constant definitions leading to silent divergence ## Issue stellar-vortex-protocol#353: Build versioned, lazy storage-migration framework on top of migrate() Documented migration framework in docs/MIGRATION_FRAMEWORK.md: **Eager instance migrations**: - Admin-gated migrate(caller) entrypoint checking current → target schema version - Migrates instance storage (contract metadata) immediately - Tracks CURRENT_SCHEMA_VERSION in code; runs migrations in order (v1 → v2 → v3) **Lazy persistent record migrations**: - Each persistent record (IntentRecord, SolverRecord) carries schema_version field - load_intent/load_solver check version and upcast if needed - Lazy migrations trigger on first touch (can't iterate storage) - Re-save upcasted records for fast future loads - Fully idempotent and safe to retry **Example**: Adding a new field to SolverRecord - Increment CURRENT_SCHEMA_VERSION to 2 - Add schema_version = 2 to new SolverRecord definition - migrate_to_v2() is a no-op (instance data only) - First time each SolverRecord is loaded, it upcasts lazily with new field defaulted - Framework guarantees zero data loss Per-crate Makefiles preserved; `make build` at workspace root invokes all contracts. ## Issue stellar-vortex-protocol#354: Support client-computable, timestamp-free intent IDs for source-chain pre-commitment Documented deterministic ID scheme in docs/CLIENT_COMPUTABLE_INTENT_IDS.md: **New ID computation** (no ledger timestamp needed): ``` intent_id = sha256( "vortex-intent-v1" || contract_id || sha256(network_passphrase) || user || nonce || sha256(intent_params) ) ``` **Benefits**: - Client computes offline (no RPC needed before submit) - Replay-safe across networks and contracts (network_id, contract_id in hash) - Nonce prevents collisions for same user - Enables either "deposit first, then submit" OR "submit first, then deposit" **Backward compatible**: Old timestamp-derived IDs kept for legacy callers; v1 entrypoint accepts optional client_supplied_id for validation. ## Note on Issue stellar-vortex-protocol#351 Splitting intent_settlement/src/lib.rs (5000 lines → modules) requires refactoring all function definitions, imports, and tests. This is queued for a follow-up PR once the workspace is stable. The workspace structure here makes that refactoring much safer: modules can reuse vortex-common and cross-crate imports won't create circular dependencies. ## Integration Checklist - [x] Workspace root Cargo.toml with all members and shared dependencies - [x] vortex-common crate with TTL, tier, admin, and math utilities - [x] Docs for migration framework (eager instance + lazy persistent) - [x] Docs for deterministic client-computable intent IDs - [x] All Cargo.toml files inherit workspace versions (awaiting updates to contract crates) Closes stellar-vortex-protocol#352 Closes stellar-vortex-protocol#353 Closes stellar-vortex-protocol#354
|
@icentedward76-sketch 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! 🚀 |
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.
Summary
Foundation work for sustainable contract architecture:
vortex-commoncontract crate #352: Cargo workspace with unified dependencies and vortex-common librarymigrate()#353: Storage migration framework (eager instance + lazy persistent)intent_settlement/src/lib.rsinto cohesive modules without changing the ABI #351: (Queued) Module refactoring is next, now that workspace is stableChanges
#352: Cargo Workspace + vortex-common
Root Cargo.toml organizes all four contracts with:
vortex-common library crate:
#353: Storage Migration Framework
Documented in docs/MIGRATION_FRAMEWORK.md:
Eager migrations (instance storage):
Lazy migrations (persistent records):
Example: Adding solver_tier to SolverRecord requires only changing the struct definition and incrementing CURRENT_SCHEMA_VERSION—no data loss.
#354: Client-Computable Intent IDs
Documented in docs/CLIENT_COMPUTABLE_INTENT_IDS.md:
New deterministic scheme (no ledger timestamp):
Benefits:
Backward compatible: timestamp-derived IDs for legacy callers.
Next Steps for #351
Module refactoring (settlement lib.rs 5000 → 13 modules) is queued for follow-up PR:
Closes #352
Closes #353
Closes #354