使用 Kiosk SDK 创建 Sui Kiosk

import { createKioskAndShare } from '@mysten/kiosk';

let tx = new TransactionBuilder();
let kioskOwnerCap = createKioskAndShare(tx);

tx.transferObjects([ kioskOwnerCap ], tx.pure(sender, 'address'));

使用可编程事务块创建 Kiosk

let tx = new TransactionBuilder();
tx.moveCall({
target: '0x2::kiosk::default'
});

使用 Sui CLI 创建信息亭

sui client call \
--package 0x2 \
--module kiosk \
--function default \
--gas-budget 1000000000

创建具有高级选项的信息亭

对于更高级的用例，当您想要选择存储模型或立即执行操作时，可以使用可编程事务块（PTB）友好功能 kiosk::new。Kiosk 旨在共享。如果您选择不同的存储模式（例如自有存储模式），您的信息亭可能无法按预期运行或无法被其他用户访问。您可以通过在 Sui Testnet 上进行测试来确保您的 Kiosk 正常运行。

使用 Kiosk SDK 创建具有高级选项的 Kiosk

import { createKiosk } from '@mysten/kiosk';

let tx = new TransactionBuilder();
let [kiosk, kioskOwnerCap] = createKiosk(tx);

tx.transferObjects([ kioskOwnerCap ], tx.pure(sender, 'address'));
tx.moveCall({
target: '0x2::transfer::public_share_object',
arguments: [ kiosk ],
typeArguments: '0x2::kiosk::Kiosk'
})

使用可编程交易块创建具有高级选项的信息亭

let tx = new TransactionBuilder();
let [kiosk, kioskOwnerCap] = tx.moveCall({
target: '0x2::kiosk::new'
});

tx.transferObjects([ kioskOwnerCap ], tx.pure(sender, 'address'));
tx.moveCall({
target: '0x2::transfer::public_share_object',
arguments: [ kiosk ],
typeArguments: '0x2::kiosk::Kiosk'
})

使用 SUI CLI 创建具有高级选项的 Kiosk

Sui CLI 尚不支持 PTB 和事务链。您可以改用 kiosk::default 函数。

将物品放入您的信息亭或从您的信息亭取出物品# 作为 Kiosk 所有者，您可以将任何资产放入您的 Sui Kiosk 中。您可以从您的售货亭中取出当前未列出的任何商品。您可以在自助服务终端中放置哪些资产没有限制。但是，您不一定会列出和交易您放置在自助服务终端中的所有商品。TransferPolicy与物品类型相关的信息决定了您是否可以交易它。要了解更多信息，请参阅从信息亭购买商品部分。

将商品放入您的信息亭# 要将项目放置到信息亭，所有者需要调用sui::kiosk::place该对象的函数Kiosk并将KioskOwnerCap和作为Item参数传递。

ITEM_TYPE以下示例中表示项目的完整类型。

使用 Kiosk SDK 放置项目

import { place } from '@mysten/kiosk';

let tx = new TransactionBuilder();

let itemArg = tx.object('<ID>');
let kioskArg = tx.object('<ID>');
let kioskOwnerCapArg = tx.object('<ID>');

place(tx, '<ITEM_TYPE>', kioskArg, kioskOwnerCapArg, item);

使用可编程交易块放置物品

let tx = new TransactionBuilder();

let itemArg = tx.object('<ID>');
let kioskArg = tx.object('<ID>');
let kioskOwnerCapArg = tx.object('<ID>');

tx.moveCall({
target: '0x2::kiosk::place',
arguments: [ kioskArg, kioskOwnerCapArg, itemArg ],
typeArguments: [ '<ITEM_TYPE>' ]

})

使用 Sui CLI 放置项目

sui client call \
--package 0x2 \
--module kiosk \
--function place \
--args "<KIOSK_ID>" "<CAP_ID>" "<ITEM_ID>" \
--type-args "<ITEM_TYPE>" \
--gas-budget 1000000000

从售货亭拿走物品

要从售货亭获取商品，您必须是售货亭所有者。作为所有者，调用对象sui::kiosk::take的函数Kiosk，并将项目的KioskOwnerCap和作为参数传递。ID

