@iota/kiosk 0.1.0

package/src/client/tp-transaction.ts

@@ -0,0 +1,360 @@
+// 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 {
+    attachFloorPriceRuleTx,
+    attachKioskLockRuleTx,
+    attachPersonalKioskRuleTx,
+    attachRoyaltyRuleTx,
+} from '../tx/rules/attach.js';
+import {
+    createTransferPolicy,
+    createTransferPolicyWithoutSharing,
+    removeTransferPolicyRule,
+    shareTransferPolicy,
+    withdrawFromPolicy,
+} from '../tx/transfer-policy.js';
+import type { ObjectArgument, TransferPolicyCap } from '../types/index.js';
+import type { KioskClient } from './kiosk-client.js';
+
+export type TransferPolicyBaseParams = {
+    type: string;
+    publisher: ObjectArgument;
+    skipCheck?: boolean;
+};
+
+export type TransferPolicyTransactionParams = {
+    kioskClient: KioskClient;
+    transactionBlock: TransactionBlock;
+    cap?: TransferPolicyCap;
+};
+
+export class TransferPolicyTransaction {
+    transactionBlock: TransactionBlock;
+    kioskClient: KioskClient;
+    policy?: ObjectArgument;
+    policyCap?: ObjectArgument;
+    type?: string;
+
+    constructor({ kioskClient, transactionBlock, cap }: TransferPolicyTransactionParams) {
+        this.kioskClient = kioskClient;
+        this.transactionBlock = transactionBlock;
+        if (cap) this.setCap(cap);
+    }
+
+    /**
+     * A function to create a new transfer policy.
+     * Checks if there's already an existing transfer policy to prevent
+     * double transfer policy mistakes.
+     * There's an optional `skipCheck` flag that will just create the policy
+     * without checking
+     *
+     * @param type The Type (`T`) for which we're creating the transfer policy.
+     * @param publisher The Publisher Object Id.
+     * @param address Address to save the `TransferPolicyCap` object to.
+     * @param skipCheck (Optional) skip checking if a transfer policy already exists
+     */
+    async createAndShare({
+        type,
+        publisher,
+        address,
+        skipCheck,
+    }: TransferPolicyBaseParams & {
+        address: string;
+    }) {
+        if (!skipCheck) {
+            const policies = await this.kioskClient.getTransferPolicies({ type });
+            if (policies.length > 0)
+                throw new Error("There's already transfer policy for this Type.");
+        }
+        const cap = createTransferPolicy(this.transactionBlock, type, publisher);
+        this.transactionBlock.transferObjects([cap], this.transactionBlock.pure.address(address));
+    }
+
+    /**
+     * A convenient function to create a Transfer Policy and attach some rules
+     * before sharing it (so you can prepare it in a single PTB)
+     * @param type The Type (`T`) for which we're creating the transfer policy.
+     * @param publisher The Publisher Object Id.
+     * @param address Address to save the `TransferPolicyCap` object to.
+     * @param skipCheck (Optional) skip checking if a transfer policy already exists
+     */
+    async create({
+        type,
+        publisher,
+        skipCheck,
+    }: TransferPolicyBaseParams): Promise<TransferPolicyTransaction> {
+        if (!skipCheck) {
+            const policies = await this.kioskClient.getTransferPolicies({ type });
+            if (policies.length > 0)
+                throw new Error("There's already transfer policy for this Type.");
+        }
+        const [policy, policyCap] = createTransferPolicyWithoutSharing(
+            this.transactionBlock,
+            type,
+            publisher,
+        );
+
+        this.#setup(policy, policyCap, type); // sets the client's TP to the newly created one.
+        return this;
+    }
+
+    /**
+     * This can be called after calling the `create` function to share the `TransferPolicy`,
+     * and transfer the `TransferPolicyCap` to the specified address
+     *
+     * @param address The address to transfer the `TransferPolicyCap`
+     */
+    shareAndTransferCap(address: string) {
+        if (!this.type || !this.policyCap || !this.policy)
+            throw new Error(
+                'This function can only be called after `transferPolicyManager.create`',
+            );
+
+        shareTransferPolicy(
+            this.transactionBlock,
+            this.type,
+            this.policy as TransactionObjectArgument,
+        );
+        this.transactionBlock.transferObjects(
+            [this.policyCap as TransactionObjectArgument],
+            this.transactionBlock.pure.address(address),
+        );
+    }
+
+    /**
+     * Setup the TransferPolicy by passing a `cap` returned from `kioskClient.getOwnedTransferPolicies` or
+     * `kioskClient.getOwnedTransferPoliciesByType`.
+     * @param policyCapId The `TransferPolicyCap`
+     */
+    setCap({ policyId, policyCapId, type }: TransferPolicyCap) {
+        return this.#setup(policyId, policyCapId, type);
+    }
+
+    /**
+     * Withdraw from the transfer policy's profits.
+     * @param address Address to transfer the profits to.
+     * @param amount (Optional) amount parameter. Will withdraw all profits if the amount is not specified.
+     */
+    withdraw(address: string, amount?: string | bigint) {
+        this.#validateInputs();
+        // Withdraw coin for specified amount (or none)
+        const coin = withdrawFromPolicy(
+            this.transactionBlock,
+            this.type!,
+            this.policy!,
+            this.policyCap!,
+            amount,
+        );
+
+        this.transactionBlock.transferObjects([coin], this.transactionBlock.pure.address(address));
+
+        return this;
+    }
+
+    /**
+     *  Adds the Kiosk Royalty rule to the Transfer Policy.
+     *  You can pass the percentage, as well as a minimum amount.
+     *  The royalty that will be paid is the MAX(percentage, minAmount).
+     * 	You can pass 0 in either value if you want only percentage royalty, or a fixed amount fee.
+     * 	(but you should define at least one of them for the rule to make sense).
+     *
+     * 	@param percentageBps The royalty percentage in basis points. Use `percentageToBasisPoints` helper to convert from percentage [0,100].
+     * 	@param minAmount The minimum royalty amount per request in nano.
+     */
+    addRoyaltyRule(
+        percentageBps: number | string, // this is in basis points.
+        minAmount: number | string,
+    ) {
+        this.#validateInputs();
+
+        // Hard-coding package Ids as these don't change.
+        // Also, it's hard to keep versioning as with network wipes, mainnet
+        // and testnet will conflict.
+        attachRoyaltyRuleTx(
+            this.transactionBlock,
+            this.type!,
+            this.policy!,
+            this.policyCap!,
+            percentageBps,
+            minAmount,
+            this.kioskClient.getRulePackageId('royaltyRulePackageId'),
+        );
+        return this;
+    }
+
+    /**
+     * Adds the Kiosk Lock Rule to the Transfer Policy.
+     * This Rule forces buyer to lock the item in the kiosk, preserving strong royalties.
+     */
+    addLockRule() {
+        this.#validateInputs();
+
+        attachKioskLockRuleTx(
+            this.transactionBlock,
+            this.type!,
+            this.policy!,
+            this.policyCap!,
+            this.kioskClient.getRulePackageId('kioskLockRulePackageId'),
+        );
+        return this;
+    }
+
+    /**
+     * Attaches the Personal Kiosk Rule, making a purchase valid only for `SoulBound` kiosks.
+     */
+    addPersonalKioskRule() {
+        this.#validateInputs();
+
+        attachPersonalKioskRuleTx(
+            this.transactionBlock,
+            this.type!,
+            this.policy!,
+            this.policyCap!,
+            this.kioskClient.getRulePackageId('personalKioskRulePackageId'),
+        );
+        return this;
+    }
+
+    /**
+     * A function to add the floor price rule to a transfer policy.
+     * @param minPrice The minimum price in nano.
+     */
+    addFloorPriceRule(minPrice: string | bigint) {
+        this.#validateInputs();
+
+        attachFloorPriceRuleTx(
+            this.transactionBlock,
+            this.type!,
+            this.policy!,
+            this.policyCap!,
+            minPrice,
+            this.kioskClient.getRulePackageId('floorPriceRulePackageId'),
+        );
+        return this;
+    }
+
+    /**
+     * Generic helper to remove a rule, not from the SDK's base ruleset.
+     * @param ruleType The Rule Type
+     * @param configType The Config Type
+     */
+    removeRule({ ruleType, configType }: { ruleType: string; configType: string }) {
+        this.#validateInputs();
+
+        removeTransferPolicyRule(
+            this.transactionBlock,
+            this.type!,
+            ruleType,
+            configType,
+            this.policy!,
+            this.policyCap!,
+        );
+    }
+
+    /**
+     * Removes the lock rule.
+     */
+    removeLockRule() {
+        this.#validateInputs();
+
+        const packageId = this.kioskClient.getRulePackageId('kioskLockRulePackageId');
+
+        removeTransferPolicyRule(
+            this.transactionBlock,
+            this.type!,
+            `${packageId}::kiosk_lock_rule::Rule`,
+            `${packageId}::kiosk_lock_rule::Config`,
+            this.policy!,
+            this.policyCap!,
+        );
+        return this;
+    }
+
+    /**
+     * Removes the Royalty rule
+     */
+    removeRoyaltyRule() {
+        this.#validateInputs();
+
+        const packageId = this.kioskClient.getRulePackageId('royaltyRulePackageId');
+
+        removeTransferPolicyRule(
+            this.transactionBlock,
+            this.type!,
+            `${packageId}::royalty_rule::Rule`,
+            `${packageId}::royalty_rule::Config`,
+            this.policy!,
+            this.policyCap!,
+        );
+        return this;
+    }
+
+    removePersonalKioskRule() {
+        this.#validateInputs();
+
+        const packageId = this.kioskClient.getRulePackageId('personalKioskRulePackageId');
+
+        removeTransferPolicyRule(
+            this.transactionBlock,
+            this.type!,
+            `${packageId}::personal_kiosk_rule::Rule`,
+            `bool`,
+            this.policy!,
+            this.policyCap!,
+        );
+        return this;
+    }
+
+    removeFloorPriceRule() {
+        this.#validateInputs();
+
+        const packageId = this.kioskClient.getRulePackageId('floorPriceRulePackageId');
+
+        removeTransferPolicyRule(
+            this.transactionBlock,
+            this.type!,
+            `${packageId}::floor_price_rule::Rule`,
+            `${packageId}::floor_price_rule::Config`,
+            this.policy!,
+            this.policyCap!,
+        );
+        return this;
+    }
+
+    getPolicy() {
+        if (!this.policy) throw new Error('Policy not set.');
+        return this.policy;
+    }
+
+    getPolicyCap() {
+        if (!this.policyCap) throw new Error('Transfer Policy Cap not set.');
+        return this.policyCap;
+    }
+
+    // Internal function that that the policy's Id + Cap + type have been set.
+    #validateInputs() {
+        const genericErrorMessage = `Please use 'setCap()' to setup the TransferPolicy.`;
+        if (!this.policy)
+            throw new Error(`${genericErrorMessage} Missing: Transfer Policy Object.`);
+        if (!this.policyCap)
+            throw new Error(`${genericErrorMessage} Missing: TransferPolicyCap Object ID`);
+        if (!this.type)
+            throw new Error(
+                `${genericErrorMessage} Missing: Transfer Policy object type (e.g. {packageId}::item::Item)`,
+            );
+    }
+
+    /**
+     * Setup the state of the TransferPolicyTransaction.
+     */
+    #setup(policyId: ObjectArgument, policyCap: ObjectArgument, type: string) {
+        this.policy = policyId;
+        this.policyCap = policyCap;
+        this.type = type;
+        return this;
+    }
+}

