Decode Sui Kiosk

Overview

Key Components

1. Kiosk Core

• Shared Object: The kiosk itself is a shared on-chain object that can store digital items using dynamic fields. It holds the assets, listings, and even “lock” markers that prevent unauthorized withdrawals.

• Owner Capability: Only the party holding the corresponding KioskOwnerCap has administrative rights. This capability allows the owner to add or remove items, list them for sale (or even list exclusively with a purchase cap), and withdraw any profits generated from sales.

• Item Management: Before listing, an item is first placed into the kiosk. The system then uses dynamic fields to register the item, track its status (e.g., listed, locked), and manage its lifecycle from deposit to sale or withdrawal.

2. Transfer Policy

• Custom Trade Enforcement: Every sale initiated through a kiosk goes through a TransferPolicy. This policy is defined by the item creator (typically the package deployer) and enforces custom rules such as royalties.

• Transfer Request: When a buyer purchases an item, a TransferRequest is generated. This “hot potato” must accumulate the necessary receipts—each corresponding to a rule defined in the TransferPolicy—before the sale can be finalized.

• Policy Management: A creator can attach or remove rules using a matching capability (the TransferPolicyCap), which ensures that each transaction complies with the creator’s requirements before ownership changes hands.

3. Kiosk Extensions

• Enhanced Functionality: Kiosk Extensions allow third-party modules to extend the kiosk’s functionality beyond what the basic owner controls provide. For example, they can enable features such as NFT rental.

• Controlled Access: Extensions are added via a dynamic field using a specific witness type. They include permission bitmaps that control which actions the extension can perform—such as placing or locking items.

• Modular Operations: With extensions, modules can execute operations (like placing an item on behalf of the owner) or interact with the kiosk’s storage without compromising the security or the core invariants of the kiosk system.

How They Work Together

• Secure Asset Management: The kiosk ensures that items are safely stored, listed, and managed, with the KioskOwnerCap granting exclusive control to the owner.

• Enforced Trade Rules: The TransferPolicy guarantees that each sale complies with predetermined rules (e.g., royalty payments), protecting the interests of creators.

• Flexible Extensions: Kiosk Extensions provide a mechanism for building advanced features (like NFT rentals) on top of the basic kiosk, offering additional flexibility and functionality without altering the core protocol.

Architecture

Kiosk

Create Kiosk

1. Kiosk
• kiosk is an intermediary object used to manage object exchange.
• Objects can be transferred into kiosk, and kiosk module exposes functions to manage objects insides.
• kiosk supports functionality like item list and purchase.
• kiosk is shared.

2. KioskOwnerCap
• KioskOwnerCap represents ownership of certain kiosk. Only KioskOwnerCap owner can execute certain actions, like object listing and removal.

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Creates a new Kiosk in a default configuration: sender receives the
/// `KioskOwnerCap` and becomes the Owner, the `Kiosk` is shared.
entry fun default(ctx: &mut TxContext) {
    let (kiosk, cap) = new(ctx);
    sui::transfer::transfer(cap, ctx.sender());
    sui::transfer::share_object(kiosk);
}

/// Creates a new `Kiosk` with a matching `KioskOwnerCap`.
public fun new(ctx: &mut TxContext): (Kiosk, KioskOwnerCap) {
    let kiosk = Kiosk {
        id: object::new(ctx),
        profits: balance::zero(),
        owner: ctx.sender(),
        item_count: 0,
        allow_extensions: false,
    };

    let cap = KioskOwnerCap {
        id: object::new(ctx),
        `for`: object::id(&kiosk),
    };

    (kiosk, cap)
}

/// An object which allows selling collectibles within "kiosk" ecosystem.
/// By default gives the functionality to list an item openly - for anyone
/// to purchase providing the guarantees for creators that every transfer
/// needs to be approved via the `TransferPolicy`.
public struct Kiosk has key, store {
    id: UID,
    /// Balance of the Kiosk - all profits from sales go here.
    profits: Balance<SUI>,
    /// Always point to `sender` of the transaction.
    /// Can be changed by calling `set_owner` with Cap.
    owner: address,
    /// Number of items stored in a Kiosk. Used to allow unpacking
    /// an empty Kiosk if it was wrapped or has a single owner.
    item_count: u32,
    /// [DEPRECATED] Please, don't use the `allow_extensions` and the matching
    /// `set_allow_extensions` function - it is a legacy feature that is being
    /// replaced by the `kiosk_extension` module and its Extensions API.
    ///
    /// Exposes `uid_mut` publicly when set to `true`, set to `false` by default.
    allow_extensions: bool,
}

/// A Capability granting the bearer a right to `place` and `take` items
/// from the `Kiosk` as well as to `list` them and `list_with_purchase_cap`.
public struct KioskOwnerCap has key, store {
    id: UID,
    `for`: ID,
}

Place Item into Kiosk

1. call has_access to check tx sender owns kiosk’s corresponding KioskOwnerCap.

2. call Kiosk.place_internal to transfer item into kiosk.
1. Kiosk.place_internal updates item count in kiosk and transfers item into kiosk using dynamic object field.

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

use sui::dynamic_object_field as dof;

/// Place any object into a Kiosk.
/// Performs an authorization check to make sure only owner can do that.
public fun place<T: key + store>(self: &mut Kiosk, cap: &KioskOwnerCap, item: T) {
    assert!(self.has_access(cap), ENotOwner);
    self.place_internal(item)
}

/// Check whether the `KioskOwnerCap` matches the `Kiosk`.
public fun has_access(self: &mut Kiosk, cap: &KioskOwnerCap): bool {
    object::id(self) == cap.`for`
}

/// Dynamic field key for an item placed into the kiosk.
public struct Item has store, copy, drop { id: ID }

/// Internal: "place" an item to the Kiosk and increment the item count.
public(package) fun place_internal<T: key + store>(self: &mut Kiosk, item: T) {
    self.item_count = self.item_count + 1;
    dof::add(&mut self.id, Item { id: object::id(&item) }, item)
}

List

List Normally

1. call has_access to check tx sender owns kiosk’s corresponding KioskOwnerCap.

2. call Kiosk.has_item_with_type<T> to check kiosk manages the item identified by id.

3. call Kiosk.is_listed_exclusively to check whether the item has already been listed exclusively. Item listed exclusively can’t be listed normally. Otherwise the exclusively listing is is meaningless.

4. add a dynamic field Listing into kiosk which records the listing price measured in SUI.

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// List the item by setting a price and making it available for purchase.
/// Performs an authorization check to make sure only owner can sell.
public fun list<T: key + store>(self: &mut Kiosk, cap: &KioskOwnerCap, id: ID, price: u64) {
    assert!(self.has_access(cap), ENotOwner);
    assert!(self.has_item_with_type<T>(id), EItemNotFound);
    assert!(!self.is_listed_exclusively(id), EListedExclusively);

    df::add(&mut self.id, Listing { id, is_exclusive: false }, price);
    event::emit(ItemListed<T> { kiosk: object::id(self), id, price })
}

