@mysten/docs 0.1.32 → 0.1.34

package/dist/llms-index.md

@@ -81,6 +81,14 @@
 - [App Integration](./slush-wallet/dapp.md): Connect your app to Slush Wallet using the Slush Wallet SDK and wallet standard.
 - [Deep Linking](./slush-wallet/deep-linking.md): Configure deep links to open Slush Wallet directly to specific screens or actions.
 
+## Sponsor
+> Build gas sponsorship services with pluggable validation
+
+- [Sponsor](./sponsor.md): Build gas sponsorship services with pluggable transaction validation
+- [Basic Usage](./sponsor/basic-usage.md): Build a service that validates and executes user-signed sponsored bytes
+- [Validation](./sponsor/validators.md): Compose built-in and custom validation analyzers for sponsorship policy
+- [Best Practices](./sponsor/best-practices.md): Operate a Sui sponsor with clear policy, gas limits, and outcome handling
+
 ## Sui SDK
 > TypeScript interfaces for Sui
 
@@ -96,10 +104,15 @@
 - [Coins and Balances](./sui/transactions/coins-and-balances.md): Work with coin objects and address balances in transactions
 - [Commands and Inputs Reference](./sui/transactions/reference.md): Complete reference for transaction commands and input types
 - [Building Offline](./sui/transactions/offline.md): Build transactions without a network connection
-- [Key pairs](./sui/cryptography/keypairs.md): Create and manage Ed25519, Secp256k1, and Secp256r1 keypairs for Sui transaction signing.
-- [Multi-Signature Transactions](./sui/cryptography/multisig.md): Create multi-signature transactions with multiple signers on Sui.
-- [Passkey](./sui/cryptography/passkey.md): Use WebAuthn passkeys for Sui transaction signing.
-- [Web Crypto Signer](./sui/cryptography/webcrypto-signer.md): Sign transactions using the Web Crypto API for secure browser-based key management.
+- [Cryptography](./sui/cryptography.md): Sign and verify Sui transactions and messages with keypairs and external signers
+- [Key pairs](./sui/cryptography/keypairs.md): Create Ed25519, Secp256k1, and Secp256r1 keypairs and derive them from mnemonics and secret keys
+- [Signers](./sui/cryptography/signers.md): Signer implementations beyond keypairs — cloud KMS, Ledger, Web Crypto, passkeys, and multisig
+- [AWS KMS Signer](./sui/cryptography/signers/aws-kms.md): Sign Sui transactions with a key stored in AWS Key Management Service
+- [GCP KMS Signer](./sui/cryptography/signers/gcp-kms.md): Sign Sui transactions with a key stored in Google Cloud Key Management Service
+- [Ledger Signer](./sui/cryptography/signers/ledger.md): Sign Sui transactions with a Ledger hardware wallet
+- [Web Crypto Signer](./sui/cryptography/signers/webcrypto.md): Sign transactions using the Web Crypto API for secure browser-based key management
+- [Passkey](./sui/cryptography/signers/passkey.md): Use WebAuthn passkeys for Sui transaction signing.
+- [Multi-Signature Transactions](./sui/cryptography/signers/multisig.md): Create multi-signature transactions with multiple signers on Sui.
 - [The `@mysten/sui/utils` package](./sui/utils.md): Utility functions for addresses, coins, and common operations in the Sui TypeScript SDK.
 - [Derived Objects](./sui/utils/derived_objects.md): Compute derived object IDs from parent objects for deterministic offline derivation.
 - [BCS](./sui/bcs.md): Binary Canonical Serialization for encoding Sui Move types.

package/dist/sponsor/basic-usage.md

