@mysten/docs 0.1.1

package/dist/kiosk/kiosk-client/introduction.md

@@ -0,0 +1,52 @@
+# Kiosk Client
+
+> Introduction to the KioskClient for querying and managing kiosks
+
+The Kiosk SDK exports a client extension that provides all Kiosk functionality.
+
+> We recommend you keep only one client instance throughout your dApp or script. For example, in
+> React, you'd use a context to provide the client.
+
+> **Note:** The Kiosk SDK requires `SuiJsonRpcClient` or `SuiGraphQLClient`. It does not work with
+> `SuiGrpcClient` because it uses event queries that are not available in gRPC.
+
+## Setting up the kiosk extension
+
+Add the kiosk extension to your Sui client using `$extend()`. The extension currently supports
+`mainnet` and `testnet`. See the next section for usage on other networks.
+
+_Mysten Kiosk rules and extensions are not supported in Devnet due to network wipes (that would
+require constantly changing the package IDs)._
+
+```typescript
+
+const client = new SuiJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('testnet'),
+	network: 'testnet',
+}).$extend(kiosk());
+
+// Now you can use client.kiosk for all kiosk operations
+const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address: '0x...' });
+```
+
+### Using the kiosk extension on devnet or localnet
+
+To use all the functionality of Kiosk SDK outside of `mainnet` and `testnet`, pass the `packageIds`
+for the rules and extensions you want to use.
+
+```typescript
+
+const client = new SuiJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('devnet'),
+	network: 'devnet',
+}).$extend(
+	kiosk({
+		packageIds: {
+			kioskLockRulePackageId: '0x...',
+			royaltyRulePackageId: '0x...',
+			personalKioskRulePackageId: '0x...',
+			floorPriceRulePackageId: '0x...',
+		},
+	}),
+);
+```

package/dist/kiosk/kiosk-client/kiosk-transaction/examples.md

@@ -0,0 +1,119 @@
+# Examples
+
+> Kiosk transaction code examples
+
+The following dApp-focused examples demonstrate how to use the SDK to interact with Kiosk.
+
+## Minting into Kiosk example
+
+For every scenario using Kiosk in dApps, the user who has connected their wallet either has at least
+one kiosk already or you must create it for them.
+
+The SDK supports the scenario of `silently` creating the kiosk, as part of our Programmable
+Transaction.
+
+Assume that the mint function of the contract is:
+
+`public fun mint(coin: Coin<SUI>, kiosk: &mut Kiosk, cap: &KioskOwnerCap){...}`
+
+### When the user has a kiosk
+
+```typescript
+const connectedAddress = '0xAnAddress';
+
+// This function should run when the user connects the wallet.
+// We should re-use the same client instance throughout our dApp.
+const getCap = async () => {
+	let { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address: connectedAddress });
+	// Assume that the user has only 1 kiosk.
+	// Here, you need to do some more checks in a realistic scenario.
+	// And possibly give the user in our dApp a kiosk selector to choose which one they want to interact with (if they own more than one).
+	return kioskOwnerCaps[0];
+};
+
+// The mint function could be like the following.
+const mint = async () => {
+	const tx = new Transaction();
+	const kioskTx = new KioskTransaction({
+		kioskClient: client.kiosk,
+		transaction: tx,
+		cap: await getCap(),
+	});
+
+	// Assume it costs one SUI
+	let coin = tx.splitCoins(tx.gas, [1_000_000_000]);
+
+	// A function that mints directly into the kiosk.
+	tx.moveCall({
+		target: '0xMyGame::hero::mint',
+		arguments: [
+			coin, // the payment
+			kioskTx.getKiosk(), // our kiosk that the hero will be placed in.
+			kioskTx.getKioskCap(), // our kiosk cap, so that the function can place or lock it.
+		],
+	});
+
+	kioskTx.finalize();
+
+	// Sign and execute transaction.
+	await signAndExecuteTransaction({ tx: tx });
+};
+```
+
+### When the user doesn't have a kiosk (silent creation)
+
+```typescript
+// Our mint function.
+const mint = async () => {
+	const tx = new Transaction();
+	const kioskTx = new KioskTransaction({ kioskClient: client.kiosk, transaction: tx });
+
+	// Creates a kiosk.
+	kioskTx.create();
+
+	// We'll assume it costs 1 SUI
+	let coin = tx.splitCoins(tx.gas, [1_000_000_000]);
+
+	// A function that mints directly into the kiosk.
+	tx.moveCall({
+		target: '0xMyGame::hero::mint',
+		arguments: [
+			coin, // the payment
+			kioskTx.getKiosk(), // our kiosk that the hero will be placed in.
+			kioskTx.getKioskCap(), // our kiosk cap, so that the function can place or lock it.
+		],
+	});
+
+	kioskTx.shareAndTransferCap('0xAddressToTransferCapTo');
+	kioskTx.finalize();
+
+	// Sign and execute transaction.
+	await signAndExecuteTransaction({ tx: tx });
+};
+```
+
+## Borrowing an item from kiosk to do an action
+
+```typescript
+// A sample function that borrows an item from kiosk and levels it up.
+const levelUp = async (object) => {
+	const tx = new Transaction();
+
+	new KioskTransaction({ kioskClient: client.kiosk, transaction: tx, cap })
+		.borrowTx(object, (item) => {
+			tx.moveCall({
+				target: '0xMyGame::hero::level_up',
+				arguments: [item],
+			});
+		})
+		.finalize();
+
+	// Sign and execute transaction.
+	await signAndExecuteTransaction({ tx: tx });
+};
+
+levelUp({
+	itemType: '0x2MyGame::hero::Hero',
+	itemId: '0xMyHeroObjectId',
+});
+```