/// Dynamic field key for an active offer to purchase the T. If an
/// item is listed without a `PurchaseCap`, exclusive is set to `false`.
public struct Listing has store, copy, drop { id: ID, is_exclusive: bool }

/// Check whether the `item` is present in the `Kiosk` and has type T.
public fun has_item_with_type<T: key + store>(self: &Kiosk, id: ID): bool {
    dof::exists_with_type<Item, T>(&self.id, Item { id })
}

/// Check whether there's a `PurchaseCap` issued for an item.
public fun is_listed_exclusively(self: &Kiosk, id: ID): bool {
    df::exists_(&self.id, Listing { id, is_exclusive: true })
}

/// Emitted when an item was listed by the safe owner. Can be used
/// to track available offers anywhere on the network; the event is
/// type-indexed which allows for searching for offers of a specific `T`
public struct ItemListed<phantom T: key + store> has copy, drop {
    kiosk: ID,
    id: ID,
    price: u64,
}

Place and List Item

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Calls `place` and `list` together - simplifies the flow.
public fun place_and_list<T: key + store>(
    self: &mut Kiosk,
    cap: &KioskOwnerCap,
    item: T,
    price: u64,
) {
    let id = object::id(&item);
    self.place(cap, item);
    self.list<T>(cap, id, price)
}

List Exclusively

1. call has_access to check tx sender owns kiosk’s corresponding KioskOwnerCap.

2. call Kiosk.has_item_with_type<T> to check kiosk manages the item identified by id.

3. call Kiosk.is_listed to check kiosk hasn’t been listed normally or exclusively before.
1. an item listed before can’t be listed exclusively
2. an item can only be listed exclusively once at the same time.

4. adds a dynamic field Listing to kiosk marks the item has been listed exclusively.

5. creates object PurchaseCap represents the authority to purchase this item listed exclusively.

1. cancelled by the PurchaseCap owner using function sui::kiosk::return_purchase_cap to return the PurchaseCap back

2. purchased by PurchaseCap owner using function sui::kiosk::purchase_with_cap

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

// === Trading Functionality: Exclusive listing with `PurchaseCap` ===

/// Creates a `PurchaseCap` which gives the right to purchase an item
/// for any price equal or higher than the `min_price`.
public fun list_with_purchase_cap<T: key + store>(
    self: &mut Kiosk,
    cap: &KioskOwnerCap,
    id: ID,
    min_price: u64,
    ctx: &mut TxContext,
): PurchaseCap<T> {
    assert!(self.has_access(cap), ENotOwner);
    assert!(self.has_item_with_type<T>(id), EItemNotFound);
    assert!(!self.is_listed(id), EAlreadyListed);

    df::add(&mut self.id, Listing { id, is_exclusive: true }, min_price);

    PurchaseCap<T> {
        min_price,
        item_id: id,
        id: object::new(ctx),
        kiosk_id: object::id(self),
    }
}

/// A capability which locks an item and gives a permission to
/// purchase it from a `Kiosk` for any price no less than `min_price`.
///
/// Allows exclusive listing: only bearer of the `PurchaseCap` can
/// purchase the asset. However, the capability should be used
/// carefully as losing it would lock the asset in the `Kiosk`.
///
/// The main application for the `PurchaseCap` is building extensions
/// on top of the `Kiosk`.
public struct PurchaseCap<phantom T: key + store> has key, store {
    id: UID,
    /// ID of the `Kiosk` the cap belongs to.
    kiosk_id: ID,
    /// ID of the listed item.
    item_id: ID,
    /// Minimum price for which the item can be purchased.
    min_price: u64,
}

/// Check whether an `item` is listed (exclusively or non exclusively).
public fun is_listed(self: &Kiosk, id: ID): bool {
    df::exists_(&self.id, Listing { id, is_exclusive: false })
        || self.is_listed_exclusively(id)
}

Delist

1. call has_access to check tx sender owns kiosk’s corresponding KioskOwnerCap.

2. call Kiosk.has_item_with_type to check the item is managed by kiosk.

3. call Kiosk.is_listed_exclusively to check item is not listed exclusively.

4. call Kiosk.is_listed to check item is listed.

5. remove Listing

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Remove an existing listing from the `Kiosk` and keep the item in the
/// user Kiosk. Can only be performed by the owner of the `Kiosk`.
public fun delist<T: key + store>(self: &mut Kiosk, cap: &KioskOwnerCap, id: ID) {
    assert!(self.has_access(cap), ENotOwner);
    assert!(self.has_item_with_type<T>(id), EItemNotFound);
    assert!(!self.is_listed_exclusively(id), EListedExclusively);
    assert!(self.is_listed(id), ENotListed);

    df::remove<Listing, u64>(&mut self.id, Listing { id, is_exclusive: false });
    event::emit(ItemDelisted<T> { kiosk: object::id(self), id })
}

Purchase

Purchase Normally

1. kiosk
kiosk manages the item.

2. id
ID of the item managed by the kiosk to purchase

3. payment
enough SUI token to purcahse the item.

1. remove Listing record and get price value

2. take item out kiosk

3. update item count in kiosk

4. check price equals payment from buyer

5. remove Lock record

6. return item and transfer request
1. TransferRequest is a hot potato should be handled properly. It records information of this transfer action. This is used to enforce custom rules defined by the item creator, like royalty.

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Make a trade: pay the owner of the item and request a Transfer to the `target`
/// kiosk (to prevent item being taken by the approving party).
///
/// Received `TransferRequest` needs to be handled by the publisher of the T,
/// if they have a method implemented that allows a trade, it is possible to
/// request their approval (by calling some function) so that the trade can be
/// finalized.
public fun purchase<T: key + store>(
    self: &mut Kiosk,
    id: ID,
    payment: Coin<SUI>,
): (T, TransferRequest<T>) {
    let price = df::remove<Listing, u64>(&mut self.id, Listing { id, is_exclusive: false });
    let inner = dof::remove<Item, T>(&mut self.id, Item { id });

    self.item_count = self.item_count - 1;
    assert!(price == payment.value(), EIncorrectAmount);
    df::remove_if_exists<Lock, bool>(&mut self.id, Lock { id });
    coin::put(&mut self.profits, payment);

    event::emit(ItemPurchased<T> { kiosk: object::id(self), id, price });

    (inner, transfer_policy::new_request(id, price, object::id(self)))
}

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/transfer_policy.move ---

/// Construct a new `TransferRequest` hot potato which requires an
/// approving action from the creator to be destroyed / resolved. Once
/// created, it must be confirmed in the `confirm_request` call otherwise
/// the transaction will fail.
public fun new_request<T>(item: ID, paid: u64, from: ID): TransferRequest<T> {
    TransferRequest { item, paid, from, receipts: vec_set::empty() }
}

