@tonyboyle/solana-wallet-universal-links-generator/README.md

A minimal, stateless TypeScript SDK for generating deep links to mobile Solana wallets

# Universal Solana Wallet Adapter

A **stateless deep link generator and response decoder** for mobile Solana wallets. This SDK provides utilities to generate deep links for wallet interactions and parse callback responses - you provide the storage and state management.

## What This SDK Does

🔗 **Deep Link Generation**: Creates secure deep links for wallet operations (connect, sign, etc.)  
📥 **Response Parsing**: Decodes and validates wallet callback responses  
🔐 **End-to-End Encryption**: Built-in encryption for sensitive data using x25519 key exchange  
📱 **Multi-Wallet Support**: Works with Phantom, Solflare, and Backpack wallets  

## What You Need to Provide

🗄️ **Session Storage**: Store connection sessions, encryption keys, and user state  
🔄 **State Management**: Handle connection state, loading states, and user authentication  
🎯 **Routing/Linking**: Handle deep link callbacks in your app (React Native Linking, etc.)  
💾 **Persistence**: Save wallet sessions across app restarts (AsyncStorage, SecureStore, etc.)  

> **This SDK is intentionally stateless** - it focuses on generating secure wallet deep links and parsing responses. You maintain control over how sessions and state are managed in your application.

## Features

- **Stateless**: No session management or state storage - you control the data flow
- **Type-safe**: Full TypeScript support with typed parameters using generics
- **Universal**: Supports multiple wallet providers (Phantom, Solflare, Backpack)
- **Extensible**: Easy to add new wallets and methods
- **Minimal**: Focused on core functionality - generating URLs and parsing callbacks
- **Organized**: Each command has its own file for easy maintenance
- **Encrypted**: Built-in encryption support using x25519 key exchange (TweetNaCl.js)
- **Auto-encryption**: Payloads are automatically encrypted when encryption parameters are provided
- **Response Parsing**: Type-safe response parsers for all wallet methods with automatic error handling

## Installation

```bash
npm install @tonyboyle/solana-wallet-universal-links-generator
```

## Quick Start

### Using Individual Command Functions
```typescript
import { connect, disconnect, parseConnectResponse } from '@tonyboyle/solana-wallet-universal-links-generator';

// Connect to Phantom (keys are generated automatically)
const connectResult = connect('phantom', {
  app_url: 'https://myapp.com',
  redirect_link: 'myapp://wallet/callback',
  cluster: 'mainnet-beta'
});

console.log('Connect URL:', connectResult.url);
console.log('DApp Public Key:', connectResult.dappPublicKey);
console.log('DApp Private Key:', connectResult.dappPrivateKey);

// Parse the wallet response
const callbackUrl = 'myapp://wallet/callback?ref=connect&data=...';
const result = parseConnectResponse(callbackUrl, connectResult.dappPrivateKey, connectResult.dappPublicKey);

if ('errorCode' in result) {
  console.error('Connection failed:', result.errorMessage);
} else {
  console.log('Connected!', result.publicKey);
  console.log('Session token:', result.session);
}
```

### Using the Class-based API
```typescript
import { UniversalWalletAdapter } from '@tonyboyle/solana-wallet-universal-links-generator';

const adapter = new UniversalWalletAdapter();

// Generate a connect URL for Phantom
const connectResult = adapter.connect('phantom', {
  app_url: 'https://myapp.com',
  redirect_link: 'myapp://wallet/callback',
  cluster: 'mainnet-beta'
});
```

## Supported Wallets

- **Phantom**: `https://phantom.app/ul/v1`
- **Solflare**: `https://solflare.com/ul/v1`
- **Backpack**: `https://backpack.app/ul/v1`

## Documentation

### 📚 Core Documentation
- **[Getting Started](./docs/getting-started.md)** - Installation, quick start, and basic concepts
- **[API Reference](./docs/api-reference.md)** - Complete method signatures and parameters
- **[Response Types](./docs/response-types.md)** - Response parsing and type definitions
- **[Encryption](./docs/encryption.md)** - Security features and best practices

### 📱 Examples and Guides
- **[React Native + Expo Example](./docs/react-native-example.md)** - Complete implementation with Zustand

## Supported Methods

- **Connect**: Establish wallet connection and get session token
- **Disconnect**: Terminate wallet session  
- **Sign Transaction**: Sign a single transaction (wallet doesn't submit)
- **Sign All Transactions**: Sign multiple transactions (wallet doesn't submit)
- **Sign and Send Transaction**: Sign and submit transaction (deprecated in Phantom)
- **Sign Message**: Sign an arbitrary message

## Project Structure

```
src/
├── index.ts                    # Main entry point with exports
├── types.ts                    # TypeScript type definitions
├── utils.ts                    # Utility functions (URL generation, parsing, auto-encryption)
├── encryption.ts               # Encryption utilities (TweetNaCl.js)
├── decoders.ts                 # Response parsers and payload decoders
├── wallet-adapter.ts           # Main UniversalWalletAdapter class
└── commands/                   # Individual command files
    ├── index.ts                # Commands index
    ├── connect.ts              # Connect command
    ├── disconnect.ts           # Disconnect command
    ├── sign-and-send-transaction.ts
    ├── sign-all-transactions.ts
    ├── sign-transaction.ts
    └── sign-message.ts
```

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

# Run linter
npm run lint
```

## Security Notes

- **This SDK is stateless** - you control session storage and key management
- **Store private keys securely** - use SecureStore, not AsyncStorage
- **Validate all responses** - always check for errors and validate data
- **Generate new keys per session** - never reuse encryption keys
- **Auto-encryption by default** - payloads are encrypted when keys are provided

## Dependencies

- **tweetnacl**: For x25519 key exchange and symmetric encryption
- **tweetnacl-util**: For base64 encoding/decoding utilities
- **bs58**: For base58 encoding/decoding of Solana addresses and keys

## License

MIT