package/dist/kiosk/kiosk-client/kiosk-transaction/kiosk-transaction.md

@@ -0,0 +1,103 @@
+# KioskTransaction
+
+> Build kiosk transactions for listing, purchasing, and managing items
+
+`KioskTransaction` is the client to build transactions that involve Kiosk. It's used similar to
+`Transaction`, and helps in building a transaction.
+
+You need to instantiate it once in every Programmable Transaction Block (PTB) that you're building.
+
+There are two flows to follow, the first being managing an existing kiosk, and the second is
+creating a new one. It hides all the complexity between a personal and a non-personal kiosk.
+
+## Using an existing kiosk
+
+If you have already retrieved a kiosk from `client.kiosk.getOwnedKiosks()`, you can pass a cap.
+
+> You must always call `kioskTx.finalize()` before signing and executing the transaction, as your
+> last command.
+
+```typescript
+const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address: '0xMyAddress' });
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({
+	transaction: tx,
+	kioskClient: client.kiosk,
+	cap: kioskOwnerCaps[0],
+});
+
+// Now you can do whatever you want with kioskTx.
+// For example, you could withdraw the profits from the kiosk.
+kioskTx.withdraw('0xMyAddress', 100_000_000n);
+
+// You could also chain some other functionality if you want to.
+kioskTx
+	.place({
+		itemType: '0xMyItemType',
+		item: '0xMyItem',
+	})
+	.list({
+		itemType: '0xMyItemType',
+		itemId: '0xMyItem',
+		price: 10000n,
+	});
+
+// Always called as our last kioskTx interaction.
+kioskTx.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+## Creating a new kiosk
+
+If you don't have a kiosk yet, you can create one using `create()`. The `KioskTransaction` enables
+use of the newly created kiosk to execute some functionality in the same PTB.
+
+```typescript
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk });
+
+// Calls the creation function.
+kioskTx.create();
+
+// We can use the kiosk for some action.
+// For example, placing an item in the newly created kiosk.
+kioskTx.place({
+	itemType: '0x...::hero::Hero',
+	item: '0xAHero',
+});
+
+// Shares the kiosk and transfers the `KioskOwnerCap` to the owner.
+kioskTx.shareAndTransferCap('0xMyAddress');
+
+// Always called as our last kioskTx interaction.
+kioskTx.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+## Creating a new personal kiosk
+
+`KioskTransaction` makes it easy to create a new personal kiosk, and use it in the same PTB.
+
+```typescript
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk });
+
+// An example that creates a personal kiosk, uses it to place an item, and shares it.
+// The `PersonalKioskCap` is automatically transferred to the sender when calling `.finalize()`.
+// The `Kiosk` is automatically shared when calling `.finalize()`.
+kioskTx
+	.createPersonal(true) // `true` allows us to reuse the kiosk in the same PTB. If we pass false, we can only call `kioskTx.finalize()`.
+	.place({
+		itemType: '0x...::hero::Hero',
+		item: '0xAHero',
+	})
+	.finalize(); // finalize is always our last call.
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```

