@iota/kiosk 0.1.0

package/src/query/transfer-policy.ts

@@ -0,0 +1,135 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IotaClient } from '@iota/iota-sdk/client';
+import { isValidIotaAddress } from '@iota/iota-sdk/utils';
+
+import { bcs } from '../bcs.js';
+import type { TransferPolicy, TransferPolicyCap } from '../types/index.js';
+import {
+    TRANSFER_POLICY_CAP_TYPE,
+    TRANSFER_POLICY_CREATED_EVENT,
+    TRANSFER_POLICY_TYPE,
+} from '../types/index.js';
+import { getAllOwnedObjects, parseTransferPolicyCapObject } from '../utils.js';
+
+/**
+ * Searches the `TransferPolicy`-s for the given type. The search is performed via
+ * the `TransferPolicyCreated` event. The policy can either be owned or shared,
+ * and the caller needs to filter the results accordingly (ie single owner can not
+ * be accessed by anyone but the owner).
+ *
+ * @param provider
+ * @param type
+ */
+export async function queryTransferPolicy(
+    client: IotaClient,
+    type: string,
+): Promise<TransferPolicy[]> {
+    // console.log('event type: %s', `${TRANSFER_POLICY_CREATED_EVENT}<${type}>`);
+    const { data } = await client.queryEvents({
+        query: {
+            MoveEventType: `${TRANSFER_POLICY_CREATED_EVENT}<${type}>`,
+        },
+    });
+
+    const search = data.map((event) => event.parsedJson as { id: string });
+    const policies = await client.multiGetObjects({
+        ids: search.map((policy) => policy.id),
+        options: { showBcs: true, showOwner: true },
+    });
+
+    return policies
+        .filter((policy) => !!policy && 'data' in policy)
+        .map(({ data: policy }) => {
+            // should never happen; policies are objects and fetched via an event.
+            // policies are filtered for null and undefined above.
+            if (!policy || !policy.bcs || !('bcsBytes' in policy.bcs)) {
+                throw new Error(
+                    `Invalid policy: ${policy?.objectId}, expected object, got package`,
+                );
+            }
+
+            const parsed = bcs.de(TRANSFER_POLICY_TYPE, policy.bcs.bcsBytes, 'base64');
+
+            return {
+                id: policy?.objectId,
+                type: `${TRANSFER_POLICY_TYPE}<${type}>`,
+                owner: policy?.owner,
+                rules: parsed.rules,
+                balance: parsed.balance,
+            } as TransferPolicy;
+        });
+}
+
+/**
+ * A function to fetch all the user's kiosk Caps
+ * And a list of the kiosk address ids.
+ * Returns a list of `kioskOwnerCapIds` and `kioskIds`.
+ * Extra options allow pagination.
+ * @returns TransferPolicyCap Object ID | undefined if not found.
+ */
+export async function queryTransferPolicyCapsByType(
+    client: IotaClient,
+    address: string,
+    type: string,
+): Promise<TransferPolicyCap[]> {
+    if (!isValidIotaAddress(address)) return [];
+
+    const filter = {
+        MatchAll: [
+            {
+                StructType: `${TRANSFER_POLICY_CAP_TYPE}<${type}>`,
+            },
+        ],
+    };
+
+    // fetch owned kiosk caps, paginated.
+    const data = await getAllOwnedObjects({
+        client,
+        filter,
+        owner: address,
+    });
+
+    return data
+        .map((item) => parseTransferPolicyCapObject(item))
+        .filter((item) => !!item) as TransferPolicyCap[];
+}
+
+/**
+ * A function to fetch all the user's kiosk Caps
+ * And a list of the kiosk address ids.
+ * Returns a list of `kioskOwnerCapIds` and `kioskIds`.
+ * Extra options allow pagination.
+ * @returns TransferPolicyCap Object ID | undefined if not found.
+ */
+export async function queryOwnedTransferPolicies(
+    client: IotaClient,
+    address: string,
+): Promise<TransferPolicyCap[] | undefined> {
+    if (!isValidIotaAddress(address)) return;
+
+    const filter = {
+        MatchAll: [
+            {
+                MoveModule: {
+                    module: 'transfer_policy',
+                    package: '0x2',
+                },
+            },
+        ],
+    };
+
+    // fetch all owned kiosk caps, paginated.
+    const data = await getAllOwnedObjects({ client, owner: address, filter });
+
+    const policies: TransferPolicyCap[] = [];
+
+    for (const item of data) {
+        const data = parseTransferPolicyCapObject(item);
+        if (data) policies.push(data);
+    }
+
+    return policies;
+}