/// A "Hot Potato" forcing the buyer to get a transfer permission
/// from the item type (`T`) owner on purchase attempt.
public struct TransferRequest<phantom T> {
    /// The ID of the transferred item. Although the `T` has no
    /// constraints, the main use case for this module is to work
    /// with Objects.
    item: ID,
    /// Amount of SUI paid for the item. Can be used to
    /// calculate the fee / transfer policy enforcement.
    paid: u64,
    /// The ID of the Kiosk / Safe the object is being sold from.
    /// Can be used by the TransferPolicy implementors.
    from: ID,
    /// Collected Receipts. Used to verify that all of the rules
    /// were followed and `TransferRequest` can be confirmed.
    receipts: VecSet<TypeName>,
}

Purchase Exclusively Listed Item

1. unpack PurchaseCap to delete it and retrieve related information, like item id, kiosk id and minimal price.

2. check payment from buyer is higher than price recorded minimal price required by seller

3. check passed-in kiosk is the one the PurchaseCap refers to

4. remove item Listing in kiosk

5. add the payment from buyer to profits of the kiosk

6. update item count in kiosk

7. remove Lock record in kiosk if exsits

8. take item out kiosk

9. returns item and creates a TransferRequest should be handled in this tx

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Unpack the `PurchaseCap` and call `purchase`. Sets the payment amount
/// as the price for the listing making sure it's no less than `min_amount`.
public fun purchase_with_cap<T: key + store>(
    self: &mut Kiosk,
    purchase_cap: PurchaseCap<T>,
    payment: Coin<SUI>,
): (T, TransferRequest<T>) {
    let PurchaseCap { id, item_id, kiosk_id, min_price } = purchase_cap;
    id.delete();

    let id = item_id;
    let paid = payment.value();
    assert!(paid >= min_price, EIncorrectAmount);
    assert!(object::id(self) == kiosk_id, EWrongKiosk);

    df::remove<Listing, u64>(&mut self.id, Listing { id, is_exclusive: true });

    coin::put(&mut self.profits, payment);
    self.item_count = self.item_count - 1;
    df::remove_if_exists<Lock, bool>(&mut self.id, Lock { id });
    let item = dof::remove<Item, T>(&mut self.id, Item { id });

    (item, transfer_policy::new_request(id, paid, object::id(self)))
}

Lock Item

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Place an item to the `Kiosk` and issue a `Lock` for it. Once placed this
/// way, an item can only be listed either with a `list` function or with a
/// `list_with_purchase_cap`.
///
/// Requires policy for `T` to make sure that there's an issued `TransferPolicy`
/// and the item can be sold, otherwise the asset might be locked forever.
public fun lock<T: key + store>(
    self: &mut Kiosk,
    cap: &KioskOwnerCap,
    _policy: &TransferPolicy<T>,
    item: T,
) {
    assert!(self.has_access(cap), ENotOwner);
    self.lock_internal(item)
}

/// Internal: "lock" an item disabling the `take` action.
public(package) fun lock_internal<T: key + store>(self: &mut Kiosk, item: T) {
    df::add(&mut self.id, Lock { id: object::id(&item) }, true);
    self.place_internal(item)
}

Take Item

1. call has_access to check tx sender owns kiosk’s corresponding KioskOwnerCap.

2. call Kiosk.is_locked to check item is not locked.

3. call Kiosk.is_listed_exclusively to check item is not listed exclusively.

4. call Kiosk.has_item to check item is stored in the kiosk.

5. update item count in kiosk

6. remove Listing if it exists

7. take item out kiosk

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Take any object from the Kiosk.
/// Performs an authorization check to make sure only owner can do that.
public fun take<T: key + store>(self: &mut Kiosk, cap: &KioskOwnerCap, id: ID): T {
    assert!(self.has_access(cap), ENotOwner);
    assert!(!self.is_locked(id), EItemLocked);
    assert!(!self.is_listed_exclusively(id), EListedExclusively);
    assert!(self.has_item(id), EItemNotFound);

    self.item_count = self.item_count - 1;
    df::remove_if_exists<Listing, u64>(&mut self.id, Listing { id, is_exclusive: false });
    dof::remove(&mut self.id, Item { id })
}

/// Check whether the `item` is present in the `Kiosk`.
public fun has_item(self: &Kiosk, id: ID): bool {
    dof::exists_(&self.id, Item { id })
}

Return Purchase Cap

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Return the `PurchaseCap` without making a purchase; remove an active offer and
/// allow the item for taking. Can only be returned to its `Kiosk`, aborts otherwise.
public fun return_purchase_cap<T: key + store>(self: &mut Kiosk, purchase_cap: PurchaseCap<T>) {
    let PurchaseCap { id, item_id, kiosk_id, min_price: _ } = purchase_cap;

    assert!(object::id(self) == kiosk_id, EWrongKiosk);
    df::remove<Listing, u64>(&mut self.id, Listing { id: item_id, is_exclusive: true });
    id.delete()
}

Withdraw

Withdraw

1. call has_access to check tx sender owns kiosk’s corresponding KioskOwnerCap.

2. determine amount of profit to withdraw

3. take profit from kiosk.profits and return

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Withdraw profits from the Kiosk.
public fun withdraw(
    self: &mut Kiosk,
    cap: &KioskOwnerCap,
    amount: Option<u64>,
    ctx: &mut TxContext,
): Coin<SUI> {
    assert!(self.has_access(cap), ENotOwner);

    let amount = if (amount.is_some()) {
        let amt = amount.destroy_some();
        assert!(amt <= self.profits.value(), ENotEnough);
        amt
    } else {
        self.profits.value()
    };

    coin::take(&mut self.profits, amount, ctx)
}

Close and Withdraw

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Unpacks and destroys a Kiosk returning the profits (even if "0").
/// Can only be performed by the bearer of the `KioskOwnerCap` in the
/// case where there's no items inside and a `Kiosk` is not shared.
public fun close_and_withdraw(self: Kiosk, cap: KioskOwnerCap, ctx: &mut TxContext): Coin<SUI> {
    let Kiosk { id, profits, owner: _, item_count, allow_extensions: _ } = self;
    let KioskOwnerCap { id: cap_id, `for` } = cap;

    assert!(id.to_inner() == `for`, ENotOwner);
    assert!(item_count == 0, ENotEmpty);

    cap_id.delete();
    id.delete();

    profits.into_coin(ctx)
}

Transfer Policy

• TransferPolicy can be used to define custom rules on the sell of item.

• Item’s TransferPolicy can only be created by package deployer where the item is defined.

• There can be multiple TransferPolicy of single item type.

• To confirm transfer request, TransferRequest must gather corresponding receipt of rules defined in the TransferPolicy.

• Only Rule definer(module) can approve the transfer request.

• So item exchange participant needs to submit the TransferRequest to corresponding rule module to check and get receipts.