ITEM_TYPE以下示例中表示项目的完整类型。

使用 Kiosk SDK 从 Kiosk 获取商品

import { take } from '@mysten/kiosk';

let tx = new TransactionBuilder();

let itemId = tx.pure('<ITEM_ID>', 'address');
let kioskArg = tx.object('<ID>');
let kioskOwnerCapArg = tx.object('<ID>');

let item = take('<ITEM_TYPE>', kioskArg, kioskOwnerCapArg, itemId);

tx.transferObjects([ item ], tx.pure(sender, 'address'));

使用可编程交易块从售货亭获取商品

let tx = new TransactionBuilder();

let itemId = tx.pure('<ITEM_ID>', 'address');
let kioskArg = tx.object('<ID>');
let kioskOwnerCapArg = tx.object('<ID>');

let item = tx.moveCall({
target: '0x2::kiosk::take',
arguments: [ kioskArg, kioskOwnerCapArg, itemId ],
typeArguments: [ '<ITEM_TYPE>' ]
});

使用 Sui CLI 从自助服务终端获取商品

该kiosk::take函数被构建为 PTB 友好并返回资产。Sui CLI 尚不支持事务链。

将物品锁定在信息亭中

一些政策要求资产永远不会从信息亭中移走，例如为了严格的特许权使用费执行。为了支持这一点，Sui Kiosk 提供了锁定机制。锁定与放置类似，不同之处在于您无法将锁定的资产带出 Kiosk。

要将资产锁定在信息亭中，请调用该sui::kiosk::lock函数。为了确保您稍后可以解锁资产，您必须将 TransferPolicy 与资产关联。

锁定信息亭中的物品

当您使用 lock 时function，与使用该函数类似place，您可以将KioskOwnerCap和指定Item为参数。但要锁定该项目，您还必须显示 TransferPolicy。

<ITEM_TYPE>以下示例中代表资产的完整类型。

使用 Kiosk SDK 锁定项目

import { lock } from '@mysten/kiosk';

const tx = new TransactionBuilder();

let kioskArg = tx.object('<ID>');
let kioskOwnerCapArg = tx.object('<ID>');
let itemArg = tx.object('<ID>');
let transferPolicyArg = tx.object('<ID>');

lock(tx, '<ITEM_TYPE>', kioskArg, kioskOwnerCapArg, transferPolicyArg, itemArg);

使用可编程交易块锁定项目

const tx = new TransactionBuilder();

let kioskArg = tx.object('<ID>');
let kioskOwnerCapArg = tx.object('<ID>');
let itemArg = tx.object('<ID>');
let transferPolicyArg = tx.object('<ID>');

tx.moveCall({
target: '0x2::kiosk::lock',
arguments: [ kioskArg, kioskOwnerCapArg, transferPolicyArg, itemArg ],
typeArguments: [ '<ITEM_TYPE>' ]
});

使用 Sui CLI 锁定项目

sui client call \
--package 0x2 \
--module kiosk \
--function lock \
--args "<KIOSK_ID>" "<CAP_ID>" "<TRANSFER_POLICY_ID>" "<ITEM_ID>" \
--type-args "<ITEM_TYPE>" \
--gas-budget 1000000000

从信息亭列出和删除商品

Sui Kiosk 提供基本的交易功能。作为信息亭所有者，您可以列出待售资产，买家可以发现并购买它们。Sui Kiosk 默认支持列出项目，具有三个主要功能：

kiosk::list- 以固定价格列出待售资产 kiosk::delist- 删除现有列表 kiosk::purchase- 购买待售资产网络上的任何人都可以购买 Sui Kiosk 列出的商品。要了解有关购买流程的更多信息，请参阅购买部分。要了解有关资产状态以及可以对列出的项目执行哪些操作的更多信息，请参阅资产状态部分。

列出信息亭中的商品

作为信息亭所有者，您可以使用该kiosk::list功能列出您添加到信息亭的任何资产。包括要销售的商品和标价作为参数。Sui 上的所有列表均采用 SUI 代币。当您列出商品时，Sui 会发出一个kiosk::ItemListed事件，其中包含 Kiosk ID、商品 ID、商品类型和标价。

