Module sui::package
Functions for operating on Move packages from within Move:
-
Creating proof-of-publish objects from one-time witnesses
-
Administering package upgrades through upgrade policies.
use std::address;
use std::ascii;
use std::bcs;
use std::option;
use std::string;
use std::type_name;
use std::vector;
use sui::address;
use sui::hex;
use sui::object;
use sui::transfer;
use sui::tx_context;
use sui::types;
Struct Publisher
This type can only be created in the transaction that generates a module, by consuming its one-time witness, so it can be used to identify the address that published the package a type originated from.
public struct Publisher has key, store
Fields
- id: sui::object::UID
- package: std::ascii::String
- module_name: std::ascii::String
Struct UpgradeCap
Capability controlling the ability to upgrade a package.
public struct UpgradeCap has key, store
Fields
- id: sui::object::UID
- package: sui::object::ID
- (Mutable) ID of the package that can be upgraded.
- version: u64
- (Mutable) The number of upgrades that have been applied successively to the original package. Initially 0.
- policy: u8
- What kind of upgrades are allowed.
Struct UpgradeTicket
Permission to perform a particular upgrade (for a fixed version of the package, bytecode to upgrade with and transitive dependencies to depend against).
An UpgradeCap can only issue one ticket at a time, to prevent races between concurrent updates or a change in its upgrade policy after issuing a ticket, so the ticket is a "Hot Potato" to preserve forward progress.
public struct UpgradeTicket
Fields
- cap: sui::object::ID
- (Immutable) ID of the UpgradeCap this originated from.
- package: sui::object::ID
- (Immutable) ID of the package that can be upgraded.
- policy: u8
- (Immutable) The policy regarding what kind of upgrade this ticket permits.
- digest: vector<u8>
- (Immutable) SHA256 digest of the bytecode and transitive dependencies that will be used in the upgrade.
Struct UpgradeReceipt
Issued as a result of a successful upgrade, containing the information to be used to update the UpgradeCap. This is a "Hot Potato" to ensure that it is used to update its UpgradeCap before the end of the transaction that performed the upgrade.
public struct UpgradeReceipt
Fields
- cap: sui::object::ID
- (Immutable) ID of the UpgradeCap this originated from.
- package: sui::object::ID
- (Immutable) ID of the package after it was upgraded.
Constants
Tried to create a Publisher using a type that isn't a one-time witness.
const ENotOneTimeWitness: u64 = 0;
Tried to set a less restrictive policy than currently in place.
const ETooPermissive: u64 = 1;
This UpgradeCap has already authorized a pending upgrade.
const EAlreadyAuthorized: u64 = 2;
This UpgradeCap has not authorized an upgrade.
const ENotAuthorized: u64 = 3;
Trying to commit an upgrade to the wrong UpgradeCap.
const EWrongUpgradeCap: u64 = 4;
Update any part of the package (function implementations, add new functions or types, change dependencies)
const COMPATIBLE: u8 = 0;
Add new functions or types, or change dependencies, existing functions can't change.
const ADDITIVE: u8 = 128;
Only be able to change dependencies.
const DEP_ONLY: u8 = 192;
Function claim
Claim a Publisher object. Requires a One-Time-Witness to prove ownership. Due to this constraint there can be only one Publisher object per module but multiple per package (!).
public fun claim<OTW: drop>(otw: OTW, ctx: &mut sui::tx_context::TxContext): sui::package::Publisher
Implementation
public fun claim<OTW: drop>(otw: OTW, ctx: &mut TxContext): Publisher {
assert!(types::is_one_time_witness(&otw), ENotOneTimeWitness);
let type_name = type_name::get_with_original_ids<OTW>();
Publisher {
id: object::new(ctx),
package: type_name.get_address(),
module_name: type_name.get_module(),
}
}
Function claim_and_keep
Claim a Publisher object and send it to transaction sender. Since this function can only be called in the module initializer, the sender is the publisher.
public fun claim_and_keep<OTW: drop>(otw: OTW, ctx: &mut sui::tx_context::TxContext)
Implementation
public fun claim_and_keep<OTW: drop>(otw: OTW, ctx: &mut TxContext) {
sui::transfer::public_transfer(claim(otw, ctx), ctx.sender())
}
Function burn_publisher
Destroy a Publisher object effectively removing all privileges associated with it.
public fun burn_publisher(self: sui::package::Publisher)
Implementation
public fun burn_publisher(self: Publisher) {
let Publisher { id, package: _, module_name: _ } = self;
id.delete();
}
Function from_package
Check whether type belongs to the same package as the publisher object.
public fun from_package<T>(self: &sui::package::Publisher): bool
Implementation
public fun from_package<T>(self: &Publisher): bool {
type_name::get_with_original_ids<T>().get_address() == self.package
}
Function from_module
Check whether a type belongs to the same module as the publisher object.
public fun from_module<T>(self: &sui::package::Publisher): bool
Implementation
public fun from_module<T>(self: &Publisher): bool {
let type_name = type_name::get_with_original_ids<T>();
(type_name.get_address() == self.package) && (type_name.get_module() == self.module_name)
}
Function published_module
Read the name of the module.
public fun published_module(self: &sui::package::Publisher): &std::ascii::String
Implementation
public fun published_module(self: &Publisher): &String {
&self.module_name
}
Function published_package
Read the package address string.
public fun published_package(self: &sui::package::Publisher): &std::ascii::String
Implementation
public fun published_package(self: &Publisher): &String {
&self.package
}