@iota/kiosk 0.0.0-dev-20251015065834

package/src/types/index.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { IotaClient, NetworkId } from '@iota/iota-sdk/client';
+import type { TransactionObjectArgument } from '@iota/iota-sdk/transactions';
+
+import type { BaseRulePackageIds } from '../constants.js';
+
+export * from './kiosk.js';
+export * from './transfer-policy.js';
+
+/**
+ * A valid argument for any of the Kiosk functions.
+ */
+export type ObjectArgument = string | TransactionObjectArgument;
+
+/**
+ * The Client Options for Both KioskClient & TransferPolicyManager.
+ */
+export type KioskClientOptions = {
+    client: IotaClient;
+    network: NetworkId;
+    packageIds?: BaseRulePackageIds;
+};

package/src/types/kiosk.ts

@@ -0,0 +1,178 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+    PaginatedObjectsResponse,
+    IotaObjectData,
+    IotaObjectDataOptions,
+} from '@iota/iota-sdk/client';
+import type { TransactionArgument } from '@iota/iota-sdk/transactions';
+
+import type { ObjectArgument } from './index.js';
+
+/** The Kiosk module. */
+export const KIOSK_MODULE = '0x2::kiosk';
+
+/** The Kiosk type. */
+export const KIOSK_TYPE = `${KIOSK_MODULE}::Kiosk`;
+
+/** The Kiosk Owner Cap Type */
+export const KIOSK_OWNER_CAP = `${KIOSK_MODULE}::KioskOwnerCap`;
+
+/** The Kiosk Item Type */
+export const KIOSK_ITEM = `${KIOSK_MODULE}::Item`;
+
+/** The Kiosk Listing Type */
+export const KIOSK_LISTING = `${KIOSK_MODULE}::Listing`;
+
+/** The Kiosk Lock Type */
+export const KIOSK_LOCK = `${KIOSK_MODULE}::Lock`;
+
+/** The Kiosk PurchaseCap type */
+export const KIOSK_PURCHASE_CAP = `${KIOSK_MODULE}::PurchaseCap`;
+
+/**
+ * The Kiosk object fields (for BCS queries).
+ */
+export type Kiosk = {
+    id: string;
+    profits: string;
+    owner: string;
+    itemCount: number;
+};
+
+/**
+ * PurchaseCap object fields (for BCS queries).
+ */
+export type PurchaseCap = {
+    id: string;
+    kioskId: string;
+    itemId: string;
+    minPrice: string;
+};
+
+/**
+ * The response type of a successful purchase flow.
+ * Returns the item, and a `canTransfer` param.
+ */
+export type PurchaseAndResolvePoliciesResponse = {
+    item: TransactionArgument;
+    canTransfer: boolean;
+};
+
+/**
+ * Optional parameters for `purchaseAndResolvePolicies` flow.
+ * This gives us the chance to extend the function in further releases
+ * without introducing more breaking changes.
+ */
+export type PurchaseOptionalParams = {
+    ownedKiosk?: ObjectArgument;
+    ownedKioskCap?: ObjectArgument;
+};
+
+/**
+ * A dynamic field `Listing { ID, isExclusive }` attached to the Kiosk.
+ * Holds a `u64` value - the price of the item.
+ */
+export type KioskListing = {
+    /** The ID of the Item */
+    objectId: string;
+    /**
+     * Whether or not there's a `PurchaseCap` issued. `true` means that
+     * the listing is controlled by some logic and can't be purchased directly.
+     *
+     * TODO: consider renaming the field for better indication.
+     */
+    isExclusive: boolean;
+    /** The ID of the listing */
+    listingId: string;
+    price?: string;
+};
+
+/**
+ * A dynamic field `Item { ID }` attached to the Kiosk.
+ * Holds an Item `T`. The type of the item is known upfront.
+ */
+export type KioskItem = {
+    /** The ID of the Item */
+    objectId: string;
+    /** The type of the Item */
+    type: string;
+    /** Whether the item is Locked (there must be a `Lock` Dynamic Field) */
+    isLocked: boolean;
+    /** Optional listing */
+    listing?: KioskListing;
+    /** The ID of the kiosk the item is placed in */
+    kioskId: string;
+    /** Optional Kiosk Data */
+    data?: IotaObjectData;
+};
+
+/** The overview type returned from `getKiosk` */
+export type KioskExtensionOverview = {
+    /** The ID of the extension's DF */
+    objectId: string;
+    /** The inner type of the Extension */
+    type: string;
+};
+/**
+ * Hold the KioskExtension data
+ */
+export type KioskExtension = KioskExtensionOverview & {
+    /** These fields are only there if we have `withExtensions` flag */
+    isEnabled: boolean;
+    permissions: string;
+    storageId: string;
+    storageSize: number;
+};
+
+/**
+ * Aggregated data from the Kiosk.
+ */
+export type KioskData = {
+    items: KioskItem[];
+    itemIds: string[];
+    listingIds: string[];
+    kiosk?: Kiosk;
+    extensions: KioskExtensionOverview[]; // type will be defined on later versions of the SDK.
+};
+
+export type PagedKioskData = {
+    data: KioskData;
+    nextCursor: string | null | undefined;
+    hasNextPage: boolean;
+};
+
+export type FetchKioskOptions = {
+    /** Include the base kiosk object, which includes the profits, the owner and the base fields. */
+    withKioskFields?: boolean;
+    /** Include the listing prices. */
+    withListingPrices?: boolean;
+    /** Include the objects for the Items in the kiosk. Defaults to `display` only. */
+    withObjects?: boolean;
+    /** Pass the data options for the objects, when fetching, in case you want to query other details. */
+    objectOptions?: IotaObjectDataOptions;
+};
+
+export type OwnedKiosks = {
+    kioskOwnerCaps: KioskOwnerCap[];
+    kioskIds: string[];
+} & Omit<PaginatedObjectsResponse, 'data'>;
+
+export type KioskOwnerCap = {
+    isPersonal?: boolean;
+    objectId: string;
+    kioskId: string;
+    digest: string;
+    version: string;
+};
+
+export type PurchaseOptions = {
+    extraArgs?: Record<string, any>;
+};
+
+export type ItemId = { itemType: string; itemId: string };
+export type ItemReference = { itemType: string; item: ObjectArgument };
+export type ItemValue = { itemType: string; item: TransactionArgument };
+export type Price = { price: string | bigint };