• Typically, we can define a single module which can define multiple rules, and implement check methods for each rule. This module can call the sui::transfer_policy::add_rule to register rule in the TransferPolicy. So that later TrasnferRequest should go through module’s check to get receipts.

New TransferPolicy

1. tx sender should pass in Publisher.
1. Publisher can only be claimed during package deployment by the package deployer. So it is a proof that the holder manages the package, and creates/defines the item.

2. check type T is defined in package represented by Publisher

3. create TransferPolicy and TransferPolicyCap.
1. TransferPolicy records policies of the item.
2. TransferPolicyCap holder can update TransferPolicy

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/transfer_policy.move ---

/// A unique capability that allows the owner of the `T` to authorize
/// transfers. Can only be created with the `Publisher` object. Although
/// there's no limitation to how many policies can be created, for most
/// of the cases there's no need to create more than one since any of the
/// policies can be used to confirm the `TransferRequest`.
public struct TransferPolicy<phantom T> has key, store {
    id: UID,
    /// The Balance of the `TransferPolicy` which collects `SUI`.
    /// By default, transfer policy does not collect anything , and it's
    /// a matter of an implementation of a specific rule - whether to add
    /// to balance and how much.
    balance: Balance<SUI>,
    /// Set of types of attached rules - used to verify `receipts` when
    /// a `TransferRequest` is received in `confirm_request` function.
    ///
    /// Additionally provides a way to look up currently attached Rules.
    rules: VecSet<TypeName>,
}

/// A Capability granting the owner permission to add/remove rules as well
/// as to `withdraw` and `destroy_and_withdraw` the `TransferPolicy`.
public struct TransferPolicyCap<phantom T> has key, store {
    id: UID,
    policy_id: ID,
}

#[allow(lint(self_transfer, share_owned))]
/// Initialize the Transfer Policy in the default scenario: Create and share
/// the `TransferPolicy`, transfer `TransferPolicyCap` to the transaction
/// sender.
entry fun default<T>(pub: &Publisher, ctx: &mut TxContext) {
    let (policy, cap) = new<T>(pub, ctx);
    sui::transfer::share_object(policy);
    sui::transfer::transfer(cap, ctx.sender());
}

/// Register a type in the Kiosk system and receive a `TransferPolicy` and
/// a `TransferPolicyCap` for the type. The `TransferPolicy` is required to
/// confirm kiosk deals for the `T`. If there's no `TransferPolicy`
/// available for use, the type can not be traded in kiosks.
public fun new<T>(pub: &Publisher, ctx: &mut TxContext): (TransferPolicy<T>, TransferPolicyCap<T>) {
    assert!(package::from_package<T>(pub), 0);
    let id = object::new(ctx);
    let policy_id = id.to_inner();

    event::emit(TransferPolicyCreated<T> { id: policy_id });

    (
        TransferPolicy { id, rules: vec_set::empty(), balance: balance::zero() },
        TransferPolicyCap { id: object::new(ctx), policy_id },
    )
}

/// --- crates/sui-framework/packages/sui-framework/sources/package.move ---

/// 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 {
    id: UID,
    package: String,
    module_name: String,
}

/// 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 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(),
    }
}

/// Check whether type belongs to the same package as the publisher object.
public fun from_package<T>(self: &Publisher): bool {
    type_name::get_with_original_ids<T>().get_address() == self.package
}

Rule

Add Rule

1. check TransferPolicyCap corresponds to the TransferPolicy

2. check there is no such rule before

3. add the rule as a dynamic field of the TransferPolicy with value cfg. (cfg only requires to have store and drop abilities, so the implementation can be flexible.)

4. inserts the rule into TransferPolicy.rules.

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/transfer_policy.move ---

/// Add a custom Rule to the `TransferPolicy`. Once set, `TransferRequest` must
/// receive a confirmation of the rule executed so the hot potato can be unpacked.
///
/// - T: the type to which TransferPolicy<T> is applied.
/// - Rule: the witness type for the Custom rule
/// - Config: a custom configuration for the rule
///
/// Config requires `drop` to allow creators to remove any policy at any moment,
/// even if graceful unpacking has not been implemented in a "rule module".
public fun add_rule<T, Rule: drop, Config: store + drop>(
    _: Rule,
    policy: &mut TransferPolicy<T>,
    cap: &TransferPolicyCap<T>,
    cfg: Config,
) {
    assert!(object::id(policy) == cap.policy_id, ENotOwner);
    assert!(!has_rule<T, Rule>(policy), ERuleAlreadySet);
    df::add(&mut policy.id, RuleKey<Rule> {}, cfg);
    policy.rules.insert(type_name::get<Rule>())
}

/// Key to store "Rule" configuration for a specific `TransferPolicy`.
public struct RuleKey<phantom T: drop> has copy, store, drop {}

/// Check whether a custom rule has been added to the `TransferPolicy`.
public fun has_rule<T, Rule: drop>(policy: &TransferPolicy<T>): bool {
    df::exists_(&policy.id, RuleKey<Rule> {})
}

/// A unique capability that allows the owner of the `T` to authorize
/// transfers. Can only be created with the `Publisher` object. Although
/// there's no limitation to how many policies can be created, for most
/// of the cases there's no need to create more than one since any of the
/// policies can be used to confirm the `TransferRequest`.
public struct TransferPolicy<phantom T> has key, store {
    id: UID,
    /// The Balance of the `TransferPolicy` which collects `SUI`.
    /// By default, transfer policy does not collect anything , and it's
    /// a matter of an implementation of a specific rule - whether to add
    /// to balance and how much.
    balance: Balance<SUI>,
    /// Set of types of attached rules - used to verify `receipts` when
    /// a `TransferRequest` is received in `confirm_request` function.
    ///
    /// Additionally provides a way to look up currently attached Rules.
    rules: VecSet<TypeName>,
}

Remove Rule

/// Remove the Rule from the `TransferPolicy`.
public fun remove_rule<T, Rule: drop, Config: store + drop>(
    policy: &mut TransferPolicy<T>,
    cap: &TransferPolicyCap<T>,
) {
    assert!(object::id(policy) == cap.policy_id, ENotOwner);
    let _: Config = df::remove(&mut policy.id, RuleKey<Rule> {});
    policy.rules.remove(&type_name::get<Rule>());
}

Add Receipt

/// Adds a `Receipt` to the `TransferRequest`, unblocking the request and
/// confirming that the policy requirements are satisfied.
public fun add_receipt<T, Rule: drop>(_: Rule, request: &mut TransferRequest<T>) {
    request.receipts.insert(type_name::get<Rule>())
}

Confirm Transfer Request

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/transfer_policy.move ---

