@haneullabs/kiosk 1.1.2 → 1.1.3

package/docs/from-v1.md

@@ -0,0 +1,314 @@
+# Migrating from Kiosk SDK V1
+
+> Migrate from Kiosk SDK v1 to the current version
+
+The original version of Kiosk SDK provided basic experimentation with the Kiosk API. The new version
+of the SDK (0.7+) provides a more robust experience for building kiosk/transfer policy transactions.
+
+The new SDK offers a builder-pattern API, which provides better autocomplete capabilities, and also
+makes code more readable.
+
+While a one-to-one mapping between the old and new SDK is not possible, the following examples
+should help you get started.
+
+> An important benefit of the new SDK is that it works seamlessly with Personal Kiosk, which was not
+> the case with the previous SDK (you would always have to wrap the transaction with `borrow_cap` /
+> `return_cap` calls depending on whether the kiosk is personal or not).
+
+## Placing an item to kiosk and listing it for sale
+
+The following example is from the original Kiosk SDK V1 documentation.
+
+### Before
+
+```typescript
+const placeAndListToKiosk = async () => {
+	const kiosk = 'SomeKioskId';
+	const kioskCap = 'KioskCapObjectId';
+	const itemType = '0xItemAddr::some:ItemType';
+	const item = 'SomeItemId';
+	const price = '100000';
+
+	const tx = new Transaction();
+
+	placeAndList(tx, itemType, kiosk, kioskCap, item, price);
+
+	// ... continue to sign and execute the transaction
+	// ...
+};
+```
+
+### After
+
+Using the new SDK, you can build the same transaction as follows:
+
+```typescript
+// You need to do this only once and re-use it in the application.
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+
+const placeAndListToKiosk = async () => {
+	// Assume you have saved the user's preferred kiosk Cap somewhere in your app's state.
+	const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address: '0xSomeAddress' });
+
+	const tx = new Transaction();
+
+	// Assume you use the first owned kiosk.
+	new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap: kioskOwnerCaps[0] })
+		.placeAndList({
+			itemType: '0xItemAddr::some:ItemType',
+			item: 'SomeItemId',
+			price: '100000',
+		})
+		.finalize();
+
+	// ... continue to sign and execute the transaction
+};
+```
+
+## Create a new kiosk
+
+The following example is from the original Kiosk SDK V1 documentation.
+
+### Before
+
+```typescript
+const createKiosk = async () => {
+	const accountAddress = '0xSomeHaneulAddress';
+
+	const tx = new Transaction();
+	const kiosk_cap = createKioskAndShare(tx);
+
+	tx.transferObjects([kiosk_cap], accountAddress);
+
+	// ... continue to sign and execute the transaction
+	// ...
+};
+```
+
+### After
+
+Using the new SDK, you can build the same transaction as follows:
+
+```typescript
+// You need to do this only once and re-use it in the application.
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+
+const createKiosk = async () => {
+	const tx = new Transaction();
+
+	const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk });
+
+	kioskTx.create().shareAndTransferCap('0xSomeHaneulAddress').finalize();
+
+	// ... continue to sign and execute the transaction
+};
+```
+
+## Purchasing an item and resolving rules
+
+The following example is from the original Kiosk SDK V1 documentation.
+
+### Before
+
+```typescript
+
+	queryTransferPolicy,
+	purchaseAndResolvePolicies,
+	place,
+	testnetEnvironment,
+} from '@haneullabs/kiosk';
+
+const client = new HaneulJsonRpcClient({
+	url: 'https://fullnode.testnet.haneul.io:443',
+});
+
+// The kiosk we're purchasing from.
+const kioskId = `0xSomeKioskAddress`;
+// A sample item retrieved from `fetchKiosk` function (or hard-coded).
+const item = {
+	isLocked: false,
+	objectId: '0xb892d61a9992a10c9453efcdbd14ca9720d7dc1000a2048224209c9e544ed223',
+	type: '0x52852c4ba80040395b259c641e70b702426a58990ff73cecf5afd31954429090::test::TestItem',
+	listing: {
+		isExclusive: false,
+		listingId: '0x368b512ff2514dbea814f26ec9a3d41198c00e8ed778099961e9ed22a9f0032b',
+		price: '20000000000', // in GEUNHWA
+	},
+};
+const ownedKiosk = `0xMyKioskAddress`;
+const ownedKioskCap = `0xMyKioskOwnerCap`;
+
+const purchaseItem = async (item, kioskId) => {
+	// Fetch the policy of the item (could be an array, if there's more than one transfer policy)
+	const policies = await queryTransferPolicy(client, item.type);
+	// Selecting the first one for simplicity.
+	const policyId = policy[0]?.id;
+	// Initialize transaction.
+	const tx = new Transaction();
+
+	// Both are required if there is a `kiosk_lock_rule`.
+	// Optional otherwise. Function throws an error if there's a kiosk_lock_rule and these are missing.
+	const extraParams = {
+		ownedKiosk,
+		ownedKioskCap,
+	};
+	// Define the environment.
+	// To use a custom package address for rules, you could call:
+	// const environment = customEnvironment('<PackageAddress>');
+	const environment = testnetEnvironment;
+
+	// Extra params. Optional, but required if the user tries to resolve a `kiosk_lock_rule`.
+	// Purchases the item. Supports `kiosk_lock_rule`, `royalty_rule` (accepts combination too).
+	const result = purchaseAndResolvePolicies(
+		tx,
+		item.type,
+		item.listing.price,
+		kioskId,
+		item.objectId,
+		policy[0],
+		environment,
+		extraParams,
+	);
+
+	// result = {item: <the_purchased_item>, canTransfer: true/false // depending on whether there was a kiosk lock rule }
+	// If the item didn't have a kiosk_lock_rule, you need to do something with it.
+	// For example, place it in your own kiosk. (demonstrated below)
+	if (result.canTransfer) place(tx, item.type, ownedKiosk, ownedKioskCap, result.item);
+
+	// ...finally, sign PTB & execute it.
+};
+```
+
+### After
+
+Using the new SDK, you can build the same transaction as follows:
+
+> This works with both personal and non-personal kiosks.
+
+```typescript
+// You need to do this only once and re-use it in the application.
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+
+// An Item as returned from `client.kiosk.getKiosk()` call.
+const item = {
+	isLocked: false,
+	objectId: '0xb892d61a9992a10c9453efcdbd14ca9720d7dc1000a2048224209c9e544ed223',
+	type: '0x52852c4ba80040395b259c641e70b702426a58990ff73cecf5afd31954429090::test::TestItem',
+	kioskId: '0xSomeKioskAddress',
+	listing: {
+		isExclusive: false,
+		listingId: '0x368b512ff2514dbea814f26ec9a3d41198c00e8ed778099961e9ed22a9f0032b',
+		price: '20000000000', // in GEUNHWA
+	},
+};
+
+const purchase = async () => {
+	// Assume you have saved the user's preferred kiosk Cap somewhere in your app's state.
+	// You wouldn't need to query this for every purchase.
+	const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address: '0xSomeAddress' });
+
+	const tx = new Transaction();
+
+	const kioskTx = new KioskTransaction({
+		transaction: tx,
+		kioskClient: client.kiosk,
+		cap: kioskOwnerCaps[0],
+	});
+
+	// Purchase the item and resolve the rules.
+	await kioskTx.purchaseAndResolve({
+		itemType: item.type,
+		itemId: item.objectId,
+		price: item.listing.price,
+		sellerKiosk: item.kioskId,
+	});
+
+	kioskTx.finalize();
+};
+```
+
+## Attach rules to transfer policy
+
+The following example was taken from the original Kiosk SDK V1 documentation.
+
+### Before
+
+```typescript
+
+	attachKioskLockRule,
+	attachRoyaltyRule,
+	createTransferPolicy,
+	percentageToBasisPoints,
+	testnetEnvironment,
+} from '@haneullabs/kiosk';
+
+// Attaches a royalty rule of 1% or 0.1 HANEUL (whichever is bigger)
+// as well as a kiosk lock, making the objects tradeable only from/to a kiosk.
+const attachStrongRoyalties = async () => {
+	const type = 'SomePackageId::type::MyType'; // the Type for which we're attaching rules.
+	const policyId = 'policyObjectId'; // the transfer Policy ID that was created for that Type.
+	const transferPolicyCap = 'transferPolicyCapId'; // the transferPolicyCap for that policy.
+
+	// Royalties configuration.
+	const percentage = 2.55; // 2.55%
+	const minAmount = 100_000_000; // 0.1 HANEUL.
+
+	// The environment on which we're referencing the rules package.
+	// Use `mainnetEnvironment` for mainnet.
+	const environment = testnetEnvironment;
+
+	const tx = new Transaction();
+
+	attachKioskLockRule(tx, type, policyId, policyCapId, environment);
+	attachRoyaltyRule(
+		tx,
+		type,
+		policyId,
+		policyCapId,
+		percentageToBasisPoints(percentage),
+		minAmount,
+		environment,
+	);
+
+	// ... continue to sign and execute the transaction
+	// ...
+};
+```
+
+### After
+
+On the new SDK, the same transaction can be built as follows:
+
+```typescript
+// You need to do this only once and re-use it in the application.
+const client = new HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+
+const adjustPolicy = async () => {
+	const tx = new Transaction();
+
+	// You could have more than one cap, since you can create more than one transfer policy.
+	const policyCaps = await client.kiosk.getOwnedTransferPoliciesByType({
+		type: `SomePackageId::type::MyType`,
+		address: '0xOwnerAddress',
+	});
+
+	new TransferPolicyTransaction({ transaction: tx, kioskClient: client.kiosk, cap: policyCaps[0] })
+		.addRoyaltyRule(percentageToBasisPoints(2.55), 100_000_000)
+		.addLockRule();
+
+	// ... continue to sign and execute the transaction
+	// ...
+};
+```