package/src/tx/kiosk.ts

@@ -0,0 +1,244 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs } from '@iota/iota-sdk/bcs';
+import type {
+    TransactionArgument,
+    TransactionBlock,
+    TransactionObjectArgument,
+} from '@iota/iota-sdk/transactions';
+
+import type { ObjectArgument } from '../types/index.js';
+import { KIOSK_MODULE, KIOSK_TYPE } from '../types/index.js';
+
+/**
+ * Create a new shared Kiosk and returns the [kiosk, kioskOwnerCap] tuple.
+ */
+export function createKiosk(
+    tx: TransactionBlock,
+): [TransactionObjectArgument, TransactionObjectArgument] {
+    const [kiosk, kioskOwnerCap] = tx.moveCall({
+        target: `${KIOSK_MODULE}::new`,
+    });
+
+    return [kiosk, kioskOwnerCap];
+}
+
+/**
+ * Calls the `kiosk::new()` function and shares the kiosk.
+ * Returns the `kioskOwnerCap` object.
+ */
+export function createKioskAndShare(tx: TransactionBlock): TransactionObjectArgument {
+    const [kiosk, kioskOwnerCap] = createKiosk(tx);
+    shareKiosk(tx, kiosk);
+    return kioskOwnerCap;
+}
+
+/**
+ * Converts Transfer Policy to a shared object.
+ */
+export function shareKiosk(tx: TransactionBlock, kiosk: TransactionArgument) {
+    tx.moveCall({
+        target: `0x2::transfer::public_share_object`,
+        typeArguments: [KIOSK_TYPE],
+        arguments: [kiosk],
+    });
+}
+
+/**
+ * Call the `kiosk::place<T>(Kiosk, KioskOwnerCap, Item)` function.
+ * Place an item to the Kiosk.
+ */
+export function place(
+    tx: TransactionBlock,
+    itemType: string,
+    kiosk: ObjectArgument,
+    kioskCap: ObjectArgument,
+    item: ObjectArgument,
+): void {
+    tx.moveCall({
+        target: `${KIOSK_MODULE}::place`,
+        typeArguments: [itemType],
+        arguments: [tx.object(kiosk), tx.object(kioskCap), tx.object(item)],
+    });
+}
+
+/**
+ * Call the `kiosk::lock<T>(Kiosk, KioskOwnerCap, TransferPolicy, Item)`
+ * function. Lock an item in the Kiosk.
+ *
+ * Unlike `place` this function requires a `TransferPolicy` to exist
+ * and be passed in. This is done to make sure the item does not get
+ * locked without an option to take it out.
+ */
+export function lock(
+    tx: TransactionBlock,
+    itemType: string,
+    kiosk: ObjectArgument,
+    kioskCap: ObjectArgument,
+    policy: ObjectArgument,
+    item: ObjectArgument,
+): void {
+    tx.moveCall({
+        target: `${KIOSK_MODULE}::lock`,
+        typeArguments: [itemType],
+        arguments: [tx.object(kiosk), tx.object(kioskCap), tx.object(policy), tx.object(item)],
+    });
+}
+
+/**
+ * Call the `kiosk::take<T>(Kiosk, KioskOwnerCap, ID)` function.
+ * Take an item from the Kiosk.
+ */
+export function take(
+    tx: TransactionBlock,
+    itemType: string,
+    kiosk: ObjectArgument,
+    kioskCap: ObjectArgument,
+    itemId: string,
+): TransactionObjectArgument {
+    const [item] = tx.moveCall({
+        target: `${KIOSK_MODULE}::take`,
+        typeArguments: [itemType],
+        arguments: [tx.object(kiosk), tx.object(kioskCap), tx.pure.id(itemId)],
+    });
+
+    return item;
+}
+
+/**
+ * Call the `kiosk::list<T>(Kiosk, KioskOwnerCap, ID, u64)` function.
+ * List an item for sale.
+ */
+export function list(
+    tx: TransactionBlock,
+    itemType: string,
+    kiosk: ObjectArgument,
+    kioskCap: ObjectArgument,
+    itemId: string,
+    price: string | bigint,
+): void {
+    tx.moveCall({
+        target: `${KIOSK_MODULE}::list`,
+        typeArguments: [itemType],
+        arguments: [tx.object(kiosk), tx.object(kioskCap), tx.pure.id(itemId), tx.pure.u64(price)],
+    });
+}
+
+/**
+ * Call the `kiosk::list<T>(Kiosk, KioskOwnerCap, ID, u64)` function.
+ * List an item for sale.
+ */
+export function delist(
+    tx: TransactionBlock,
+    itemType: string,
+    kiosk: ObjectArgument,
+    kioskCap: ObjectArgument,
+    itemId: string,
+): void {
+    tx.moveCall({
+        target: `${KIOSK_MODULE}::delist`,
+        typeArguments: [itemType],
+        arguments: [tx.object(kiosk), tx.object(kioskCap), tx.pure.id(itemId)],
+    });
+}
+
+/**
+ * Call the `kiosk::place_and_list<T>(Kiosk, KioskOwnerCap, Item, u64)` function.
+ * Place an item to the Kiosk and list it for sale.
+ */
+export function placeAndList(
+    tx: TransactionBlock,
+    itemType: string,
+    kiosk: ObjectArgument,
+    kioskCap: ObjectArgument,
+    item: ObjectArgument,
+    price: string | bigint,
+): void {
+    tx.moveCall({
+        target: `${KIOSK_MODULE}::place_and_list`,
+        typeArguments: [itemType],
+        arguments: [tx.object(kiosk), tx.object(kioskCap), tx.object(item), tx.pure.u64(price)],
+    });
+}
+
+/**
+ * Call the `kiosk::purchase<T>(Kiosk, ID, Coin<IOTA>)` function and receive an Item and
+ * a TransferRequest which needs to be dealt with (via a matching TransferPolicy).
+ */
+export function purchase(
+    tx: TransactionBlock,
+    itemType: string,
+    kiosk: ObjectArgument,
+    itemId: string,
+    payment: ObjectArgument,
+): [TransactionObjectArgument, TransactionObjectArgument] {
+    const [item, transferRequest] = tx.moveCall({
+        target: `${KIOSK_MODULE}::purchase`,
+        typeArguments: [itemType],
+        arguments: [tx.object(kiosk), tx.pure.id(itemId), tx.object(payment)],
+    });
+
+    return [item, transferRequest];
+}
+
+/**
+ * Call the `kiosk::withdraw(Kiosk, KioskOwnerCap, Option<u64>)` function and receive a Coin<IOTA>.
+ * If the amount is null, then the entire balance will be withdrawn.
+ */
+export function withdrawFromKiosk(
+    tx: TransactionBlock,
+    kiosk: ObjectArgument,
+    kioskCap: ObjectArgument,
+    amount?: string | bigint | number,
+): TransactionObjectArgument {
+    const amountArg = bcs.option(bcs.u64()).serialize(amount);
+
+    const [coin] = tx.moveCall({
+        target: `${KIOSK_MODULE}::withdraw`,
+        arguments: [tx.object(kiosk), tx.object(kioskCap), amountArg],
+    });
+
+    return coin;
+}
+
+/**
+ * Call the `kiosk::borrow_value<T>(Kiosk, KioskOwnerCap, ID): T` function.
+ * Immutably borrow an item from the Kiosk and return it in the end.
+ *
+ * Requires calling `returnValue` to return the item.
+ */
+export function borrowValue(
+    tx: TransactionBlock,
+    itemType: string,
+    kiosk: ObjectArgument,
+    kioskCap: ObjectArgument,
+    itemId: string,
+): [TransactionArgument, TransactionArgument] {
+    const [item, promise] = tx.moveCall({
+        target: `${KIOSK_MODULE}::borrow_val`,
+        typeArguments: [itemType],
+        arguments: [tx.object(kiosk), tx.object(kioskCap), tx.pure.id(itemId)],
+    });
+
+    return [item, promise];
+}
+
+/**
+ * Call the `kiosk::return_value<T>(Kiosk, Item, Borrow)` function.
+ * Return an item to the Kiosk after it was `borrowValue`-d.
+ */
+export function returnValue(
+    tx: TransactionBlock,
+    itemType: string,
+    kiosk: ObjectArgument,
+    item: TransactionArgument,
+    promise: TransactionArgument,
+): void {
+    tx.moveCall({
+        target: `${KIOSK_MODULE}::return_val`,
+        typeArguments: [itemType],
+        arguments: [tx.object(kiosk), item, promise],
+    });
+}