/// Allow a `TransferRequest` for the type `T`. The call is protected
/// by the type constraint, as only the publisher of the `T` can get
/// `TransferPolicy<T>`.
///
/// Note: unless there's a policy for `T` to allow transfers,
/// Kiosk trades will not be possible.
public fun confirm_request<T>(
    self: &TransferPolicy<T>,
    request: TransferRequest<T>,
): (ID, u64, ID) {
    let TransferRequest { item, paid, from, receipts } = request;
    let mut completed = receipts.into_keys();
    let mut total = completed.length();

    assert!(total == self.rules.size(), EPolicyNotSatisfied);

    while (total > 0) {
        let rule_type = completed.pop_back();
        assert!(self.rules.contains(&rule_type), EIllegalRule);
        total = total - 1;
    };

    (item, paid, from)
}

Withdraw

Withdraw

1. check TransferPolicyCap corresponds to the TransferPolicy

2. determine amount of profit to withdraw

3. withdraw profit

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/transfer_policy.move ---

/// Withdraw some amount of profits from the `TransferPolicy`. If amount
/// is not specified, all profits are withdrawn.
public fun withdraw<T>(
    self: &mut TransferPolicy<T>,
    cap: &TransferPolicyCap<T>,
    amount: Option<u64>,
    ctx: &mut TxContext,
): Coin<SUI> {
    assert!(object::id(self) == cap.policy_id, ENotOwner);

    let amount = if (amount.is_some()) {
        let amt = amount.destroy_some();
        assert!(amt <= self.balance.value(), ENotEnough);
        amt
    } else {
        self.balance.value()
    };

    coin::take(&mut self.balance, amount, ctx)
}

Destroy and Withdraw

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/transfer_policy.move ---

/// Destroy a TransferPolicyCap.
/// Can be performed by any party as long as they own it.
public fun destroy_and_withdraw<T>(
    self: TransferPolicy<T>,
    cap: TransferPolicyCap<T>,
    ctx: &mut TxContext,
): Coin<SUI> {
    assert!(object::id(&self) == cap.policy_id, ENotOwner);

    let TransferPolicyCap { id: cap_id, policy_id } = cap;
    let TransferPolicy { id, rules: _, balance } = self;

    id.delete();
    cap_id.delete();
    event::emit(TransferPolicyDestroyed<T> { id: policy_id });
    balance.into_coin(ctx)
}

Kiosk Extension

Key Aspects of Kiosk Extensions

• Modular Flexibility: They let developers build and deploy additional features (such as NFT rental services) without changing the core kiosk logic.

• Controlled Permissions: Each extension comes with a permission bitmap that specifies what actions it can perform (for instance, placing or locking items).

• Secure Interaction: Even though an extension can perform certain operations on behalf of the kiosk owner, strict checks ensure that only authorized extensions can access and modify the kiosk’s state.

• Dynamic Integration: Extensions are added as dynamic fields within the kiosk, which means they can be installed, enabled, disabled, or removed without impacting the core asset management functions.

Add & Remove Extension

Add Extension

• parameter _ext is type of extension (witness owned by module)

• parameter permissions: define permission on the kiosk owned by the extension. It uses bitmap to record permission.

• It adds a dynamic field (ExtensionKey<Ext>, Extension) into kiosk.

• Extension object records permissions and storage of the extension, and whether the extension is currently enabled.

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk_extension.move ---

/// Add an extension to the Kiosk. Can only be performed by the owner. The
/// extension witness is required to allow extensions define their set of
/// permissions in the custom `add` call.
public fun add<Ext: drop>(
    _ext: Ext,
    self: &mut Kiosk,
    cap: &KioskOwnerCap,
    permissions: u128,
    ctx: &mut TxContext,
) {
    assert!(self.has_access(cap), ENotOwner);
    df::add(
        self.uid_mut_as_owner(cap),
        ExtensionKey<Ext> {},
        Extension {
            storage: bag::new(ctx),
            permissions,
            is_enabled: true,
        },
    )
}

/// The Extension struct contains the data used by the extension and the
/// configuration for this extension. Stored under the `ExtensionKey`
/// dynamic field.
public struct Extension has store {
    /// Storage for the extension, an isolated Bag. By putting the extension
    /// into a single dynamic field, we reduce the amount of fields on the
    /// top level (eg items / listings) while giving extension developers
    /// the ability to store any data they want.
    storage: Bag,
    /// Bitmap of permissions that the extension has (can be revoked any
    /// moment). It's all or nothing policy - either the extension has the
    /// required permissions or no permissions at all.
    ///
    /// 1st bit - `place` - allows to place items for sale
    /// 2nd bit - `lock` and `place` - allows to lock items (and place)
    ///
    /// For example:
    /// - `10` - allows to place items and lock them.
    /// - `11` - allows to place items and lock them (`lock` includes `place`).
    /// - `01` - allows to place items, but not lock them.
    /// - `00` - no permissions.
    permissions: u128,
    /// Whether the extension can call protected actions. By default, all
    /// extensions are enabled (on `add` call), however the Kiosk
    /// owner can disable them at any time.
    ///
    /// Disabling the extension does not limit its access to the storage.
    is_enabled: bool,
}

/// The `ExtensionKey` is a typed dynamic field key used to store the
/// extension configuration and data. `Ext` is a phantom type that is used
/// to identify the extension witness.
public struct ExtensionKey<phantom Ext> has store, copy, drop {}

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk.move ---

/// Access the `UID` using the `KioskOwnerCap`.
public fun uid_mut_as_owner(self: &mut Kiosk, cap: &KioskOwnerCap): &mut UID {
    assert!(self.has_access(cap), ENotOwner);
    &mut self.id
}

Remove Extension

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk_extension.move ---

/// Remove an extension from the Kiosk. Can only be performed by the owner,
/// the extension storage must be empty for the transaction to succeed.
public fun remove<Ext: drop>(self: &mut Kiosk, cap: &KioskOwnerCap) {
    assert!(self.has_access(cap), ENotOwner);
    assert!(is_installed<Ext>(self), EExtensionNotInstalled);

    let Extension {
        storage,
        permissions: _,
        is_enabled: _,
    } = df::remove(self.uid_mut_as_owner(cap), ExtensionKey<Ext> {});

    storage.destroy_empty();
}


/// Check whether an extension of type `Ext` is installed.
public fun is_installed<Ext: drop>(self: &Kiosk): bool {
    df::exists_(self.uid(), ExtensionKey<Ext> {})
}

Enable & Disable Extension

Enable

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk_extension.move ---

/// Re-enable the extension allowing it to call protected actions (eg
/// `place`, `lock`). By default, all added extensions are enabled. Kiosk
/// owner can disable them via `disable` call.
public fun enable<Ext: drop>(self: &mut Kiosk, cap: &KioskOwnerCap) {
    assert!(self.has_access(cap), ENotOwner);
    assert!(is_installed<Ext>(self), EExtensionNotInstalled);
    extension_mut<Ext>(self).is_enabled = true;
}

Disable

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk_extension.move ---

