package-version-safety

name	package-version-safety
description	Trigger Pattern PACKAGE_UPGRADE flag (UpgradeCap detected, multiple package versions, upgrade policy references) - Inject Into Breadth agents, depth-external

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:

#	Package	UpgradeCap Location	UpgradeCap Holder	Has store?	Upgrade Policy	Destroyed?
1	{pkg_name}	{init function:line}	{address / shared / wrapped in governance}	YES/NO	{compatible/additive/dep_only}	YES (immutable) / NO

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

Governance Model	Risk Level	Assessment
Single EOA	CRITICAL	One key compromise replaces all package logic
Multisig (2/3 or lower)	HIGH	Low collusion threshold
Multisig (3/5+)	MEDIUM	Requires majority collusion
Multisig + timelock	LOW	Users can exit before malicious upgrade takes effect
DAO/governance contract	LOW	Distributed control, but check voter distribution
Destroyed (immutable)	NONE	Cannot upgrade, but also cannot patch bugs

---

Step 2: Version Consistency Check

For shared objects created by this package:

Shared Object	Created By (Version)	Current Version Field?	V1 Functions Access?	V2 Functions Access?	Consistency Risk
{obj_type}	V1 init()	YES: version: u64 / NO	{list funcs}	{list funcs}	{describe}

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:

Dependency	Source	Pinned To	Immutable?	Upgrade Risk
Sui Framework	sui = "..."	{git rev or latest}	Upgraded by validators	Framework upgrade could change behavior
MoveStdlib	MoveStdlib = "..."	{git rev}	Upgraded with framework	Same as above
{third_party}	{git url or on-chain}	{specific rev / branch / on-chain version}	YES/NO	{describe}

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:

Type	V1 Definition	V2 Changes	Compatible Upgrade Rule	Migration Needed?
{struct_name}	{fields}	{cannot change for compatible}	Struct layouts FROZEN	NO -- same layout
{new_struct}	N/A	{new in V2}	New types allowed	N/A

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?

Migration Function	Trigger	What It Updates	Reversible?	Access Control
{migrate_func}	{admin call / automatic}	{version field, new state}	NO	{AdminCap / anyone}

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:

Risk	Description	Severity
Full logic replacement	Attacker upgrades package with malicious code. All shared objects now interact with attacker's logic.	CRITICAL
Subtle parameter change	Attacker upgrades to change a fee calculation or threshold in function body. Hard to detect.	HIGH
Dependency manipulation	Attacker upgrades to change dependency versions, pulling in vulnerable code.	HIGH
Policy escalation blocked	Upgrade policies can only be tightened (compatible -> additive -> dep_only -> immutable). Attacker cannot escalate from additive to compatible.	Mitigation

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)

Step	Required	Completed?	Notes
1. Upgrade Policy Inventory	YES		UpgradeCap location, holder, policy
1b. UpgradeCap Governance Assessment	YES		Risk level for each package
2. Version Consistency Check	YES		All shared objects checked for dual-version access
3. Dependency Version Pinning	YES		Move.toml analyzed
4. Type Compatibility Across Versions	YES		Dynamic fields included
5. Upgrade Migration Safety	YES		Version guard pattern checked
6. UpgradeCap Governance	IF single-address holder		Multisig/timelock/approval checks

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).