@mysten/kiosk 0.2.0 → 0.3.1

package/src/constants.ts

@@ -0,0 +1,10 @@
+// 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';
+
+/** The transfer policy rules package address on mainnet */
+export const MAINNET_RULES_PACKAGE_ADDRESS =
+  '0x434b5bd8f6a7b05fede0ff46c6e511d71ea326ed38056e3bcd681d2d7c2a7879';

package/src/index.ts

@@ -7,3 +7,5 @@ export * from './query/kiosk';
 export * from './bcs';
 export * from './utils';
 export * from './query/transfer-policy';
+export * from './types';
+export * from './constants';

package/src/query/kiosk.ts

@@ -4,72 +4,27 @@
 import {
   JsonRpcProvider,
   ObjectId,
-  ObjectType,
   PaginationArguments,
   SuiAddress,
+  SuiObjectData,
+  SuiObjectResponse,
+  getObjectFields,
+  isValidSuiAddress,
 } from '@mysten/sui.js';
 import {
   attachListingsAndPrices,
   attachLockedItems,
   extractKioskData,
+  getAllDynamicFields,
   getKioskObject,
 } from '../utils';
-import { Kiosk } from '../bcs';
-
-/**
- * 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: ObjectId;
-  /**
-   * 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: ObjectId;
-  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: ObjectId;
-  /** The type of the Item */
-  type: ObjectType;
-  /** Whether the item is Locked (there must be a `Lock` Dynamic Field) */
-  isLocked: boolean;
-  /** Optional listing */
-  listing?: KioskListing;
-};
-/**
- * Aggregated data from the Kiosk.
- */
-export type KioskData = {
-  items: KioskItem[];
-  itemIds: ObjectId[];
-  listingIds: ObjectId[];
-  kiosk?: Kiosk;
-  extensions: any[]; // type will be defined on later versions of the SDK.
-};
-
-export type PagedKioskData = {
-  data: KioskData;
-  nextCursor: string | null;
-  hasNextPage: boolean;
-};
-
-export type FetchKioskOptions = {
-  withKioskFields?: boolean;
-  withListingPrices?: boolean;
-};
+import {
+  FetchKioskOptions,
+  KIOSK_OWNER_CAP,
+  KioskListing,
+  OwnedKiosks,
+  PagedKioskData,
+} from '../types';
 
 export async function fetchKiosk(
   provider: JsonRpcProvider,
@@ -77,10 +32,11 @@ export async function fetchKiosk(
   pagination: PaginationArguments<string>,
   options: FetchKioskOptions,
 ): Promise<PagedKioskData> {
-  const { data, nextCursor, hasNextPage } = await provider.getDynamicFields({
-    parentId: kioskId,
-    ...pagination,
-  });
+  // 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(provider, kioskId, pagination);
 
   const listings: KioskListing[] = [];
   const lockedItemIds: ObjectId[] = [];
@@ -113,7 +69,62 @@ export async function fetchKiosk(
 
   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(
+  provider: JsonRpcProvider,
+  address: SuiAddress,
+  options?: {
+    pagination?: PaginationArguments<string>;
+  },
+): Promise<OwnedKiosks> {
+  if (!isValidSuiAddress(address))
+    return {
+      nextCursor: null,
+      hasNextPage: false,
+      kioskOwnerCaps: [],
+      kioskIds: [],
+    };
+
+  // fetch owned kiosk caps, paginated.
+  const { data, hasNextPage, nextCursor } = await provider.getOwnedObjects({
+    owner: address,
+    filter: { StructType: KIOSK_OWNER_CAP },
+    options: {
+      showContent: true,
+    },
+    ...(options?.pagination || {}),
+  });
+
+  // get kioskIds from the OwnerCaps.
+  const kioskIdList = data?.map(
+    (x: SuiObjectResponse) => getObjectFields(x)?.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 SuiObjectData[];
+
+  return {
     nextCursor,
     hasNextPage,
+    kioskOwnerCaps: filteredData.map((x, idx) => ({
+      digest: x.digest,
+      version: x.version,
+      objectId: x.objectId,
+      kioskId: kioskIdList[idx],
+    })),
+    kioskIds: kioskIdList,
   };
 }

package/src/query/transfer-policy.ts

@@ -2,10 +2,12 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { JsonRpcProvider } from '@mysten/sui.js';
-import { TransferPolicy, bcs } from '../bcs';
-
-/** Name of the event emitted when a TransferPolicy for T is created. */
-export const TRANSFER_POLICY_CREATED_EVENT = `0x2::transfer_policy::TransferPolicyCreated`;
+import { bcs } from '../bcs';
+import {
+  TRANSFER_POLICY_CREATED_EVENT,
+  TRANSFER_POLICY_TYPE,
+  TransferPolicy,
+} from '../types';
 
 /**
  * Searches the `TransferPolicy`-s for the given type. The seach is performed via
@@ -44,15 +46,11 @@ export async function queryTransferPolicy(
         );
       }
 
-      let parsed = bcs.de(
-        '0x2::transfer_policy::TransferPolicy',
-        policy.bcs.bcsBytes,
-        'base64',
-      );
+      let parsed = bcs.de(TRANSFER_POLICY_TYPE, policy.bcs.bcsBytes, 'base64');
 
       return {
         id: policy?.objectId,
-        type: `0x2::transfer_policy::TransferPolicy<${type}>`,
+        type: `${TRANSFER_POLICY_TYPE}<${type}>`,
         owner: policy?.owner!,
         rules: parsed.rules,
         balance: parsed.balance,

package/src/tx/kiosk.ts

@@ -7,19 +7,23 @@ import {
   TransactionBlock,
 } from '@mysten/sui.js';
 
-import { ObjectArgument, getTypeWithoutPackageAddress, objArg } from '../utils';
-import { KioskListing } from '../query/kiosk';
-import { TransferPolicy } from '../bcs';
-import { confirmRequest, resolveRoyaltyRule } from './transfer-policy';
-
-/** 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`;
+import { getTypeWithoutPackageAddress, objArg } from '../utils';
+import {
+  confirmRequest,
+  resolveKioskLockRule,
+  resolveRoyaltyRule,
+} from './transfer-policy';
+import {
+  KIOSK_LOCK_RULE,
+  KIOSK_MODULE,
+  KIOSK_TYPE,
+  ObjectArgument,
+  PurchaseAndResolvePoliciesResponse,
+  PurchaseOptionalParams,
+  ROYALTY_RULE,
+  RulesEnvironmentParam,
+  TransferPolicy,
+} from '../types';
 
 /**
  * Create a new shared Kiosk and returns the [kiosk, kioskOwnerCap] tuple.
@@ -228,7 +232,12 @@ export function withdrawFromKiosk(
 ): TransactionArgument {
   let amountArg =
     amount !== null
-      ? tx.pure(amount, 'Option<u64>')
+      ? tx.pure(
+          {
+            Some: amount,
+          },
+          'Option<u64>',
+        )
       : tx.pure({ None: true }, 'Option<u64>');
 
   let [coin] = tx.moveCall({
@@ -335,46 +344,71 @@ export function returnValue(
  * Completes the full purchase flow that includes:
  * 1. Purchasing the item.
  * 2. Resolving all the transfer policies (if any).
- * 3. Returns the PurchasedItem OR places the item in the user's kiosk (if there's a kiosk lock policy).
+ * 3. Returns the item and whether the user can transfer it or not.
+ *
+ * If the item can be transferred, there's an extra transaction required by the user
+ * to transfer it to an address or place it in their kiosk.
  */
 export function purchaseAndResolvePolicies(
   tx: TransactionBlock,
   itemType: string,
-  listing: KioskListing,
-  kioskId: string,
-  itemId: string,
+  price: string,
+  kiosk: ObjectArgument,
+  itemId: SuiAddress,
   policy: TransferPolicy,
-): TransactionArgument | null {
+  environment: RulesEnvironmentParam,
+  extraParams?: PurchaseOptionalParams,
+): PurchaseAndResolvePoliciesResponse {
   // if we don't pass the listing or the listing doens't have a price, return.
-  if (!listing || listing?.price === undefined) return null;
+  if (price === undefined || typeof price !== 'string')
+    throw new Error(`Price of the listing is not supplied.`);
 
   // Split the coin for the amount of the listing.
-  const coin = tx.splitCoins(tx.gas, [tx.pure(listing.price)]);
+  const coin = tx.splitCoins(tx.gas, [tx.pure(price, 'u64')]);
 
   // initialize the purchase `kiosk::purchase`
   const [purchasedItem, transferRequest] = purchase(
     tx,
     itemType,
-    kioskId,
+    kiosk,
     itemId,
     coin,
   );
 
   // Start resolving rules.
-  // For now, we only support royalty rule.
-  // Will need some tweaking to make it function properly with the other
-  // ruleset.
+  // Right now we support `kiosk_lock_rule` and `royalty_rule`.
+  // They can also be supplied in parallel (supports combination).
+  let hasKioskLockRule = false;
+
   for (let rule of policy.rules) {
     const ruleWithoutAddr = getTypeWithoutPackageAddress(rule);
 
     switch (ruleWithoutAddr) {
-      case 'royalty_rule::Rule':
+      case ROYALTY_RULE:
         resolveRoyaltyRule(
           tx,
           itemType,
-          listing.price,
+          price,
+          policy.id,
+          transferRequest,
+          environment,
+        );
+        break;
+      case KIOSK_LOCK_RULE:
+        if (!extraParams?.ownedKiosk || !extraParams?.ownedKioskCap)
+          throw new Error(
+            `This item type ${itemType} has a 'kiosk_lock_rule', but function call is missing user's kiosk and kioskCap params`,
+          );
+        hasKioskLockRule = true;
+        resolveKioskLockRule(
+          tx,
+          itemType,
+          purchasedItem,
+          extraParams.ownedKiosk,
+          extraParams.ownedKioskCap,
           policy.id,
           transferRequest,
+          environment,
         );
         break;
       default:
@@ -385,5 +419,8 @@ export function purchaseAndResolvePolicies(
   // confirm the Transfer Policy request.
   confirmRequest(tx, itemType, policy.id, transferRequest);
 
-  return purchasedItem;
+  return {
+    item: purchasedItem,
+    canTransfer: !hasKioskLockRule,
+  };
 }

package/src/tx/transfer-policy.ts

@@ -2,15 +2,14 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { TransactionArgument, TransactionBlock } from '@mysten/sui.js';
-import { ObjectArgument, objArg } from '../utils';
-
-/** The Transfer Policy module. */
-export const TRANSFER_POLICY_MODULE = '0x2::transfer_policy';
-
-/** The Transer Policy Rules package address */
-// TODO: Figure out how we serve this for both testnet & mainnet (different package)
-export const TRANSFER_POLICY_RULES_PACKAGE_ADDRESS =
-  'bd8fc1947cf119350184107a3087e2dc27efefa0dd82e25a1f699069fe81a585';
+import { getRulePackageAddress, objArg } from '../utils';
+import { lock } from './kiosk';
+import {
+  ObjectArgument,
+  RulesEnvironmentParam,
+  TRANSFER_POLICY_MODULE,
+  TRANSFER_POLICY_TYPE,
+} from '../types';
 
 /**
  * Call the `transfer_policy::new` function to create a new transfer policy.
@@ -29,7 +28,7 @@ export function createTransferPolicy(
 
   tx.moveCall({
     target: `0x2::transfer::public_share_object`,
-    typeArguments: [itemType],
+    typeArguments: [`${TRANSFER_POLICY_TYPE}<${itemType}>`],
     arguments: [transferPolicy],
   });
 
@@ -48,7 +47,7 @@ export function withdrawFromPolicy(
 ): TransactionArgument {
   let amountArg =
     amount !== null
-      ? tx.pure(amount, 'Option<u64>')
+      ? tx.pure({ Some: amount }, 'Option<u64>')
       : tx.pure({ None: true }, 'Option<u64>');
 
   let [profits] = tx.moveCall({
@@ -104,13 +103,14 @@ export function resolveRoyaltyRule(
   tx: TransactionBlock,
   itemType: string,
   price: string,
-  policyId: string,
+  policyId: ObjectArgument,
   transferRequest: TransactionArgument,
+  environment: RulesEnvironmentParam,
 ) {
   const policyObj = objArg(tx, policyId);
   // calculates the amount
   const [amount] = tx.moveCall({
-    target: `${TRANSFER_POLICY_RULES_PACKAGE_ADDRESS}::royalty_rule::fee_amount`,
+    target: `${getRulePackageAddress(environment)}::royalty_rule::fee_amount`,
     typeArguments: [itemType],
     arguments: [policyObj, objArg(tx, price)],
   });
@@ -120,8 +120,34 @@ export function resolveRoyaltyRule(
 
   // pays the policy
   tx.moveCall({
-    target: `${TRANSFER_POLICY_RULES_PACKAGE_ADDRESS}::royalty_rule::pay`,
+    target: `${getRulePackageAddress(environment)}::royalty_rule::pay`,
     typeArguments: [itemType],
     arguments: [policyObj, transferRequest, feeCoin],
   });
 }
+
+/**
+ * Locks the item in the supplied kiosk and
+ * proves to the `kiosk_lock` rule that the item was indeed locked,
+ * by calling the `kiosk_lock_rule::prove` function to resolve it.
+ */
+export function resolveKioskLockRule(
+  tx: TransactionBlock,
+  itemType: string,
+  item: TransactionArgument,
+  kiosk: ObjectArgument,
+  kioskCap: ObjectArgument,
+  policyId: ObjectArgument,
+  transferRequest: TransactionArgument,
+  environment: RulesEnvironmentParam,
+) {
+  // lock item in the kiosk.
+  lock(tx, itemType, kiosk, kioskCap, policyId, item);
+
+  // proves that the item is locked in the kiosk to the TP.
+  tx.moveCall({
+    target: `${getRulePackageAddress(environment)}::kiosk_lock_rule::prove`,
+    typeArguments: [itemType],
+    arguments: [transferRequest, objArg(tx, kiosk)],
+  });
+}

package/src/types/env.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { SuiAddress } from '@mysten/sui.js';
+
+/* A list of environments. */
+export type Environment = 'mainnet' | 'testnet' | 'devnet' | 'custom';
+
+/** A Parameter to support enivronments for rules.  */
+export type RulesEnvironmentParam = { env: Environment; address?: SuiAddress };
+
+/** A default Testnet Environment object  */
+export const testnetEnvironment: RulesEnvironmentParam = { env: 'testnet' };
+
+/** A default Mainnet Environment object  */
+export const mainnetEnvironment: RulesEnvironmentParam = { env: 'mainnet' };
+
+/** A helper to easily export a custom environment */
+export const customEnvironment = (address: string): RulesEnvironmentParam => ({
+  env: 'custom',
+  address,
+});

package/src/types/index.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  SharedObjectRef,
+  SuiObjectRef,
+  TransactionArgument,
+} from '@mysten/sui.js';
+
+export * from './kiosk';
+export * from './transfer-policy';
+export * from './env';
+
+/**
+ * A valid argument for any of the Kiosk functions.
+ */
+export type ObjectArgument =
+  | string
+  | TransactionArgument
+  | SharedObjectRef
+  | SuiObjectRef;

package/src/types/kiosk.ts

@@ -0,0 +1,139 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  ObjectDigest,
+  ObjectId,
+  ObjectType,
+  PaginatedObjectsResponse,
+  TransactionArgument,
+} from '@mysten/sui.js';
+import { ObjectArgument } from '.';
+
+/** 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: ObjectId;
+  /**
+   * 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: ObjectId;
+  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: ObjectId;
+  /** The type of the Item */
+  type: ObjectType;
+  /** Whether the item is Locked (there must be a `Lock` Dynamic Field) */
+  isLocked: boolean;
+  /** Optional listing */
+  listing?: KioskListing;
+};
+/**
+ * Aggregated data from the Kiosk.
+ */
+export type KioskData = {
+  items: KioskItem[];
+  itemIds: ObjectId[];
+  listingIds: ObjectId[];
+  kiosk?: Kiosk;
+  extensions: any[]; // type will be defined on later versions of the SDK.
+};
+
+export type PagedKioskData = {
+  data: KioskData;
+  nextCursor: string | null;
+  hasNextPage: boolean;
+};
+
+export type FetchKioskOptions = {
+  withKioskFields?: boolean;
+  withListingPrices?: boolean;
+};
+
+export type OwnedKiosks = {
+  kioskOwnerCaps: KioskOwnerCap[];
+  kioskIds: ObjectId[];
+} & Omit<PaginatedObjectsResponse, 'data'>;
+
+export type KioskOwnerCap = {
+  objectId: ObjectId;
+  kioskId: ObjectId;
+  digest: ObjectDigest;
+  version: string;
+};

package/src/types/transfer-policy.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ObjectOwner } from '@mysten/sui.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 Kiosk Lock Rule */
+export const KIOSK_LOCK_RULE = 'kiosk_lock_rule::Rule';
+
+/** The Royalty rule */
+export const ROYALTY_RULE = 'royalty_rule::Rule';
+
+/** 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;
+};