@mysten/sui 2.6.0 → 2.8.0

package/docs/plugins.md

@@ -0,0 +1,255 @@
+# Transaction Plugins
+
+> Extend transaction building with reusable plugins
+
+> **Warning:** The `Transaction` plugin API is experimental and may change rapidly as it is being
+> developed.
+
+This document describes the plugin API for the `Transaction` builder. It covers internal details
+intended for developers interested in extending the `Transaction` builder. Developers using the
+`Transaction` builder to build transactions do not need this level of detail. The `Transaction`
+builder includes a plugin system designed to extend how transactions are built. The two primary
+goals are:
+
+1. Allow developers to customize how data is resolved when building transactions.
+2. Provide a way for developers to extend the core commands that can be added to transactions.
+
+The Plugin API consists of three main components: serialization plugins, build plugins, and
+Transaction Intents. Serialization and build plugins act like middleware, allowing developers to
+modify the data and commands added to a transaction before it is serialized to JSON or built into
+BCS bytes. Transaction Intents are custom representations of user intents for a transaction,
+eventually resolved to one or more commands in the transaction.
+
+## Contents of a Transaction
+
+When a `Transaction` is created (e.g., `new Transaction()`), it is initialized with an empty
+[TransactionDataBuilder](/typedoc/classes/_mysten_sui.transactions.TransactionDataBuilder.html)
+instance which stores the state of the partially built transaction. The full API of the
+`TransactionDataBuilder` won't be covered here, but you can find the available methods and
+properties in the
+[typedoc definition](/typedoc/classes/_mysten_sui.transactions.TransactionDataBuilder.html).
+
+As commands are added to the `Transaction`, they are stored in the `TransactionDataBuilder`. The
+`TransactionData` contains a list of commands and their arguments. The exact arguments a command
+takes depend on the command, but they will be one of a few different types:
+
+- `GasCoin`: A reference to the coin used to pay for gas.
+- `Input`: An input to the transaction (described below).
+- `Result`: The result of a previous command.
+- `NestedResult`: If a previous command returns a tuple (e.g., `SplitCoin`), a `NestedResult` is
+  used to refer to a specific value in that tuple.
+
+Transactions also store a list of Inputs, which refer to user-provided values. Inputs can either be
+objects or Pure values and can be represented in several different ways:
+
+- `Pure`: An input value serialized to BCS. Pure values are generally scalar values or simple
+  wrappers like options or vectors and cannot represent object types.
+- `Object`: A fully resolved object reference, which will be one of the following types:
+  - `ImmOrOwnedObject`: A reference to an object, including the object's `id`, `version`, and
+    `digest`.
+  - `SharedObject`: A reference to a shared object, including the object's `id`,
+    `initialSharedVersion`, and whether the shared object is used mutably.
+  - `Receiving`: A reference to a receiving object, including the object's `id`, `version`, and
+    `digest`.
+- `UnresolvedPure`: A placeholder for a pure value that has not been serialized to BCS.
+- `UnresolvedObject`: A partial reference to an object, often containing just the object's `id`, but
+  may also include a version, digest, or initialSharedVersion.
+
+## Lifecycle of a Transaction
+
+Because transactions can contain `UnresolvedPure` and `UnresolvedObject` inputs, these values need
+to be resolved before the transaction can be serialized to BCS. However, these unresolved inputs can
+be represented in JSON. What may not be able to be represented in JSON are Transaction Intents.
+Transaction Intents represent custom concepts added by plugins or third-party SDKs. To account for
+this, the build process of a transaction is split into two phases: serialization and building.
+Serialization prepares the transaction to be serialized to JSON by running serialization plugins,
+and resolving any unsupported intents. The Build phase then runs, which runs build plugins and
+resolves any UnresolvedPure and UnresolvedObject inputs, before the transaction is serialized to
+BCS.
+
+## Serialization Plugins
+
+Serialization plugins can be added to a `Transaction` by calling the `addSerializationPlugin` method
+on a `Transaction` instance. Serialization plugins are called in the order they are added and are
+passed the `TransactionDataBuilder` instance of the transaction.
+
+```typescript
+const transaction = new Transaction();
+
+transaction.addSerializationPlugin(async (transactionData, buildOptions, next) => {
+	// Modify the data before running other serialization steps
+	await next();
+	// Modify the data after running other serialization steps
+});
+```
+
+## Build Plugins
+
+The build phase is responsible for taking unresolved objects and unresolved pure values and
+converting them to their resolved versions by querying the RPC API to fetch the missing data. Build
+plugins can hook into this phase to resolve some of this data from a cache instead, avoiding extra
+API calls.
+
+Build plugins work just like serialization plugins and can be added to a `Transaction` by calling
+the `addBuildPlugin` method on a `Transaction` instance. Build plugins are called in the order they
+are added and are passed the `TransactionDataBuilder` instance of the transaction.
+
+The following example demonstrates a simplified version of the caching plugin used by the
+`SerialTransactionExecutor` and `ParallelTransactionExecutor` classes. This example works by adding
+missing object versions and digest from a cache. Updating the cache (which could be done by looking
+at transaction effects of previous transactions) is not covered in this example.
+
+```typescript
+
+	BuildTransactionOptions,
+	Transaction,
+	TransactionDataBuilder,
+} from '@mysten/sui/transactions';
+
+const objectCache = new Map<string, { objectId: string; version: string; digest: string }>();
+
+function simpleObjectCachePlugin(
+	transactionData: TransactionDataBuilder,
+	_options: BuildTransactionOptions,
+	next: () => Promise<void>,
+) {
+	for (const input of transactionData.inputs) {
+		if (!input.UnresolvedObject) continue;
+
+		const cached = objectCache.get(input.UnresolvedObject.objectId);
+
+		if (!cached) continue;
+
+		if (cached.version && !input.UnresolvedObject.version) {
+			input.UnresolvedObject.version = cached.version;
+		}
+
+		if (cached.digest && !input.UnresolvedObject.digest) {
+			input.UnresolvedObject.digest = cached.digest;
+		}
+	}
+
+	return next();
+}
+
+// Example usage of the build plugin
+const transaction = new Transaction();
+transaction.addBuildPlugin(simpleObjectCachePlugin);
+```
+
+## Transaction Intents
+
+Transaction Intents consist of two parts: adding the intent to the transaction and resolving the
+intent to standard commands.
+
+Adding an intent is similar to adding any other command to a transaction:
+
+```typescript
+const transaction = new Transaction();
+
+transaction.add(
+	Commands.Intent({
+		name: 'TransferToSender',
+		inputs: {
+			objects: [transaction.object(someId)],
+		},
+	}),
+);
+```
+
+To make our custom `TransferToSender` intent easier to use, we can write a helper function that
+wraps things up a bit. The `add` method on transactions accepts a function that will be passed the
+current transaction instance. This allows us to create a helper that automatically adds the intent:
+
+```typescript
+function transferToSender(objects: TransactionObjectInput[]) {
+	return (tx: Transaction) => {
+		tx.add(
+			Commands.Intent({
+				name: 'TransferToSender',
+				inputs: {
+					objects: objects.map((obj) => tx.object(obj)),
+				},
+			}),
+		);
+	};
+}
+
+const transaction = new Transaction();
+
+transaction.add(transferToSender(['0x1234']));
+```
+
+Now that we've added the intent to the transaction, we need to resolve the intent to standard
+commands. To do this, we'll use the `addIntentResolver` method on the `Transaction` instance. The
+`addIntentResolver` method works like serialization and build plugins but will only be called if the
+intent is present in the transaction.
+
+```typescript
+const transaction = new Transaction();
+
+transaction.addIntentResolver('TransferToSender', resolveTransferToSender);
+
+async function resolveTransferToSender(
+	transactionData: TransactionDataBuilder,
+	buildOptions: BuildTransactionOptions,
+	next: () => Promise<void>,
+) {
+	if (!transactionData.sender) {
+		throw new Error('Sender must be set to resolve TransferToSender');
+	}
+
+	// Add an input that references the sender's address
+	const addressInput = Inputs.Pure(bcs.Address.serialize(transactionData.sender));
+	transactionData.inputs.push(addressInput);
+	// Get the index of the input to use when adding the TransferObjects command
+	const addressIndex = transactionData.inputs.length - 1;
+
+	for (const [index, transaction] of transactionData.commands.entries()) {
+		if (transaction.$kind !== '$Intent' || transaction.$Intent.name !== 'TransferToSender') {
+			continue;
+		}
+
+		// This will replace the intent command with the correct TransferObjects command
+		transactionData.replaceCommand(index, [
+			Commands.TransferObjects(
+				// The inputs for intents are not currently typed, so we need to cast to the correct type here
+				transaction.$Intent.inputs.objects as Extract<
+					TransactionObjectArgument,
+					{ $kind: 'Input' }
+				>,
+				// This is a CallArg referencing the addressInput we added above
+				{
+					Input: addressIndex,
+				},
+			),
+		]);
+	}
+
+	// Plugins always need to call next() to continue the build process
+	return next();
+}
+```
+
+Manually adding intent resolvers to a transaction can be cumbersome, so we can add the resolver
+automatically when our `transferToSender` helper is called:
+
+```typescript
+function transferToSender(objects: TransactionObjectInput[]) {
+	return (tx: Transaction) => {
+		// As long as we are adding the same function reference, it will only be added once
+		tx.addIntentResolver('TransferToSender', resolveTransferToSender);
+		tx.add(
+			Commands.Intent({
+				name: 'TransferToSender',
+				inputs: {
+					objects: objects.map((obj) => tx.object(obj)),
+				},
+			}),
+		);
+	};
+}
+
+const transaction = new Transaction();
+transaction.add(transferToSender(['0x1234']));
+```