/// Revoke permissions from the extension. While it does not remove the
/// extension completely, it keeps it from performing any protected actions.
/// The storage is still available to the extension (until it's removed).
public fun disable<Ext: drop>(self: &mut Kiosk, cap: &KioskOwnerCap) {
    assert!(self.has_access(cap), ENotOwner);
    assert!(is_installed<Ext>(self), EExtensionNotInstalled);
    extension_mut<Ext>(self).is_enabled = false;
}

Place Item into Kiosk

1. should pass _ext witness as parameter to prove caller is the corresponding extension module

2. check the extension has been installed in kiosk

3. check the extension has place or lock permission

4. call kiosk.place_internal to place the item into kiosk.

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk_extension.move ---

/// Protected action: place an item into the Kiosk. Can be performed by an
/// authorized extension. The extension must have the `place` permission or
/// a `lock` permission.
///
/// To prevent non-tradable items from being placed into `Kiosk` the method
/// requires a `TransferPolicy` for the placed type to exist.
public fun place<Ext: drop, T: key + store>(
    _ext: Ext,
    self: &mut Kiosk,
    item: T,
    _policy: &TransferPolicy<T>,
) {
    assert!(is_installed<Ext>(self), EExtensionNotInstalled);
    assert!(can_place<Ext>(self) || can_lock<Ext>(self), EExtensionNotAllowed);

    self.place_internal(item)
}

/// Check whether an extension of type `Ext` is installed.
public fun is_installed<Ext: drop>(self: &Kiosk): bool {
    df::exists_(self.uid(), ExtensionKey<Ext> {})
}

/// Check whether an extension of type `Ext` can `place` into Kiosk.
public fun can_place<Ext: drop>(self: &Kiosk): bool {
    is_enabled<Ext>(self) && extension<Ext>(self).permissions & PLACE != 0
}

/// Check whether an extension of type `Ext` can `lock` items in Kiosk.
/// Locking also enables `place`.
public fun can_lock<Ext: drop>(self: &Kiosk): bool {
    is_enabled<Ext>(self) && extension<Ext>(self).permissions & LOCK != 0
}

/// Check whether an extension of type `Ext` is enabled.
public fun is_enabled<Ext: drop>(self: &Kiosk): bool {
    extension<Ext>(self).is_enabled
}

/// Value that represents the `place` permission in the permissions bitmap.
const PLACE: u128 = 1;

/// Value that represents the `lock` and `place` permission in the
/// permissions bitmap.
const LOCK: u128 = 2;

Lock Item into Kiosk

1. should pass _ext witness as parameter to prove caller is the corresponding extension module

2. check the extension has been installed in kiosk

3. check the extension has lock permission

4. call kiosk.lock_internal to lock the item into kiosk.

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk_extension.move ---

/// Protected action: lock an item in the Kiosk. Can be performed by an
/// authorized extension. The extension must have the `lock` permission.
public fun lock<Ext: drop, T: key + store>(
    _ext: Ext,
    self: &mut Kiosk,
    item: T,
    _policy: &TransferPolicy<T>,
) {
    assert!(is_installed<Ext>(self), EExtensionNotInstalled);
    assert!(can_lock<Ext>(self), EExtensionNotAllowed);

    self.lock_internal(item)
}

Retrieve Items from Extension Storage

Get Immutable Item

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk_extension.move ---

/// Get immutable access to the extension storage. Can only be performed by
/// the extension as long as the extension is installed.
public fun storage<Ext: drop>(_ext: Ext, self: &Kiosk): &Bag {
    assert!(is_installed<Ext>(self), EExtensionNotInstalled);
    &extension<Ext>(self).storage
}

Get Mutable Item

/// --- crates/sui-framework/packages/sui-framework/sources/kiosk/kiosk_extension.move ---

/// Get mutable access to the extension storage. Can only be performed by
/// the extension as long as the extension is installed. Disabling the
/// extension does not prevent it from accessing the storage.
///
/// Potentially dangerous: extension developer can keep data in a Bag
/// therefore never really allowing the KioskOwner to remove the extension.
/// However, it is the case with any other solution (1) and this way we
/// prevent intentional extension freeze when the owner wants to ruin a
/// trade (2) - eg locking extension while an auction is in progress.
///
/// Extensions should be crafted carefully, and the KioskOwner should be
/// aware of the risks.
public fun storage_mut<Ext: drop>(_ext: Ext, self: &mut Kiosk): &mut Bag {
    assert!(is_installed<Ext>(self), EExtensionNotInstalled);
    &mut extension_mut<Ext>(self).storage
}

NFT Rental Analysis

Install & Remove Extension

Install

/// --- examples/move/nft-rental/sources/nft_rental.move ---

/// Enables someone to install the Rentables extension in their Kiosk.
public fun install(kiosk: &mut Kiosk, cap: &KioskOwnerCap, ctx: &mut TxContext) {
    kiosk_extension::add(Rentables {}, kiosk, cap, PERMISSIONS, ctx);
}

Remove

/// --- examples/move/nft-rental/sources/nft_rental.move ---

/// Remove the extension from the Kiosk. Can only be performed by the owner,
/// The extension storage must be empty for the transaction to succeed.
public fun remove(kiosk: &mut Kiosk, cap: &KioskOwnerCap, _ctx: &mut TxContext) {
    kiosk_extension::remove<Rentables>(kiosk, cap);
}

setup_renting

1. create TransferPolicy of the item type.

2. create ProtectedTP to store TransferPolicy and TransferPolicyCap

3. create RentalPolicy

4. share ProtectedTP and RentalPolicy

/// --- examples/move/nft-rental/sources/nft_rental.move ---

/// Mints and shares a ProtectedTP & a RentalPolicy object for type T.
/// Can only be performed by the publisher of type T.
public fun setup_renting<T>(publisher: &Publisher, amount_bp: u64, ctx: &mut TxContext) {
    // Creates an empty TP and shares a ProtectedTP<T> object.
    // This can be used to bypass the lock rule under specific conditions.
    // Storing inside the cap the ProtectedTP with no way to access it
    // as we do not want to modify this policy
    let (transfer_policy, policy_cap) = transfer_policy::new<T>(publisher, ctx);

    let protected_tp = ProtectedTP {
        id: object::new(ctx),
        transfer_policy,
        policy_cap,
    };

    let rental_policy = RentalPolicy<T> {
        id: object::new(ctx),
        balance: balance::zero<SUI>(),
        amount_bp,
    };

    transfer::share_object(protected_tp);
    transfer::share_object(rental_policy);
}

/// A shared object that should be minted by every creator.
/// Even for creators that do not wish to enforce royalties. Provides authorized access to an
/// empty TransferPolicy.
public struct ProtectedTP<phantom T> has key, store {
    id: UID,
    transfer_policy: TransferPolicy<T>,
    policy_cap: TransferPolicyCap<T>,
}