package/src/tx/personal-kiosk.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { TransactionBlock, TransactionObjectArgument } from '@iota/iota-sdk/transactions';
+
+import type { ObjectArgument } from '../types/index.js';
+
+export function convertToPersonalTx(
+    tx: TransactionBlock,
+    kiosk: ObjectArgument,
+    kioskOwnerCap: ObjectArgument,
+    packageId: string,
+): TransactionObjectArgument {
+    const personalKioskCap = tx.moveCall({
+        target: `${packageId}::personal_kiosk::new`,
+        arguments: [tx.object(kiosk), tx.object(kioskOwnerCap)],
+    });
+
+    return personalKioskCap;
+}
+
+/**
+ * Transfers the personal kiosk Cap to the sender.
+ */
+export function transferPersonalCapTx(
+    tx: TransactionBlock,
+    personalKioskCap: TransactionObjectArgument,
+    packageId: string,
+) {
+    tx.moveCall({
+        target: `${packageId}::personal_kiosk::transfer_to_sender`,
+        arguments: [personalKioskCap],
+    });
+}

package/src/tx/rules/attach.ts

@@ -0,0 +1,74 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { TransactionBlock } from '@iota/iota-sdk/transactions';
+
+import type { ObjectArgument } from '../../types/index.js';
+
+export function attachKioskLockRuleTx(
+    tx: TransactionBlock,
+    type: string,
+    policy: ObjectArgument,
+    policyCap: ObjectArgument,
+    packageId: string,
+) {
+    tx.moveCall({
+        target: `${packageId}::kiosk_lock_rule::add`,
+        typeArguments: [type],
+        arguments: [tx.object(policy), tx.object(policyCap)],
+    });
+}
+
+export function attachRoyaltyRuleTx(
+    tx: TransactionBlock,
+    type: string,
+    policy: ObjectArgument,
+    policyCap: ObjectArgument,
+    percentageBps: number | string, // this is in basis points.
+    minAmount: number | string,
+    packageId: string,
+) {
+    if (Number(percentageBps) < 0 || Number(percentageBps) > 10_000)
+        throw new Error('Invalid basis point percentage. Use a value between [0,10000].');
+
+    tx.moveCall({
+        target: `${packageId}::royalty_rule::add`,
+        typeArguments: [type],
+        arguments: [
+            tx.object(policy),
+            tx.object(policyCap),
+            tx.pure.u16(Number(percentageBps)),
+            tx.pure.u64(minAmount),
+        ],
+    });
+}
+
+export function attachPersonalKioskRuleTx(
+    tx: TransactionBlock,
+    type: string,
+    policy: ObjectArgument,
+    policyCap: ObjectArgument,
+    packageId: string,
+) {
+    tx.moveCall({
+        target: `${packageId}::personal_kiosk_rule::add`,
+        typeArguments: [type],
+        arguments: [tx.object(policy), tx.object(policyCap)],
+    });
+}
+
+export function attachFloorPriceRuleTx(
+    tx: TransactionBlock,
+    type: string,
+    policy: ObjectArgument,
+    policyCap: ObjectArgument,
+    minPrice: string | bigint,
+    packageId: string,
+) {
+    tx.moveCall({
+        target: `${packageId}::floor_price_rule::add`,
+        typeArguments: [type],
+        arguments: [tx.object(policy), tx.object(policyCap), tx.pure.u64(minPrice)],
+    });
+}