使用 Kiosk SDK 列出项目

import { list } from '@mysten/kiosk';

let tx = new TransactionBlock();
let kioskArg = tx.object('<ID>');
let capArg = tx.object('<ID>');
let itemId = tx.pure('<ID>', 'address');
let itemType = 'ITEM_TYPE';
let price = '<price>'; // in MIST (1 SUI = 10^9 MIST)

list(tx, itemType, kioskArg, capArg, itemId, price);

使用可编程事务块列出项目

let tx = new TransactionBlock();

let kioskArg = tx.object('<ID>');
let capArg = tx.object('<ID>');
let itemId = tx.pure('<ID>', 'address');
let itemType = 'ITEM_TYPE';
let priceArg = tx.pure('<price>', 'u64'); // in MIST (1 SUI = 10^9 MIST)

tx.moveCall({
target: '0x2::kiosk::list',
arguments: [ kioskArg, capArg, itemId, priceArg ],
typeArguments: [ itemType ]
});

使用 Sui CLI 列出项目

sui client call \
--package 0x2 \
--module kiosk \
--function list \
--args "<KIOSK_ID>" "<CAP_ID>" "<ITEM_ID>" "<PRICE>" \
--type-args "ITEM_TYPE" \
--gas-budget 1000000000

删除项目

作为信息亭所有者，您可以使用kiosk::delist来删除当前列出的任何资产。指定要除名的项目作为参数。

当您下架某个商品时，Sui 会将列出该商品所收取的汽油费返还给信息亭所有者。

当您删除项目时，Sui 会发出一个kiosk::ItemDelisted事件，其中包含 Kiosk ID、项目 ID 和项目类型。

使用 Kiosk SDK 删除商品

import { delist } from '@mysten/kiosk';

let tx = new TransactionBlock();
let kioskArg = tx.object('<ID>');
let capArg = tx.object('<ID>');
let itemId = tx.pure('<ID>', 'address');
let itemType = 'ITEM_TYPE';

delist(tx, itemType, kioskArg, capArg, itemId);

使用可编程交易块删除项目

let tx = new TransactionBlock();
let kioskArg = tx.object('<ID>');
let capArg = tx.object('<ID>');
let itemId = tx.pure('<ID>', 'address');
let itemType = 'ITEM_TYPE';

tx.moveCall({
target: '0x2::kiosk::delist',
arguments: [ kioskArg, capArg, itemId ],
typeArguments: [ itemType ]
});

使用 Sui CLI 删除项目

sui client call \
--package 0x2 \
--module kiosk \
--function delist \
--args "<KIOSK_ID>" "<CAP_ID>" "<ITEM_ID>" \
--type-args "ITEM_TYPE" \
--gas-budget 1000000000

从售货亭购买商品

任何在 Sui 网络上有地址的人都可以购买 Sui Kiosk 列出的商品。要购买商品，您可以使用该kiosk::purchase功能。指定要购买的商品并支付信息亭所有者设定的标价。

您可以通过事件发现网络上列出的项目kiosk::ItemListed。

当您使用该kiosk::purchase函数时，它会返回购买的资产以及TransferRequest与该资产关联的类型。要完成购买，您必须满足应用于资产的 TransferPolicy 中定义的条款。要了解更多信息，请参阅 TransferPolicy 主题。

从售货亭借物品

作为信息亭所有者，您可以访问放置或锁定在信息亭中的资产，而无需从信息亭中取出资产。您始终可以一成不变地借用资产。是否可以可变地借用资产取决于资产的状态。例如，您无法借用列出的资产，因为您无法在列出时对其进行修改。可用的功能包括：

kiosk::borrow- 返回对资产的不可变引用
kiosk::borrow_mut- 返回对资产的可变引用
kiosk::borrow_val- PTB 友好版本borrow_mut，允许您获取资产并将其放回同一交易中。

不可变的借用

您始终可以从自助服务终端一成不变地借用资产。您可以使用该 kiosk::borrow功能借用资产，但是无法在可编程交易块中使用引用。要访问资产，您必须使用已发布的模块（函数）。

使用 Sui Move 永久借用资产

