In the rapid evolution of blockchain technology, the Move programming language stands out for its security, flexibility, and auditability.
One of its core strengths is the refined management of smart contract packages.

This article dives deep into the sui::package module — the engine behind publishing, upgrading, and maintaining Move packages on the Sui blockchain.

---

🔍 Module Overview

sui::package is a cornerstone in the Move ecosystem. It provides developers with robust tools and interfaces to manage packages securely and efficiently.

📦 Declaration & Imports

module sui::package;

use std::ascii::String;
use std::type_name;
use sui::types;

This defines the module and brings in essential Move standard libraries and Sui-native modules for complex logic.

---

🧩 Core Structures & Public Interfaces

1. Publisher

Handles the publisher identity of a package.

Key functions:

• claim
• claim_and_keep
• burn_publisher

---

2. UpgradeCap

Controls a package’s upgrade capability.

Key fields:

• package_id
• version
• policy (upgrade policy)

Key functions:

• upgrade_package
• restrict

---

3. UpgradeTicket

Grants permission for a specific upgrade.

Key functions:

• ticket_package
• ticket_policy
• ticket_digest

---

4. UpgradeReceipt

Issued after a successful upgrade.

Key functions:

• receipt_cap
• receipt_package

---

🚨 Error Constants

Helps developers debug with clarity.

• ENotOneTimeWitness: The one-time witness is invalid
• ETooPermissive: Upgrade policy is too lenient
• EInvalidPackage: The package provided is invalid

---

🔒 Upgrade Strategy Constants

Controls how packages may evolve:

• COMPATIBLE: Backward-compatible upgrades
• ADDITIVE: Add new features, but don't change/delete existing ones
• DEP_ONLY: Only dependency changes allowed

These constants enforce safe and controlled upgrades.

---

🧱 Structure Definitions

Publisher

• package address: Uniquely identifies the publisher
• module name: The publisher’s module namespace

---

UpgradeCap

• package ID: The target package
• version: Current version
• policy: Upgrade policy applied

---

UpgradeTicket

• upgrade_cap_id: Link to the controlling UpgradeCap
• package_id: Target package
• policy: Upgrade policy used
• digest: Bytecode summary (vector of bytes)

---

UpgradeReceipt

• upgrade_cap_id: Controller identity
• package_id: The upgraded package

---

🧠 Core Function Definitions

claim

fun claim(otw: &OneTimeWitness) -> Publisher;

Claims a publisher identity using a one-time witness (OTW). Ensures uniqueness and trust.

---

claim_and_keep

fun claim_and_keep(otw: &OneTimeWitness) -> Publisher;

Similar to claim, but sends the Publisher object to the caller’s account.

---

burn_publisher

fun burn_publisher(publisher: &mut Publisher);

Destroys a publisher identity and all associated privileges.

---

authorize_upgrade

fun authorize_upgrade(cap: &UpgradeCap, package_id: &PackageID, policy: u8, digest: &vector<u8>) -> UpgradeTicket {
    assert!(cap.package_id == *package_id, EInvalidPackage);
    assert!(cap.policy <= policy, ETooPermissive);
    UpgradeTicket {
        upgrade_cap_id: cap.id(),
        package_id: *package_id,
        policy: policy,
        digest: digest.clone()
    }
}

Validates:

• That UpgradeCap matches the package_id
• The policy is not more permissive than allowed
  Then returns a signed UpgradeTicket.

---

upgrade_package

fun upgrade_package(ticket: &UpgradeTicket, data: &vector<u8>) -> UpgradeReceipt {
    // Upgrade logic
}

• Verifies UpgradeTicket
• Replaces the current package code with the new bytecode (data)
• Returns a UpgradeReceipt as proof of successful upgrade

---

restrict

fun restrict(cap: &mut UpgradeCap, policy: u8) {
    assert!(cap.policy < policy, ETooPermissive);
    cap.policy = policy;
}

Used to tighten upgrade permissions.
Cannot downgrade to a more permissive policy.

---

🛡️ Security & Auditing Features

sui::package is designed with security and auditability in mind:

• One-time witness (OTW): Prevents impersonation in publishing
• Upgrade policy constants: Prevent unauthorized or breaking upgrades
• Assertions: Built-in guards to prevent misuse or unexpected logic

---

🧪 Testing & Simulation Support

The module includes test-only functions that are gated to dev/test environments:

• TestOnly: Marks test-only logic
• publish: Simulates publishing in tests
• upgrade: Simulates upgrading in tests

---

✅ Summary

The sui::package module gives Move developers a powerful, structured, and secure system to:

• Publish packages
• Authorize and execute upgrades
• Manage upgrade capabilities and policies

It ensures trust, flexibility, and maintainability in smart contract development on Sui.

With modules like sui::package, the Move language continues to show its strength in modular design, security-first architecture, and developer ergonomics — paving the way for scalable, secure Web3 systems.