@mysten/docs 0.1.1

package/dist/payment-kit/getting-started.md

@@ -0,0 +1,256 @@
+# Getting Started
+
+> Install and set up Payment Kit for your Sui dApp
+
+> **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.
+
+This guide will help you set up and start using the Payment Kit SDK in your Sui application.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- A Sui wallet with testnet/mainnet SUI tokens
+- Basic understanding of TypeScript and the Sui blockchain
+
+## Installation
+
+Install the Payment Kit SDK and the Sui TypeScript SDK:
+
+```bash npm2yarn
+npm install --save @mysten/payment-kit @mysten/sui
+```
+
+## Setting Up the Client
+
+The Payment Kit SDK extends the standard `SuiGrpcClient` to provide payment functionality. Here's
+how to set it up:
+
+```ts
+
+// Create a Sui client with Payment Kit extension
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+}).$extend(paymentKit());
+```
+
+The client will automatically configure the correct package IDs for the network you're using
+(testnet or mainnet).
+
+## Your First Payment
+
+Let's process a simple registry-based payment using the default payment registry:
+
+```ts
+
+// Create or load your keypair
+const keypair = Ed25519Keypair.generate();
+const sender = keypair.getPublicKey().toSuiAddress();
+
+// Create the payment transaction
+const tx = client.paymentKit.tx.processRegistryPayment({
+	nonce: crypto.randomUUID(), // Unique identifier for this payment
+	coinType: '0x2::sui::SUI', // Coin type (SUI in this case)
+	amount: 1n * MIST_PER_SUI, // 1 SUI (in MIST)
+	receiver,
+	sender: sender,
+});
+
+// Sign and execute
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+	options: {
+		showEffects: true,
+		showEvents: true,
+	},
+});
+
+// Check transaction status
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Payment failed: ${result.FailedTransaction.status.error?.message}`);
+}
+
+console.log('Payment processed:', result.Transaction.digest);
+```
+
+## Understanding the Payment
+
+In this example:
+
+1. **Nonce**: A unique identifier (UUIDv4) that prevents duplicate payments when using a registry
+2. **Coin Type**: The type of coin being transferred (SUI token)
+3. **Amount**: The payment amount in the smallest unit (MIST for SUI)
+4. **Receiver**: The address receiving the payment
+5. **Sender**: The address sending the payment (must match the transaction signer)
+6. **Registry Name**: The payment registry to use (defaults to `DEFAULT_REGISTRY_NAME`)
+
+## Verifying the Payment
+
+After processing a payment, you can query the payment record to verify it exists:
+
+```ts
+// Query the payment record
+const paymentRecord = await client.paymentKit.getPaymentRecord({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1n * MIST_PER_SUI,
+	receiver,
+});
+
+if (paymentRecord) {
+	console.log('Payment verified!');
+	console.log('Transaction:', paymentRecord.paymentTransactionDigest);
+	console.log('Epoch:', paymentRecord.epochAtTimeOfRecord);
+} else {
+	console.log('Payment not found');
+}
+```
+
+## Processing an Ephemeral Payment
+
+If you don't need duplicate prevention or persistent storage, use ephemeral payments:
+
+```ts
+const tx = client.paymentKit.tx.processEphemeralPayment({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1n * MIST_PER_SUI,
+	receiver,
+	sender: sender,
+});
+
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+
+// Check transaction status
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Ephemeral payment failed: ${result.FailedTransaction.status.error?.message}`);
+}
+
+console.log('Ephemeral payment processed:', result.Transaction.digest);
+```
+
+Ephemeral payments:
+
+- Don't create a `PaymentRecord`
+- Don't prevent duplicates
+- Still emit a `PaymentReceipt` event
+- Have lower gas costs
+
+## Working with Different Coin Types
+
+Payment Kit supports any Sui coin type. Here's how to process payments with custom coins:
+
+```ts
+// Example with a custom coin type
+const customCoinType = '0xabcd...::my_coin::MY_COIN';
+
+const tx = client.paymentKit.tx.processRegistryPayment({
+	nonce: crypto.randomUUID(),
+	coinType: customCoinType,
+	amount: 5000,
+	receiver,
+	sender: sender,
+});
+
+// Execute the transaction
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+```
+
+## Error Handling
+
+Always wrap payment operations in try-catch blocks:
+
+```ts
+try {
+	const tx = client.paymentKit.tx.processRegistryPayment({...});
+	const result = await client.signAndExecuteTransaction({
+		transaction: tx,
+		signer: keypair,
+	});
+
+	if (result.$kind === 'FailedTransaction') {
+		throw new Error(`Payment failed: ${result.FailedTransaction.status.error?.message}`);
+	}
+
+	console.log('Success:', result.Transaction.digest);
+} catch (error) {
+	if (error.message.includes('Duplicate')) {
+		console.error('Payment already processed');
+	} else if (error.message.includes('insufficient')) {
+		console.error('Insufficient balance');
+	} else {
+		console.error('Payment failed:', error.message);
+	}
+}
+```
+
+## Creating Payment URIs
+
+Payment Kit provides helper functions to create and parse Payment Kit transaction URIs. These URIs
+are useful for generating payment links, QR codes, or deep links in your application:
+
+```ts
+
+// Create a payment URI
+const paymentUri = createPaymentTransactionUri({
+	receiverAddress: '0x123...abc',
+	amount: 1000000000n, // 1 SUI in MIST
+	coinType: '0x2::sui::SUI',
+	nonce: crypto.randomUUID(),
+	label: 'Coffee Payment',
+	message: 'Payment for espresso',
+	registryName: 'my-registry', // Optional: specify a registry name
+	// Or use registryId: '0x...' for a specific registry object ID
+});
+
+console.log(paymentUri);
+// Output: sui:pay?receiver=0x123...abc&amount=1000000000&coinType=0x2%3A%3Asui%3A%3ASUI&nonce=...&label=Coffee%20Payment&message=Payment%20for%20espresso&registry=my-registry
+```
+
+The URI parameters include:
+
+- **receiver**: The Sui address receiving the payment (required)
+- **amount**: The payment amount as a positive bigint (required)
+- **coinType**: The coin type being transferred (required)
+- **nonce**: A unique identifier up to 36 characters (required)
+- **registry**: Either a registry name or object ID (optional)
+- **label**: A short label for the payment (optional)
+- **message**: A longer description message (optional)
+- **iconUrl**: URL to an icon for display purposes (optional)
+
+You can then parse URIs back into payment parameters:
+
+```ts
+
+// Parse a payment URI
+const params = parsePaymentTransactionUri(paymentUri);
+// Returns: { receiverAddress, amount, coinType, nonce, label?, message?, iconUrl?, registryName? | registryId? }
+
+// Use the parsed parameters to create a transaction
+const tx = client.paymentKit.tx.processRegistryPayment({
+	receiver: params.receiverAddress,
+	amount: params.amount,
+	coinType: params.coinType,
+	nonce: params.nonce,
+	registryName: params.registryName,
+	sender: sender,
+});
+```
+
+## Next Steps
+
+Now that you understand the basics, explore more advanced features:
+
+- [Payment Processing](./payment-processing) - Deep dive into payment models
+- [Registry Management](./registry-management) - Create and configure custom registries
+- [SDK API Reference](./payment-kit-sdk) - Complete SDK API documentation