module examples::immutable_borrow
use sui::object::ID;
use sui::kiosk::{Self, Kiosk, KioskOwnerCap};

    public fun immutable_borrow_example<T>(self: &Kiosk, cap: &KioskOwnerCap, item_id: ID): &T {
        kiosk::borrow(self, cap, item_id)
    }
}

使用borrow_mut进行可变借用

如果资产未列出，您可以从自助服务终端可变地借用该资产。您可以使用该kiosk::borrow_mut函数可变地借用资产。但是，无法在 PTB 内使用引用，因此要访问可变借用的资产，您必须使用已发布的模块（函数）。

使用 Sui Move 可变借用资产

module examples::mutable_borrow
use sui::object::ID;
use sui::kiosk::{Self, Kiosk, KioskOwnerCap};

    public fun mutable_borrow_example<T>(
        self: &mut Kiosk, cap: &KioskOwnerCap, item_id: ID
    ): &mut T {
        kiosk::borrow_mut(self, cap, item_id)
    }
}

可变借用borrow_val

您可以使用 PTB 友好的 kiosk::borrow_val 函数。它允许您取出资产并将其放回同一交易中。为了确保资产被放回自助服务终端，该功能会向呼叫者“强制”“烫手山芋”。

borrow_val使用 Kiosk SDK进行可变借用# Kiosk SDK 提供了一个带有借用逻辑的函数，您可以在 PTB 中使用：（borrowValue和returnValue）。

import { borrowValue, returnValue } from '@sui/kiosk-sdk';

let tx = new TransactionBuilder();
let itemType = 'ITEM_TYPE';
let itemId = tx.pure('<ITEM_ID>', 'address');
let kioskArg = tx.object('<ID>');
let capArg = tx.object('<ID>');

let [item, promise] = borrowValue(tx, itemType, kioskArg, capArg, itemId);

// freely mutate or reference the `item`
// any calls are available as long as they take a reference
// `returnValue` must be explicitly called

returnValue(tx, itemType, kioskArg, item, promise);

borrow_val使用可编程事务块进行可变借用

let tx = new TransactionBuilder();

let itemType = 'ITEM_TYPE';
let itemId = tx.pure('<ITEM_ID>', 'address');
let kioskArg = tx.object('<ID>');
let capArg = tx.object('<ID>');

let [item, promise] = tx.moveCall({
target: '0x2::kiosk::borrow_val',
arguments: [ kioskArg, capArg, itemId ],
typeArguments: [ itemType ],
});

// freely mutate or reference the `item`
// any calls are available as long as they take a reference
// `returnValue` must be explicitly called

tx.moveCall({
target: '0x2::kiosk::return_val',
arguments: [ kioskArg, item, promise ],
typeArguments: [ itemType ],
});

从已完成的销售中提取收益

当有人购买商品时，Sui 将销售收益存储在信息亭中。作为自助终端所有者，您可以随时通过调用该kiosk::withdraw功能提取收益。该功能很简单，但由于它是 PTB 友好的，因此目前在 Sui CLI 中不支持。

使用 Kiosk SDK 提取收益

import { withdrawFromKiosk } from '@mysten/kiosk';

let tx = new TransactionBlock();
let kioskArg = tx.object('<ID>');
let capArg = tx.object('<ID>');

// The amount can be `null` to withdraw everything or a specific amount
let amount = '<amount>';
let withdrawAll = null;

let coin = withdrawFromKiosk(tx, kioskArg, capArg, amount);

使用可编程交易块提取收益

let tx = new TransactionBlock();
let kioskArg = tx.object('<ID>');
let capArg = tx.object('<ID>');

// because the function uses an Option<u64> argument,
// constructing is a bit more complex
let amountArg = tx.moveCall({
target: '0x1::option::some',
arguments: [ tx.pure('<amount>', 'u64') ],
typeArguments: [ 'u64' ],
});

// alternatively
let withdrawAllArg = tx.moveCall({
target: '0x1::option::none',
typeArguments: [ 'u64' ],
});

let coin = tx.moveCall({
target: '0x2::kiosk::withdraw',
arguments: [ kioskArg, capArg, amountArg ],
typeArguments: [ 'u64' ],
});

sui move book