package/src/constants.ts

@@ -0,0 +1,85 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+// eslint-disable-next-line import/no-cycle
+import type { KioskConfiguration } from '@iota/iota-sdk/client';
+import { getAllNetworks } from '@iota/iota-sdk/client';
+import {
+    resolveFloorPriceRule,
+    resolveKioskLockRule,
+    resolvePersonalKioskRule,
+    resolveRoyaltyRule,
+} from './tx/rules//resolve.js';
+import type { ObjectArgument, RuleResolvingParams } from './types/index.js';
+
+/**
+ * The base rule package ids that can be extended
+ */
+export type BaseRulePackageIds = {
+    royaltyRulePackageId?: string;
+    kioskLockRulePackageId?: string;
+    personalKioskRulePackageId?: string;
+    floorPriceRulePackageId?: string;
+};
+
+/**
+ * The Transfer Policy rule.
+ */
+export type TransferPolicyRule = {
+    rule: string;
+    packageId: string;
+    resolveRuleFunction: (rule: RuleResolvingParams) => ObjectArgument | void;
+    hasLockingRule?: boolean;
+};
+
+/**
+ * Constructs a list of rule resolvers based on the params.
+ */
+export function getBaseRules({
+    royaltyRulePackageId,
+    kioskLockRulePackageId,
+    personalKioskRulePackageId,
+    floorPriceRulePackageId,
+}: BaseRulePackageIds): TransferPolicyRule[] {
+    const rules = [];
+
+    if (royaltyRulePackageId) {
+        rules.push({
+            rule: `${royaltyRulePackageId}::royalty_rule::Rule`,
+            packageId: royaltyRulePackageId,
+            resolveRuleFunction: resolveRoyaltyRule,
+        });
+    }
+
+    if (kioskLockRulePackageId) {
+        rules.push({
+            rule: `${kioskLockRulePackageId}::kiosk_lock_rule::Rule`,
+            packageId: kioskLockRulePackageId,
+            resolveRuleFunction: resolveKioskLockRule,
+            hasLockingRule: true,
+        });
+    }
+
+    if (personalKioskRulePackageId) {
+        rules.push({
+            rule: `${personalKioskRulePackageId}::personal_kiosk_rule::Rule`,
+            packageId: personalKioskRulePackageId,
+            resolveRuleFunction: resolvePersonalKioskRule,
+        });
+    }
+
+    if (floorPriceRulePackageId) {
+        rules.push({
+            rule: `${floorPriceRulePackageId}::floor_price_rule::Rule`,
+            packageId: floorPriceRulePackageId,
+            resolveRuleFunction: resolveFloorPriceRule,
+        });
+    }
+
+    return rules;
+}
+
+export const rules: TransferPolicyRule[] = Object.values(getAllNetworks())
+    .filter((network) => network.kiosk)
+    .flatMap((network) => getBaseRules(network.kiosk as KioskConfiguration));

