@mysten/kiosk 0.5.3 → 0.7.0

package/src/client/tp-transaction.ts

@@ -0,0 +1,350 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { TransactionArgument, type TransactionBlock } from '@mysten/sui.js/transactions';
+
+import {
+	attachFloorPriceRuleTx,
+	attachKioskLockRuleTx,
+	attachPersonalKioskRuleTx,
+	attachRoyaltyRuleTx,
+} from '../tx/rules/attach';
+import {
+	createTransferPolicy,
+	createTransferPolicyWithoutSharing,
+	removeTransferPolicyRule,
+	shareTransferPolicy,
+	withdrawFromPolicy,
+} from '../tx/transfer-policy';
+import { TransferPolicyCap, type ObjectArgument } from '../types';
+import { KioskClient } from './kiosk-client';
+
+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 polciy 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 TransactionArgument);
+		this.transactionBlock.transferObjects(
+			[this.policyCap as TransactionArgument],
+			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 MIST.
+	 */
+	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 MIST.
+	 */
+	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

@@ -1,10 +1,117 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-/** The Transer Policy Rules package address on testnet */
-export const TESTNET_RULES_PACKAGE_ADDRESS =
-	'bd8fc1947cf119350184107a3087e2dc27efefa0dd82e25a1f699069fe81a585';
+import {
+	resolveFloorPriceRule,
+	resolveKioskLockRule,
+	resolvePersonalKioskRule,
+	resolveRoyaltyRule,
+} from './tx/rules//resolve';
+import { Network, type ObjectArgument, type RuleResolvingParams } from './types';
 
-/** The transfer policy rules package address on mainnet */
-export const MAINNET_RULES_PACKAGE_ADDRESS =
-	'0x434b5bd8f6a7b05fede0ff46c6e511d71ea326ed38056e3bcd681d2d7c2a7879';
+/**
+ * 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;
+};
+
+export const ROYALTY_RULE_ADDRESS: Record<Network, string> = {
+	[Network.TESTNET]: 'bd8fc1947cf119350184107a3087e2dc27efefa0dd82e25a1f699069fe81a585',
+	[Network.MAINNET]: '0x434b5bd8f6a7b05fede0ff46c6e511d71ea326ed38056e3bcd681d2d7c2a7879',
+	[Network.CUSTOM]: '',
+};
+
+export const KIOSK_LOCK_RULE_ADDRESS: Record<Network, string> = {
+	[Network.TESTNET]: 'bd8fc1947cf119350184107a3087e2dc27efefa0dd82e25a1f699069fe81a585',
+	[Network.MAINNET]: '0x434b5bd8f6a7b05fede0ff46c6e511d71ea326ed38056e3bcd681d2d7c2a7879',
+	[Network.CUSTOM]: '',
+};
+
+export const FLOOR_PRICE_RULE_ADDRESS: Record<Network, string> = {
+	[Network.TESTNET]: '0x06f6bdd3f2e2e759d8a4b9c252f379f7a05e72dfe4c0b9311cdac27b8eb791b1',
+	[Network.MAINNET]: '0x34cc6762780f4f6f153c924c0680cfe2a1fb4601e7d33cc28a92297b62de1e0e',
+	[Network.CUSTOM]: '',
+};
+
+export const PERSONAL_KIOSK_RULE_ADDRESS: Record<Network, string> = {
+	[Network.TESTNET]: '0x06f6bdd3f2e2e759d8a4b9c252f379f7a05e72dfe4c0b9311cdac27b8eb791b1',
+	[Network.MAINNET]: '0x0cb4bcc0560340eb1a1b929cabe56b33fc6449820ec8c1980d69bb98b649b802',
+	[Network.CUSTOM]: '',
+};
+
+/**
+ * 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;
+}
+
+// A list of testnet's base rules.
+export const testnetRules: TransferPolicyRule[] = getBaseRules({
+	royaltyRulePackageId: ROYALTY_RULE_ADDRESS[Network.TESTNET],
+	kioskLockRulePackageId: KIOSK_LOCK_RULE_ADDRESS[Network.TESTNET],
+	personalKioskRulePackageId: PERSONAL_KIOSK_RULE_ADDRESS[Network.TESTNET],
+	floorPriceRulePackageId: FLOOR_PRICE_RULE_ADDRESS[Network.TESTNET],
+});
+
+// A list of mainnet's base rules.
+export const mainnetRules: TransferPolicyRule[] = getBaseRules({
+	royaltyRulePackageId: ROYALTY_RULE_ADDRESS[Network.MAINNET],
+	kioskLockRulePackageId: KIOSK_LOCK_RULE_ADDRESS[Network.MAINNET],
+});
+
+export const rules: TransferPolicyRule[] = [...testnetRules, ...mainnetRules];

package/src/index.ts

@@ -1,12 +1,9 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-export * from './tx/kiosk';
-export * from './tx/transfer-policy';
-export * from './tx/rules';
-export * from './query/kiosk';
-export * from './bcs';
 export * from './utils';
-export * from './query/transfer-policy';
 export * from './types';
 export * from './constants';
+export * from './client/kiosk-client';
+export * from './client/tp-transaction';
+export * from './client/kiosk-transaction';

package/src/query/kiosk.ts

@@ -1,15 +1,15 @@
 // Copyright (c) Mysten Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-import { SuiObjectData, SuiObjectResponse } from '@mysten/sui.js/client';
-import { isValidSuiAddress } from '@mysten/sui.js/utils';
 import {
-	attachListingsAndPrices,
-	attachLockedItems,
-	extractKioskData,
-	getAllDynamicFields,
-	getKioskObject,
-} from '../utils';
+	PaginationArguments,
+	SuiClient,
+	SuiObjectData,
+	SuiObjectDataFilter,
+	SuiObjectResponse,
+} from '@mysten/sui.js/client';
+import { isValidSuiAddress } from '@mysten/sui.js/utils';
+
 import {
 	FetchKioskOptions,
 	KIOSK_OWNER_CAP,
@@ -17,7 +17,15 @@ import {
 	OwnedKiosks,
 	PagedKioskData,
 } from '../types';
-import { SuiClient, PaginationArguments } from '@mysten/sui.js/client';
+import {
+	attachListingsAndPrices,
+	attachLockedItems,
+	attachObjects,
+	extractKioskData,
+	getAllDynamicFields,
+	getAllObjects,
+	getKioskObject,
+} from '../utils';
 
 export async function fetchKiosk(
 	client: SuiClient,
@@ -35,21 +43,21 @@ export async function fetchKiosk(
 	const lockedItemIds: string[] = [];
 
 	// extracted kiosk data.
-	const kioskData = extractKioskData(data, listings, lockedItemIds);
+	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] = await Promise.all([
+	const [kiosk, listingObjects, items] = await Promise.all([
 		options.withKioskFields ? getKioskObject(client, kioskId) : Promise.resolve(undefined),
 		options.withListingPrices
-			? client.multiGetObjects({
-					ids: kioskData.listingIds,
-					options: {
-						showContent: true,
-					},
+			? 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;
@@ -58,6 +66,12 @@ export async function fetchKiosk(
 	// 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,
@@ -76,6 +90,7 @@ export async function getOwnedKiosks(
 	address: string,
 	options?: {
 		pagination?: PaginationArguments<string>;
+		personalKioskType: string;
 	},
 ): Promise<OwnedKiosks> {
 	if (!isValidSuiAddress(address))
@@ -86,12 +101,27 @@ export async function getOwnedKiosks(
 			kioskIds: [],
 		};
 
+	const filter: SuiObjectDataFilter = {
+		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: { StructType: KIOSK_OWNER_CAP },
+		filter,
 		options: {
 			showContent: true,
+			showType: true,
 		},
 		...(options?.pagination || {}),
 	});
@@ -99,7 +129,9 @@ export async function getOwnedKiosks(
 	// get kioskIds from the OwnerCaps.
 	const kioskIdList = data?.map((x: SuiObjectResponse) => {
 		const fields = x.data?.content?.dataType === 'moveObject' ? x.data.content.fields : null;
-		return (fields as { for: string })?.for;
+		// @ts-ignore-next-line 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.
@@ -110,6 +142,7 @@ export async function getOwnedKiosks(
 		nextCursor,
 		hasNextPage,
 		kioskOwnerCaps: filteredData.map((x, idx) => ({
+			isPersonal: x.type !== KIOSK_OWNER_CAP,
 			digest: x.digest,
 			version: x.version,
 			objectId: x.objectId,