@mysten/docs 0.1.26 → 0.1.28

package/dist/sui/transactions/signing-and-execution.md

@@ -0,0 +1,401 @@
+# Signing and Execution
+
+> Sign transactions and execute them on the Sui network
+
+Once you've built a transaction, you need to sign it and submit it to the network. For background on
+how transaction signing and finality work at the protocol level, see the Sui documentation on
+[transaction lifecycle](https://docs.sui.io/concepts/transactions/transaction-lifecycle) and
+[transaction auth](https://docs.sui.io/concepts/transactions/transaction-auth).
+
+## Simulating transactions
+
+Use `simulateTransaction` to dry-run a transaction without executing it. This is useful for
+estimating gas costs, checking return values, and validating transactions before executing.
+
+```typescript
+
+const grpcClient = new SuiGrpcClient({
+	network: 'mainnet',
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+});
+
+const result = await grpcClient.simulateTransaction({
+	transaction: tx,
+	include: {
+		effects: true,
+		balanceChanges: true,
+		commandResults: true,
+	},
+});
+
+if (result.$kind === 'FailedTransaction') {
+	console.error('Simulation failed:', result.FailedTransaction.status.error?.message);
+} else {
+	console.log('Balance changes:', result.Transaction.balanceChanges);
+	console.log('Command results:', result.commandResults);
+}
+```
+
+### `include` options
+
+The `include` parameter controls what data is returned from the simulation. All fields are optional
+and default to `false`:
+
+| Field            | Description                                                                            |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| `effects`        | Execution effects: created, mutated, and deleted objects, gas usage                    |
+| `events`         | Move events emitted during execution                                                   |
+| `balanceChanges` | Token balance changes for each affected address and coin type                          |
+| `objectTypes`    | Map of object ID to type string for all changed objects                                |
+| `transaction`    | The full transaction data (sender, commands, gas config)                               |
+| `bcs`            | Raw BCS-encoded transaction bytes                                                      |
+| `commandResults` | BCS-encoded return values and mutated references from each command _(simulation only)_ |
+
+The `commandResults` field is unique to simulation. It is not available on `executeTransaction`.
+Each entry contains `returnValues` and `mutatedReferences`, both as BCS-encoded `Uint8Array` values
+that you can decode with the [BCS library](/bcs).
+
+## With a keypair (backend or scripts)
+
+The simplest approach. The keypair signs the transaction and submits it to the network in one call:
+
+```typescript
+
+const keypair = Ed25519Keypair.fromSecretKey('suiprivkey1...');
+const grpcClient = new SuiGrpcClient({
+	network: 'mainnet',
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+});
+
+const result = await keypair.signAndExecuteTransaction({
+	transaction: tx,
+	client: grpcClient,
+});
+```
+
+`fromSecretKey` accepts a Bech32-encoded private key (`suiprivkey1...`) or a raw 32-byte
+`Uint8Array`. You can also use `Ed25519Keypair.deriveKeypair(mnemonic)` to derive from a mnemonic
+phrase.
+
+This method automatically sets the sender to the keypair's address, builds the transaction, signs
+it, and executes it. The result includes the transaction data and effects by default.
+
+Available keypair types:
+
+- `Ed25519Keypair` from `@mysten/sui/keypairs/ed25519`
+- `Secp256k1Keypair` from `@mysten/sui/keypairs/secp256k1`
+- `Secp256r1Keypair` from `@mysten/sui/keypairs/secp256r1`
+- `PasskeyKeypair` from `@mysten/sui/keypairs/passkey`
+
+## With dapp-kit (React frontend)
+
+In a React app, use the `useSignAndExecuteTransaction` hook. The user's connected wallet signs and
+submits the transaction:
+
+```tsx
+
+function SendButton() {
+	const { mutate: signAndExecute } = useSignAndExecuteTransaction();
+
+	function handleClick() {
+		const tx = new Transaction();
+		// ... build your transaction ...
+
+		signAndExecute(
+			{ transaction: tx },
+			{
+				onSuccess: (result) => {
+					console.log('Transaction digest:', result.digest);
+				},
+				onError: (error) => {
+					console.error('Transaction failed:', error);
+				},
+			},
+		);
+	}
+
+	return <button onClick={handleClick}>Send</button>;
+}
+```
+
+See the [dapp-kit documentation](/dapp-kit) for full setup instructions.
+
+## Sign without executing
+
+Sometimes you need the signature without immediately executing, such as for multi-sig, sponsored
+transactions, or delayed execution.
+
+### With a keypair
+
+```typescript
+// Build the transaction bytes first
+tx.setSender(keypair.toSuiAddress());
+const bytes = await tx.build({ client: grpcClient });
+
+// Sign the bytes
+const { signature } = await keypair.signTransaction(bytes);
+```
+
+### With dapp-kit
+
+```tsx
+
+function SignButton() {
+	const { mutate: signTransaction } = useSignTransaction();
+
+	function handleClick() {
+		const tx = new Transaction();
+		// ... build your transaction ...
+
+		signTransaction(
+			{ transaction: tx },
+			{
+				onSuccess: ({ bytes, signature }) => {
+					// Send bytes + signature to your backend, sponsor, etc.
+				},
+			},
+		);
+	}
+
+	return <button onClick={handleClick}>Sign</button>;
+}
+```
+
+## Manual execution
+
+When you already have the transaction bytes and signature(s), execute directly through the client:
+
+```typescript
+const result = await grpcClient.executeTransaction({
+	transaction: bytes, // Uint8Array
+	signatures: [signature], // string[]
+	include: {
+		effects: true,
+		events: true,
+		balanceChanges: true,
+		objectTypes: true,
+	},
+});
+```
+
+The `include` parameter controls what data is returned with the result:
+
+| Field            | Description                                              |
+| ---------------- | -------------------------------------------------------- |
+| `transaction`    | The full transaction data (sender, commands, gas)        |
+| `effects`        | Execution effects (created, mutated, or deleted objects) |
+| `events`         | Move events emitted during execution                     |
+| `balanceChanges` | Token balance changes for each affected address          |
+| `objectTypes`    | Map of object ID to type for changed objects             |
+| `bcs`            | Raw BCS bytes of the transaction                         |
+
+## Observing results
+
+### Checking success or failure
+
+Every transaction result is a discriminated union. Always check which variant you received:
+
+```typescript
+const result = await keypair.signAndExecuteTransaction({
+	transaction: tx,
+	client: grpcClient,
+});
+
+if (result.$kind === 'FailedTransaction') {
+	const { status } = result.FailedTransaction;
+	console.error('Transaction failed:', status.error?.message);
+} else {
+	console.log('Transaction succeeded:', result.Transaction.digest);
+}
+```
+
+You can also use the shorthand:
+
+```typescript
+const tx = result.Transaction ?? result.FailedTransaction;
+if (!tx.status.success) {
+	throw new Error(`Failed: ${tx.status.error?.message}`);
+}
+```
+
+### Waiting for indexing
+
+After a transaction executes, read APIs (like `getBalance` or `getObject`) might not immediately
+show the effects. You must also wait before executing a subsequent transaction that depends on
+objects created or modified by the first one. Use `waitForTransaction` to ensure consistency:
+
+```typescript
+const result = await keypair.signAndExecuteTransaction({
+	transaction: tx,
+	client: grpcClient,
+});
+
+// Wait for the transaction to be indexed
+await grpcClient.waitForTransaction({ result });
+
+// Now reads will reflect the transaction's effects
+const { balance } = await grpcClient.getBalance({ owner: myAddress });
+```
+
+You can also wait by digest:
+
+```typescript
+await grpcClient.waitForTransaction({ digest: result.Transaction.digest });
+```
+
+## Gas configuration
+
+Every Sui transaction costs gas. The SDK handles gas automatically in most cases. It sets the gas
+price, estimates the budget, and selects how to pay. You only need to configure gas explicitly for
+special cases.
+
+### Defaults
+
+When you don't configure gas explicitly, the SDK:
+
+1. **Gas price**: Uses the network's reference gas price
+2. **Gas budget**: Simulates the transaction and uses the result to set an appropriate budget
+3. **Gas payment**: Uses address balances, falling back to coin objects when the balance is below
+   the budget
+
+For most transactions, the defaults work well and you don't need to change anything.
+
+### Explicit gas settings
+
+```typescript
+// Override the reference gas price
+tx.setGasPrice(1500);
+
+// Override the simulated budget (in MIST)
+tx.setGasBudget(50_000_000);
+```
+
+### Gas payment with coin objects
+
+Specify exactly which coins to use for gas. The system merges these coins into a single gas coin
+before execution:
+
+```typescript
+tx.setGasPayment([
+	{ objectId: '0xCoin1', version: '1', digest: 'abc...' },
+	{ objectId: '0xCoin2', version: '2', digest: 'def...' },
+]);
+```
+
+The coins you provide must not overlap with any object inputs in your transaction.
+
+### Gas payment with address balance
+
+To pay gas from your address balance instead of coin objects, pass an empty array:
+
+```typescript
+tx.setGasPayment([]);
+```
+
+This is particularly useful for [offline building](./offline) and
+[sponsored transactions](#sponsored-transactions), because there are no coin object versions to look
+up or coordinate.
+
+### The gas coin (`tx.gas`)
+
+`tx.gas` references the coin used for gas payment. You can split SUI from it, merge coins into it,
+or transfer it to another address:
+
+```typescript
+const [coin] = tx.splitCoins(tx.gas, [1_000_000_000]);
+tx.transferObjects([coin], '0xRecipientAddress');
+```
+
+> **Warning:** `tx.gas` only works when gas is paid from coin objects. If gas is paid from address balances
+> (through `setGasPayment([])`), `tx.gas` is not available. Use [`tx.coin()`](./coins-and-balances)
+> instead, which works in both cases.
+
+## Sponsored transactions
+
+In a sponsored transaction, someone other than the sender pays for gas. There are two flows
+depending on whether gas is paid from coin objects or address balances.
+
+### Coin-based sponsorship
+
+The traditional flow where the sponsor provides specific gas coin objects:
+
+```typescript
+// 1. User builds transaction kind bytes (no gas info)
+const tx = new Transaction();
+// ... add commands ...
+const kindBytes = await tx.build({ client: grpcClient, onlyTransactionKind: true });
+
+// 2. Sponsor wraps with gas info
+const sponsoredTx = Transaction.fromKind(kindBytes);
+sponsoredTx.setSender(userAddress);
+sponsoredTx.setGasOwner(sponsorAddress);
+sponsoredTx.setGasPayment(sponsorGasCoins);
+
+// 3. Build the full transaction
+const fullBytes = await sponsoredTx.build({ client: grpcClient });
+
+// 4. Both parties sign
+const { signature: userSignature } = await userKeypair.signTransaction(fullBytes);
+const { signature: sponsorSignature } = await sponsorKeypair.signTransaction(fullBytes);
+
+// 5. Execute with both signatures
+const result = await grpcClient.executeTransaction({
+	transaction: fullBytes,
+	signatures: [userSignature, sponsorSignature],
+});
+```
+
+> **Warning:** The user must wait for the sponsor to set gas coins before signing, because gas coins are part of
+> the signed transaction data.
+
+### Address balance sponsorship
+
+When the sponsor pays from their address balance instead of specific coins, the flow is simpler
+because there are no coin object references to coordinate:
+
+```typescript
+// 1. User builds and signs the transaction first
+const tx = new Transaction();
+tx.setSender(userAddress);
+tx.setGasOwner(sponsorAddress);
+tx.setGasPayment([]); // empty array = use address balance for gas
+// ... add commands ...
+
+const bytes = await tx.build({ client: grpcClient });
+const { signature: userSignature } = await userKeypair.signTransaction(bytes);
+
+// 2. Sponsor signs (can happen asynchronously)
+const { signature: sponsorSignature } = await sponsorKeypair.signTransaction(bytes);
+
+// 3. Either party executes
+const result = await grpcClient.executeTransaction({
+	transaction: bytes,
+	signatures: [userSignature, sponsorSignature],
+});
+```
+
+The key advantage: the sender can sign before the sponsor, enabling simpler async flows. No need to
+coordinate gas coin selection.
+
+### Sending tokens in sponsored transactions
+
+When building sponsored transactions, set `useGasCoin: false` so the SDK doesn't try to split the
+gas coin (which belongs to the sponsor):
+
+```typescript
+
+const tx = new Transaction();
+
+// Send to address balance (preferred)
+tx.moveCall({
+	target: '0x2::balance::send_funds',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [
+		tx.balance({ balance: 1_000_000_000n, useGasCoin: false }),
+		tx.pure.address('0xRecipientAddress'),
+	],
+});
+
+// Or send as a coin object
+tx.transferObjects([tx.coin({ balance: 1_000_000_000, useGasCoin: false })], '0xRecipientAddress');
+```

package/dist/zksend/index.md

@@ -7,7 +7,7 @@ to create your own zkSend Claim Links, with support for any publicly transferrab
 
 ## Installation
 
-```sh npm2yarn
+```npm
 npm i @mysten/zksend @mysten/sui
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mysten/docs",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "LLM-friendly documentation for the Sui TypeScript SDK ecosystem",
   "license": "Apache-2.0",
   "repository": {
@@ -29,24 +29,24 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "@mysten/aws-kms-signer": "0.1.2",
+    "@mysten/bcs": "2.0.5",
     "@mysten/dapp-kit": "1.0.6",
     "@mysten/dapp-kit-core": "1.3.2",
     "@mysten/dapp-kit-react": "2.0.3",
-    "@mysten/bcs": "2.0.5",
-    "@mysten/deepbook-v3": "1.3.6",
     "@mysten/enoki-connect": "1.0.4",
     "@mysten/enoki": "1.0.8",
+    "@mysten/deepbook-v3": "1.4.1",
     "@mysten/gcp-kms-signer": "0.1.2",
-    "@mysten/ledger-signer": "0.1.2",
     "@mysten/kiosk": "1.2.6",
     "@mysten/payment-kit": "0.1.11",
     "@mysten/seal": "1.1.3",
-    "@mysten/signers": "1.0.5",
     "@mysten/slush-wallet": "1.0.5",
+    "@mysten/ledger-signer": "0.1.2",
+    "@mysten/signers": "1.0.5",
     "@mysten/sui": "2.17.0",
     "@mysten/utils": "0.3.3",
-    "@mysten/walrus": "1.1.7",
     "@mysten/wallet-standard": "0.20.3",
+    "@mysten/walrus": "1.1.7",
     "@mysten/webcrypto-signer": "0.1.2",
     "@mysten/zksend": "1.1.2",
     "@mysten/suins": "1.1.4"
@@ -69,6 +69,7 @@
     "dev": "next dev",
     "start": "next start",
     "postinstall": "fumadocs-mdx",
+    "test": "node scripts/validate-llm-docs.ts",
     "validate-docs": "node scripts/validate-llm-docs.ts",
     "prettier:check": "prettier -c --ignore-unknown .",
     "prettier:fix": "prettier -w --ignore-unknown .",

package/dist/sui/faucet.md

@@ -1,26 +0,0 @@
-# Faucet
-
-> Request test SUI tokens from the faucet on Devnet, Testnet, or local networks.
-
-Devnet, Testnet, and local networks include faucets that mint SUI. You can use the Sui TypeScript
-SDK to call a network's faucet and provide SUI to the address you provide.
-
-To request SUI from a faucet, import the `requestSuiFromFaucetV2` function from the
-`@mysten/sui/faucet` package to your project.
-
-```typescript
-
-```
-
-Use `requestSuiFromFaucetV2` in your TypeScript code to request SUI from the network's faucet.
-
-```typescript
-await requestSuiFromFaucetV2({
-	host: getFaucetHost('testnet'),
-	recipient: <RECIPIENT_ADDRESS>,
-});
-```
-
-> **Note:** Faucets on Devnet and Testnet are rate limited. If you run the script too many times, you surpass
-> the limit and must wait to successfully run it again. For Testnet, the best way to get SUI is
-> through the Web UI: `faucet.sui.io`.

package/dist/sui/hello-sui.md

@@ -1,115 +0,0 @@
-# Hello Sui
-
-> Build your first Sui application with the TypeScript SDK.
-
-This basic example introduces you to the Sui TypeScript SDK. The Node.js example mints SUI on a Sui
-network and then queries the address to get a sum for the owned SUI. You don't need to use an IDE to
-complete the example, but one like Microsoft Visual Studio Code helps centralize more advanced
-projects.
-
-## Before you begin
-
-You need an address on a Sui development network (Devnet, Testnet, or local). If you don't already
-have an address, use the [Sui Client CLI](https://docs.sui.io/references/cli/client) or the
-[Sui Wallet browser extension](https://docs.mystenlabs.com) to create one.
-
-You also need [Node.js](https://nodejs.org/en/download/current) and a package manager like
-[pnpm](https://pnpm.io/installation) to follow this example, so install them on your system if you
-haven't already.
-
-## Start a project
-
-Using a Terminal or Console, create a folder on your system (`hello-sui` in this example) and make
-it the working directory.
-
-```sh
-mkdir hello-sui
-cd hello-sui
-```
-
-When you use a package manager to install the necessary packages, it downloads the modules to your
-`node_modules` folder and adds the references to your `package.json` file, creating the file if it
-doesn't already exist. For this example, you need only the Sui TypeScript SDK:
-
-```sh npm2yarn
-npm i -D @mysten/sui
-```
-
-The SDK is published as an ESM only package, so you also need to set `"type": "module"` in your
-`package.json`. Your `package.json` file should look like this:
-
-```json
-{
-	"type": "module",
-	"dependencies": {
-		"@mysten/sui": "^<VERSION_NUMBER>"
-	}
-}
-```
-
-## Get some SUI for your account
-
-Instead of a 'Hello World' output to your console, this example introduces some SUI to your wallet
-address. You must be on Devnet, Testnet, or a local network to use a faucet for minting SUI.
-
-Create a new `index.js` file in the root of your project with the following code.
-
-```js
-
-// replace <YOUR_SUI_ADDRESS> with your actual address, which is in the form 0x123...
-const MY_ADDRESS = '<YOUR_SUI_ADDRESS>';
-
-// create a new SuiGrpcClient object pointing to the network you want to use
-const suiClient = new SuiGrpcClient({
-	network: 'devnet',
-	baseUrl: 'https://fullnode.devnet.sui.io:443',
-});
-
-// Convert MIST to Sui
-const balance = (balance) => {
-	return Number.parseInt(balance.totalBalance) / Number(MIST_PER_SUI);
-};
-
-// store the JSON representation for the SUI the address owns before using faucet
-const suiBefore = await suiClient.getBalance({
-	owner: MY_ADDRESS,
-});
-
-await requestSuiFromFaucetV2({
-	// use getFaucetHost to make sure you're using correct faucet address
-	// you can also just use the address (see Sui TypeScript SDK Quick Start for values)
-	host: getFaucetHost('devnet'),
-	recipient: MY_ADDRESS,
-});
-
-// store the JSON representation for the SUI the address owns after using faucet
-const suiAfter = await suiClient.getBalance({
-	owner: MY_ADDRESS,
-});
-
-// Output result to console.
-console.log(
-	`Balance before faucet: ${balance(suiBefore)} SUI. Balance after: ${balance(
-		suiAfter,
-	)} SUI. Hello, SUI!`,
-);
-```
-
-Save the file, then use Node.js to run it in your Console or Terminal:
-
-```sh
-node index.js
-```
-
-The code imports the `requestSuiFromFaucetV2` function from the SDK and calls it to mint SUI for the
-provided address. The code also imports `SuiGrpcClient` to create a new client on the Sui network
-that it uses to query the address and output the amount of SUI the address owns before and after
-using the faucet. You can check the total SUI for your address using the Sui Wallet or Sui Client
-CLI.
-
-> **Note:** Faucets on Devnet and Testnet are rate limited. If you run the script too many times, you surpass
-> the limit and must wait to successfully run it again. For Testnet, the best way to get SUI is
-> through the Web UI: `faucet.sui.io`.
-
-You can also use the [Sui Client CLI](https://docs.sui.io/references/cli/client) to perform client
-calls on a Sui network.

package/dist/sui/install.md

@@ -1,61 +0,0 @@
-# Install Sui TypeScript SDK
-
-> Install the @mysten/sui package and configure your project.
-
-The Sui TypeScript SDK is available in the
-[Sui TS SDK monorepo](https://github.com/MystenLabs/ts-sdks) and NPM.
-
-## Install from NPM
-
-To use the Sui TypeScript SDK in your project, run the following command in your project root:
-
-```sh npm2yarn
-npm i @mysten/sui
-```
-
-The SDK is published as an ESM only package. Make sure your `package.json` includes
-`"type": "module"`:
-
-```json
-{
-	"type": "module"
-}
-```
-
-If you are using TypeScript, your `tsconfig.json` should use a compatible `moduleResolution` setting
-such as `"NodeNext"`, `"Node16"`, or `"Bundler"`. See the
-[2.0 migration guide](/sui/migrations/sui-2.0#esm-migration) for more details.
-
-## Experimental tag for use with a local Sui network
-
-Projects developing against one of the onchain Sui networks (Devnet, Testnet, Mainnet) should use
-the base SDK published in the NPM registry (previous section) because the code aligns with the
-relevant JSON-RPC. If you are developing against a
-[local network](https://docs.sui.io/guides/developer/getting-started/local-network) built from the
-`main` branch of the Sui monorepo, however, you should use the `experimental`-tagged SDK package as
-it contains the latest features (or a local build detailed in the section that follows).
-
-```sh npm2yarn
-npm i @mysten/sui@experimental
-```
-
-## Install from local build
-
-To build the SDK from the Sui monorepo, you must use [pnpm](https://pnpm.io/). With pnpm installed,
-run the following command from the `sui` root directory:
-
-```bash
-# Install all dependencies
-pnpm install
-# Run the build for the TypeScript SDK
-pnpm sdk build
-```
-
-With the SDK built, you can import the library from your `sui` project. To do so, use a path to the
-`ts-sdks/packages/sui` directory that is relative to your project. For example, if you created a
-folder `my-sui-project` at the same level as `sui`, use the following to import the locally built
-Sui TypeScript package:
-
-```bash
-pnpm add ../ts-sdks/packages/sui
-```