@mysten/docs 0.1.1

package/dist/dapp-kit/web-components/connect-button.md

@@ -0,0 +1,89 @@
+# Connect Button
+
+> Framework-agnostic web component for wallet connection
+
+The `<mysten-dapp-kit-connect-button>` Web Component provides a complete wallet connection UI. It
+displays a "Connect Wallet" button when no wallet is connected, and shows the connected account with
+a menu when a wallet is active.
+
+> Auto-connect is enabled by default and will attempt to restore the previous wallet connection on
+> page reload. This provides a seamless user experience but can be
+> [disabled](../dapp-kit-instance#disabling-auto-connect) if needed.
+
+## Basic Usage
+
+### Vanilla
+
+```html
+<mysten-dapp-kit-connect-button></mysten-dapp-kit-connect-button>
+
+<script>
+	const button = document.querySelector('mysten-dapp-kit-connect-button');
+	   button!.instance = dAppKit;
+</script>
+```
+
+### Vue
+
+```vue
+<script setup>
+
+</script>
+
+<template>
+	<mysten-dapp-kit-connect-button :instance="dAppKit" />
+</template>
+```
+
+### React
+
+DApp Kit React bindings provide a [React wrapper](../react/components/connect-button) for the
+button.
+
+## Features
+
+The connect button component automatically handles:
+
+- **Wallet Connection**: Opens a modal to select and connect a wallet
+- **Account Display**: Shows the connected account address
+- **Account Switching**: Provides a menu to switch between multiple accounts when connected
+- **Disconnection**: Includes a disconnect option in the menu
+
+## Properties
+
+- **instance** - The dApp Kit instance
+- **modalOptions** (optional) - Configuration options for the connect modal
+  - `filterFn` - Function to filter available wallets
+  - `sortFn` - Function to sort available wallets
+
+## Custom Button Text
+
+Use the default slot to customize the button text when not connected:
+
+```html
+<mysten-dapp-kit-connect-button>
+	<span>Sign In</span>
+</mysten-dapp-kit-connect-button>
+```
+
+## Modal Integration
+
+The connect button automatically manages its own modal. You don't need to add a separate
+`<mysten-dapp-kit-connect-modal>` component when using the connect button.
+
+## Connected State
+
+When a wallet is connected, the button transforms into an account menu that displays:
+
+- Account address (truncated)
+- SUI balance
+- Network indicator
+- Menu options for:
+  - Switching accounts (if multiple accounts available)
+  - Managing connection
+  - Disconnecting
+
+## Server-Side Rendering (SSR)
+
+The `<mysten-dapp-kit-connect-button>` Web Component can be only client-side rendered, as wallets
+are detected in the browser. For Next.js guide see [here](../getting-started/next-js).

package/dist/dapp-kit/web-components/connect-modal.md

@@ -0,0 +1,177 @@
+# Connect Modal
+
+> Framework-agnostic web component for wallet selection
+
+The `<mysten-dapp-kit-connect-modal>` Web Component provides a modal dialog for wallet connection.
+While most apps should use the [`Connect Button`](./connect-button) which includes an integrated
+modal, the standalone modal is useful for advanced scenarios requiring custom trigger mechanisms.
+
+## When to Use
+
+Use the standalone modal when you need:
+
+- **Custom trigger elements** - Menu items, keyboard shortcuts, or other non-button triggers
+- **Complex UI flows** - Integration into existing navigation or custom wallet management interfaces
+- **Programmatic control** - Opening the modal based on application logic or user actions
+- **Multiple triggers** - Different parts of your UI that can open the same modal
+
+For standard wallet connection with a button, use the [Connect Button](./connect-button) component
+instead.
+
+## Basic Usage
+
+### Vanilla
+
+```html
+<button id="custom-trigger">Open Wallet Selector</button>
+<mysten-dapp-kit-connect-modal></mysten-dapp-kit-connect-modal>
+
+<script>
+	import { createDAppKit } from '@mysten/dapp-kit-core';
+	import { SuiGrpcClient } from '@mysten/sui/grpc';
+
+	const GRPC_URLS = {
+	    mainnet: 'https://fullnode.mainnet.sui.io:443',
+	    testnet: 'https://fullnode.testnet.sui.io:443',
+	};
+
+	const dAppKit = createDAppKit({
+	    enableBurnerWallet: import.meta.env.DEV,
+	    networks: ['mainnet', 'testnet'],
+	    defaultNetwork: 'testnet',
+	    createClient(network) {
+	        return new SuiGrpcClient({ network, baseUrl: GRPC_URLS[network] });
+	    },
+	});
+
+	const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+	modal!.instance = dAppKit;
+
+	const trigger = document.getElementById('custom-trigger');
+	trigger?.addEventListener('click', () => {
+	    modal!.show();
+	});
+</script>
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+
+const modalRef = ref();
+const isModalOpen = ref(false);
+
+const openModal = () => {
+	// Using property binding
+	isModalOpen.value = true;
+	// Or using method
+	modalRef.value.show();
+};
+</script>
+
+<template>
+	<!-- Custom trigger -->
+	<button @click="openModal">Select Wallet</button>
+
+	<!-- Modal component -->
+	<mysten-dapp-kit-connect-modal
+		ref="modalRef"
+		:instance="dAppKit"
+		:open="isModalOpen"
+		@closed="isModalOpen = false"
+	/>
+</template>
+```
+
+### React
+
+DApp Kit React bindings provide a [React wrapper](../react/components/connect-modal) for the modal.
+
+## Properties
+
+- **instance** - The dApp Kit instance
+- **open** - Boolean to control modal visibility programmatically
+- **filterFn** (optional) - Function to filter available wallets
+  - Type: `(wallet: UiWallet, index: number, array: UiWallet[]) => boolean`
+- **sortFn** (optional) - Function to sort available wallets
+  - Type: `(a: UiWallet, b: UiWallet) => number`
+
+## Methods
+
+### show()
+
+Opens the modal programmatically:
+
+```js
+const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+await modal?.show();
+```
+
+### close(returnValue: string)
+
+Closes the modal with an optional return value:
+
+```js
+const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+await modal?.close('user-cancelled');
+```
+
+## Events
+
+The modal fires several events during its lifecycle:
+
+- **open** - Fired before the modal opens (cancelable)
+- **opened** - Fired after the modal has fully opened
+- **close** - Fired before the modal closes (cancelable)
+- **closed** - Fired after the modal has fully closed
+- **cancel** - Fired when clicking backdrop or pressing Escape (cancelable)
+
+```js
+const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+
+modal?.addEventListener('open', (event) => {
+	console.log('Modal is about to open');
+	// Prevent opening if needed
+	// event.preventDefault();
+});
+
+modal?.addEventListener('opened', () => {
+	console.log('Modal is now open');
+});
+
+modal?.addEventListener('closed', () => {
+	console.log('Modal has closed');
+});
+
+modal?.addEventListener('cancel', (event) => {
+	console.log('User clicked backdrop or pressed Escape');
+});
+```
+
+## Examples
+
+### Programmatic Control
+
+```js
+const modal = document.querySelector('mysten-dapp-kit-connect-modal');
+modal.instance = dAppKit;
+
+// Open modal when user tries to perform an action that requires connection
+async function performAction() {
+	const connection = dAppKit.stores.$connection.get();
+
+	if (!connection.account) {
+		await modal.show();
+		// Wait for connection or cancellation
+		return;
+	}
+
+	// Proceed with action...
+}
+```
+
+## Server-Side Rendering (SSR)
+
+The `<mysten-dapp-kit-connect-modal>` Web Component can be only client-side rendered, as wallets are
+detected in the browser. For Next.js guide see [here](../getting-started/next-js).

package/dist/kiosk/advanced-examples.md

@@ -0,0 +1,101 @@
+# Advanced Examples
+
+> Advanced Kiosk SDK usage patterns and examples
+
+# Some extended examples
+
+For these examples, assume you have the following data and functions available:
+
+```typescript
+
+// a constant for bullshark's type.
+const bullsharkType = `${packageId}::suifrens::SuiFren<${packageId}::bullshark::Bullshark>`;
+// a constant for capy's type.
+const capyType = `${packageId}::suifrens::SuiFren<${packageId}::capy::Capy>`;
+
+// initialize the client with the kiosk extension.
+const client = new SuiJsonRpcClient({
+	url: getJsonRpcFullnodeUrl('mainnet'),
+	network: 'mainnet',
+}).$extend(kiosk());
+```
+
+## Minting a SuiFren
+
+This example demonstrates how to mint a SuiFren.
+
+```typescript
+async function mintFren(address: string) {
+	const { kioskOwnerCaps } = await client.kiosk.getOwnedKiosks({ address });
+
+	// Choose the first kiosk for simplicity. We could have extra logic here (e.g. let the user choose, pick a personal one, etc).
+	const cap = kioskOwnerCaps[0];
+
+	const tx = new Transaction();
+	const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+	// We're mixing the logic here. If the cap is undefined, we create a new kiosk.
+	if (!cap) kioskTx.create();
+
+	// Let's mint a capy here into the kiosk (either a new or an existing one).
+	tx.moveCall({
+		target: `${packageId}::suifrens::mint_app::mint`,
+		arguments: [kioskTx.getKiosk(), kioskTx.getKioskCap()],
+		typeArguments: [capyType],
+	});
+
+	// If we don't have a cap, that means we create a new kiosk for the user in this flow.
+	if (!cap) kioskTx.shareAndTransferCap(address);
+
+	kioskTx.finalize();
+
+	// sign and execute transaction.
+	await signAndExecuteTransaction({ tx: tx });
+}
+```
+
+## Mixing two Suifrens
+
+This example demonstrates how to use the Kiosk SDK to mix two `bullsharks`.
+
+```typescript
+// We're mixing two frens.
+async function mixFrens(firstFrenObjectId: string, secondFrenObjectId: string, cap: KioskOwnerCap) {
+	const tx = new Transaction();
+	const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk, cap });
+
+	// borrow both frens.
+	const [fren1, promise1] = kioskTx.borrow({
+		itemType: bullsharkType,
+		itemId: firstFrenObjectId,
+	});
+
+	const [fren2, promise2] = kioskTx.borrow({
+		itemType: bullsharkType,
+		itemId: secondFrenObjectId,
+	});
+
+	// Let's call the mix function. We skip any payment related stuff here.
+	tx.moveCall({
+		target: `${packageId}::mix_app::mix`,
+		arguments: [fren1, fren2, kioskTx.getKiosk(), kioskTx.getKioskCap()],
+		typeArguments: [bullsharkType],
+	});
+
+	kioskTx
+		.return({
+			itemType: bullsharkType,
+			item: fren1,
+			promise: promise1,
+		})
+		.return({
+			itemType: bullsharkType,
+			item: fren2,
+			promise: promise2,
+		})
+		.finalize();
+
+	// sign and execute transaction.
+	await signAndExecuteTransaction({ tx: tx });
+}
+```

package/dist/kiosk/from-v1.md

@@ -0,0 +1,320 @@
+# 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 SuiJsonRpcClient({
+	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 = '0xSomeSuiAddress';
+
+	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 SuiJsonRpcClient({
+	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('0xSomeSuiAddress').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 '@mysten/kiosk';
+
+const client = new SuiJsonRpcClient({
+	url: 'https://fullnode.testnet.sui.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 MIST
+	},
+};
+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 SuiJsonRpcClient({
+	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 MIST
+	},
+};
+
+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 '@mysten/kiosk';
+
+// Attaches a royalty rule of 1% or 0.1 SUI (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 SUI.
+
+	// 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 SuiJsonRpcClient({
+	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/dist/kiosk/index.md

@@ -0,0 +1,22 @@
+# Kiosk SDK
+
+> TypeScript SDK for interacting with Sui Kiosk on-chain commerce
+
+Kiosk SDK is a tool to interact with Sui/Mysten 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 @mysten/kiosk
+```
+
+## About
+
+The Kiosk SDK exports a client extension that integrates with Sui clients. Add it to your client
+using `$extend(kiosk())` to access kiosk functionality via `client.kiosk`.
+
+> **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.
+
+- [Read more about setting up the Kiosk client extension](/kiosk/kiosk-client/introduction)