@mysten/docs 0.1.1

package/dist/payment-kit/registry-management.md

@@ -0,0 +1,529 @@
+# Registry Management
+
+> Manage payment registries and accepted coin types
+
+> **Note:** This package is in active development and should be used with caution. APIs are experimental and
+> subject to breaking changes without notice. We recommend thoroughly testing any implementation
+> before using in production environments.
+
+Payment registries are the core of Payment Kit's duplicate prevention and payment tracking system.
+This guide covers creating, configuring, and managing payment registries.
+
+## Understanding Payment Registries
+
+A `PaymentRegistry` is an on-chain object that:
+
+- Stores `PaymentRecord` dynamic fields for each unique payment
+- Manages configuration settings (expiration, fund management)
+- Can be owned and administered by a specific account
+- Provides namespaced payment tracking
+
+### Default Registry
+
+Payment Kit provides a default registry that's ready to use:
+
+```ts
+// Use the default registry
+const tx = client.paymentKit.tx.processRegistryPayment({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1000000000,
+	receiver,
+	sender: senderAddress,
+});
+```
+
+### When to Create a Custom Registry
+
+Consider creating your own registry when:
+
+- You want isolated payment tracking for your application
+- You need custom expiration policies
+- You want to manage funds centrally
+- You need better indexing of your payments
+- You want to avoid potential congestion on the default registry
+
+## Creating a Registry
+
+### Basic Registry Creation
+
+Creating a registry is simple - you only need to provide a unique name:
+
+```ts
+// Create a new registry
+const tx = client.paymentKit.tx.createRegistry({
+	registryName: 'my-app-payments',
+});
+
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+	options: {
+		showEffects: true,
+		showObjectChanges: true,
+	},
+});
+
+// Check transaction status
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Registry creation failed: ${result.FailedTransaction.status.error?.message}`);
+}
+
+console.log('Registry created!');
+console.log('Transaction:', result.Transaction.digest);
+```
+
+### What Gets Created
+
+When you create a registry, two objects are created:
+
+1. **PaymentRegistry**: The registry object that stores payment records
+2. **RegistryAdminCap**: A capability object that grants admin permissions
+
+### Extracting the Admin Capability
+
+The `RegistryAdminCap` is crucial for configuring your registry:
+
+```ts
+// Find the admin cap in the transaction result
+const adminCapObject = result.Transaction.objectChanges?.find(
+	(change) => change.type === 'created' && change.objectType.includes('RegistryAdminCap'),
+);
+
+if (adminCapObject && 'objectId' in adminCapObject) {
+	const adminCapId = adminCapObject.objectId;
+
+	console.log('Admin Capability ID:', adminCapId);
+
+	// Store this ID - you'll need it to configure the registry
+	await database.saveAdminCap({
+		registryName: 'my-app-payments',
+		adminCapId: adminCapId,
+		owner: senderAddress,
+	});
+}
+```
+
+### Deriving the Registry ID
+
+Payment Kit derives registry IDs deterministically from the registry name:
+
+```ts
+// You can compute the registry ID without querying the chain
+const registryName = 'random-registry-name';
+const registryId = client.paymentKit.getRegistryIdFromName(registryName);
+
+console.log('Registry ID:', registryId);
+```
+
+This allows you to reference registries by name throughout your application.
+
+## Registry Configuration
+
+Registries have two main configuration options:
+
+### 1. Epoch Expiration Duration
+
+Controls how long payment records persist before they can be deleted.
+
+**Default**: 30 epochs (~30 days on mainnet)
+
+```ts
+// Set expiration to 60 epochs
+const tx = client.paymentKit.tx.setConfigEpochExpirationDuration({
+	registryName: 'my-app-payments',
+	epochExpirationDuration: 60,
+	adminCapId: adminCapId,
+});
+
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+
+// Check transaction status
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Configuration update failed: ${result.FailedTransaction.status.error?.message}`);
+}
+
+console.log('Expiration set to 60 epochs');
+```
+
+**How It Works:**
+
+When a payment is recorded, it stores the current epoch. After the expiration duration has passed,
+anyone can delete the record to reclaim storage fees:
+
+```ts
+// Current epoch: 1000
+// Payment recorded at epoch: 1000
+// Expiration duration: 30
+// Can be deleted after epoch: 1030
+```
+
+**Use Cases:**
+
+- **Short expiration (7-14 epochs)**: High-volume, time-sensitive payments (subscriptions, tickets)
+- **Medium expiration (30-60 epochs)**: Standard e-commerce transactions
+- **Long expiration (180+ epochs)**: Important financial records requiring long-term verification
+
+### 2. Registry Managed Funds
+
+Controls whether payments must be sent to the registry itself for later withdrawal.
+
+**Default**: Disabled (funds go directly to receivers)
+
+```ts
+// Enable registry-managed funds
+const tx = client.paymentKit.tx.setConfigRegistryManagedFunds({
+	registryName: 'my-app-payments',
+	registryManagedFunds: true,
+	adminCapId: adminCapId,
+});
+
+await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+
+console.log('Registry now manages funds');
+```
+
+**How It Works:**
+
+When enabled:
+
+- All payments must specify the registry as the receiver
+- Coins are transferred to the registry object
+- Registry admin can withdraw accumulated funds later
+- Simplifies coin merging for high-throughput scenarios
+
+```ts
+// With registry-managed funds enabled
+const registryId = getRegistryIdFromName('my-app-payments', namespaceId);
+
+const tx = client.paymentKit.tx.processRegistryPayment({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1000000000,
+	receiver: registryId, // Must be the registry itself
+	sender: senderAddress,
+	registryName: 'my-app-payments',
+});
+```
+
+**Use Cases:**
+
+- Platforms collecting payments on behalf of sellers
+- Applications that need to batch process payouts
+- Scenarios with very high transaction volumes
+- Simplified accounting and reconciliation
+
+### Configuring Both Settings
+
+You can configure both settings independently:
+
+```ts
+
+const tx = new Transaction();
+
+// Set expiration duration
+tx.add(
+	client.paymentKit.calls.setConfigEpochExpirationDuration({
+		registryName: 'my-app-payments',
+		epochExpirationDuration: 90,
+		adminCapId: adminCapId,
+	}),
+);
+
+// Enable managed funds
+tx.add(
+	client.paymentKit.calls.setConfigRegistryManagedFunds({
+		registryName: 'my-app-payments',
+		registryManagedFunds: true,
+		adminCapId: adminCapId,
+	}),
+);
+
+// Apply both configurations in one transaction
+await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+```
+
+## Withdrawing Funds from a Registry
+
+If you've enabled registry-managed funds, you can withdraw accumulated coins:
+
+```ts
+// Withdraw all SUI from the registry
+const tx = client.paymentKit.tx.withdrawFromRegistry({
+	coinType: '0x2::sui::SUI',
+	registryName: 'my-app-payments',
+	adminCapId: adminCapId,
+});
+
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+	options: {
+		showEffects: true,
+	},
+});
+
+console.log('Funds withdrawn!');
+```
+
+**Important Notes:**
+
+- Only the admin cap owner can withdraw funds
+- You must specify the coin type to withdraw
+- All coins of that type are withdrawn in one operation
+- The withdrawn coins are sent to the transaction sender
+
+### Withdrawing Multiple Coin Types
+
+If your registry accumulates different coin types:
+
+```ts
+const tx = new Transaction();
+
+// Withdraw SUI
+tx.add(
+	client.paymentKit.calls.withdrawFromRegistry({
+		coinType: '0x2::sui::SUI',
+		registryName: 'my-app-payments',
+		adminCapId: adminCapId,
+	}),
+);
+
+// Withdraw custom token
+tx.add(
+	client.paymentKit.calls.withdrawFromRegistry({
+		coinType: '0xabc123::my_token::MY_TOKEN',
+		registryName: 'my-app-payments',
+		adminCapId: adminCapId,
+	}),
+);
+
+await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+```
+
+## Deleting Expired Payment Records
+
+After the expiration period, payment records can be deleted to reclaim storage fees:
+
+```ts
+// Delete an expired payment record
+const tx = client.paymentKit.tx.deletePaymentRecord({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1000000000,
+	receiver,
+	registryName: 'my-app-payments',
+});
+
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+
+console.log('Record deleted, storage rebate received');
+```
+
+**Key Points:**
+
+- Records can only be deleted after expiration
+- Anyone can delete expired records (permissionless cleanup)
+- The deleter receives a small storage rebate
+- This incentivizes automatic cleanup of old records
+
+### Checking If a Record Can Be Deleted
+
+```ts
+// Get the payment record
+const record = await client.paymentKit.getPaymentRecord({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1000000000,
+	receiver,
+	registryName: 'my-app-payments',
+});
+
+if (record) {
+	const recordEpoch = parseInt(record.epochAtTimeOfRecord);
+	const currentEpoch = await client.core
+		.getLatestSuiSystemState()
+		.then((state) => Number(state.epoch));
+
+	const expirationDuration = 30; // Your registry's setting
+	const canDelete = currentEpoch >= recordEpoch + expirationDuration;
+
+	console.log('Record epoch:', recordEpoch);
+	console.log('Current epoch:', currentEpoch);
+	console.log('Can delete:', canDelete);
+}
+```
+
+## Using Registry ID Directly
+
+If you know the registry ID, you can use it instead of the name:
+
+```ts
+const registryId = '0x123abc...';
+
+// Process payment using registry ID
+const tx = client.paymentKit.tx.processRegistryPayment({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1000000000,
+	receiver,
+	sender: senderAddress,
+	registryId: registryId, // Use ID instead of name
+});
+
+// Query using registry ID
+const record = await client.paymentKit.getPaymentRecord({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1000000000,
+	receiver,
+	registryId: registryId,
+});
+```
+
+## Complete Registry Setup Example
+
+Here's a complete workflow for setting up a custom registry:
+
+```ts
+
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+}).$extend(paymentKit());
+
+const keypair = Ed25519Keypair.generate();
+const registryName = 'my-marketplace-registry';
+
+// Step 1: Create the registry
+console.log('Creating registry...');
+const createTx = client.paymentKit.tx.createRegistry({
+	registryName: registryName,
+});
+
+const createResult = await client.signAndExecuteTransaction({
+	transaction: createTx,
+	signer: keypair,
+	options: {
+		showEffects: true,
+		showObjectChanges: true,
+	},
+});
+
+// Check transaction status
+if (createResult.$kind === 'FailedTransaction') {
+	throw new Error(
+		`Registry creation failed: ${createResult.FailedTransaction.status.error?.message}`,
+	);
+}
+
+// Step 2: Extract the admin cap
+const adminCapObject = createResult.Transaction.objectChanges?.find(
+	(change) => change.type === 'created' && change.objectType.includes('RegistryAdminCap'),
+);
+
+const adminCapId = adminCapObject && 'objectId' in adminCapObject ? adminCapObject.objectId : '';
+
+console.log('Registry created!');
+console.log('Admin Cap ID:', adminCapId);
+
+// Step 3: Configure the registry
+console.log('Configuring registry...');
+const configTx = new Transaction();
+
+// Set 60-epoch expiration
+configTx.add(
+	client.paymentKit.calls.setConfigEpochExpirationDuration({
+		registryName: registryName,
+		epochExpirationDuration: 60,
+		adminCapId: adminCapId,
+	}),
+);
+
+// Enable managed funds
+configTx.add(
+	client.paymentKit.calls.setConfigRegistryManagedFunds({
+		registryName: registryName,
+		registryManagedFunds: true,
+		adminCapId: adminCapId,
+	}),
+);
+
+const configResult = await client.signAndExecuteTransaction({
+	transaction: configTx,
+	signer: keypair,
+});
+
+// Check transaction status
+if (configResult.$kind === 'FailedTransaction') {
+	throw new Error(`Configuration failed: ${configResult.FailedTransaction.status.error?.message}`);
+}
+
+console.log('Registry configured!');
+console.log('Ready to process payments');
+
+// Step 4: Process a payment
+const registryId = getRegistryIdFromName(registryName, namespaceId);
+
+const paymentTx = client.paymentKit.tx.processRegistryPayment({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1000000000,
+	receiver: registryId, // Funds go to registry
+	sender: keypair.getPublicKey().toSuiAddress(),
+	registryName: registryName,
+});
+
+const paymentResult = await client.signAndExecuteTransaction({
+	transaction: paymentTx,
+	signer: keypair,
+});
+
+// Check transaction status
+if (paymentResult.$kind === 'FailedTransaction') {
+	throw new Error(`Payment failed: ${paymentResult.FailedTransaction.status.error?.message}`);
+}
+
+console.log('First payment processed:', paymentResult.Transaction.digest);
+```
+
+## Best Practices
+
+1. **Store Admin Caps Securely**: Treat your admin capability like private keys - they control your
+   registry
+
+2. **Use Descriptive Names**: Choose registry names that clearly identify their purpose (e.g.,
+   `acme-subscriptions`, `store-123-payments`)
+
+3. **Set Appropriate Expiration**: Balance storage costs with verification needs
+   - Short expiration = lower storage costs
+   - Long expiration = longer verification period
+
+4. **Monitor Registry Growth**: Track the number of payment records to anticipate storage costs
+
+5. **Plan Fund Management**: Decide upfront whether to use registry-managed funds based on your
+   withdrawal patterns
+
+6. **Document Your Configuration**: Keep records of your registry settings for operational
+   consistency
+
+7. **Test Thoroughly**: Always test registry operations on testnet before mainnet deployment
+
+## Next Steps
+
+- [SDK API Reference](./payment-kit-sdk) - Complete SDK API documentation