package/docs/index.md

@@ -0,0 +1,22 @@
+# Kiosk SDK
+
+> TypeScript SDK for interacting with Haneul Kiosk on-chain commerce
+
+Kiosk SDK is a tool to interact with Haneul/Haneullabs Kiosk. You can use it to query kiosk related
+data, build transactions to interact, and extend Kiosk to support custom rules.
+
+## Installation
+
+```sh npm2yarn
+npm i @haneullabs/kiosk
+```
+
+## About
+
+The Kiosk SDK exports a client extension that integrates with Haneul clients. Add it to your client
+using `$extend(kiosk())` to access kiosk functionality via `client.kiosk`.
+
+> **Note:** The Kiosk SDK requires `HaneulJsonRpcClient` or `HaneulGraphQLClient`. It does not work
+> with `HaneulGrpcClient` because it uses event queries that are not available in gRPC.
+
+- [Read more about setting up the Kiosk client extension](/kiosk/kiosk-client/introduction)

package/docs/kiosk-client/introduction.md

@@ -0,0 +1,50 @@
+# 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 `HaneulJsonRpcClient` or `HaneulGraphQLClient`. It does not work
+> with `HaneulGrpcClient` because it uses event queries that are not available in gRPC.
+
+## Setting up the kiosk extension
+
+Add the kiosk extension to your Haneul client using `$extend()`. The extension currently supports
+`mainnet` and `testnet`. See the next section for usage on other networks.
+
+_Haneullabs 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 HaneulJsonRpcClient({
+	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 HaneulJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('devnet'),
+	network: 'devnet',
+}).$extend(
+	kiosk({
+		packageIds: {
+			kioskLockRulePackageId: '0x...',
+			royaltyRulePackageId: '0x...',
+			personalKioskRulePackageId: '0x...',
+			floorPriceRulePackageId: '0x...',
+		},
+	}),
+);
+```

package/docs/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<HANEUL>, 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 HANEUL
+	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 HANEUL
+	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/docs/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 });
+```