@@ -0,0 +1,170 @@
+# Basic Usage
+
+> Build a service that validates and executes user-signed sponsored bytes
+
+In the examples below, `userSigner` is the user's `Signer`. In an app, the user signs through
+dapp-kit's `signTransaction` instead.
+
+## Recommended flow
+
+Prefer services that expect **already-built bytes plus the user's signature**:
+
+1. The client gets the sponsor address.
+2. The client builds final transaction bytes with the sponsor as gas owner and address-balance gas.
+3. The user signs those exact bytes.
+4. The backend validates the bytes, co-signs, and executes.
+
+This means the sponsor knows exactly what it is co-signing, there is no half-signed transaction
+waiting on a user after the sponsor signs, and the flow avoids an extra sponsor-build round trip
+before the user can sign.
+
+## Provide the sponsor address
+
+The client needs a sponsor address before it builds the transaction. For services where the sponsor
+account might rotate, expose the current address through a small config endpoint:
+
+```ts
+app.get('/config', (c) => c.json({ sponsor: sponsor.address }));
+```
+
+Prefer fetching this value dynamically when you want the backend to rotate the sponsor key or move
+sponsorship to a different account without forcing client deployments. Use the chosen address as the
+transaction gas owner. In local examples where the client and sponsor live in the same process,
+`sponsor.address` is the same value.
+
+## Client builds the transaction
+
+The client sets the **sender**, the **gas owner to the sponsor**, and the **gas payment to `[]`**
+(address-balance gas). The user signs those final bytes and sends them to the sponsor service:
+
+```ts
+
+const { sponsor } = await fetch('/config').then((res) => res.json());
+
+transaction.setSender(userAddress);
+transaction.setGasOwner(sponsor); // gas is paid by the sponsor…
+transaction.setGasPayment([]); // …from its address balance (no specific gas coins)
+const bytes = await transaction.build({ client });
+
+const { signature: userSignature } = await userSigner.signTransaction(bytes);
+
+await fetch('/sponsor', {
+	method: 'POST',
+	headers: { 'content-type': 'application/json' },
+	body: JSON.stringify({ transaction: toBase64(bytes), userSignature }),
+});
+```
+
+The backend validates those bytes, co-signs, and executes:
+
+```ts
+const result = await sponsor.signAndExecuteTransaction({
+	transaction: body.transaction,
+	userSignature: body.userSignature,
+});
+
+switch (result.$kind) {
+	case 'Rejected': // a validator declined; the sponsor never signed or executed
+		throw new Error(result.issues.map((issue) => issue.message).join('; '));
+	case 'FailedTransaction': // executed onchain but aborted, the sponsor still paid gas
+		throw new Error(`Transaction failed onchain: ${result.FailedTransaction.digest}`);
+	case 'Transaction': // executed successfully
+		return result.Transaction.digest;
+}
+```
+
+`signAndExecuteTransaction` has **three** outcomes: a policy `Rejected` (never executed), a
+`FailedTransaction` (executed but aborted onchain, where the sponsor still pays gas either way), and
+a successful `Transaction`. The non-obvious one is `FailedTransaction`: a result that isn't
+`Rejected` still isn't necessarily a success.
+
+Pass `include` when the service needs extra transaction details in the response. The response always
+includes effects because the service needs them to distinguish successful execution from failed
+execution.
+
+## A user transaction
+
+A sponsored transaction operates on the **user's** objects, never the gas coin. When the user spends
+SUI, source it from their own balance with `useGasCoin: false`:
+
+```ts
+function userPayment(amount: bigint) {
+	const tx = new Transaction();
+	const coin = tx.coin({ balance: amount, useGasCoin: false });
+	tx.transferObjects([coin], recipient);
+	return tx;
+}
+```
+
+## Over the network
+
+The methods are transport-agnostic: they take transaction bytes as `Uint8Array` or base64 strings,
+and user signatures as signature strings. You own the HTTP shape, so serialize binary fields as
+base64. The client side is exactly the [build-and-sign flow above](#client-builds-the-transaction);
+the backend maps each result `$kind` to a response. Every outcome is a `$kind`, so no try/catch is
+needed for a policy rejection:
+
+```ts
+// Server handler — wire it into your framework's route however you like.
+async function handleSponsorRequest(body: { transaction: string; userSignature: string }) {
+	const result = await sponsor.signAndExecuteTransaction({
+		transaction: body.transaction,
+		userSignature: body.userSignature,
+	});
+	switch (result.$kind) {
+		case 'Rejected':
+			return { ok: false as const, issues: result.issues };
+		case 'FailedTransaction':
+			return { ok: false as const, issues: [{ message: 'Transaction failed on-chain.' }] };
+		case 'Transaction':
+			return { ok: true as const, digest: result.Transaction.digest };
+	}
+}
+```
+
+Need per-request context, such as an auth token or tenant id? Validators read it from `options`, and
+the sponsor requires it as typed `validationOptions`. See [Validation](/sponsor/validators). Handle
+replay prevention and rate limiting in your service.
+
+For a complete Hono server using this shape, see the
+[sponsor server example](https://github.com/MystenLabs/ts-sdks/tree/main/packages/sponsor/examples/sponsor-server).
+
+## Gas and unresolved transactions
+
+When the client builds, the user already built and signed final bytes, so they must be resolved. The
+sponsor never rebuilds them.
+
+When the sponsor builds the transaction, what you pass to `signTransaction` can be **unresolved**,
+with unresolved object inputs and no gas budget being fine. The sponsor sets itself as gas owner
+with address-balance gas and calls `build({ client })`, which in one pass resolves object inputs,
+sets the gas price and expiration, and (unless the transaction already pins one with
+`tx.setGasBudget(…)`) **estimates the gas budget by dry-running**. Validation then runs on the
+_built_ transaction, so `gasBudget({ max })` checks the resolved budget and analyzers see the exact
+bytes that get signed.
+
+## Advanced: sponsor builds the transaction
+
+> **Warning:** For public sponsorship services, prefer accepting final bytes plus `userSignature`. Use the
+> sponsor-builds flow only when the backend owns transaction construction and you understand the
+> trust boundary.
+
+Alternatively, hand the sponsor the user's commands. The sponsor sets itself as gas owner,
+builds\n(address-balance gas, and a dry-run-estimated budget unless you pinned one), validates, and
+signs. The user then signs the returned bytes, and both signatures execute together. `sender` is
+optional, applied only when the transaction doesn't already set one (for example, bare commands):
+
+```ts
+const result = await sponsor.signTransaction({
+	transaction,
+	sender: userAddress, // optional — only used if `transaction` has no sender
+});
+if (result.$kind === 'Rejected') {
+	throw new Error(result.issues.map((issue) => issue.message).join('; '));
+}
+
+const { signature: userSignature } = await userSigner.signTransaction(result.bytes);
+await client.core.executeTransaction({
+	transaction: result.bytes,
+	signatures: [userSignature, result.sponsorSignature],
+});
+```

package/dist/sponsor/best-practices.md

@@ -0,0 +1,163 @@
+# Best Practices
+
+> Operate a Sui sponsor with clear policy, gas limits, and outcome handling
+
+Gas sponsorship is a backend operating boundary. The user supplies transaction bytes; the sponsor
+decides whether to pay for them. Treat every sponsored transaction as untrusted input until your
+policy validates the exact bytes that get signed.
+
+## Prefer user-signed transaction bytes
+
+For public sponsor services, prefer accepting **already-built bytes plus `userSignature`**. The
+client builds the transaction with the sponsor as gas owner, the user signs those final bytes, and
+the sponsor validates, co-signs, and executes.
+
+This keeps the safer trust boundary: the sponsor only signs after the user has signed the exact
+transaction bytes. See [Basic Usage](/sponsor/basic-usage) for the recommended flow.
+
+## Understand the Sui gas model
+
+The Sponsor SDK uses address-balance gas:
+
+```ts
+transaction.setGasOwner(sponsorAddress);
+transaction.setGasPayment([]);
+```
+
+An empty gas payment means the sponsor pays from its SUI address balance. This avoids locking
+specific gas coin objects and allows parallel sponsor execution, but it also means the sponsor's
+address balance is the operating balance at risk.
+
+Fund the address balance intentionally. Faucet coins are coin objects; move SUI into the address
+balance with a transaction such as `0x2::coin::send_funds`.
+
+## Constrain sponsorship to product flows
+
+Never expose an endpoint that blindly co-signs any user transaction. At minimum, constrain:
+
+- **Allowed targets:** Use `allowedFunctions()` for fully qualified `package::module::function`
+  targets, not broad package allowlists, when the product flow only needs one function.
+- **PTB templates:** Validate the full Programmable Transaction Block shape your product expects:
+  command count, command kinds, Move targets, type arguments, argument sources, object ownership,
+  and value movement. A function allowlist is a starting point, not a complete policy.
+- **Gas budget:** Add `gasBudget({ max })` so a valid but expensive transaction cannot use the
+  protocol maximum.
+- **Sender signature:** Add `userSignatureMatchesSender()` so the supplied signature matches the
+  transaction sender before the sponsor co-signs.
+- **Value movement:** Use analyzers such as `balanceFlows` when sponsorship depends on payment,
+  refunds, or tenant-specific balances.
+
+The
+[sponsor server example](https://github.com/MystenLabs/ts-sdks/tree/main/packages/sponsor/examples/sponsor-server)
+uses a basic PTB template: exactly one command, and that command must be a call to one configured
+`package::module::function`. Real products should make the template as specific as their flow
+requires.
+
+## Keep `defaults()`
+
+`defaults()` protects against common sponsorship mistakes:
+
+| Validator                 | Why it matters                                                                |
+| ------------------------- | ----------------------------------------------------------------------------- |
+| `validSender()`           | Rejects unset senders and transactions where the sender is the sponsor        |
+| `onlyAddressBalanceGas()` | Requires empty gas payment so users cannot nominate sponsor gas coin objects  |
+| `gasCoinNotUsed()`        | Rejects commands that use `tx.gas`, which belongs to the sponsor              |
+| `onlySenderWithdrawals()` | Rejects address-balance withdrawals from the sponsor or any non-sender source |
+| `simulationSucceeds()`    | Rejects transactions that dry-run as aborting                                 |
+| `boundedExpiration()`     | Rejects missing or too-far-ahead transaction expirations                      |
+
+Once you pass `validate`, defaults no longer run automatically. Include `defaults()` explicitly:
+
+```ts
+const sponsor = createSponsor({
+	signer,
+	client,
+	validate: [defaults(), gasBudget({ max: 50_000_000n }), allowedFunctions([target])],
+});
+```
+
+## Gas budget is not the whole economic risk
+
+A gas cap limits how much gas the sponsor is willing to cover, but it is not a full business-policy
+check.
+
+Sui transactions can create, mutate, transfer, share, and delete objects. Storage costs and storage
+rebates can create economic incentives that are not obvious from the gas budget alone. If you
+sponsor arbitrary transactions, a user can try to externalize costs to the sponsor while directing
+objects, balances, or rebate-related value to themselves or another address.
+
+For product flows with financial value, validate the command shape and inspect net value movement:
+
+```ts
+
+const USDC = '0x...::usdc::USDC';
+
+const requirePayment = createAnalyzer({
+	dependencies: { balanceFlows: analyzers.balanceFlows },
+	analyze:
+		() =>
+		({ balanceFlows }) => {
+			const paidToSponsor =
+				balanceFlows.sponsor
+					?.filter((flow) => flow.coinType === USDC)
+					.reduce((sum, flow) => sum + flow.amount, 0n) ?? 0n;
+
+			return paidToSponsor >= 10_000n
+				? { result: null }
+				: { result: [{ code: 'UNDERPAID', message: 'Sponsor was not paid enough.' }] };
+		},
+});
+```
+
+## Keep sponsor balances intentional
+
+If the sponsor signer is loaded from an environment variable, treat it as a hot key. Keep only the
+SUI needed for short operating windows in the sponsor address balance, and top it up from a more
+protected account.
+
+For production services, prefer a managed signer:
+
+- Use a KMS-backed signer such as `@mysten/aws-kms-signer` or `@mysten/gcp-kms-signer`.
+- Restrict who can deploy or read the signer configuration.
+- Separate the sponsor hot account from treasury accounts.
+- Rotate keys and drain old sponsor balances when access changes.
+
+The Sponsor SDK accepts any `Signer`, so KMS signers can be used in place of an in-memory keypair.
+
+## Dry-run is not an execution guarantee
+
+`simulationSucceeds()` dry-runs the transaction before signing, but chain state can change before
+execution. A transaction that passed simulation can still abort later and charge the sponsor gas.
+
+Use dry-run as one policy input, not as the only control. Add:
+
+- gas caps,
+- target allowlists,
+- command-shape checks,
+- rate limits,
+- authentication,
+- per-user or per-tenant quotas.
+
+Onchain replay isn't something you handle here. Sui executes a signed transaction at most once, and
+`boundedExpiration()` (a default) supplies the bounded expiration it requires for address-balance
+gas. Application-level idempotency is still yours: if a flow should be sponsored only once per user,
+dedupe it with a request ID, nonce, or stored intent.
+
+## Handle rejection and failed execution separately
+
+A `Rejected` result means the sponsor did not sign or execute. A `FailedTransaction` means the
+transaction executed onchain and failed, so the sponsor might have paid gas.
+
+```ts
+switch (result.$kind) {
+	case 'Rejected':
+		return { ok: false, status: 403, issues: result.issues };
+	case 'FailedTransaction':
+		return { ok: false, status: 502, digest: result.FailedTransaction.digest };
+	case 'Transaction':
+		return { ok: true, digest: result.Transaction.digest };
+}
+```
+
+Do not collapse those outcomes into a single error. They have different accounting and retry
+semantics.

package/dist/sponsor/index.md

@@ -0,0 +1,114 @@
+# Sponsor
+
+> Build gas sponsorship services with pluggable transaction validation
+
+> **Warning:** **Incubation package.** This package is still experimental and might change without notice. Pin
+> versions and review changes before upgrading.
+
+Primitives for building gas-sponsorship flows on Sui. You are the **sponsor operator**: you bring a
+`Signer` (the sponsor) and a policy for what you'll pay for, and `createSponsor` takes a user's
+transaction, fills in the gas, validates it against that policy, and adds the sponsor's signature.
+The hard part, validating what you're sponsoring, is handled by a pluggable pipeline backed by the
+[`@mysten/wallet-sdk` transaction analyzer](https://www.npmjs.com/package/@mysten/wallet-sdk).
+
+The transaction comes from your user; you decide what's allowed and cover the gas.
+
+## Install
+
+```npm
+npm i @mysten-incubation/sponsor @mysten/sui
+```
+
+## Quick start
+
+```ts
+
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+});
+
+const sponsor = createSponsor({
+	signer: Ed25519Keypair.fromSecretKey(process.env.SPONSOR_KEY!),
+	client,
+	// `defaults()` keeps the baseline (see Defaults).
+	validate: [defaults(), gasBudget({ max: 50_000_000n }), allowedFunctions(['0xabc::shop::buy'])],
+});
+```
+
+## How gas works
+
+The sponsor pays gas from its **address balance**. The empty gas payment (`setGasPayment([])`) draws
+from the sponsor's onchain SUI balance rather than from specific gas coins. This means the sponsor
+can sign and execute in parallel:
+
+Address-balance gas doesn't lock specific coin objects, so concurrent sponsored transactions don't
+contend for gas coins. A sender that reuses its own versioned objects (coins) across rapid
+transactions still has to serialize those, but that's the sender's concern, not the sponsor's.
+
+You fund the address balance by depositing SUI into it (for example, a one-time
+`0x2::coin::send_funds(coin, sponsorAddress)`); the faucet only hands out coin objects, not address
+balance.
+
+Because gas is the sponsor's, **a sponsored transaction must never use the gas coin** (`tx.gas`).
+`gasCoinNotUsed()` (a default) enforces this. When the user needs SUI, they spend their own with
+`tx.coin({ balance, useGasCoin: false })`.
+
+## Defaults
+
+If you pass no `validate`, the sponsor runs `defaults()`: `validSender()`,
+`onlyAddressBalanceGas()`, `gasCoinNotUsed()`, `onlySenderWithdrawals()`, `simulationSucceeds()`,
+and `boundedExpiration()`. Once you add your own validators they no longer run automatically; drop
+them back in as one entry (the `validate` array flattens nested arrays):
+
+```ts
+createSponsor({ signer, client }); // runs defaults()
+createSponsor({ signer, client, validate: [defaults(), allowedFunctions(['0xabc::shop::buy'])] });
+```
+
+Each default guards something real: `validSender()` requires a sender and rejects transactions where
+the sponsor is also the sender; `onlyAddressBalanceGas()` and `gasCoinNotUsed()` stop a caller from
+spending the sponsor's gas (its address balance pays, and the gas coin is the sponsor's);
+`onlySenderWithdrawals()` rejects any `FundsWithdrawal` input that isn't the sender's, including one
+from the sponsor's **address balance** (the same balance that pays gas, a direct drain the gas-coin
+check can't see, because the withdrawal is an input, not a command argument); `simulationSucceeds()`
+avoids paying for a transaction that aborts; and `boundedExpiration()` requires a bounded expiration
+for address-balance gas.
+
+Two things the defaults **don't** do, by design (handle them at your service boundary):
+
+- **No gas ceiling.** A legitimate but expensive transaction can cost up to the protocol max. Add
+  `gasBudget({ max })` for a cap, and rate-limit / authenticate callers.
+- **No execution guarantee.** `simulationSucceeds()` is a dry-run; onchain state can shift before
+  execution, so a later-aborting sponsored transaction can still charge the sponsor gas.
+
+Keep `defaults()` unless you're deliberately replacing those checks.
+
+For **offline-only signing** (no dry-run), use validators that read only `data` (no
+`transactionResponse`). Nothing depends on simulation, so the sponsor never simulates:
+
+```ts
+createSponsor({ signer, client, validate: [validSender(), gasCoinNotUsed()] });
+```
+
+## What `transaction` is
+
+The sponsor methods take a `transaction` that is anything `Transaction.from` accepts:
+
+```ts
+type TransactionInput = Transaction | Uint8Array | string; // a Transaction, built bytes, base64, or JSON
+```
+
+When you also pass a `userSignature`, the bytes are already final (the user signed them), so that
+form must be the exact bytes: a `Uint8Array` or a base64 string (not a `Transaction` or JSON). The
+sponsor never rebuilds them (so the user's signature stays valid). The sender is already part of
+those bytes, so there's no `sender` parameter in this flow. `userSignature` might be a single string
+or an array (for example, multiple required signers).
+
+## Next steps
+
+- [Basic Usage](/sponsor/basic-usage) covers the recommended service flow: client-built bytes, user
+  signatures, network usage, and the advanced sponsor-builds flow.
+- [Validation](/sponsor/validators) explains custom validation analyzers, request-scoped options,
+  analyzer execution, and built-in validation analyzers.
+- [Best Practices](/sponsor/best-practices) adds policy, gas, and operational guidance.

package/dist/sponsor/llms-index.md

@@ -0,0 +1,7 @@
+# Sponsor
+> Build gas sponsorship services with pluggable validation
+
+- [Sponsor](..md): Build gas sponsorship services with pluggable transaction validation
+- [Basic Usage](./basic-usage.md): Build a service that validates and executes user-signed sponsored bytes
+- [Validation](./validators.md): Compose built-in and custom validation analyzers for sponsorship policy
+- [Best Practices](./best-practices.md): Operate a Sui sponsor with clear policy, gas limits, and outcome handling