package/src/types/transfer-policy.ts

@@ -0,0 +1,70 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ObjectOwner } from '@iota/iota-sdk/client';
+import type { Transaction, TransactionObjectArgument } from '@iota/iota-sdk/transactions';
+
+import type { ObjectArgument } from './index.js';
+
+/** The Transfer Policy module. */
+export const TRANSFER_POLICY_MODULE = '0x2::transfer_policy';
+
+/** Name of the event emitted when a TransferPolicy for T is created. */
+export const TRANSFER_POLICY_CREATED_EVENT = `${TRANSFER_POLICY_MODULE}::TransferPolicyCreated`;
+
+/** The Transfer Policy Type */
+export const TRANSFER_POLICY_TYPE = `${TRANSFER_POLICY_MODULE}::TransferPolicy`;
+
+/** The Transfer Policy Cap Type */
+export const TRANSFER_POLICY_CAP_TYPE = `${TRANSFER_POLICY_MODULE}::TransferPolicyCap`;
+
+/** The Kiosk Lock Rule */
+export const KIOSK_LOCK_RULE = 'kiosk_lock_rule::Rule';
+
+/** The Royalty rule */
+export const ROYALTY_RULE = 'royalty_rule::Rule';
+
+/**
+ * The Transfer Policy Cap in a consumable way.
+ */
+export type TransferPolicyCap = {
+    policyId: string;
+    policyCapId: string;
+    type: string;
+};
+
+/** The `TransferPolicy` object */
+export type TransferPolicy = {
+    id: string;
+    type: string;
+    balance: string;
+    rules: string[];
+    owner: ObjectOwner;
+};
+
+/** Event emitted when a TransferPolicy is created. */
+export type TransferPolicyCreated = {
+    id: string;
+};
+
+// The object a Rule resolving function accepts
+// It can accept a set of fixed fields, that are part of every purchase flow as well any extra arguments to resolve custom policies!
+// Each rule resolving function should check that the key it's seeking is in the object
+// e.g. `if(!'my_key' in ruleParams!) throw new Error("Can't resolve that rule!")`
+export type RuleResolvingParams = {
+    transaction: Transaction;
+    /** @deprecated use transaction instead */
+    transactionBlock: Transaction;
+    itemType: string;
+    itemId: string;
+    price: string;
+    policyId: ObjectArgument;
+    sellerKiosk: ObjectArgument;
+    kiosk: ObjectArgument;
+    kioskCap: ObjectArgument;
+    transferRequest: TransactionObjectArgument;
+    purchasedItem: TransactionObjectArgument;
+    packageId: string;
+    extraArgs: Record<string, any>; // extraParams contains more possible {key, values} to pass for custom rules.
+};

package/src/utils.ts

