@haneullabs/kiosk 0.1.0

package/src/query/kiosk.ts

@@ -0,0 +1,264 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+	PaginatedObjectsResponse,
+	PaginationArguments,
+	HaneulClient,
+	HaneulObjectData,
+	HaneulObjectResponse,
+} from '@haneullabs/haneul/client';
+import { isValidHaneulAddress } from '@haneullabs/haneul/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: HaneulClient,
+	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.
+ */
+
+const DEFAULT_PAGE_SIZE = 50;
+const PERSON_KIOSK_CURSOR = 'personal';
+const OWNED_KIOSKS_CURSOR = 'owned';
+export async function getOwnedKiosks(
+	client: HaneulClient,
+	address: string,
+	options?: {
+		pagination?: PaginationArguments<string>;
+		personalKioskType: string;
+	},
+): Promise<OwnedKiosks> {
+	// TODO: this should throw an error, but I am not going to change it right now incase it breaks existing code.
+	if (!isValidHaneulAddress(address)) {
+		return {
+			nextCursor: null,
+			hasNextPage: false,
+			kioskOwnerCaps: [],
+			kioskIds: [],
+		};
+	}
+
+	const limit = options?.pagination?.limit ?? DEFAULT_PAGE_SIZE;
+	const [cursorType, cursor] = options?.pagination?.cursor?.split(':') ?? [
+		PERSON_KIOSK_CURSOR,
+		null,
+	];
+
+	if (options?.personalKioskType && cursorType === PERSON_KIOSK_CURSOR) {
+		const personalKioskResponse = formatOwnedKioskResponse(
+			await client.getOwnedObjects({
+				owner: address,
+				filter: {
+					StructType: options.personalKioskType,
+				},
+				options: {
+					showContent: true,
+					showType: true,
+				},
+				cursor,
+				limit,
+			}),
+			PERSON_KIOSK_CURSOR,
+		);
+
+		if (personalKioskResponse.hasNextPage) {
+			return personalKioskResponse;
+		}
+
+		const remainingLimit = limit - personalKioskResponse.kioskOwnerCaps.length;
+
+		// If we have all personal kiosks, but don't have space for the owned kiosks
+		// we need to start loading owned kiosks for the next page, but don't have a real cursor
+		if (remainingLimit < 1) {
+			return {
+				nextCursor: `${OWNED_KIOSKS_CURSOR}:`,
+				hasNextPage: true,
+				kioskOwnerCaps: personalKioskResponse.kioskOwnerCaps,
+				kioskIds: personalKioskResponse.kioskIds,
+			};
+		}
+
+		const ownedKiosksResponse = formatOwnedKioskResponse(
+			await client.getOwnedObjects({
+				owner: address,
+				filter: {
+					StructType: KIOSK_OWNER_CAP,
+				},
+				options: {
+					showContent: true,
+					showType: true,
+				},
+				limit: remainingLimit,
+			}),
+			OWNED_KIOSKS_CURSOR,
+		);
+
+		return {
+			nextCursor: ownedKiosksResponse.nextCursor,
+			hasNextPage: ownedKiosksResponse.hasNextPage,
+			kioskOwnerCaps: [
+				...personalKioskResponse.kioskOwnerCaps,
+				...ownedKiosksResponse.kioskOwnerCaps,
+			],
+			kioskIds: [...personalKioskResponse.kioskIds, ...ownedKiosksResponse.kioskIds],
+		};
+	}
+
+	return formatOwnedKioskResponse(
+		await client.getOwnedObjects({
+			owner: address,
+			filter: {
+				StructType: KIOSK_OWNER_CAP,
+			},
+			options: {
+				showContent: true,
+				showType: true,
+			},
+			// cursor might be an empty string if the number of personal kiosks was a multiple of the limit.
+			cursor: cursor ? cursor : null,
+			limit,
+		}),
+		OWNED_KIOSKS_CURSOR,
+	);
+}
+
+function formatOwnedKioskResponse(
+	response: PaginatedObjectsResponse,
+	cursorType: string,
+): OwnedKiosks {
+	const { data, hasNextPage, nextCursor } = response;
+	// get kioskIds from the OwnerCaps.
+	const kioskIdList = data?.map((x: HaneulObjectResponse) => {
+		const fields =
+			x.data?.content?.dataType === 'moveObject'
+				? (x.data.content.fields as unknown as
+						| {
+								cap: { fields: { for: string } };
+								for?: never;
+						  }
+						| {
+								cap?: never;
+								for: string;
+						  })
+				: null;
+		return fields?.cap ? fields?.cap?.fields?.for : (fields?.for as string);
+	});
+
+	// 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 HaneulObjectData[];
+
+	return {
+		nextCursor: nextCursor ? `${cursorType}:${nextCursor}` : 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: HaneulClient,
+	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,
+	};
+}

package/src/query/transfer-policy.ts

@@ -0,0 +1,134 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HaneulClient } from '@haneullabs/haneul/client';
+import { fromBase64, isValidHaneulAddress } from '@haneullabs/haneul/utils';
+
+import '../bcs.js';
+
+import { TransferPolicyType } 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 seach 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: HaneulClient,
+	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 = TransferPolicyType.parse(fromBase64(policy.bcs.bcsBytes));
+
+			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: HaneulClient,
+	address: string,
+	type: string,
+): Promise<TransferPolicyCap[]> {
+	if (!isValidHaneulAddress(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: HaneulClient,
+	address: string,
+): Promise<TransferPolicyCap[] | undefined> {
+	if (!isValidHaneulAddress(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,243 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs } from '@haneullabs/haneul/bcs';
+import type {
+	Transaction,
+	TransactionArgument,
+	TransactionObjectArgument,
+} from '@haneullabs/haneul/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: Transaction,
+): [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: Transaction): TransactionObjectArgument {
+	const [kiosk, kioskOwnerCap] = createKiosk(tx);
+	shareKiosk(tx, kiosk);
+	return kioskOwnerCap;
+}
+
+/**
+ * Converts Transfer Policy to a shared object.
+ */
+export function shareKiosk(tx: Transaction, 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: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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<SUI>)` function and receive an Item and
+ * a TransferRequest which needs to be dealt with (via a matching TransferPolicy).
+ */
+export function purchase(
+	tx: Transaction,
+	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<SUI>.
+ * If the amount is null, then the entire balance will be withdrawn.
+ */
+export function withdrawFromKiosk(
+	tx: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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,34 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Transaction, TransactionObjectArgument } from '@haneullabs/haneul/transactions';
+
+import type { ObjectArgument } from '../types/index.js';
+
+export function convertToPersonalTx(
+	tx: Transaction,
+	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: Transaction,
+	personalKioskCap: TransactionObjectArgument,
+	packageId: string,
+) {
+	tx.moveCall({
+		target: `${packageId}::personal_kiosk::transfer_to_sender`,
+		arguments: [personalKioskCap],
+	});
+}