@mysten/docs 0.1.1

package/dist/codegen/index.md

@@ -0,0 +1,441 @@
+# Sui TypeScript Codegen
+
+> Generate type-safe TypeScript bindings from on-chain Sui Move packages
+
+The `@mysten/codegen` package automatically generates type-safe TypeScript code from your Move
+packages, enabling seamless interaction with your smart contracts from TypeScript applications.
+
+> **Warning:** This package is currently in development and may have breaking changes.
+
+## Features
+
+- **Type-safe Move calls**: Generate TypeScript functions with full type safety for calling your
+  Move functions
+- **BCS type definitions**: Automatic BCS struct definitions for parsing on-chain data
+- **Auto-completion**: IDE support with intelligent code completion for Move function arguments
+- **Package resolution**: Support for both MVR-registered packages and local packages
+
+## Installation
+
+Install the codegen package as a dev dependency:
+
+```sh npm2yarn
+npm install -D @mysten/codegen
+```
+
+## Quick Start
+
+### 1. Create a configuration file
+
+Create a `sui-codegen.config.ts` file in your project root:
+
+```typescript
+
+const config: SuiCodegenConfig = {
+	output: './src/contracts',
+	packages: [
+		{
+			package: '@local-pkg/counter',
+			path: './move/counter',
+		},
+	],
+};
+
+```
+
+### 2. Generate TypeScript code
+
+Add a script to your `package.json`:
+
+```json
+{
+	"scripts": {
+		"codegen": "sui-ts-codegen generate"
+	}
+}
+```
+
+Then run:
+
+```bash
+pnpm codegen
+```
+
+This generates TypeScript code in your configured output directory (e.g., `./src/contracts`).
+
+## Configuration Options
+
+The `SuiCodegenConfig` type supports the following options:
+
+| Option                         | Type                   | Default | Description                                                                                                                                                           |
+| ------------------------------ | ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `output`                       | `string`               | —       | The directory where generated code will be written                                                                                                                    |
+| `packages`                     | `PackageConfig[]`      | —       | Array of Move packages to generate code for                                                                                                                           |
+| `prune`                        | `boolean`              | `true`  | When enabled, only generates code for the main package and omits dependency modules (dependency types referenced by included types are still generated under `deps/`) |
+| `generateSummaries`            | `boolean`              | `true`  | Automatically run `sui move summary` before generating code. Creates a `package_summaries` directory in your Move package which can be added to `.gitignore`          |
+| `generate`                     | `GenerateOptions`      | —       | Default [generate options](#the-generate-option) (types, functions) for all packages                                                                                  |
+| `importExtension`              | `'.js' \| '.ts' \| ''` | `'.js'` | File extension used in generated import statements                                                                                                                    |
+| `includePhantomTypeParameters` | `boolean`              | `false` | Include [phantom type parameters](#phantom-types) as function arguments in generated BCS types                                                                        |
+
+### Package Configuration
+
+Each entry in the `packages` array configures a Move package to generate code from. Packages can be
+local (from source) or on-chain (fetched from a network).
+
+#### Local Packages
+
+| Option        | Type                     | Required | Description                                        |
+| ------------- | ------------------------ | -------- | -------------------------------------------------- |
+| `package`     | `string`                 | yes      | Package identifier (e.g., `@local-pkg/my-package`) |
+| `path`        | `string`                 | yes      | Path to the Move package directory                 |
+| `packageName` | `string`                 | no       | Custom name for generated code directory           |
+| `generate`    | `PackageGenerateOptions` | no       | Control what gets generated from this package      |
+
+```typescript
+{
+  package: '@local-pkg/my-package',
+  path: './move/my-package',
+}
+```
+
+#### On-Chain Packages
+
+For packages already deployed on-chain, generate code directly from a package ID or MVR name without
+needing local source code:
+
+| Option        | Type                     | Required | Description                                   |
+| ------------- | ------------------------ | -------- | --------------------------------------------- |
+| `package`     | `string`                 | yes      | Package ID or MVR name                        |
+| `packageName` | `string`                 | yes      | Name for the generated code directory         |
+| `network`     | `'mainnet' \| 'testnet'` | yes      | Network to fetch the package from             |
+| `generate`    | `PackageGenerateOptions` | no       | Control what gets generated from this package |
+
+```typescript
+{
+  package: '0xabf837e98c26087cba0883c0a7a28326b1fa3c5e1e2c5abdb486f9e8f594c837',
+  packageName: 'pyth',
+  network: 'testnet',
+}
+```
+
+## The `generate` option
+
+The `generate` option controls what code is produced. It can be set at the global level (as a
+default for all packages), at the per-package level, and at the per-module level. More specific
+settings override less specific ones.
+
+When no `generate` option is set, everything is generated (all types and functions). Package-level
+`types` and `functions` also default to `true`. In the record form of `modules`, per-module `types`
+and `functions` default to `false` — you opt in to exactly what you need from each module. Use
+`true` as a shorthand to include everything from a module with package-level defaults.
+
+At the **global** and **package** levels, `types` and `functions` only accept boolean values (or an
+object for `functions`). Name-based filtering with `string[]` is only available at the **module**
+level inside the record form of `modules`, where the filter applies unambiguously to a single
+module.
+
+```typescript
+// Global or package level
+generate: {
+  types: true | false,
+  functions: true | false | { private: boolean | 'entry' },
+  modules: string[] | Record<string, true | { types?, functions? }>,  // package-level only
+}
+
+// Module level (inside the record form of modules)
+modules: {
+  my_module: true,  // shorthand for "include everything"
+  other_module: {
+    types: true | false | string[],
+    functions: true | false | string[] | { private: boolean | 'entry' },
+  }
+}
+```
+
+### Types
+
+Controls which BCS type definitions (structs and enums) are generated:
+
+- `true` — generate all types
+- `false` — skip type generation
+- `string[]` — generate only the listed types by name _(module level only)_
+
+### Functions
+
+Controls which Move function wrappers are generated:
+
+- `true` — generate all public functions and private entry functions
+- `false` — skip function generation
+- `string[]` — generate only the listed functions by name; includes private functions _(module level
+  only)_
+- `{ private: 'entry' }` — generate public functions plus private entry functions
+- `{ private: true }` — generate all functions including private
+- `{ private: false }` — only generate public functions
+
+### Modules
+
+Controls which modules from the package are included. Only available at the package level, not at
+the global level.
+
+- Not set (default) — include all modules
+- `string[]` — only include the listed modules
+- `Record<string, true | { types?, functions? }>` — only include the listed modules, with per-module
+  overrides for `types` and `functions`. Use `true` as a shorthand to include everything from a
+  module with package-level defaults
+
+### Examples
+
+Only generate code from specific modules of the Sui framework:
+
+```typescript
+{
+  package: '0x0000000000000000000000000000000000000000000000000000000000000002',
+  packageName: '0x2',
+  network: 'testnet',
+  generate: {
+    modules: ['kiosk', 'kiosk_extension', 'transfer_policy'],
+  },
+}
+```
+
+Only generate a single type from a dependency (functions are omitted automatically since `generate`
+is configured and `functions` is not specified):
+
+```typescript
+{
+  package: '0xabf837e98c26087cba0883c0a7a28326b1fa3c5e1e2c5abdb486f9e8f594c837',
+  packageName: 'pyth',
+  network: 'testnet',
+  generate: {
+    modules: {
+      state: { types: ['State'] },
+    },
+  },
+}
+```
+
+Generate specific types and functions from individual modules:
+
+```typescript
+{
+  package: '@local-pkg/my-package',
+  path: './move/my-package',
+  generate: {
+    modules: {
+      token: {
+        types: ['Token', 'TokenMetadata'],
+        functions: ['mint', 'burn', 'transfer'],
+      },
+      admin: {
+        types: true,
+        functions: ['initialize'],
+      },
+    },
+  },
+}
+```
+
+Generate all types but include all private functions for a local package:
+
+```typescript
+{
+  package: '@local-pkg/my-package',
+  path: './move/my-package',
+  generate: {
+    functions: { private: true },
+  },
+}
+```
+
+### Dependency pruning
+
+The global `prune` option (default: `true`) controls whether dependency packages are included in the
+output. Even when pruning is enabled, dependency types referenced by your included types are still
+generated under `deps/`:
+
+```
+src/contracts/
+├── mypackage/
+│   ├── module_a.ts
+│   ├── module_b.ts
+│   └── deps/
+│       └── 0x2/
+│           └── balance.ts     # Auto-included dependency type
+└── utils/
+    └── index.ts               # Shared utilities (always generated)
+```
+
+Set `prune: false` to generate all dependency modules with their full types and functions.
+
+## Phantom Types
+
+In Move, phantom type parameters are type parameters that only appear at the type level and don't
+affect the runtime data layout of a struct. For example, `Balance<T>` has a phantom type parameter
+`T` that indicates the coin type, but the actual serialized data only contains a `u64` value:
+
+```move
+public struct Balance<phantom T> has store {
+    value: u64,
+}
+```
+
+### Default Behavior
+
+By default, codegen excludes phantom type parameters from the generated BCS type functions since
+they don't affect serialization. The generated type is a constant rather than a function:
+
+```typescript
+
+	name: `${$moduleName}::Balance<phantom T>`,
+	fields: {
+		value: bcs.u64(),
+	},
+});
+```
+
+This works correctly for parsing on-chain data because phantom types don't change the binary layout.
+
+> **Note:** With the default behavior, phantom parameters appear as literals in the type name (e.g.,
+> `Balance<phantom T>`). These names are useful for debugging but are not valid on-chain type tags. If
+> you need valid type names with resolved phantom parameters, enable `includePhantomTypeParameters`.
+
+### Including Phantom Type Parameters
+
+If you need the phantom type parameters as function arguments (for example, to preserve type
+information for other tooling), enable `includePhantomTypeParameters`:
+
+```typescript
+const config: SuiCodegenConfig = {
+	output: './src/contracts',
+	includePhantomTypeParameters: true,
+	packages: [
+		// ...
+	],
+};
+```
+
+With this option enabled, phantom type parameters become function arguments:
+
+```typescript
+
+	return new MoveStruct({
+		name: `${$moduleName}::Balance<${T.name}>` as const,
+		fields: {
+			value: bcs.u64(),
+		},
+	});
+}
+```
+
+## Using Generated Code
+
+### Calling Move Functions
+
+The generated code provides type-safe functions for calling Move functions:
+
+```typescript
+
+// Increment a counter
+const tx = new Transaction();
+tx.add(
+	counter.increment({
+		arguments: {
+			counter: '0x123...', // Counter object ID
+		},
+	}),
+);
+```
+
+### Parsing BCS Data
+
+Use generated BCS types to parse on-chain object data. Fetch the object with
+`include: { content: true }` and pass `object.content` to the generated type's `.parse()` method:
+
+```typescript
+
+async function readCounter(client: ClientWithCoreApi, id: string) {
+	const { object } = await client.core.getObject({
+		objectId: id,
+		include: { content: true },
+	});
+
+	// Parse the Move struct fields from BCS content
+	const parsed = CounterStruct.parse(object.content);
+	console.log('Counter value:', parsed.value);
+	console.log('Counter owner:', parsed.owner);
+
+	return parsed;
+}
+```
+
+> **Warning:** Always use `content`, not `objectBcs`, when parsing with generated types. The `objectBcs` field
+> contains a full object envelope with additional metadata that will cause parsing to fail. See the
+> [Core API docs](/sui/clients/core#objectbcs) for details.
+
+## Client Configuration
+
+### Using with MVR (Move Version Registry)
+
+If your package is registered on MVR, the generated code works without additional configuration.
+
+### Local Packages
+
+For local packages using `@local-pkg/*` identifiers, configure your client with package overrides:
+
+```typescript
+
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+	mvr: {
+		overrides: {
+			packages: {
+				'@local-pkg/counter': '0xYOUR_PACKAGE_ID',
+			},
+		},
+	},
+});
+```
+
+### With dApp Kit
+
+Configure package overrides when creating your dApp Kit instance:
+
+```typescript
+
+const GRPC_URLS = {
+	testnet: 'https://fullnode.testnet.sui.io:443',
+};
+
+const PACKAGE_IDS = {
+	testnet: {
+		counter: '0xYOUR_PACKAGE_ID',
+	},
+};
+
+const dAppKit = createDAppKit({
+	networks: ['testnet'],
+	createClient: (network) => {
+		return new SuiGrpcClient({
+			network,
+			baseUrl: GRPC_URLS[network],
+			mvr: {
+				overrides: {
+					packages: {
+						'@local-pkg/counter': PACKAGE_IDS[network].counter,
+					},
+				},
+			},
+		});
+	},
+});
+```
+
+## Related Resources
+
+- [create-dapp](/dapp-kit/getting-started/create-dapp) - Bootstrap a working dApp with codegen
+  already configured
+- [Sui Move documentation](https://docs.sui.io/concepts/sui-move-concepts)
+- [BCS documentation](/bcs)
+- [Transaction building](/sui/transaction-building/basics)
+- [dApp Kit](/dapp-kit)

package/dist/codegen/llms-index.md

@@ -0,0 +1,4 @@
+# TypeScript Codegen
+> Generate type-safe TypeScript code from Sui Move packages
+
+- [Sui TypeScript Codegen](./index.md): Generate type-safe TypeScript bindings from on-chain Sui Move packages

package/dist/dapp-kit/actions/connect-wallet.md

@@ -0,0 +1,69 @@
+# Connect Wallet
+
+> Programmatically connect to a Sui wallet
+
+The dApp Kit SDK provides an action for wallet connection, allowing users to connect, disconnect,
+and switch between wallets and accounts.
+
+> The [Connect Button](../web-components/connect-button) Web Component provides a complete wallet
+> connection UI.
+
+## Usage
+
+> 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.
+
+The `connectWallet` action prompts a wallet to connect and authorize accounts for your application:
+
+```typescript
+
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+// Connect to a specific wallet
+const result = await dAppKit.connectWallet({
+	wallet: myWallet, // UiWallet instance
+	account: myAccount, // Optional: specific account to select
+});
+
+console.log('Connected accounts:', result.accounts);
+```
+
+## Parameters
+
+- **`wallet`** - The `UiWallet` instance to connect to
+- **`account`** (optional) - A specific `UiWalletAccount` to set as the selected account. Defaults
+  to the first authorized account
+
+## Return Value
+
+Returns a `Promise` that resolves to an object containing:
+
+- **`accounts`** - Array of authorized `UiWalletAccount` instances
+
+## Example
+
+```typescript
+const wallets = dAppKit.stores.$wallets.get();
+
+const unsubscribe = dAppKit.stores.$connection.subscribe((connection) => {
+	if (connection.isConnected) {
+		console.log(`Connected account address: ${connection.account.address}`);
+	} else {
+		console.log({ connection });
+	}
+});
+
+if (wallets.length > 0) {
+	try {
+		const { accounts } = await dAppKit.connectWallet({
+			wallet: wallets[0],
+		});
+		console.log('Available accounts:', accounts);
+	} catch (error) {
+		console.error('Connection failed:', error);
+	}
+}
+```

package/dist/dapp-kit/actions/disconnect-wallet.md

@@ -0,0 +1,38 @@
+# Disconnect Wallet
+
+> Programmatically disconnect from a Sui wallet
+
+The `disconnectWallet` action terminates the connection with the currently connected wallet.
+
+> The [Connect Button](../web-components/connect-button) Web Component provides a complete wallet
+> connection UI.
+
+## Usage
+
+> **Note:** The disconnect action clears the connection state locally and attempts to notify the wallet. Even
+> if the wallet notification fails, the local state is always cleared to ensure a clean
+> disconnection.
+> 
+> Note that wallets may or may not implement the `disconnect` feature. Calling `disconnectWallet`
+> doesn't necessarily mean that the wallet accounts will be disconnected from the dApp within the
+> wallet itself - this is determined by each wallet's implementation.
+
+```typescript
+
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+await dAppKit.disconnectWallet();
+```
+
+## Parameters
+
+None.
+
+## Return Value
+
+Returns a `Promise` that resolves to `void` when the disconnection is complete.
+
+> The action may throw `WalletNotConnectedError` if no wallet is connected. However, wallet-specific
+> disconnect failures are logged but don't prevent the local connection state from being cleared.

package/dist/dapp-kit/actions/sign-and-execute-transaction.md

@@ -0,0 +1,96 @@
+# Sign and Execute Transaction
+
+> Sign and execute a transaction using the connected wallet
+
+The `signAndExecuteTransaction` action prompts the connected wallet to sign and immediately execute
+a transaction on the Sui network. This is the most common way to execute transactions in your dApp.
+
+## Usage
+
+```typescript
+
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+const tx = new Transaction();
+// No need to manually set sender - it's done automatically
+tx.transferObjects([coinWithBalance({ balance: 123 })], '0xrecipient...');
+
+const result = await dAppKit.signAndExecuteTransaction({
+	transaction: tx,
+});
+
+if (result.FailedTransaction) {
+	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+}
+
+console.log('Transaction digest:', result.Transaction.digest);
+```
+
+## Parameters
+
+- **`transaction`** - `Transaction | string` - The transaction to sign and execute. Can be either a
+  Transaction instance or base64-encoded bcs bytes for the transaction.
+- **`signal`** (optional) - `AbortSignal` - An abort signal to cancel the transaction request.
+
+## Return Value
+
+Returns a `Promise` that resolves to a `TransactionResult` discriminated union:
+
+```typescript
+type TransactionResult =
+	| { $kind: 'Transaction'; Transaction: Transaction }
+	| { $kind: 'FailedTransaction'; FailedTransaction: Transaction };
+```
+
+The `Transaction` object contains:
+
+- **`digest`** - `string` - The transaction digest (unique identifier for the executed transaction)
+- **`signatures`** - `string[]` - The signatures as base64-encoded strings
+- **`epoch`** - `string | null` - The epoch in which the transaction was executed
+- **`status`** - `ExecutionStatus` - The execution status with `success: boolean` and
+  `error: string | null`
+- **`effects`** - `TransactionEffects | null` - The parsed transaction effects (may be `null` if
+  effects parsing fails for unknown effect versions)
+- **`transaction`** - `TransactionData` - The parsed transaction data
+
+```typescript
+const result = await dAppKit.signAndExecuteTransaction({ transaction });
+
+if (result.FailedTransaction) {
+	console.error('Transaction failed:', result.FailedTransaction.status.error?.message);
+	return;
+}
+
+// Access the successful transaction results
+const tx = result.Transaction;
+console.log('Digest:', tx.digest);
+console.log('Signatures:', tx.signatures);
+console.log('Epoch:', tx.epoch);
+```
+
+## Transaction Building
+
+When passing a Transaction instance, the action automatically:
+
+1. Sets the sender address if not already set
+2. Builds the transaction using the current network's client
+3. Converts it to the appropriate format for the wallet
+4. Submits the transaction to the network
+
+## Wallet Compatibility
+
+- The action transparently handles both `sui:signAndExecuteTransaction` and
+  `sui:signAndExecuteTransactionBlock` wallet-standard features
+- The wallet handles network submission and response
+- Some wallets (Enoki, Enoki Connect, WalletConnect) may use the dApp Kit client and execute
+  transactions within the application as an implementation detail
+
+```typescript
+// The action automatically detects and uses the appropriate method
+// No special configuration needed
+const result = await dAppKit.signAndExecuteTransaction({
+	transaction: tx,
+});
+```

package/dist/dapp-kit/actions/sign-personal-message.md

@@ -0,0 +1,58 @@
+# Sign Personal Message
+
+> Sign an arbitrary message with the connected wallet
+
+The `signPersonalMessage` action prompts the connected wallet to sign a personal message. This is
+useful for authentication, proof of ownership, or other scenarios where you need cryptographic proof
+that a user controls a specific account.
+
+## Usage
+
+```typescript
+
+const dAppKit = createDAppKit({
+	/* config */
+});
+
+const message = new TextEncoder().encode('Please sign this message');
+const result = await dAppKit.signPersonalMessage({
+	message,
+});
+
+console.log('Message bytes:', result.bytes);
+console.log('Signature:', result.signature);
+```
+
+## Parameters
+
+- **`message`** - `Uint8Array` - The message to sign as a byte array
+
+## Return Value
+
+Returns a `Promise` that resolves to an object containing:
+
+- **`bytes`** - `string` - Base64 encoded message bytes
+- **`signature`** - `string` - Base64 encoded signature
+
+## Message Format
+
+The message parameter must be a `Uint8Array`. Common patterns for creating byte arrays:
+
+```typescript
+const textMessage = new TextEncoder().encode('Hello, Sui!');
+await dAppKit.signPersonalMessage({ message: textMessage });
+
+const jsonMessage = new TextEncoder().encode(
+	JSON.stringify({ action: 'sign', timestamp: Date.now() }),
+);
+await dAppKit.signPersonalMessage({ message: jsonMessage });
+```
+
+## Security Considerations
+
+### Message Content
+
+- Always display the message content clearly to users before signing
+- Avoid signing opaque or encoded data that users cannot understand
+- Include human-readable prefixes for different message types
+- Consider adding timestamps to prevent replay attacks