/// A shared object that should be minted by every creator.
/// Defines the royalties the creator will receive from each rent invocation.
public struct RentalPolicy<phantom T> has key, store {
    id: UID,
    balance: Balance<SUI>,
    /// Note: Move does not support float numbers.
    ///
    /// If you need to represent a float, you need to determine the desired
    /// precision and use a larger integer representation.
    ///
    /// For example, percentages can be represented using basis points:
    /// 10000 basis points represent 100% and 100 basis points represent 1%.
    amount_bp: u64,
}

List

1. check the kiosk has installed renting extension

2. set the kiosk.owner to be tx sender

3. list the item in kiosk on zero price

4. purchase the item and get the item object

5. confirm transfer request using ProtectedTP.transfer_policy

6. construct a Rentable object which stores the object to be rented and the renting information, such as renting duration and price per day.

7. store the Rentable object into extension’s storage.

/// --- examples/move/nft-rental/sources/nft_rental.move ---

/// Enables someone to list an asset within the Rentables extension's Bag,
/// creating a Bag entry with the asset's ID as the key and a Rentable wrapper object as the value.
/// Requires the existance of a ProtectedTP which can only be created by the creator of type T.
/// Assumes item is already placed (& optionally locked) in a Kiosk.
public fun list<T: key + store>(
    kiosk: &mut Kiosk,
    cap: &KioskOwnerCap,
    protected_tp: &ProtectedTP<T>,
    item_id: ID,
    duration: u64,
    price_per_day: u64,
    ctx: &mut TxContext,
) {
    assert!(kiosk_extension::is_installed<Rentables>(kiosk), EExtensionNotInstalled);

    kiosk.set_owner(cap, ctx);
    kiosk.list<T>(cap, item_id, 0);

    let coin = coin::zero<SUI>(ctx);
    let (object, request) = kiosk.purchase<T>(item_id, coin);

    let (_item, _paid, _from) = protected_tp.transfer_policy.confirm_request(request);

    let rentable = Rentable {
        object,
        duration,
        start_date: option::none<u64>(),
        price_per_day,
        kiosk_id: object::id(kiosk),
    };

    place_in_bag<T, Listed>(kiosk, Listed { id: item_id }, rentable);
}

fun place_in_bag<T: key + store, Key: store + copy + drop>(
    kiosk: &mut Kiosk,
    item: Key,
    rentable: Rentable<T>,
) {
    let ext_storage_mut = kiosk_extension::storage_mut(Rentables {}, kiosk);
    bag::add(ext_storage_mut, item, rentable);
}

/// Struct representing a listed item.
/// Used as a key for the Rentable that's placed in the Extension's Bag.
public struct Listed has store, copy, drop { id: ID }

/// --- sui-framework/sources/kiosk/kiosk_extension.move ---

/// Get mutable access to the extension storage. Can only be performed by
/// the extension as long as the extension is installed. Disabling the
/// extension does not prevent it from accessing the storage.
///
/// Potentially dangerous: extension developer can keep data in a Bag
/// therefore never really allowing the KioskOwner to remove the extension.
/// However, it is the case with any other solution (1) and this way we
/// prevent intentional extension freeze when the owner wants to ruin a
/// trade (2) - eg locking extension while an auction is in progress.
///
/// Extensions should be crafted carefully, and the KioskOwner should be
/// aware of the risks.
public fun storage_mut<Ext: drop>(_ext: Ext, self: &mut Kiosk): &mut Bag {
    assert!(is_installed<Ext>(self), EExtensionNotInstalled);
    &mut extension_mut<Ext>(self).storage
}

/// --- sui-framework/sources/kiosk/kiosk.move ---

/// Change the `owner` field to the transaction sender.
/// The change is purely cosmetical and does not affect any of the
/// basic kiosk functions unless some logic for this is implemented
/// in a third party module.
public fun set_owner(self: &mut Kiosk, cap: &KioskOwnerCap, ctx: &TxContext) {
    assert!(self.has_access(cap), ENotOwner);
    self.owner = ctx.sender();
}

Delist

1. check KioskOwnerCap corresponds to the kiosk

2. take the Rentable out of extension’s storage

3. lock or place the item back into the kiosk according to whether the TransferPolicy has LockRule.

/// --- examples/move/nft-rental/sources/nft_rental.move ---

use kiosk::kiosk_lock_rule::Rule as LockRule;

/// Allows the renter to delist an item, that is not currently being rented.
/// Places (or locks, if a lock rule is present) the object back to owner's Kiosk.
/// Creators should mint an empty TransferPolicy even if they don't want to apply any royalties.
/// If they wish at some point to enforce royalties, they can update the existing TransferPolicy.
public fun delist<T: key + store>(
    kiosk: &mut Kiosk,
    cap: &KioskOwnerCap,
    transfer_policy: &TransferPolicy<T>,
    item_id: ID,
    _ctx: &mut TxContext,
) {
    assert!(kiosk.has_access(cap), ENotOwner);

    let rentable = take_from_bag<T, Listed>(kiosk, Listed { id: item_id });

    let Rentable {
        object,
        duration: _,
        start_date: _,
        price_per_day: _,
        kiosk_id: _,
    } = rentable;

    if (has_rule<T, LockRule>(transfer_policy)) {
        kiosk.lock(cap, transfer_policy, object);
    } else {
        kiosk.place(cap, object);
    };
}

fun take_from_bag<T: key + store, Key: store + copy + drop>(
    kiosk: &mut Kiosk,
    item: Key,
): Rentable<T> {
    let ext_storage_mut = kiosk_extension::storage_mut(Rentables {}, kiosk);
    assert!(bag::contains(ext_storage_mut, item), EObjectNotExist);
    bag::remove<Key, Rentable<T>>(
        ext_storage_mut,
        item,
    )
}

/// --- sui-framework/sources/kiosk/kiosk_extension.move ---

/// Get mutable access to the extension storage. Can only be performed by
/// the extension as long as the extension is installed. Disabling the
/// extension does not prevent it from accessing the storage.
///
/// Potentially dangerous: extension developer can keep data in a Bag
/// therefore never really allowing the KioskOwner to remove the extension.
/// However, it is the case with any other solution (1) and this way we
/// prevent intentional extension freeze when the owner wants to ruin a
/// trade (2) - eg locking extension while an auction is in progress.
///
/// Extensions should be crafted carefully, and the KioskOwner should be
/// aware of the risks.
public fun storage_mut<Ext: drop>(_ext: Ext, self: &mut Kiosk): &mut Bag {
    assert!(is_installed<Ext>(self), EExtensionNotInstalled);
    &mut extension_mut<Ext>(self).storage
}

/// Internal: get a mutable access to the Extension.
fun extension_mut<Ext: drop>(self: &mut Kiosk): &mut Extension {
    df::borrow_mut(self.uid_mut_internal(), ExtensionKey<Ext> {})
}

Rent

1. check renting extension has been installed in the kiosk

2. take Rentable from extension storage of renter’s kiosk

3. calculate rent fee and royalty fee. Transfer rent fee to renter kiosk’s owner and royalty fee to RentalPolicy.