package/dist/seal/index.md

@@ -0,0 +1,85 @@
+# Seal SDK
+
+> Decentralized secrets management with threshold encryption on Sui
+
+> **Note:** This is a beta version of Seal. See https://github.com/MystenLabs/seal for more details.
+
+The Seal SDK provides threshold encryption capabilities for Sui applications, enabling secure data
+encryption with configurable key servers.
+
+## Installation
+
+```bash npm2yarn
+npm install --save @mysten/seal @mysten/sui
+```
+
+## Setup
+
+To use the Seal SDK, create a Sui client and extend it with the Seal extension:
+
+```ts
+
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+}).$extend(
+	seal({
+		serverConfigs: [
+			{ objectId: '0x...keyserver1', weight: 1 },
+			{ objectId: '0x...keyserver2', weight: 1 },
+		],
+	}),
+);
+```
+
+## Configuration Options
+
+The `seal()` function accepts the following options:
+
+- **`serverConfigs`** (required) - Array of key server configurations with `objectId` and `weight`
+- **`verifyKeyServers`** (optional) - Whether to verify key server authenticity (default: `true`)
+- **`timeout`** (optional) - Timeout in milliseconds for network requests (default: `10000`)
+
+## Basic Usage
+
+### Encrypting Data
+
+```ts
+const data = new Uint8Array([1, 2, 3]);
+
+const { encryptedObject } = await client.seal.encrypt({
+	threshold: 2, // Number of key servers needed to decrypt
+	packageId: '0x...your-package-id',
+	id: '0x...your-object-id',
+	data,
+});
+```
+
+### Decrypting Data
+
+```ts
+
+// Create a session key for decryption
+const sessionKey = await SessionKey.create({
+	address: senderAddress,
+	packageId: '0x...your-package-id',
+	ttlMin: 10, // Time-to-live in minutes
+	signer: keypair,
+	suiClient: client,
+});
+
+// Build transaction bytes that call seal_approve
+const txBytes = await buildApprovalTransaction(/* ... */);
+
+// Decrypt the data
+const decryptedData = await client.seal.decrypt({
+	data: encryptedObject,
+	sessionKey,
+	txBytes,
+});
+```
+
+## Resources
+
+For detailed documentation on threshold encryption and key server setup, see the
+[Seal repository](https://github.com/MystenLabs/seal).

package/dist/seal/llms-index.md

@@ -0,0 +1,4 @@
+# Seal
+> Use Seal, a decentralized secrets management service that secures your data using threshold encryption and on-chain access control.
+
+- [Seal SDK](./index.md): Decentralized secrets management with threshold encryption on Sui

package/dist/slush-wallet/dapp.md

@@ -0,0 +1,95 @@
+# dApp Integration
+
+> Connect your dApp to Slush Wallet
+
+> **Note:** If you are using `dapp-kit`, you do not need to install any additional packages to integrate with
+> the Slush wallet. [Read how to integrate with dapp-kit.](/dapp-kit/legacy/slush)
+
+Using the Slush Wallet SDK, you can allow users to connect to the Slush wallet from your dApp. The
+wallet is provided through the [Wallet Standard](https://docs.sui.io/standards/wallet-standard), and
+should appear automatically in your existing wallet connection UI.
+
+> The Slush Wallet SDK is only needed if you want to support the Slush web wallet in your dApp. If
+> you want to integrate with the Slush browser extension or native mobile wallet, you do not need to
+> install any additional packages - they will work automatically through the Wallet Standard.
+
+## Setup
+
+To use the Slush web wallet, you will need to register it in your application, using
+`registerSlushWallet`. This only needs to be done once, and should be done as early as possible in
+your application's lifecycle.
+
+`registerSlushWallet` takes two arguments:
+
+- `name`: The name of your dApp. This will be shown to the user when they are asked to approve the
+  connection in Slush.
+- `options`: An optional object with the following properties:
+  - `origin`: The origin of the Slush website. Defaults to `https://[TODO]`.
+  - `network`: The network that you would like the Slush wallet to use. Defaults to `mainnet`,
+    supports `mainnet` and `testnet`.
+
+```ts
+
+registerSlushWallet('Your dApp Name');
+```
+
+## Supported features
+
+The Slush wallet currently supports the following features:
+
+- `signTransaction`
+- `signAndExecuteTransaction`
+- `signPersonalMessage`
+
+## Detecting the Slush wallet
+
+If you'd like to detect whether the user is connected to the Slush wallet, you can use the `id` or
+`name` property on the wallet
+
+For example, if you are using `dapp-kit`, you can use the `useCurrentWallet` hook to get the current
+wallet, and check if it is the Slush wallet.
+
+```ts
+
+function SlushOnly() {
+	const { currentWallet } = useCurrentWallet();
+	const walletIsSlushWallet = currentWallet?.name === SLUSH_WALLET_NAME;
+
+	// rest of component logic...
+}
+```
+
+# Migration from Stashed Wallet -> Slush Wallet
+
+If you're currently using `@mysten/zksend`'s `registerStashedWallet` directly, you should migrate to
+the `@mysten/slush-wallet` package to ensure compatibility with the new Slush experience.
+
+## 🚀 Installation
+
+```bash
+pnpm install @mysten/slush-wallet
+```
+
+## 🔁 Migration
+
+If you're using `registerStashedWallet`, switch to `registerSlushWallet`:
+
+**Before:**
+
+```ts
+
+registerStashedWallet(...);
+```
+
+**After:**
+
+```ts
+
+registerSlushWallet(...);
+```
+
+If you're using dapp-kit, update to the latest dapp-kit version and change the `stashedWallet` prop
+on WalletProvider to `slushWallet`
+
+> Note: In the connect modal, users with the Slush Wallet extension installed will only see the
+> extension. If they don’t have it, the connection will default to the Slush web app.