package/src/index.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+export * from './utils.js';
+export * from './types/index.js';
+export * from './constants.js';
+export * from './client/kiosk-client.js';
+export * from './client/tp-transaction.js';
+export * from './client/kiosk-transaction.js';

package/src/query/kiosk.ts

@@ -0,0 +1,190 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+    PaginationArguments,
+    IotaClient,
+    IotaObjectData,
+    IotaObjectDataFilter,
+    IotaObjectResponse,
+} from '@iota/iota-sdk/client';
+import { isValidIotaAddress } from '@iota/iota-sdk/utils';
+
+import type {
+    FetchKioskOptions,
+    KioskExtension,
+    KioskListing,
+    OwnedKiosks,
+    PagedKioskData,
+} from '../types/index.js';
+import { KIOSK_OWNER_CAP } from '../types/index.js';
+import {
+    attachListingsAndPrices,
+    attachLockedItems,
+    attachObjects,
+    extractKioskData,
+    getAllDynamicFields,
+    getAllObjects,
+    getKioskObject,
+} from '../utils.js';
+
+export async function fetchKiosk(
+    client: IotaClient,
+    kioskId: string,
+    pagination: PaginationArguments<string>,
+    options: FetchKioskOptions,
+): Promise<PagedKioskData> {
+    // TODO: Replace the `getAllDynamicFields` with a paginated
+    // response, once we have better RPC support for
+    // type filtering & batch fetching.
+    // This can't work with pagination currently.
+    const data = await getAllDynamicFields(client, kioskId, pagination);
+
+    const listings: KioskListing[] = [];
+    const lockedItemIds: string[] = [];
+
+    // extracted kiosk data.
+    const kioskData = extractKioskData(data, listings, lockedItemIds, kioskId);
+
+    // split the fetching in two queries as we are most likely passing different options for each kind.
+    // For items, we usually seek the Display.
+    // For listings we usually seek the DF value (price) / exclusivity.
+    const [kiosk, listingObjects, items] = await Promise.all([
+        options.withKioskFields ? getKioskObject(client, kioskId) : Promise.resolve(undefined),
+        options.withListingPrices
+            ? getAllObjects(client, kioskData.listingIds, {
+                  showContent: true,
+              })
+            : Promise.resolve([]),
+        options.withObjects
+            ? getAllObjects(
+                  client,
+                  kioskData.itemIds,
+                  options.objectOptions || { showDisplay: true },
+              )
+            : Promise.resolve([]),
+    ]);
+
+    if (options.withKioskFields) kioskData.kiosk = kiosk;
+    // attach items listings. IF we have `options.withListingPrices === true`, it will also attach the prices.
+    attachListingsAndPrices(kioskData, listings, listingObjects);
+    // add `locked` status to items that are locked.
+    attachLockedItems(kioskData, lockedItemIds);
+
+    // Attach the objects for the queried items.
+    attachObjects(
+        kioskData,
+        items.filter((x) => !!x.data).map((x) => x.data!),
+    );
+
+    return {
+        data: kioskData,
+        nextCursor: null,
+        hasNextPage: false,
+    };
+}
+
+/**
+ * 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.
+ */
+export async function getOwnedKiosks(
+    client: IotaClient,
+    address: string,
+    options?: {
+        pagination?: PaginationArguments<string>;
+        personalKioskType: string;
+    },
+): Promise<OwnedKiosks> {
+    if (!isValidIotaAddress(address))
+        return {
+            nextCursor: null,
+            hasNextPage: false,
+            kioskOwnerCaps: [],
+            kioskIds: [],
+        };
+
+    const filter: IotaObjectDataFilter = {
+        MatchAny: [
+            {
+                StructType: KIOSK_OWNER_CAP,
+            },
+        ],
+    };
+
+    if (options?.personalKioskType) {
+        filter.MatchAny.push({
+            StructType: options.personalKioskType,
+        });
+    }
+
+    // fetch owned kiosk caps, paginated.
+    const { data, hasNextPage, nextCursor } = await client.getOwnedObjects({
+        owner: address,
+        filter,
+        options: {
+            showContent: true,
+            showType: true,
+        },
+        ...(options?.pagination || {}),
+    });
+
+    // get kioskIds from the OwnerCaps.
+    const kioskIdList = data?.map((x: IotaObjectResponse) => {
+        const fields = x.data?.content?.dataType === 'moveObject' ? x.data.content.fields : null;
+        // @ts-expect-error TODO: should i remove ts ignore here?
+        return (fields?.cap ? fields?.cap?.fields?.for : fields?.for) as string;
+        // return (fields as { for: string })?.for;
+    });
+
+    // clean up data that might have an error in them.
+    // only return valid objects.
+    const filteredData = data.filter((x) => 'data' in x).map((x) => x.data) as IotaObjectData[];
+
+    return {
+        nextCursor,
+        hasNextPage,
+        kioskOwnerCaps: filteredData.map((x, idx) => ({
+            isPersonal: x.type !== KIOSK_OWNER_CAP,
+            digest: x.digest,
+            version: x.version,
+            objectId: x.objectId,
+            kioskId: kioskIdList[idx],
+        })),
+        kioskIds: kioskIdList,
+    };
+}
+
+// Get a kiosk extension data for a given kioskId and extensionType.
+export async function fetchKioskExtension(
+    client: IotaClient,
+    kioskId: string,
+    extensionType: string,
+): Promise<KioskExtension | null> {
+    const extension = await client.getDynamicFieldObject({
+        parentId: kioskId,
+        name: {
+            type: `0x2::kiosk_extension::ExtensionKey<${extensionType}>`,
+            value: {
+                dummy_field: false,
+            },
+        },
+    });
+
+    if (!extension.data) return null;
+
+    const fields = (extension?.data?.content as { fields: { [k: string]: any } })?.fields?.value
+        ?.fields;
+
+    return {
+        objectId: extension.data.objectId,
+        type: extensionType,
+        isEnabled: fields?.is_enabled,
+        permissions: fields?.permissions,
+        storageId: fields?.storage?.fields?.id?.id,
+        storageSize: fields?.storage?.fields?.size,
+    };
+}