package/src/tx/rules/resolve.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { RuleResolvingParams } from '../../types/index.js';
+import { lock } from '../kiosk.js';
+
+/**
+ * A helper to resolve the royalty rule.
+ */
+export function resolveRoyaltyRule(params: RuleResolvingParams) {
+    const { transactionBlock: txb, itemType, price, packageId, transferRequest, policyId } = params;
+
+    const policyObj = txb.object(policyId);
+
+    // calculates the amount
+    const [amount] = txb.moveCall({
+        target: `${packageId}::royalty_rule::fee_amount`,
+        typeArguments: [itemType],
+        arguments: [policyObj, txb.pure.u64(price || '0')],
+    });
+
+    // splits the coin.
+    const feeCoin = txb.splitCoins(txb.gas, [amount]);
+
+    // pays the policy
+    txb.moveCall({
+        target: `${packageId}::royalty_rule::pay`,
+        typeArguments: [itemType],
+        arguments: [policyObj, transferRequest, feeCoin],
+    });
+}
+
+export function resolveKioskLockRule(params: RuleResolvingParams) {
+    const {
+        transactionBlock: txb,
+        packageId,
+        itemType,
+        kiosk,
+        kioskCap,
+        policyId,
+        purchasedItem,
+        transferRequest,
+    } = params;
+
+    if (!kiosk || !kioskCap) throw new Error('Missing Owned Kiosk or Owned Kiosk Cap');
+
+    lock(txb, itemType, kiosk, kioskCap, policyId, purchasedItem);
+
+    // proves that the item is locked in the kiosk to the TP.
+    txb.moveCall({
+        target: `${packageId}::kiosk_lock_rule::prove`,
+        typeArguments: [itemType],
+        arguments: [transferRequest, txb.object(kiosk)],
+    });
+}
+
+/**
+ * A helper to resolve the personalKioskRule.
+ * @param params
+ */
+export function resolvePersonalKioskRule(params: RuleResolvingParams) {
+    const { transactionBlock: txb, packageId, itemType, kiosk, transferRequest } = params;
+
+    if (!kiosk) throw new Error('Missing owned Kiosk.');
+
+    // proves that the destination kiosk is personal.
+    txb.moveCall({
+        target: `${packageId}::personal_kiosk_rule::prove`,
+        typeArguments: [itemType],
+        arguments: [txb.object(kiosk), transferRequest],
+    });
+}
+
+/**
+ * Resolves the floor price rule.
+ */
+export function resolveFloorPriceRule(params: RuleResolvingParams) {
+    const { transactionBlock: txb, packageId, itemType, policyId, transferRequest } = params;
+
+    // proves that the destination kiosk is personal
+    txb.moveCall({
+        target: `${packageId}::floor_price_rule::prove`,
+        typeArguments: [itemType],
+        arguments: [txb.object(policyId), transferRequest],
+    });
+}