package/dist/kiosk/kiosk-client/kiosk-transaction/managing.md

@@ -0,0 +1,235 @@
+# Managing Owned Kiosk
+
+> Manage kiosk items: place, list, delist, and withdraw
+
+The kiosk extension (`client.kiosk`) helps in managing a kiosk.
+
+You need to follow the steps explained in the [Kiosk Transaction section](#kiosk-transaction) to
+create a `KioskTransaction`.
+
+## Available functions
+
+### take
+
+Removes an item from the Kiosk and returns a `TransactionArgument` to use it in a different
+Programmable Transaction Block (PTB) call.
+
+```typescript
+const itemId = '0xHeroAddress';
+const itemType = '0x..::hero::Hero';
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+// Take item from kiosk.
+const item = kioskTx.take({
+	itemId,
+	itemType,
+});
+
+// Do something with `item`, like transfer it to someone else.
+tx.transferObjects([item], 'address_to_transfer_the_object');
+
+// Finalize the kiosk Tx.
+kioskTx.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+### transfer
+
+Similar to `take`, but transfers the item to an address internally.
+
+```typescript
+const itemId = '0xHeroAddress';
+const itemType = '0x..::hero::Hero';
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+// Take item from kiosk.
+kioskTx
+	.transfer({
+		itemId,
+		itemType,
+		address: 'address_to_transfer_the_object',
+	})
+	.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+### place
+
+Places an item in the kiosk.
+
+```typescript
+const item = '0xHeroAddress';
+const itemType = '0x..::hero::Hero';
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+kioskTx
+	.place({
+		item,
+		itemType,
+	})
+	.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+### list
+
+Lists an item for sale (the item must be in the kiosk).
+
+```typescript
+const itemId = '0xHeroAddress';
+const itemType = '0x..::hero::Hero';
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+kioskTx
+	.list({
+		itemId,
+		itemType,
+		price: 100000n,
+	})
+	.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+### placeAndList
+
+List an item for sale by first placing it in the kiosk (places the item and lists it for sale). It's
+a short hand for `place()` and `list()`.
+
+```typescript
+const item = '0xHeroAddress';
+const itemType = '0x..::hero::Hero';
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+kioskTx
+	.placeAndList({
+		item,
+		itemType,
+		price: 100000n,
+	})
+	.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+### delist
+
+Removes the listing, keeping the item placed in the kiosk.
+
+```typescript
+const itemId = '0xHeroAddress';
+const itemType = '0x..::hero::Hero';
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+kioskTx
+	.delist({
+		itemId,
+		itemType,
+	})
+	.finalize();
+
+// sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+### withdraw
+
+Withdraw (all or specific amount) from a kiosk.
+
+`amount`: Can be empty, which will withdraw all the funds.
+
+```typescript
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+kioskTx.withdraw('address_to_transfer_funds', 100000n).finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+### borrowTx (callback)
+
+Borrows an item from a kiosk. This function follows the `callback` approach, similar to the
+ownerCap. The return of the item happens automatically after the execution of the callback.
+
+```typescript
+const itemId = '0xHeroAddress';
+const itemType = '0x..::hero::Hero';
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+kioskTx
+	.borrowTx(
+		{
+			itemId,
+			itemType,
+		},
+		(item) => {
+			tx.moveCall({
+				target: '0xMyGame::hero::level_up',
+				arguments: [item],
+			});
+		},
+	)
+	.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+### borrow / return
+
+Similar to `borrowTx`, borrows an item from the kiosk, but returns two transaction arguments: `item`
+& `promise`. You can use the `item` in your PTBs, but you must always call the `return()` function
+with the `item` and the `Promise`.
+
+```typescript
+const itemId = '0xHeroAddress';
+const itemType = '0x..::hero::Hero';
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+const [item, promise] = kioskTx.borrow({
+	itemId,
+	itemType,
+});
+
+tx.moveCall({
+	target: '0xMyGame::hero::level_up',
+	arguments: [item],
+});
+
+kioskTx
+	.return({
+		itemType,
+		item,
+		promise,
+	})
+	.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```

package/dist/kiosk/kiosk-client/kiosk-transaction/purchasing.md

@@ -0,0 +1,110 @@
+# Purchasing from a kiosk
+
+> Purchase items from kiosks with transfer policy resolution
+
+One of the base functionalities of the SDK is a seamless purchasing flow, allowing for ease of rules
+resolving (hiding away the calls). The SDK supports all four rules by default, and works for
+`TESTNET` and `MAINNET`. To support other networks,
+[follow the instructions in the Introduction](../introduction#using-kioskclient-on-devnet-or-localnet).
+
+## How to purchase
+
+By default, the SDK places the item in the caller's kiosk, unless there's a lock rule, in which case
+it locks it.
+
+Then following is an example of a purchase call.
+
+```typescript
+const item = {
+	itemType: '0x..::hero::Hero',
+	itemId: '0x..',
+	price: 100000n,
+	sellerKiosk: '0xSellerKiosk',
+};
+
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+await kioskTx.purchaseAndResolve({
+	itemType: item.itemType,
+	itemId: item.itemId,
+	price: item.price,
+	sellerKiosk: item.sellerKiosk,
+});
+
+kioskTx.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+> The function queries for a TransferPolicy for that item, and if a policy is found, it
+> automatically resolves all the rules, one by one. You can add a custom rule resolver to the kiosk
+> extension, with instructions on how to resolve a custom rule. Read more in the next section.
+
+## Supporting a custom rule
+
+You can use the `purchaseAndResolve` function to support a custom rule.
+
+```typescript
+// Assuming client is set up with .$extend(kiosk())
+const myCustomRule = {
+	rule: `0xMyRuleAddress::game_rule::Rule`,
+	packageId: `0xMyRuleAddress`,
+	// The resolving function. This is called when calling the `purchaseAndResolve`.
+	resolveRuleFunction: (params: RuleResolvingParams) => {
+		// By knowing the params we have here, we can extract the variables we need to resolve this rule.
+		const { transaction, itemType, packageId, extraArgs, transferRequest } = params;
+		const { gamePass } = extraArgs;
+		if (!gamePass) throw new Error('GamePass not supplied');
+
+		// Calls the game's rule prove function, which could, for example
+		// allow rules to resolve only if the holder has a gamePass object.
+		transaction.moveCall({
+			target: `${packageId}::game_rule::prove_pass`,
+			typeArguments: [itemType],
+			arguments: [transferRequest, transaction.object(gamePass)],
+		});
+	},
+};
+// This allows rules resolution from the `purchaseAndResolve` function.
+client.kiosk.addRuleResolver(myCustomRule);
+
+// Assume `cap` is obtained from client.kiosk.getOwnedKiosks()
+const tx = new Transaction();
+const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+await kioskTx.purchaseAndResolve({
+	itemType: item.itemType,
+	itemId: item.itemId,
+	price: item.price,
+	sellerKiosk: item.sellerKiosk,
+	extraArgs: {
+		gamePass: '0xMyGamePassObjectId',
+	},
+});
+
+kioskTx.finalize();
+
+// Sign and execute transaction.
+await signAndExecuteTransaction({ tx: tx });
+```
+
+```typescript
+// For reference, here's the RuleResolvingParams contents.
+type RuleResolvingParams = {
+	transaction: 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; // This is the client.kiosk extension
+};
+```