Package Version Safety

Skill: PACKAGE_VERSION_SAFETY (Sui)

Trigger Pattern: PACKAGE_UPGRADE flag (UpgradeCap detected, multiple package versions, upgrade policy references) Inject Into: Breadth agents, depth-external Finding prefix: [PV-N] Rules referenced: R4, R8, R9, R10

Sui packages are immutable once published. "Upgrading" a package means publishing a NEW version at a NEW on-chain address, linked to the original via the UpgradeCap lineage. The old version's code remains callable forever. This creates a fundamentally different upgrade risk model compared to EVM proxies: instead of replacing logic in-place, Sui packages accumulate versions -- and shared objects may be accessible by ALL versions simultaneously.

Trigger Patterns

UpgradeCap|upgrade_policy|package::make_immutable|compatible|additive|dep_only|version|
migrate|old_version|new_version

Step 1: Upgrade Policy Inventory

For each package in scope:

Checks:

• Where is UpgradeCap stored?

  • Owned by deployer address: Single point of failure. Key loss -> permanent immutability. Key theft -> attacker can upgrade.
  • Shared object: DANGEROUS -- anyone can pass it to upgrade functions.
  • Wrapped in governance object: Good pattern -- upgrade requires governance approval.
  • Destroyed via make_immutable(): Package is permanently immutable. No upgrade risk.
  • Transferred to @0x0 or burn address: Effectively immutable.

• Can UpgradeCap be transferred?

  • UpgradeCap has key + store by default -> freely transferable via public_transfer.
  • Is there a custom wrapper restricting transfer? (e.g., GovernanceCap wrapping UpgradeCap)
  • If transferable and held by EOA -> attacker stealing key can transfer UpgradeCap.

• Can UpgradeCap be destroyed?

  • sui::package::make_immutable(cap) consumes UpgradeCap -> permanent immutability.
  • If UpgradeCap has drop via wrapper -> accidental destruction possible.

1b. UpgradeCap Governance Assessment

Step 2: Version Consistency Check

For shared objects created by this package:

What happens when package is upgraded?

• Existing shared objects created by V1 remain at their original address
• V2 functions CAN access V1-created shared objects (types are preserved in compatible upgrades)
• V1 functions are STILL callable and CAN access the same shared objects
• This dual-access is the primary version safety concern

Can old-version and new-version calls on same shared object create inconsistency?

• V1 function writes field A based on formula F1
• V2 function writes field A based on formula F2
• User calls V1 then V2 in separate transactions -> field A has inconsistent state
• Especially dangerous: V2 adds a new check that V1 lacks. Attacker calls V1 to bypass V2's check.

Step 3: Dependency Version Pinning

For each dependency in Move.toml:

Checks:

• Are third-party dependencies pinned to specific git revisions? If pinned to main -> upstream changes included on recompile.
• For on-chain published dependencies: is the dependency package immutable? If it has active UpgradeCap -> behavior can change.
• Can a dependency upgrade break our package's invariants?
• Are there transitive dependencies with their own upgrade risks?

Can dependency upgrade break our package?

• Compatible dependency upgrade: function implementations can change but signatures preserved. Our calls still compile but behavior may differ.
• Additive dependency upgrade: only new functions/types added. Existing behavior frozen.
• Framework upgrades: sui::* packages upgraded by validators. Can change Move VM behavior, gas costs, object model rules.

Step 4: Type Compatibility Across Versions

When package V2 adds new types or fields:

Sui type rules for compatible upgrades:

• Existing struct field layouts CANNOT change (enforced by validator during upgrade)
• New structs CAN be added
• Existing function signatures CANNOT change
• Function bodies CAN change (this is where logic vulnerabilities occur)
• Generic type parameters must remain the same

Can V1 objects be used with V2 functions?

• YES for compatible upgrades: types are identical, V2 functions accept V1 objects.
• NO for separate package deployment: different package address = different types.

Can V2 objects be used with V1 functions?

• V2 does not create new object types that V1 knows about (V1 code is frozen).
• But V2 functions can modify shared objects that V1 functions then read -- state corruption possible.

Dynamic field implications:

• Dynamic fields keyed by type. If V2 changes key/value types for dynamic fields -> V1-era entries orphaned.
• Check: does V2 change any dynamic field key types?

Step 5: Upgrade Migration Safety

Does the package have migration functions to update shared objects from V1->V2 state?

Version guard pattern: Shared objects contain version: u64. V1 functions check assert!(version == 1). V2 migration function sets version = 2. After migration, V1 functions abort because version != 1.

Check:

• Is version guard implemented? If NOT -> old functions remain callable indefinitely -> FINDING.
• Can migration be triggered by unauthorized parties?
• Is migration atomic? Can it be partially completed?
• What happens to user-owned objects during migration? (Owned objects cannot be modified by admin migration)

Step 6: UpgradeCap Governance

If UpgradeCap is owned by a single address:

Mitigations to check:

• Is UpgradeCap behind multisig?
• Is there an upgrade timelock (users can exit before upgrade takes effect)?
• Is there a multi-party approval mechanism for upgrades?
• Has the upgrade policy been tightened from the default compatible?
• Is make_immutable() called in init() for packages that should never upgrade?

Key Questions (Must Answer All)

1. UpgradeCap security: Who holds it? What is the attack surface if compromised?
2. Upgrade policy: Is the policy appropriate? Could it be tightened without losing needed functionality?
3. Cross-version bypass: Can old functions bypass security checks added in new versions?
4. Version guard: Is there a mechanism to disable old functions after upgrade?
5. Type compatibility: Are all types compatible? Are dynamic fields accessible across versions?

Common False Positives

1. Immutable package: UpgradeCap destroyed or make_immutable called -> no upgrade risk
2. No shared objects: If old and new packages share no objects, cross-version interaction impossible
3. Version guard implemented: Shared objects check version field, old functions abort after migration
4. Capability migrated: Old package's capabilities consumed by new package, old functions uncallable
5. additive or dep_only policy: Existing logic frozen (but new functions can still access shared objects -- check Step 3c)

Output Schema

## Finding [PV-N]: Title

**Verdict**: CONFIRMED / PARTIAL / REFUTED / CONTESTED
**Step Execution**: check1,2,3,4,5,6 | skip(reason) | uncertain
**Rules Applied**: [R4:___, R8:___, R9:___, R10:___]
**Severity**: Critical/High/Medium/Low/Info
**Location**: sources/{module}.move:LineN

**Upgrade Risk Type**: UPGRADECAP_MANAGEMENT / POLICY_INAPPROPRIATE / CROSS_VERSION_BYPASS / TYPE_INCOMPATIBILITY / DEPENDENCY_RISK / MISSING_VERSION_GUARD
**Package Version**: V{N} -> V{N+1}
**Shared Objects Affected**: {list}

**Description**: What is wrong
**Impact**: What can happen (logic replacement, security bypass, stranded assets, type mismatch)
**Evidence**: Code showing vulnerability
**Recommendation**: How to fix (tighten policy, add version guard, migrate capabilities, destroy UpgradeCap)

Step Execution Checklist (MANDATORY)

Cross-Reference Markers

After Step 1: If UpgradeCap held by single address -> immediate finding (minimum HIGH).

After Step 2: If cross-version bypass possible -> cross-reference with MIGRATION_ANALYSIS Step 5 for shared object function enumeration.

After Step 3: Feed dependency risks to DEPENDENCY_AUDIT for transitive dependency analysis.

After Step 5: If no version guard AND shared objects hold user funds -> minimum HIGH finding.

If any step skipped, document valid reason (N/A, package is immutable, no shared objects, no third-party dependencies).