package/src/tx/transfer-policy.ts

@@ -0,0 +1,121 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs } from '@iota/iota-sdk/bcs';
+import type {
+    TransactionArgument,
+    TransactionBlock,
+    TransactionObjectArgument,
+} from '@iota/iota-sdk/transactions';
+
+import type { ObjectArgument } from '../types/index.js';
+import { TRANSFER_POLICY_MODULE, TRANSFER_POLICY_TYPE } from '../types/index.js';
+
+/**
+ * Call the `transfer_policy::new` function to create a new transfer policy.
+ * Returns `transferPolicyCap`
+ */
+export function createTransferPolicy(
+    tx: TransactionBlock,
+    itemType: string,
+    publisher: ObjectArgument,
+): TransactionObjectArgument {
+    const [transferPolicy, transferPolicyCap] = createTransferPolicyWithoutSharing(
+        tx,
+        itemType,
+        publisher,
+    );
+
+    shareTransferPolicy(tx, itemType, transferPolicy);
+
+    return transferPolicyCap;
+}
+
+/**
+ * Creates a transfer Policy and returns both the Policy and the Cap.
+ * Used if we want to use the policy before making it a shared object.
+ */
+export function createTransferPolicyWithoutSharing(
+    tx: TransactionBlock,
+    itemType: string,
+    publisher: ObjectArgument,
+): [TransactionObjectArgument, TransactionObjectArgument] {
+    const [transferPolicy, transferPolicyCap] = tx.moveCall({
+        target: `${TRANSFER_POLICY_MODULE}::new`,
+        typeArguments: [itemType],
+        arguments: [tx.object(publisher)],
+    });
+
+    return [transferPolicy, transferPolicyCap];
+}
+/**
+ * Converts Transfer Policy to a shared object.
+ */
+export function shareTransferPolicy(
+    tx: TransactionBlock,
+    itemType: string,
+    transferPolicy: TransactionObjectArgument,
+) {
+    tx.moveCall({
+        target: `0x2::transfer::public_share_object`,
+        typeArguments: [`${TRANSFER_POLICY_TYPE}<${itemType}>`],
+        arguments: [transferPolicy],
+    });
+}
+
+/**
+ * Call the `transfer_policy::withdraw` function to withdraw profits from a transfer policy.
+ */
+export function withdrawFromPolicy(
+    tx: TransactionBlock,
+    itemType: string,
+    policy: ObjectArgument,
+    policyCap: ObjectArgument,
+    amount?: string | bigint | null,
+): TransactionObjectArgument {
+    const amountArg = bcs.option(bcs.u64()).serialize(amount);
+
+    const [profits] = tx.moveCall({
+        target: `${TRANSFER_POLICY_MODULE}::withdraw`,
+        typeArguments: [itemType],
+        arguments: [tx.object(policy), tx.object(policyCap), amountArg],
+    });
+
+    return profits;
+}
+
+/**
+ * Call the `transfer_policy::confirm_request` function to unblock the
+ * transaction.
+ */
+export function confirmRequest(
+    tx: TransactionBlock,
+    itemType: string,
+    policy: ObjectArgument,
+    request: TransactionArgument,
+): void {
+    tx.moveCall({
+        target: `${TRANSFER_POLICY_MODULE}::confirm_request`,
+        typeArguments: [itemType],
+        arguments: [tx.object(policy), request],
+    });
+}
+
+/**
+ * Calls the `transfer_policy::remove_rule` function to remove a Rule from the transfer policy's ruleset.
+ */
+export function removeTransferPolicyRule(
+    tx: TransactionBlock,
+    itemType: string,
+    ruleType: string,
+    configType: string,
+    policy: ObjectArgument,
+    policyCap: ObjectArgument,
+): void {
+    tx.moveCall({
+        target: `${TRANSFER_POLICY_MODULE}::remove_rule`,
+        typeArguments: [itemType, ruleType, configType],
+        arguments: [tx.object(policy), tx.object(policyCap)],
+    });
+}