llms.txt
Skip to main content

Publisher Authority

Applications often need to prove who published a type. This is especially important in the context of digital assets, where the publisher may enable or disable certain features for their assets. The Publisher object, defined in the Sui Framework, is what allows the publisher to prove their authority over a type.

Definition​

The Publisher object is defined in the sui::package module of the Sui Framework. It is a very simple, non-generic object that can be initialized once per module (and multiple times per package) and is used to prove the authority of the publisher over a type. To claim a Publisher object, the publisher must present a One Time Witness to the package::claim function.

module sui::package;

public struct Publisher has key, store {
    id: UID,
    package: String,
    module_name: String,
}

Here's a simple example of claiming a Publisher object in a module:

module book::publisher;

use sui::package::{Self, Publisher};

/// Some type defined in the module.
public struct Book {}

/// The OTW for the module.
public struct PUBLISHER has drop {}

/// Uses the One Time Witness to claim the Publisher object.
fun init(otw: PUBLISHER, ctx: &mut TxContext) {
    // Claim the Publisher object.
    let publisher: Publisher = sui::package::claim(otw, ctx);

    // Usually it is transferred to the sender.
    // It can also be stored in another object.
    transfer::public_transfer(publisher, ctx.sender())
}

For the common claim-and-transfer flow, the sui::package module also provides a shorthand - package::claim_and_keep - which claims the Publisher object and transfers it to the sender in one call.

Usage​

The Publisher object has two functions associated with it - from_module and from_package - which check whether a type was defined in the module or package this Publisher stands for:

// Checks if the type is from the same module, hence the `Publisher` has the
// authority over it.
assert!(publisher.from_module<Book>());

// Checks if the type is from the same package, hence the `Publisher` has the
// authority over it.
assert!(publisher.from_package<Book>());

Publisher as Admin Role​

For small applications or simple use cases, the Publisher object can be used as an admin capability. While in the broader context, the Publisher object has control over system configurations, it can also be used to manage the application's state.

/// Some action in the application gated by the Publisher object.
public fun admin_action(cap: &Publisher, /* app objects... */ param: u64) {
    assert!(cap.from_module<Book>(), ENotAuthorized);

    // perform application-specific action
}

However, the Publisher object lacks some of the native properties of Capabilities, such as type safety and expressiveness. The signature of admin_action says nothing about the required authority - the function can be called by anyone holding any Publisher object, so the authorization must be checked inside the function body. And since every published package produces a Publisher, forgetting the from_module check opens the action to every publisher on the network. For these reasons, it is important to be cautious when using the Publisher object as an admin role.

Role on Sui​

Publisher is required for certain features on Sui. Object Display can be created with the Publisher when it is set up outside of the module defining the type, and TransferPolicy - an important component of the Kiosk system - also requires the Publisher object to prove ownership of the type.

Next Steps​

In the next section we will cover the first feature that can use the Publisher object - Object Display - a way to describe objects for clients, and standardize metadata. A must-have for user-friendly applications.

llms.txt