package/docs/sdk-building.md

@@ -0,0 +1,340 @@
+# Building SDKs
+
+> Build custom SDKs on top of the Sui TypeScript SDK
+
+This guide covers recommended patterns for building TypeScript SDKs that integrate with the Sui SDK.
+Following these patterns ensures your SDK integrates seamlessly with the ecosystem, works across
+different transports (JSON-RPC, GraphQL, gRPC), and composes well with other SDKs.
+
+**Key requirement:** All SDKs should depend on [`ClientWithCoreApi`](./clients/core), which is the
+transport-agnostic interface implemented by all Sui clients. This ensures your SDK works with any
+client the user chooses.
+
+## Package Setup
+
+### Use Mysten Packages as Peer Dependencies
+
+SDKs should declare all `@mysten/*` packages as **peer dependencies** rather than direct
+dependencies. This ensures users get a single shared instance of each package, avoiding version
+conflicts and duplicate code.
+
+```json title="package.json"
+{
+	"name": "@your-org/your-sdk",
+	"peerDependencies": {
+		"@mysten/sui": "^2.0.0",
+		"@mysten/bcs": "^2.0.0"
+	},
+	"devDependencies": {
+		"@mysten/sui": "^2.0.0",
+		"@mysten/bcs": "^2.0.0"
+	}
+}
+```
+
+This approach:
+
+- Prevents multiple versions of Mysten packages from being bundled
+- Ensures compatibility with user's chosen package versions
+- Reduces bundle size for end users
+- Avoids subtle bugs from mismatched package instances
+- Allows the SDK to work with any compatible client
+
+## Client Extensions
+
+The recommended way to build SDKs is using the **client extension pattern**. This allows your SDK to
+extend the Sui client with custom functionality. This makes it easier to use custom SDKs across the
+ecosystem without having to build custom bindings (like react context providers) for each individual
+SDK and client.
+
+### Extension Pattern
+
+Client extensions use the `$extend` method to add functionality to any Sui client. Create a factory
+function that returns a `name` and `register` function:
+
+```typescript
+
+	name?: Name;
+	// Add SDK-specific configuration here
+	apiKey?: string;
+}
+
+	name = 'mySDK' as Name,
+	...options
+}: MySDKOptions<Name> = {}) {
+	return {
+		name,
+		register: (client: ClientWithCoreApi) => {
+			return new MySDKClient({ client, ...options });
+		},
+	};
+}
+
+	#client: ClientWithCoreApi;
+	#apiKey?: string;
+
+	constructor({ client, apiKey }: { client: ClientWithCoreApi; apiKey?: string }) {
+		this.#client = client;
+		this.#apiKey = apiKey;
+	}
+
+	async getResource(id: string) {
+		const result = await this.#client.core.getObject({ objectId: id });
+		// Process and return result
+		return result;
+	}
+}
+```
+
+Users can then extend their client:
+
+```typescript
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+}).$extend(mySDK());
+
+// Access your extension
+await client.mySDK.getResource('0x...');
+```
+
+### Real-World Examples
+
+Several official SDKs use this pattern:
+
+- **[@mysten/walrus](https://www.npmjs.com/package/@mysten/walrus)** - Decentralized storage
+- **[@mysten/seal](https://www.npmjs.com/package/@mysten/seal)** - Encryption and key management
+
+## SDK Organization
+
+Most Mysten SDKs do not strictly follow these patterns yet, but we recommend scoping methods on your
+client extension into the following categories for clarity and consistency:
+
+| Property | Purpose                                                   | Example                             |
+| -------- | --------------------------------------------------------- | ----------------------------------- |
+| Methods  | Top-level operations (execute actions or read/parse data) | `sdk.readBlob()`, `sdk.getConfig()` |
+| `tx`     | Methods that create transactions without executing        | `sdk.tx.registerBlob()`             |
+| `bcs`    | BCS type definitions for encoding/decoding                | `sdk.bcs.MyStruct`                  |
+| `call`   | Methods returning Move calls that can be used with tx.add | `sdk.call.myFunction()`             |
+| `view`   | Methods that use simulate API to read onchain state       | `sdk.view.getState()`               |
+
+```typescript
+
+	#client: ClientWithCoreApi;
+
+	constructor({ client }: { client: ClientWithCoreApi }) {
+		this.#client = client;
+	}
+
+	// Top-level methods - execute actions or read/parse data
+	async executeAction(options: ActionOptions) {
+		const transaction = this.tx.createAction(options);
+		// Execute and return result
+	}
+
+	async getResource(objectId: string) {
+		const { object } = await this.#client.core.getObject({
+			objectId,
+			include: { content: true },
+		});
+		return myModule.MyStruct.parse(object.content);
+	}
+
+	// Transaction builders
+	tx = {
+		createAction: (options: ActionOptions) => {
+			const transaction = new Transaction();
+			transaction.add(this.call.action(options));
+			return transaction;
+		},
+	};
+
+	// Move call helpers - use generated functions with typed options
+	call = {
+		action: (options: ActionOptions) => {
+			return myModule.action({
+				arguments: {
+					obj: options.objectId,
+					amount: options.amount,
+				},
+			});
+		},
+	};
+
+	// View methods - use simulate API to read onchain state
+	view = {
+		getBalance: async (managerId: string) => {
+			const tx = new Transaction();
+			tx.add(myModule.getBalance({ arguments: { manager: managerId } }));
+
+			const res = await this.#client.core.simulateTransaction({
+				transaction: tx,
+				include: { commandResults: true },
+			});
+
+			return bcs.U64.parse(res.commandResults![0].returnValues[0].bcs);
+		},
+	};
+}
+```
+
+## Transaction Building Patterns
+
+### Transaction Thunks
+
+Transaction thunks are functions that accept a `Transaction` and mutate it. This pattern enables
+composition across multiple SDKs in a single transaction.
+
+```typescript
+// Synchronous thunk for operations that don't need async work
+function createResource(options: { name: string }) {
+	return (tx: Transaction): TransactionObjectArgument => {
+		const [resource] = tx.moveCall({
+			target: `${PACKAGE_ID}::module::create`,
+			arguments: [tx.pure.string(options.name)],
+		});
+		return resource;
+	};
+}
+
+// Usage
+const tx = new Transaction();
+const resource = tx.add(createResource({ name: 'my-resource' }));
+tx.transferObjects([resource], recipient);
+```
+
+### Async Thunks
+
+For operations requiring async work (like fetching package IDs or configuration), return async
+thunks. These are used with `tx.add()` exactly like synchronous thunks - the async resolution
+happens automatically before signing:
+
+```typescript
+function createResourceAsync(options: { name: string }) {
+	return async (tx: Transaction): Promise<TransactionObjectArgument> => {
+		// Async work happens here, before the transaction is signed
+		const packageId = await getLatestPackageId();
+
+		const [resource] = tx.moveCall({
+			target: `${packageId}::module::create`,
+			arguments: [tx.pure.string(options.name)],
+		});
+		return resource;
+	};
+}
+
+// Usage is identical to synchronous thunks
+const tx = new Transaction();
+const resource = tx.add(createResourceAsync({ name: 'my-resource' }));
+tx.transferObjects([resource], recipient);
+
+// Async work resolves automatically when the transaction is built/signed
+await signer.signAndExecuteTransaction({ transaction: tx, client });
+```
+
+This pattern is critical for web wallet compatibility - async work that happens during transaction
+construction won't block the popup triggered by user interaction.
+
+## Transaction Execution
+
+### Accept a Signer Parameter
+
+For methods that execute transactions, accept a `Signer` parameter and always use the signer to
+execute the transaction. This enables:
+
+- Wallet integration through dApp Kit
+- Transaction sponsorship
+- Custom signing flows
+
+```typescript
+
+	#client: ClientWithCoreApi;
+
+	async createAndExecute({ signer, ...options }: CreateOptions & { signer: Signer }) {
+		const transaction = this.tx.create(options);
+
+		// Use signAndExecuteTransaction for maximum flexibility
+		const result = await signer.signAndExecuteTransaction({
+			transaction,
+			client: this.#client,
+		});
+
+		return result;
+	}
+}
+```
+
+Using `signAndExecuteTransaction` allows wallets and sponsors to customize execution behavior.
+
+## Code Generation
+
+For SDKs that interact with Move contracts, use **[@mysten/codegen](/codegen)** to generate
+type-safe TypeScript bindings from your Move packages.
+
+Benefits include type safety, BCS parsing, IDE support, and MoveRegistry support for human-readable
+package names. See the [codegen documentation](/codegen) for setup instructions.
+
+### Using Generated Code
+
+The generated code provides both Move call functions and BCS struct definitions:
+
+```typescript
+// Generated Move call functions return thunks with typed options
+const tx = new Transaction();
+tx.add(
+	myContract.doSomething({
+		arguments: {
+			obj: '0x123...',
+			amount: 100n,
+		},
+	}),
+);
+
+// Generated BCS types parse on-chain data
+const { object } = await client.core.getObject({
+	objectId: '0x123...',
+	include: { content: true },
+});
+const parsed = myContract.MyStruct.parse(object.content);
+```
+
+See the [codegen documentation](/codegen) for complete setup and configuration options.
+
+## Reading Object Contents
+
+SDKs often need to fetch objects and parse their BCS-encoded content. Use `getObject` with
+`include: { content: true }` and generated BCS types:
+
+```typescript
+async function getResource(objectId: string) {
+	const { object } = await this.#client.core.getObject({
+		objectId,
+		include: { content: true },
+	});
+
+	if (!object) {
+		throw new Error(`Object ${objectId} not found`);
+	}
+
+	// Parse BCS content using generated type
+	return MyStruct.parse(object.content);
+}
+```
+
+For batching multiple object fetches, use `getObjects`:
+
+```typescript
+async function getResources(objectIds: string[]) {
+	const { objects } = await this.#client.core.getObjects({
+		objectIds,
+		include: { content: true },
+	});
+
+	return objects.map((obj) => {
+		if (obj instanceof Error) {
+			throw obj;
+		}
+		return MyStruct.parse(obj.content);
+	});
+}
+```