@@ -0,0 +1,289 @@
+// Copyright (c) Mysten Labs, Inc.
+// Modifications Copyright (c) 2024 IOTA Stiftung
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+    DynamicFieldInfo,
+    PaginationArguments,
+    IotaClient,
+    IotaObjectData,
+    IotaObjectDataFilter,
+    IotaObjectDataOptions,
+    IotaObjectResponse,
+} from '@iota/iota-sdk/client';
+import {
+    fromBase64,
+    normalizeStructTag,
+    normalizeIotaAddress,
+    parseStructTag,
+} from '@iota/iota-sdk/utils';
+
+import { KioskType } from './bcs.js';
+import type { Kiosk, KioskData, KioskListing, TransferPolicyCap } from './types/index.js';
+import { TRANSFER_POLICY_CAP_TYPE } from './types/index.js';
+
+const DEFAULT_QUERY_LIMIT = 50;
+
+export async function getKioskObject(client: IotaClient, id: string): Promise<Kiosk> {
+    const queryRes = await client.getObject({ id, options: { showBcs: true } });
+
+    if (!queryRes || queryRes.error || !queryRes.data) {
+        throw new Error(`Kiosk ${id} not found; ${queryRes.error}`);
+    }
+
+    if (!queryRes.data.bcs || !('bcsBytes' in queryRes.data.bcs)) {
+        throw new Error(`Invalid kiosk query: ${id}, expected object, got package`);
+    }
+
+    return KioskType.parse(fromBase64(queryRes.data.bcs!.bcsBytes));
+}
+
+// helper to extract kiosk data from dynamic fields.
+export function extractKioskData(
+    data: DynamicFieldInfo[],
+    listings: KioskListing[],
+    lockedItemIds: string[],
+    kioskId: string,
+): KioskData {
+    return data.reduce<KioskData>(
+        (acc: KioskData, val: DynamicFieldInfo) => {
+            const type = val.name.type;
+
+            if (type.startsWith('0x2::kiosk::Item')) {
+                acc.itemIds.push(val.objectId);
+                acc.items.push({
+                    objectId: val.objectId,
+                    type: val.objectType,
+                    isLocked: false,
+                    kioskId,
+                });
+            }
+            if (type.startsWith('0x2::kiosk::Listing')) {
+                acc.listingIds.push(val.objectId);
+                listings.push({
+                    objectId: (val.name.value as { id: string }).id,
+                    listingId: val.objectId,
+                    isExclusive: (val.name.value as { is_exclusive: boolean }).is_exclusive,
+                });
+            }
+            if (type.startsWith('0x2::kiosk::Lock')) {
+                lockedItemIds?.push((val.name.value as { id: string }).id);
+            }
+
+            if (type.startsWith('0x2::kiosk_extension::ExtensionKey')) {
+                acc.extensions.push({
+                    objectId: val.objectId,
+                    type: normalizeStructTag(parseStructTag(val.name.type).typeParams[0]),
+                });
+            }
+
+            return acc;
+        },
+        { items: [], itemIds: [], listingIds: [], extensions: [] },
+    );
+}
+
+/**
+ * A helper that attaches the listing prices to kiosk listings.
+ */
+export function attachListingsAndPrices(
+    kioskData: KioskData,
+    listings: KioskListing[],
+    listingObjects: IotaObjectResponse[],
+) {
+    // map item listings as {item_id: KioskListing}
+    // for easier mapping on the nex
+    const itemListings = listings.reduce<Record<string, KioskListing>>(
+        (acc: Record<string, KioskListing>, item, idx) => {
+            acc[item.objectId] = { ...item };
+
+            // return in case we don't have any listing objects.
+            // that's the case when we don't have the `listingPrices` included.
+            if (listingObjects.length === 0) return acc;
+
+            const content = listingObjects[idx].data?.content;
+            const data = content?.dataType === 'moveObject' ? content?.fields : null;
+
+            if (!data) return acc;
+
+            acc[item.objectId].price = (data as { value: string }).value;
+            return acc;
+        },
+        {},
+    );
+
+    kioskData.items.forEach((item) => {
+        item.listing = itemListings[item.objectId] || undefined;
+    });
+}
+
+/**
+ * A helper that attaches the listing prices to kiosk listings.
+ */
+export function attachObjects(kioskData: KioskData, objects: IotaObjectData[]) {
+    const mapping = objects.reduce<Record<string, IotaObjectData>>(
+        (acc: Record<string, IotaObjectData>, obj) => {
+            acc[obj.objectId] = obj;
+            return acc;
+        },
+        {},
+    );
+
+    kioskData.items.forEach((item) => {
+        item.data = mapping[item.objectId] || undefined;
+    });
+}
+
+/**
+ * A Helper to attach locked state to items in Kiosk Data.
+ */
+export function attachLockedItems(kioskData: KioskData, lockedItemIds: string[]) {
+    // map lock status in an array of type { item_id: true }
+    const lockedStatuses = lockedItemIds.reduce<Record<string, boolean>>(
+        (acc: Record<string, boolean>, item: string) => {
+            acc[item] = true;
+            return acc;
+        },
+        {},
+    );
+
+    // parse lockedItemIds and attach their locked status.
+    kioskData.items.forEach((item) => {
+        item.isLocked = lockedStatuses[item.objectId] || false;
+    });
+}
+
+/**
+ * A helper to fetch all DF pages.
+ * We need that to fetch the kiosk DFs consistently, until we have
+ * RPC calls that allow filtering of Type / batch fetching of spec
+ */
+export async function getAllDynamicFields(
+    client: IotaClient,
+    parentId: string,
+    pagination: PaginationArguments<string>,
+) {
+    let hasNextPage = true;
+    let cursor = undefined;
+    const data: DynamicFieldInfo[] = [];
+
+    while (hasNextPage) {
+        const result = await client.getDynamicFields({
+            parentId,
+            limit: pagination.limit || undefined,
+            cursor,
+        });
+        data.push(...result.data);
+        hasNextPage = result.hasNextPage;
+        cursor = result.nextCursor;
+    }
+
+    return data;
+}
+
+/**
+ * A helper to fetch all objects that works with pagination.
+ * It will fetch all objects in the array, and limit it to 50/request.
+ * Requests are sent using `Promise.all`.
+ */
+export async function getAllObjects(
+    client: IotaClient,
+    ids: string[],
+    options: IotaObjectDataOptions,
+    limit: number = DEFAULT_QUERY_LIMIT,
+) {
+    const chunks = Array.from({ length: Math.ceil(ids.length / limit) }, (_, index) =>
+        ids.slice(index * limit, index * limit + limit),
+    );
+
+    const results = await Promise.all(
+        chunks.map((chunk) => {
+            return client.multiGetObjects({
+                ids: chunk,
+                options,
+            });
+        }),
+    );
+
+    return results.flat();
+}
+
+/**
+ * A helper to return all owned objects, with an optional filter.
+ * It parses all the pages and returns the data.
+ */
+export async function getAllOwnedObjects({
+    client,
+    owner,
+    filter,
+    limit = DEFAULT_QUERY_LIMIT,
+    options = { showType: true, showContent: true },
+}: {
+    client: IotaClient;
+    owner: string;
+    filter?: IotaObjectDataFilter;
+    options?: IotaObjectDataOptions;
+    limit?: number;
+}) {
+    let hasNextPage = true;
+    let cursor = undefined;
+    const data: IotaObjectResponse[] = [];
+
+    while (hasNextPage) {
+        const result = await client.getOwnedObjects({
+            owner,
+            filter,
+            limit,
+            cursor,
+            options,
+        });
+        data.push(...result.data);
+        hasNextPage = result.hasNextPage;
+        cursor = result.nextCursor;
+    }
+
+    return data;
+}
+
+/**
+ * Converts a number to basis points.
+ * Supports up to 2 decimal points.
+ * E.g 9.95 -> 995
+ * @param percentage A percentage amount in the range [0, 100] including decimals.
+ */
+export function percentageToBasisPoints(percentage: number) {
+    if (percentage < 0 || percentage > 100)
+        throw new Error('Percentage needs to be in the [0,100] range.');
+    return Math.ceil(percentage * 100);
+}
+
+/**
+ * A helper to parse a transfer policy Cap into a usable object.
+ */
+export function parseTransferPolicyCapObject(
+    item: IotaObjectResponse,
+): TransferPolicyCap | undefined {
+    const type = (item?.data?.content as { type: string })?.type;
+
+    //@ts-expect-error Silencing error here
+    const policy = item?.data?.content?.fields?.policy_id as string;
+
+    if (!type.includes(TRANSFER_POLICY_CAP_TYPE)) return undefined;
+
+    // Transform 0x2::transfer_policy::TransferPolicyCap<itemType> -> itemType
+    const objectType = type.replace(TRANSFER_POLICY_CAP_TYPE + '<', '').slice(0, -1);
+
+    return {
+        policyId: policy,
+        // eslint-disable-next-line @typescript-eslint/no-non-null-asserted-optional-chain
+        policyCapId: item.data?.objectId!,
+        type: objectType,
+    };
+}
+
+// Normalizes the packageId part of a rule's type.
+export function getNormalizedRuleType(rule: string) {
+    const normalizedRuleAddress = rule.split('::');
+    normalizedRuleAddress[0] = normalizeIotaAddress(normalizedRuleAddress[0]);
+    return normalizedRuleAddress.join('::');
+}