6e53f9082e
- Replaced NPool with NWelshman for intelligent relay management - Added router configuration for specialized relay selection - Implemented quality scoring for relay prioritization - Added comprehensive unit and integration tests - Updated README with detailed documentation - Configured redundancy and connection limits for better reliability
154 lines
4.3 KiB
Markdown
154 lines
4.3 KiB
Markdown
# MKStack with Welshman
|
|
|
|
Template for building Nostr client applications with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify - enhanced with Welshman for intelligent relay management.
|
|
|
|
## Overview
|
|
|
|
This is an enhanced version of the MKStack template that replaces the basic `NPool` implementation with `NWelshman` - a more sophisticated relay pool manager that provides intelligent routing, quality scoring, and specialized relay selection.
|
|
|
|
## Key Differences from Base MKStack
|
|
|
|
### 1. Enhanced Relay Management
|
|
|
|
**Base MKStack (NPool):**
|
|
- Simple relay connection using `NRelay1`
|
|
- All queries go to a single configured relay
|
|
- Basic round-robin publishing to preset relays
|
|
- No distinction between relay types or capabilities
|
|
|
|
**This Template (NWelshman):**
|
|
- Intelligent relay routing with quality scoring
|
|
- Specialized relay selection based on query type:
|
|
- **Indexer relays** for metadata (kinds 0, 3, 10002)
|
|
- **Search relays** for NIP-50 full-text search
|
|
- **Static relays** for general queries
|
|
- Quality-based relay prioritization
|
|
- Configurable redundancy and connection limits
|
|
|
|
### 2. Router Configuration
|
|
|
|
The `NostrProvider` now implements a sophisticated Router class that provides:
|
|
|
|
```typescript
|
|
// Relay selection based on capability
|
|
getIndexerRelays() // Returns relays optimized for metadata
|
|
getSearchRelays() // Returns NIP-50 compatible search relays
|
|
getStaticRelays() // Returns general-purpose relays
|
|
|
|
// Quality assessment
|
|
getRelayQuality(url) // Returns 0-1 quality score per relay
|
|
|
|
// Connection management
|
|
getRedundancy() // Number of relays to query (default: 2)
|
|
getLimit() // Maximum relay connections (default: 5)
|
|
```
|
|
|
|
### 3. Performance Benefits
|
|
|
|
- **Reduced latency**: Queries are sent to relays best suited for the task
|
|
- **Better reliability**: Redundancy ensures queries succeed even if one relay fails
|
|
- **Optimized bandwidth**: Intelligent routing reduces unnecessary connections
|
|
- **Faster metadata lookups**: Dedicated indexer relays for profile data
|
|
- **Enhanced search**: NIP-50 aware relay selection for text search
|
|
|
|
## Dependencies
|
|
|
|
This template adds the following dependencies to base MKStack:
|
|
|
|
```json
|
|
{
|
|
"@nostrify/welshman": "^0.35.0",
|
|
"@welshman/util": "^0.4.2"
|
|
}
|
|
```
|
|
|
|
## Usage
|
|
|
|
The template maintains full compatibility with the base MKStack API. All existing hooks and components work without modification:
|
|
|
|
```tsx
|
|
// Works exactly the same as base MKStack
|
|
const { nostr } = useNostr();
|
|
const events = await nostr.query([{ kinds: [1], limit: 20 }]);
|
|
```
|
|
|
|
## Relay Configuration
|
|
|
|
The Router automatically categorizes relays based on their known capabilities:
|
|
|
|
### Known Indexer Relays
|
|
- `wss://relay.nostr.band`
|
|
- `wss://relay.damus.io`
|
|
- `wss://purplepag.es`
|
|
|
|
### Known Search Relays (NIP-50)
|
|
- `wss://relay.nostr.band`
|
|
- `wss://nostr.wine`
|
|
- `wss://search.nos.today`
|
|
|
|
### Quality Scoring
|
|
Relays are scored from 0.0 to 1.0 based on:
|
|
- User's configured relay: 1.0 (highest priority)
|
|
- Known high-quality relays: 0.8-0.9
|
|
- Preset relays: 0.7
|
|
- Unknown relays: 0.5 (lowest priority)
|
|
|
|
## Testing
|
|
|
|
The template includes comprehensive test coverage:
|
|
|
|
- **Unit tests** (`NostrProvider.test.tsx`): Mock-based testing of router configuration
|
|
- **Integration tests** (`NostrProvider.integration.test.tsx`): Real relay connection tests
|
|
|
|
Run tests with:
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
## Migration from Base MKStack
|
|
|
|
To migrate an existing MKStack project to use Welshman:
|
|
|
|
1. Install the new dependencies:
|
|
```bash
|
|
npm install @nostrify/welshman @welshman/util
|
|
```
|
|
|
|
2. Replace the `NostrProvider` component with the Welshman version
|
|
|
|
3. No other code changes required - the API remains the same
|
|
|
|
## When to Use This Template
|
|
|
|
Choose this Welshman-enhanced template when you need:
|
|
|
|
- **High-performance Nostr apps** that benefit from intelligent relay routing
|
|
- **Apps with heavy metadata queries** (profile lookups, contact lists)
|
|
- **Search functionality** using NIP-50
|
|
- **Better reliability** through redundancy
|
|
- **Production-ready** relay management
|
|
|
|
Use the base MKStack template for:
|
|
- Simple prototypes or learning projects
|
|
- Apps that only need basic relay connectivity
|
|
- Minimal dependency requirements
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Start development server
|
|
npm run dev
|
|
|
|
# Build for production
|
|
npm run build
|
|
|
|
# Run tests
|
|
npm test
|
|
```
|
|
|
|
## License
|
|
|
|
Same as MKStack base template. |