Managing on-chain Move dependencies on Sui requires a fundamentally different operational approach than traditional software dependency management. Unlike off-chain package managers, Sui's on-chain packages are published as immutable or mutable objects, and their upgrade policies are enforced at the protocol level. When a critical dependency—such as the core Sui Framework or a widely used standard library—publishes a breaking upgrade, downstream packages do not automatically inherit the new version. Teams must explicitly plan and execute a migration, which involves pointing their package to a new dependency address, recompiling, and redeploying. This process introduces coordination challenges, especially for protocols that are themselves dependencies for other applications, creating cascading upgrade graphs that must be carefully sequenced.
Dependency Management and Framework Forking for Move Packages
Introduction
A technical guide for Sui development teams on managing on-chain Move dependencies, planning for breaking framework upgrades, and evaluating package upgrade policies.
The operational impact is most acute when the Sui Framework itself is upgraded during a network-wide protocol version change. Framework upgrades can modify the behavior of core types like Coin, DynamicField, or Transfer, or introduce new abilities and constraints that break existing Move bytecode compatibility. A package compiled against an older framework version will continue to function until a breaking change is introduced to a type or function it depends on. At that point, the package must be upgraded to reference the new framework version. Teams that fail to monitor testnet framework deployments risk discovering breaking changes only after a mainnet activation, leading to downtime for their users and any downstream integrators. This makes continuous integration testing against testnet framework versions a critical operational practice.
The choice between immutable and mutable package upgrade policies is a key architectural decision that directly affects dependency management. An immutable package provides strong guarantees to downstream consumers that its interface will never change, eliminating the risk of surprise breakage but also preventing any bug fixes or feature additions. A mutable package controlled by an UpgradeCap allows the publisher to push upgrades, but this introduces a trust assumption for all dependent packages. Downstream developers must decide whether to pin to a specific version of a mutable dependency or to accept automatic upgrades. For protocols that serve as infrastructure for other builders, a common pattern is to use a proxy or wrapper package that can be upgraded while maintaining a stable interface, decoupling internal changes from downstream breakage. Chainscore Labs can help teams plan and review dependency upgrade paths, assess the risks of mutable dependency graphs, and design stable interface patterns that minimize ecosystem disruption.
Quick Facts
Operational facts for teams managing on-chain Move dependencies and planning for breaking framework upgrades.
| Area | What changes | Who is affected | Action |
|---|---|---|---|
Dependency Upgrade Policy | A dependency can publish a breaking upgrade if its upgrade policy is set to 'compatible' or 'additive'. An 'immutable' policy prevents all upgrades. | Protocol developers, DeFi protocols, wallet builders | Audit the upgrade policy of all direct and transitive on-chain dependencies. Verify against the canonical source. |
Framework Forking | Teams may fork the Sui Framework to modify or lock its logic, creating a parallel dependency tree that diverges from the canonical framework. | Application developers, core protocol teams | Assess the security and maintenance burden of maintaining a fork. Review the forked modules for correctness and missing upstream fixes. |
Testnet Migration Testing | New framework versions are deployed to testnet before mainnet. Teams must test their packages against the new version to catch breaking changes. | QA engineers, integration teams, smart contract developers | Run full CI/CD test suites against the testnet framework as soon as it is deployed. Simulate all critical user flows. |
Object and Type Compatibility | A framework upgrade can change object abilities, transfer rules, or dynamic field behavior, breaking downstream packages that depend on the old semantics. | Indexers, explorers, wallets, cross-chain bridges | Review the framework changelog for changes to object model rules. Update parsing logic and integration tests to handle new structures. |
Dependency Graph Analysis | A breaking change in a deeply nested transitive dependency can unexpectedly brick a top-level application. | Protocol architects, security auditors | Map the full dependency graph for your on-chain packages. Identify all transitive dependencies and their upgrade policies. |
Gas and Transaction Changes | Framework upgrades may alter native function gas costs or programmable transaction block rules, affecting transaction simulation and gas estimation. | Wallet providers, exchanges, gas station operators | Update gas estimation models and simulation logic. Test sponsored transaction flows against the new framework version. |
Migration Coordination | A breaking dependency upgrade requires a coordinated migration: publishing a new package version and migrating state from the old package. | DeFi protocol operators, NFT project teams | Plan a state migration strategy. Ensure downstream integrators are notified and have updated their package pointers. |
The Dependency Upgrade Surface
How a breaking upgrade to a Move package dependency forces every downstream package to execute a coordinated migration, and why immutable upgrade policies create permanent integration risk.
On Sui, every on-chain Move package declares its dependencies explicitly in its Move.toml manifest. When a dependency publishes a breaking upgrade—whether it is the core Sui Framework, a standard library like std, or a third-party protocol package—every downstream package that depends on it must also publish a new version to update its dependency graph. This is not a simple recompilation. A breaking change to a dependency's public function signatures, struct layouts, or abilities can silently break the bytecode verification of a downstream package, preventing it from being upgraded or, in the worst case, bricking its existing on-chain state if the package has an immutable upgrade policy and cannot be upgraded at all.
The operational surface is deceptively large. A single Sui Framework upgrade that changes the signature of a widely-used function like transfer::public_transfer or alters the rules for dynamic field access forces every wallet, marketplace, bridge contract, and DeFi protocol that imports that module to plan, test, and execute a coordinated migration. Teams must monitor testnet framework deployments, run their full test suite against the new dependency version, and publish their own upgrade transaction within the same epoch window if the change is consensus-critical. For packages with an immutable upgrade policy, there is no migration path—they become permanently pinned to the old framework version, creating a growing compatibility gap that integrators like indexers, explorers, and analytics platforms must handle as a special case.
Chainscore Labs helps protocol teams and infrastructure operators map their full dependency upgrade surface before a framework release. This includes auditing Move.toml dependency graphs for hidden transitive dependencies, simulating the bytecode verification impact of a proposed framework change against a team's published packages, and designing upgrade transaction sequences that minimize the window where a protocol's contracts are out of sync with the active framework version. For teams managing packages with immutable upgrade policies, we assess the long-term integration risk and recommend patterns for wrapping or proxying calls to isolate breaking changes.
Affected Actors
Package Publishers
Publishers of shared Move packages must manage the downstream impact of their upgrade policies. The choice between an immutable and a mutable upgrade policy is a critical governance decision.
Key responsibilities:
- Breaking changes: When publishing a new version with breaking changes, you must clearly communicate the migration path. This includes documenting new object schemas, changed function signatures, and any required data migrations.
- Dependent coordination: Proactively notify dependent teams through on-chain events or off-chain channels. A surprise upgrade can brick integrators who have not updated their transaction-building logic.
- Testnet staging: Always stage new framework versions on testnet first. This allows indexers, wallets, and downstream protocols to test compatibility before mainnet activation.
Chainscore can review your upgrade package for downstream compatibility risks and help design a safe, phased rollout plan.
Migration Planning and Testing Strategy
A structured approach to planning, testing, and executing a migration when a critical on-chain dependency publishes a breaking upgrade.
Dependency Upgrade Impact Assessment
Before any code changes, map every module, function, and type from the upgraded dependency that your package uses. A breaking change in the Sui Framework or a standard library can silently alter object abilities, transfer semantics, or dynamic field behavior. Chainscore performs a structured impact assessment that identifies every call site affected by a new framework version, including transitive dependencies that may not be immediately obvious.
Testnet Fork and State Simulation
Testing against a public testnet is insufficient for a high-stakes migration. You must fork the testnet state at a specific checkpoint, deploy your upgraded package, and replay a representative set of historical Programmable Transaction Blocks to verify that state transitions remain consistent. This simulation should explicitly test for object version mismatches, dynamic field iteration failures, and gas budget regressions that only surface under realistic load.
Immutable vs. Mutable Upgrade Policy Planning
If your package has an immutable upgrade policy, a breaking dependency change forces a full redeployment to a new package ID, requiring all users and integrators to migrate manually. For mutable packages, plan the upgrade transaction carefully, ensuring that the new dependency version is compatible with your existing state. Chainscore can review your upgrade policy against your operational requirements to determine the safest path forward.
Downstream Integrator Communication Protocol
Wallets, explorers, and indexers that parse your package's objects and events will break if your migration changes type layouts or event emission patterns. Establish a communication channel with major integrators at least two weeks before mainnet activation. Provide a detailed changelog of type definition changes, new object structures, and any deprecated event types so they can update their parsing logic and avoid data loss.
Rollback and Emergency Pause Strategy
A failed migration can lock user funds or break composability with other protocols. Design your upgrade to include an emergency pause mechanism that can be triggered by a multisig or governance body. If your package is immutable, pre-deploy a 'migration router' pattern that can redirect calls to a new version, allowing for a staged rollout. Test the rollback procedure on testnet before mainnet activation.
Post-Migration State Validation
After the upgrade transaction executes, run an automated validation suite that queries all critical objects and verifies their state against expected values. This should include checking ownership records, dynamic field counts, and balance invariants. For high-value protocols, Chainscore recommends a post-migration monitoring period where a dedicated script continuously validates state integrity for at least 24 hours after activation.
Risk Matrix
Operational risks and failure modes when managing on-chain Move package dependencies and framework upgrades, and the actions teams should take to mitigate them.
| Risk Area | Failure Mode | Who is affected | Severity | Mitigation and Action |
|---|---|---|---|---|
Immutable Dependency Breakage | A dependency publishes a breaking upgrade, but the dependent package has an immutable upgrade policy, permanently bricking its ability to interact with the new version. | Protocol developers, DeFi protocols | Critical | Audit all dependency upgrade policies. For immutable packages, implement a wrapper or proxy pattern. Chainscore can review dependency trees for immutability dead-ends. |
Framework Migration Lag | A team fails to test and migrate their package against a new Sui Framework version on testnet before it activates on mainnet, causing transaction failures. | All application developers | High | Establish a monitoring system for new framework releases on testnet. Automate integration tests against the new framework version. Chainscore can perform a pre-upgrade compatibility assessment. |
Type Mismatch on Shared Object | A dependency changes the type or abilities of a shared object, causing dependent packages to fail when deserializing or interacting with the object's new schema. | Indexers, wallets, DeFi protocols | High | Verify object type compatibility in all integration tests. Implement robust error handling for deserialization failures. Chainscore can audit object model interaction logic. |
Dynamic Field Migration Error | A dependency migrates data into dynamic fields with a new structure, but a dependent package's iteration or query logic fails to parse the new format. | Explorers, analytics platforms, wallets | High | Design dynamic field access patterns to be defensive against type changes. Test iteration logic against migrated state. Chainscore can provide an upgrade impact assessment for dynamic field changes. |
Sponsored Transaction Gas Logic Failure | A framework upgrade changes gas cost schedules or gas object rules, causing a gas station's sponsored transaction logic to consistently underestimate budgets. | Wallet infrastructure, gas station operators | Medium | Recalibrate gas estimation models against each new framework version. Simulate sponsored transactions on testnet. Chainscore can review gas station architecture for reliability under new cost parameters. |
Epoch Transition State Inconsistency | A migration transaction spanning an epoch boundary fails because a dependency's state changed during the epoch transition, leading to a partial or inconsistent upgrade. | All teams performing state migrations | Medium | Design migration transactions to be idempotent and atomic. Avoid multi-epoch migration patterns. Chainscore can review migration scripts for epoch-boundary safety. |
Governance Attack on Dependency | A mutable dependency is taken over by a malicious governance actor who publishes a breaking upgrade that steals funds or bricks dependent protocols. | All protocols depending on mutable packages | Critical | Pin dependencies to a specific, audited version where possible. Monitor governance events for all critical dependencies. Chainscore can help establish a dependency monitoring and alerting system. |
Indexer Desync from Object Versioning | An indexer fails to correctly parse the new object version history after a dependency upgrade, leading to incorrect balance or ownership displays. | Exchanges, custodians, data teams | High | Validate indexing logic against all object versioning edge cases. Re-index from the upgrade checkpoint. Chainscore can review indexing architecture for object model correctness. |
Dependency Upgrade Operational Checklist
A step-by-step operational checklist for teams managing on-chain Move packages that depend on the Sui Framework or other upstream packages. This process ensures a safe migration when a dependency publishes a breaking upgrade, minimizing the risk of bricking a live package or causing integration failures for downstream users.
What to check: Verify the UpgradeCap policy of every direct and transitive dependency. Determine if the dependency is immutable or can be upgraded by its publisher.
Why it matters: An immutable dependency guarantees that its API will never change, eliminating a class of risk. A mutable dependency requires continuous monitoring. If a dependency's UpgradeCap is destroyed, you can safely pin to its current version. If it is held by a multi-sig or governance, you must track their proposal cycles.
Readiness signal: A complete dependency graph with each package annotated as immutable, mutable (single publisher), or mutable (governed).
Source Resources
Dependency Management and Framework Forking for Move Packages should be based on canonical Sui sources, not copied package IDs or stale framework snapshots. Use these resources to pin versions, review breaking changes, test migrations, and monitor upstream changes before publishing upgraded Move packages.
Looking to build on a specific blockchain?
We build smart contracts, DeFi applications, wallets, tokenization platforms, and blockchain infrastructure across the major ecosystems teams choose today. That includes Ethereum, Arbitrum, Optimism, Polygon, Avalanche, Solana, Sui, Aptos, Hedera, Stellar, and NEAR, with support for additional EVM and non-EVM networks based on your product requirements.
EVM ecosystems
- Ethereum
- Arbitrum
- Optimism
- Polygon
- Avalanche
- Cronos
Non-EVM ecosystems
- Solana
- Sui
- Aptos
- Hedera
- Stellar
- NEAR
Additional ecosystems
- Polkadot
- Cosmos
- TON
- Cardano
- Algorand
- Tempo
Also available for Base, appchains, custom EVM networks, and cross-chain product architecture.
Frequently Asked Questions
Common questions from development teams planning a migration when an upstream Move package dependency publishes a breaking upgrade.
Monitor the UpgradeCap of every direct and transitive dependency. A new version is published when the UpgradeCap owner calls package::upgrade. Teams should:
- Subscribe to
PublishEventandUpgradeEventon mainnet and testnet. - Diff the new package's
UpgradePolicyto confirm whether it is compatible (additive) or incompatible (breaking). - Check for removed public functions, changed struct abilities, or altered dynamic field key types.
Why it matters: A silent upgrade can break your package's ability to call into the dependency, causing transaction failures for users. Early detection gives you time to test and migrate before the new version becomes the dominant instance.
Delivering blockchain solutions for 5+ years.
We have partnered with 50+ leading DeFi protocols, NFT ecosystems, and fintech innovators to build secure, scalable, and capital-efficient blockchain products.
Selected Partners & Clients
“I've been working with Chainscore Labs for last 3+ years, they've consistently delivered with strong ownership across multiple projects. The team is reliable and detail-oriented.”
How to get started?
If you're looking for blockchain integration, ChainScore Labs has 5+ years of experience helping teams build and integrate exchanges, wallets, smart contracts, tokenization solutions, and protocol-connected products, we can help you choose the right path, integrate securely, and get to production faster. Our team consists of experienced blockchain developers and architects who can help you with your blockchain integration needs.
Exploration & Strategy
Define your product goals and choose the right blockchain architecture for your use case.
Architecture & Design
Design the smart contracts, tokenomics, and security parameters of your system.
Development & Integration
Build and integrate with wallets, oracles, and front-end dApps for a seamless experience.
Security & Launch
Comprehensive audits followed by a risk-managed mainnet deployment to protect your users.
Discover our
blockchain development services.
We build production-grade blockchain solutions for top-tier projects across DeFi and Web3.
Need a blockchain engineering team?
Send the project context and we will respond with next steps, scope questions, and a practical path to delivery.