package/dist/payment-kit/index.md

@@ -0,0 +1,132 @@
+# Payment Kit
+
+> Accept payments in any coin type on Sui
+
+> **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.
+
+The Sui Payment Kit SDK is a TypeScript library that provides a simple and secure way to process
+blockchain payments on the Sui network. It offers flexible payment processing with built-in
+duplicate prevention, configurable payment registries, and comprehensive receipt management.
+
+## Overview
+
+Payment Kit enables developers to integrate secure payment processing into their Sui applications
+with minimal setup. The SDK provides two payment models:
+
+- **Registry-based payments**: Persistent payment records with duplicate prevention and configurable
+  expiration
+- **Ephemeral payments**: Lightweight payment processing without persistent storage
+
+All payments emit a `PaymentReceipt` that can be stored off-chain for verification and
+record-keeping.
+
+## Key Features
+
+- **Duplicate Prevention**: Registry-based payments automatically prevent duplicate transactions
+- **Flexible Payment Models**: Choose between registry-based or ephemeral payment processing
+- **Payment Registries**: Create and manage custom payment registries with configurable policies
+- **Receipt Management**: Automatic receipt generation for all payments
+- **Multi-coin Support**: Process payments with any Sui coin type
+- **Configurable Expiration**: Set custom expiration policies for payment records
+- **Fund Management**: Optional registry-managed funds for simplified coin handling
+
+## Installation
+
+```bash npm2yarn
+npm install --save @mysten/payment-kit @mysten/sui
+```
+
+## Quick Start
+
+```ts
+
+// Create a Sui client with a Payment Kit extension
+const client = new SuiGrpcClient({
+	network: 'testnet',
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+}).$extend(paymentKit());
+
+// Process a registry-based payment
+const tx = client.paymentKit.tx.processRegistryPayment({
+	nonce: crypto.randomUUID(),
+	coinType: '0x2::sui::SUI',
+	amount: 1n * MIST_PER_SUI, // 1 SUI in MIST
+	receiver: '0x123...abc',
+	sender: '0x456...def',
+});
+
+// Sign and execute the transaction
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+
+// Check transaction status
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Payment failed: ${result.FailedTransaction.status.error?.message}`);
+}
+```
+
+## Network Support
+
+Payment Kit supports the following Sui networks:
+
+- **Mainnet**: Production environment
+- **Testnet**: Testing environment
+
+The SDK automatically configures the correct package and object IDs based on the network specified
+in your `SuiGrpcClient` configuration.
+
+## Core Concepts
+
+### Payment Processing
+
+Payment Kit offers two distinct payment processing models to suit different application needs:
+
+1. **Registry-based Payments**: Creates a persistent `PaymentRecord` that prevents duplicate
+   payments and provides verifiable proof of payment
+2. **Ephemeral Payments**: Processes payments without persistent storage, suitable for scenarios
+   where duplicate prevention is handled externally
+
+### Payment Registries
+
+A `PaymentRegistry` manages payment records and configurations. Benefits include:
+
+- Centralized payment tracking
+- Configurable expiration policies
+- Optional fund management
+- Custom naming for easy identification and indexing
+
+### Payment Records
+
+When using registry-based payments, a `PaymentRecord` is created as a Dynamic Field on the registry.
+Records are identified by a composite key derived from:
+
+- Payment nonce (unique identifier)
+- Payment amount
+- Coin type
+- Receiver address
+
+### Payment Receipts
+
+Every payment (registry-based or ephemeral) emits a `PaymentReceipt` event containing:
+
+```ts
+type PaymentReceipt = {
+	paymentType: 'Registry' | 'Ephemeral';
+	nonce: string;
+	amount: number;
+	receiver: string;
+	coinType: string;
+	timestampMs: number;
+};
+```
+
+## Next Steps
+
+- [Getting Started Guide](/payment-kit/getting-started) - Detailed setup and usage instructions
+- [Payment Processing](/payment-kit/payment-processing) - Learn about different payment models
+- [Registry Management](/payment-kit/registry-management) - Create and configure payment registries
+- [SDK API Reference](/payment-kit/payment-kit-sdk) - Complete SDK API documentation

package/dist/payment-kit/llms-index.md

@@ -0,0 +1,8 @@
+# Payment Kit
+> Accept payments in any coin type on Sui
+
+- [Payment Kit](./index.md): Accept payments in any coin type on Sui
+- [Getting Started](./getting-started.md): Install and set up Payment Kit for your Sui dApp
+- [Payment Kit SDK](./payment-kit-sdk.md): Payment Kit SDK API reference and configuration
+- [Payment Processing](./payment-processing.md): Process payments and handle transaction results
+- [Registry Management](./registry-management.md): Manage payment registries and accepted coin types