@haneullabs/kiosk 0.1.0

package/src/tx/rules/attach.ts

@@ -0,0 +1,73 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Transaction } from '@haneullabs/haneul/transactions';
+
+import type { ObjectArgument } from '../../types/index.js';
+
+export function attachKioskLockRuleTx(
+	tx: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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,126 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { bcs } from '@haneullabs/haneul/bcs';
+import type { TransactionArgument } from '@haneullabs/haneul/transactions';
+import { Transaction } from '@haneullabs/haneul/transactions';
+import { normalizeHaneulAddress } from '@haneullabs/haneul/utils';
+
+import type { RuleResolvingParams } from '../../types/index.js';
+import { lock } from '../kiosk.js';
+
+/**
+ * A helper to resolve the royalty rule.
+ */
+export async function resolveRoyaltyRule(params: RuleResolvingParams) {
+	const {
+		kioskClient,
+		transaction: tx,
+		itemType,
+		price,
+		packageId,
+		transferRequest,
+		policyId,
+	} = params;
+
+	// We attempt to resolve the fee amount outside of the PTB so that the split amount is known before the transaction is sent.
+	// This improves the display of the transaction within the wallet.
+
+	const feeTx = new Transaction();
+
+	// calculates the amount
+	feeTx.moveCall({
+		target: `${packageId}::royalty_rule::fee_amount`,
+		typeArguments: [itemType],
+		arguments: [feeTx.object(policyId), feeTx.pure.u64(price || '0')],
+	});
+
+	const policyObj = tx.object(policyId);
+
+	const { results } = await kioskClient.client.devInspectTransactionBlock({
+		sender: tx.getData().sender || normalizeHaneulAddress('0x0'),
+		transactionBlock: feeTx,
+	});
+
+	let amount: TransactionArgument | bigint | null = null;
+	if (results) {
+		const returnedAmount = results?.[0].returnValues?.[0]?.[0];
+		if (returnedAmount) {
+			amount = BigInt(bcs.U64.parse(new Uint8Array(returnedAmount as number[])));
+		}
+	}
+
+	// We were not able to calculate the amount outside of the transaction, so fall back to resolving it within the PTB
+	if (!amount) {
+		[amount] = tx.moveCall({
+			target: `${packageId}::royalty_rule::fee_amount`,
+			typeArguments: [itemType],
+			arguments: [policyObj, tx.pure.u64(price || '0')],
+		});
+	}
+
+	// splits the coin.
+	const feeCoin = tx.splitCoins(tx.gas, [amount]);
+
+	// pays the policy
+	tx.moveCall({
+		target: `${packageId}::royalty_rule::pay`,
+		typeArguments: [itemType],
+		arguments: [policyObj, transferRequest, feeCoin],
+	});
+}
+
+export function resolveKioskLockRule(params: RuleResolvingParams) {
+	const {
+		transaction: tx,
+		packageId,
+		itemType,
+		kiosk,
+		kioskCap,
+		policyId,
+		purchasedItem,
+		transferRequest,
+	} = params;
+
+	if (!kiosk || !kioskCap) throw new Error('Missing Owned Kiosk or Owned Kiosk Cap');
+
+	lock(tx, itemType, kiosk, kioskCap, policyId, purchasedItem);
+
+	// proves that the item is locked in the kiosk to the TP.
+	tx.moveCall({
+		target: `${packageId}::kiosk_lock_rule::prove`,
+		typeArguments: [itemType],
+		arguments: [transferRequest, tx.object(kiosk)],
+	});
+}
+
+/**
+ * A helper to resolve the personalKioskRule.
+ * @param params
+ */
+export function resolvePersonalKioskRule(params: RuleResolvingParams) {
+	const { transaction: tx, packageId, itemType, kiosk, transferRequest } = params;
+
+	if (!kiosk) throw new Error('Missing owned Kiosk.');
+
+	// proves that the destination kiosk is personal.
+	tx.moveCall({
+		target: `${packageId}::personal_kiosk_rule::prove`,
+		typeArguments: [itemType],
+		arguments: [tx.object(kiosk), transferRequest],
+	});
+}
+
+/**
+ * Resolves the floor price rule.
+ */
+export function resolveFloorPriceRule(params: RuleResolvingParams) {
+	const { transaction: tx, packageId, itemType, policyId, transferRequest } = params;
+
+	// proves that the destination kiosk is personal
+	tx.moveCall({
+		target: `${packageId}::floor_price_rule::prove`,
+		typeArguments: [itemType],
+		arguments: [tx.object(policyId), transferRequest],
+	});
+}

package/src/tx/transfer-policy.ts

@@ -0,0 +1,120 @@
+// 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 { 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: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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: Transaction,
+	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)],
+	});
+}

package/src/types/index.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HaneulClient } from '@haneullabs/haneul/client';
+import type { TransactionObjectArgument } from '@haneullabs/haneul/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;
+
+/**
+ * A Network selector.
+ * Kiosk SDK supports mainnet & testnet.
+ * Pass `custom` for any other network (devnet, localnet).
+ */
+export enum Network {
+	MAINNET = 'mainnet',
+	TESTNET = 'testnet',
+	CUSTOM = 'custom',
+}
+
+/**
+ * The Client Options for Both KioskClient & TransferPolicyManager.
+ */
+export type KioskClientOptions = {
+	client: HaneulClient;
+	network: Network;
+	packageIds?: BaseRulePackageIds;
+};

package/src/types/kiosk.ts

@@ -0,0 +1,178 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+	PaginatedObjectsResponse,
+	HaneulObjectData,
+	HaneulObjectDataOptions,
+} from '@haneullabs/haneul/client';
+import type { TransactionArgument } from '@haneullabs/haneul/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;
+	allowExtensions: boolean;
+};
+
+/**
+ * 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?: HaneulObjectData;
+};
+
+/** 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?: HaneulObjectDataOptions;
+};
+
+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,71 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { ObjectOwner } from '@haneullabs/haneul/client';
+import type { Transaction, TransactionObjectArgument } from '@haneullabs/haneul/transactions';
+
+import type { KioskClient } from '../client/kiosk-client.js';
+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.
+	kioskClient: KioskClient;
+};