4. place the Rentable object into extension storage of borrower’s kiosk

/// --- examples/move/nft-rental/sources/nft_rental.move ---

/// This enables individuals to rent a listed Rentable.
///
/// It permits anyone to borrow an item on behalf of another user, provided they have the
/// Rentables extension installed.
///
/// The Rental Policy defines the portion of the coin that will be retained as fees and added to
/// the Rental Policy's balance.
public fun rent<T: key + store>(
    renter_kiosk: &mut Kiosk,
    borrower_kiosk: &mut Kiosk,
    rental_policy: &mut RentalPolicy<T>,
    item_id: ID,
    mut coin: Coin<SUI>,
    clock: &Clock,
    ctx: &mut TxContext,
) {
    assert!(kiosk_extension::is_installed<Rentables>(borrower_kiosk), EExtensionNotInstalled);

    let mut rentable = take_from_bag<T, Listed>(renter_kiosk, Listed { id: item_id });

    let max_price_per_day = MAX_VALUE_U64 / rentable.duration;
    assert!(rentable.price_per_day <= max_price_per_day, ETotalPriceOverflow);
    let total_price = rentable.price_per_day * rentable.duration;

    let coin_value = coin.value();
    assert!(coin_value == total_price, ENotEnoughCoins);

    // Calculate fees_amount using the given basis points amount (percentage), ensuring the
    // result fits into a 64-bit unsigned integer.
    let mut fees_amount = coin_value as u128;
    fees_amount = fees_amount * (rental_policy.amount_bp as u128);
    fees_amount = fees_amount / (MAX_BASIS_POINTS as u128);

    let fees = coin.split(fees_amount as u64, ctx);

    coin::put(&mut rental_policy.balance, fees);
    transfer::public_transfer(coin, renter_kiosk.owner());
    rentable.start_date.fill(clock.timestamp_ms());

    place_in_bag<T, Rented>(borrower_kiosk, Rented { id: item_id }, rentable);
}

/// Struct representing a rented item.
/// Used as a key for the Rentable that's placed in the Extension's Bag.
public struct Rented has store, copy, drop { id: ID }

fun place_in_bag<T: key + store, Key: store + copy + drop>(
    kiosk: &mut Kiosk,
    item: Key,
    rentable: Rentable<T>,
) {
    let ext_storage_mut = kiosk_extension::storage_mut(Rentables {}, kiosk);
    bag::add(ext_storage_mut, item, rentable);
}

Borrow

Borrow

/// --- examples/move/nft-rental/sources/nft_rental.move ---

/// Enables the borrower to acquire the Rentable by reference from their bag.
public fun borrow<T: key + store>(
    kiosk: &mut Kiosk,
    cap: &KioskOwnerCap,
    item_id: ID,
    _ctx: &mut TxContext,
): &T {
    assert!(kiosk.has_access(cap), ENotOwner);
    let ext_storage_mut = kiosk_extension::storage_mut(Rentables {}, kiosk);
    let rentable: &Rentable<T> = &ext_storage_mut[Rented { id: item_id }];
    &rentable.object
}

Borrow Value

/// --- examples/move/nft-rental/sources/nft_rental.move ---

/// Enables the borrower to temporarily acquire the Rentable with an agreement or promise to
/// return it.
///
/// All the information about the Rentable is stored within the promise, facilitating the
/// reconstruction of the Rentable when the object is returned.
public fun borrow_val<T: key + store>(
    kiosk: &mut Kiosk,
    cap: &KioskOwnerCap,
    item_id: ID,
    _ctx: &mut TxContext,
): (T, Promise) {
    assert!(kiosk.has_access(cap), ENotOwner);
    let borrower_kiosk = object::id(kiosk);

    let rentable = take_from_bag<T, Rented>(kiosk, Rented { id: item_id });

    let promise = Promise {
        item: Rented { id: item_id },
        duration: rentable.duration,
        start_date: *option::borrow(&rentable.start_date),
        price_per_day: rentable.price_per_day,
        renter_kiosk: rentable.kiosk_id,
        borrower_kiosk,
    };

    let Rentable {
        object,
        duration: _,
        start_date: _,
        price_per_day: _,
        kiosk_id: _,
    } = rentable;

    (object, promise)
}

/// Promise struct for borrowing by value.
public struct Promise {
    item: Rented,
    duration: u64,
    start_date: u64,
    price_per_day: u64,
    renter_kiosk: ID,
    borrower_kiosk: ID,
}

Return

/// Enables the borrower to return the borrowed item.
public fun return_val<T: key + store>(
    kiosk: &mut Kiosk,
    object: T,
    promise: Promise,
    _ctx: &mut TxContext,
) {
    assert!(kiosk_extension::is_installed<Rentables>(kiosk), EExtensionNotInstalled);

    let Promise {
        item,
        duration,
        start_date,
        price_per_day,
        renter_kiosk,
        borrower_kiosk,
    } = promise;

    let kiosk_id = object::id(kiosk);
    assert!(kiosk_id == borrower_kiosk, EInvalidKiosk);

    let rentable = Rentable {
        object,
        duration,
        start_date: option::some(start_date),
        price_per_day,
        kiosk_id: renter_kiosk,
    };

    place_in_bag(kiosk, item, rentable);
}

Reclaim

1. check renting extension has been installed in the kiosk

2. take Rentable from extension storage of renter’s kiosk

3. check renting is ended

4. lock or place the item back into renter’s kiosk.

/// --- examples/move/nft-rental/sources/nft_rental.move ---

/// Enables the owner to reclaim their asset once the rental period has concluded.
public fun reclaim<T: key + store>(
    renter_kiosk: &mut Kiosk,
    borrower_kiosk: &mut Kiosk,
    transfer_policy: &TransferPolicy<T>,
    clock: &Clock,
    item_id: ID,
    _ctx: &mut TxContext,
) {
    assert!(kiosk_extension::is_installed<Rentables>(renter_kiosk), EExtensionNotInstalled);

    let rentable = take_from_bag<T, Rented>(borrower_kiosk, Rented { id: item_id });

    let Rentable {
        object,
        duration,
        start_date,
        price_per_day: _,
        kiosk_id,
    } = rentable;

    assert!(object::id(renter_kiosk) == kiosk_id, EInvalidKiosk);

    let start_date_ms = *option::borrow(&start_date);
    let current_timestamp = clock.timestamp_ms();
    let final_timestamp = start_date_ms + duration * SECONDS_IN_A_DAY;
    assert!(current_timestamp > final_timestamp, ERentingPeriodNotOver);

    if (transfer_policy.has_rule<T, LockRule>()) {
        kiosk_extension::lock<Rentables, T>(
            Rentables {},
            renter_kiosk,
            object,
            transfer_policy,
        );
    } else {
        kiosk_extension::place<Rentables, T>(
            Rentables {},
            renter_kiosk,
            object,
            transfer_policy,
        );
    };
}