From a13e26d6e9864aef94b05aaa2c2271409f6c5c7c Mon Sep 17 00:00:00 2001 From: Kye Gomez Date: Tue, 25 Mar 2025 16:43:31 -0700 Subject: [PATCH] docs cleanup --- docs/finance/subscription.md | 1030 ---------------------------------- docs/finance/wallet.md | 383 ------------- docs/index.md | 14 +- 3 files changed, 13 insertions(+), 1414 deletions(-) delete mode 100644 docs/finance/subscription.md delete mode 100644 docs/finance/wallet.md diff --git a/docs/finance/subscription.md b/docs/finance/subscription.md deleted file mode 100644 index b7123a42..00000000 --- a/docs/finance/subscription.md +++ /dev/null @@ -1,1030 +0,0 @@ -# $swarms Token Subscription Payment System - -## Overview -This documentation covers the implementation of subscription-based payments using $swarms tokens on the Solana blockchain. - -## System Architecture - -```mermaid -flowchart TB - subgraph Frontend - UI[User Interface] - PM[Payment Manager] - end - - subgraph Backend - SM[Subscription Manager] - DB[(Database)] - Queue[Job Queue] - end - - subgraph Blockchain - SC[Smart Contract] - Token[$swarms Token] - end - - UI -->|Subscribe| PM - PM -->|Create Subscription| SM - SM -->|Store| DB - SM -->|Schedule| Queue - Queue -->|Execute Payment| SC - SC -->|Transfer| Token -``` - -## Core Components - -### 1. Subscription Smart Contract - -```typescript -import { Program, web3 } from '@project-serum/anchor'; -import { PublicKey, SystemProgram } from '@solana/web3.js'; - -interface SubscriptionAccount { - subscriber: PublicKey; - merchant: PublicKey; - amount: number; - interval: number; - nextPaymentDate: number; - active: boolean; -} - -class SubscriptionContract { - program: Program; - - constructor(program: Program) { - this.program = program; - } - - async createSubscription( - subscriber: PublicKey, - merchant: PublicKey, - amount: number, - interval: number - ): Promise { - const subscription = web3.Keypair.generate(); - const currentTimestamp = Math.floor(Date.now() / 1000); - - await this.program.rpc.createSubscription( - new BN(amount), - new BN(interval), - new BN(currentTimestamp + interval), - { - accounts: { - subscription: subscription.publicKey, - subscriber, - merchant, - systemProgram: SystemProgram.programId, - }, - signers: [subscription], - } - ); - - return subscription.publicKey.toString(); - } - - async processPayment(subscriptionAddress: string): Promise { - const subscription = await this.program.account.subscription.fetch( - new PublicKey(subscriptionAddress) - ); - - // Transfer tokens - const signature = await this.transferTokens( - subscription.subscriber, - subscription.merchant, - subscription.amount - ); - - // Update next payment date - await this.updateNextPaymentDate( - subscriptionAddress, - subscription.nextPaymentDate + subscription.interval - ); - - return signature; - } -} -``` - -### 2. Subscription Manager Service - -```typescript -class SubscriptionManager { - private contract: SubscriptionContract; - private db: Database; - private queue: Queue; - - constructor( - contract: SubscriptionContract, - db: Database, - queue: Queue - ) { - this.contract = contract; - this.db = db; - this.queue = queue; - } - - async createSubscription( - subscriberAddress: string, - merchantAddress: string, - amount: number, - interval: number, - planDetails: SubscriptionPlan - ): Promise { - // Create blockchain subscription - const subscriptionAddress = await this.contract.createSubscription( - new PublicKey(subscriberAddress), - new PublicKey(merchantAddress), - amount, - interval - ); - - // Store subscription details - const subscription = await this.db.subscriptions.create({ - address: subscriptionAddress, - subscriber: subscriberAddress, - merchant: merchantAddress, - amount, - interval, - planDetails, - status: 'active', - createdAt: new Date() - }); - - // Schedule first payment - await this.scheduleNextPayment(subscription); - - return { - subscriptionId: subscription.id, - address: subscriptionAddress, - status: 'active' - }; - } - - async cancelSubscription( - subscriptionId: string, - reason?: string - ): Promise { - // Update blockchain state - await this.contract.deactivateSubscription(subscriptionId); - - // Update database - await this.db.subscriptions.update({ - where: { id: subscriptionId }, - data: { - status: 'cancelled', - cancelledAt: new Date(), - cancelReason: reason - } - }); - - // Remove scheduled payments - await this.queue.removeScheduledJobs(subscriptionId); - } -} -``` - -### 3. Payment Processing System - -```typescript -class PaymentProcessor { - private connection: Connection; - private subscriptionManager: SubscriptionManager; - - async processSubscriptionPayment( - subscriptionId: string - ): Promise { - const subscription = await this.subscriptionManager.get(subscriptionId); - - try { - // Create and send transaction - const signature = await this.createAndExecutePayment(subscription); - - // Update payment history - await this.recordPayment({ - subscriptionId, - amount: subscription.amount, - signature, - status: 'success' - }); - - // Schedule next payment - await this.subscriptionManager.scheduleNextPayment(subscription); - - return { success: true, signature }; - - } catch (error) { - await this.handlePaymentFailure(subscription, error); - return { success: false, error }; - } - } - - private async createAndExecutePayment( - subscription: Subscription - ): Promise { - const transaction = await this.buildPaymentTransaction(subscription); - return await this.sendAndConfirmTransaction(transaction); - } -} -``` - -## Subscription Plans and Pricing - -```mermaid -classDiagram - class SubscriptionPlan { - +string id - +string name - +number amount - +number interval - +Feature[] features - +boolean isActive - +create(PlanData) Plan - +update(string, PlanData) Plan - +delete(string) void - } - - class Feature { - +string id - +string name - +string description - +boolean isEnabled - } - - class PricingTier { - +string id - +string name - +number amount - +Discount[] discounts - } - - class Discount { - +string id - +number percentage - +number duration - } - - SubscriptionPlan "1" -- "*" Feature - SubscriptionPlan "1" -- "1" PricingTier - PricingTier "1" -- "*" Discount -``` - -### Implementation Example - -```typescript -interface SubscriptionPlan { - id: string; - name: string; - amount: number; - interval: number; - features: Feature[]; - isActive: boolean; -} - -class PlanManager { - async createPlan(planData: CreatePlanDTO): Promise { - // Validate plan data - this.validatePlanData(planData); - - // Create plan in database - const plan = await this.db.plans.create({ - data: { - ...planData, - isActive: true, - createdAt: new Date() - } - }); - - // Create on-chain representation - await this.contract.registerPlan(plan.id, plan.amount, plan.interval); - - return plan; - } - - async updatePlan( - planId: string, - updates: UpdatePlanDTO - ): Promise { - // Validate updates - this.validatePlanUpdates(updates); - - // Update in database - const updatedPlan = await this.db.plans.update({ - where: { id: planId }, - data: updates - }); - - // Update on-chain if necessary - if (updates.amount || updates.interval) { - await this.contract.updatePlan( - planId, - updates.amount, - updates.interval - ); - } - - return updatedPlan; - } -} -``` - -## Payment Flow - -```mermaid -sequenceDiagram - participant User - participant UI - participant Backend - participant Blockchain - participant Wallet - - User->>UI: Select Subscription Plan - UI->>Backend: Create Subscription Request - Backend->>Blockchain: Deploy Subscription Contract - Blockchain-->>Backend: Contract Address - Backend->>UI: Subscription Details - UI->>Wallet: Request Approval - Wallet->>User: Confirm Transaction - User->>Wallet: Approve - Wallet->>Blockchain: Submit Transaction - Blockchain-->>Backend: Confirmation - Backend->>UI: Success Response - UI->>User: Show Confirmation -``` - -## Error Handling and Recovery - -```typescript -class SubscriptionErrorHandler { - async handlePaymentFailure( - subscription: Subscription, - error: Error - ): Promise { - // Log error - await this.logError({ - subscriptionId: subscription.id, - error, - timestamp: new Date() - }); - - // Determine retry strategy - const retryStrategy = this.determineRetryStrategy( - subscription, - error - ); - - if (retryStrategy.shouldRetry) { - await this.scheduleRetry( - subscription, - retryStrategy.retryAfter - ); - } else { - await this.handleSubscriptionFailure(subscription); - } - - // Notify relevant parties - await this.sendNotifications(subscription, error); - } - - private async handleSubscriptionFailure( - subscription: Subscription - ): Promise { - // Update subscription status - await this.subscriptionManager.updateStatus( - subscription.id, - 'failed' - ); - - // Notify merchant - await this.notifyMerchant(subscription); - - // Create recovery task - await this.createRecoveryTask(subscription); - } -} -``` - -## Analytics and Reporting - -```typescript -class SubscriptionAnalytics { - async generateMetrics( - timeframe: TimeFrame - ): Promise { - const metrics = { - activeSubscriptions: await this.countActiveSubscriptions(), - recurringRevenue: await this.calculateMRR(), - churnRate: await this.calculateChurnRate(timeframe), - lifetimeValue: await this.calculateLTV(), - conversionRate: await this.calculateConversionRate() - }; - - return metrics; - } - - async generateReport( - options: ReportOptions - ): Promise { - const report = { - metrics: await this.generateMetrics(options.timeframe), - subscriptionsByPlan: await this.aggregateByPlan(), - revenueProjection: await this.projectRevenue(options.months), - churnAnalysis: await this.analyzeChurn() - }; - - return report; - } -} -``` - -## Security Measures - -```typescript -class SubscriptionSecurity { - validateSubscription(subscription: Subscription): boolean { - return this.validateSignature(subscription.signature) && - this.validatePermissions(subscription.subscriber) && - this.validateLimits(subscription.amount); - } - - async monitorTransactions(): Promise { - // Monitor for suspicious activity - const transactions = await this.getRecentTransactions(); - - for (const tx of transactions) { - if (this.isAnomalous(tx)) { - await this.flagTransaction(tx); - await this.notifyAdmin(tx); - } - } - } -} -``` - -## Testing Framework - -```typescript -describe('Subscription System', () => { - let subscriptionManager: SubscriptionManager; - let paymentProcessor: PaymentProcessor; - - beforeEach(async () => { - // Setup test environment - subscriptionManager = new SubscriptionManager( - mockContract, - mockDb, - mockQueue - ); - - paymentProcessor = new PaymentProcessor( - mockConnection, - subscriptionManager - ); - }); - - describe('Subscription Creation', () => { - it('should create a new subscription', async () => { - const subscription = await subscriptionManager.createSubscription( - testData.subscriber, - testData.merchant, - testData.amount, - testData.interval, - testData.plan - ); - - expect(subscription).to.have.property('id'); - expect(subscription.status).to.equal('active'); - }); - }); - - describe('Payment Processing', () => { - it('should process recurring payments', async () => { - const result = await paymentProcessor.processSubscriptionPayment( - testData.subscriptionId - ); - - expect(result.success).to.be.true; - expect(result).to.have.property('signature'); - }); - }); -}); -``` - -## Migration and Upgrades - -```typescript -class SubscriptionMigrationManager { - async migrateSubscriptions( - fromVersion: string, - toVersion: string - ): Promise { - const subscriptions = await this.getSubscriptionsForMigration( - fromVersion - ); - - const results = await Promise.allSettled( - subscriptions.map(sub => this.migrateSubscription(sub, toVersion)) - ); - - return this.generateMigrationReport(results); - } - - private async migrateSubscription( - subscription: Subscription, - newVersion: string - ): Promise { - // Create new subscription with updated structure - const newSubscription = await this.createNewVersionSubscription( - subscription, - newVersion - ); - - // Migrate payment history - await this.migratePaymentHistory( - subscription.id, - newSubscription.id - ); - - // Update references - await this.updateSubscriptionReferences( - subscription.id, - newSubscription.id - ); - - // Archive old subscription - await this.archiveSubscription(subscription.id); - } -} -``` - -## Compliance and Audit - -```typescript -class SubscriptionAuditor { - async auditSubscription( - subscriptionId: string - ): Promise { - const subscription = await this.getSubscription(subscriptionId); - const payments = await this.getPaymentHistory(subscriptionId); - - return { - subscription: this.validateSubscriptionData(subscription), - payments: this.validatePayments(payments), - compliance: await this.checkCompliance(subscription), - recommendations: this.generateRecommendations(subscription) - }; - } - - async generateComplianceReport(): Promise { - return { - totalSubscriptions: await this.countSubscriptions(), - activeSubscriptions: await this.countActiveSubscriptions(), - riskAssessment: await this.assessRisk(), - complianceStatus: await this.checkComplianceStatus(), - regulatoryRequirements: await this.checkRegulatory() - }; - } -} -``` - -## Performance Optimization - -```typescript -class SubscriptionOptimizer { - async optimizePerformance(): Promise { - const metrics = await this.gatherPerformanceMetrics(); - const bottlenecks = this.identifyBottlenecks(metrics); - - // Optimize database queries - await this.optimizeDatabaseQueries(); - - // Optimize blockchain interactions - await this.optimizeBlockchainCalls(); - - // Cache frequently accessed data - await this.setupCaching(); - - return { - beforeMetrics: metrics, - afterMetrics: await this.gatherPerformanceMetrics(), - improvements: this.calculateImprovements(), - recommendations: this.generateOptimizationRecommendations() - }; - } - - private async optimizeDatabaseQueries(): Promise { - await this.createIndexes(); - await this.optimizeJoins(); - await this.implementQueryCaching(); - } - - private async optimizeBlockchainCalls(): Promise { - await this.implementBatchProcessing(); - await this.setupWebSocketConnections(); - await this.cacheBlockchainState(); - } -} -``` - -## Webhook Integration - -```typescript -class SubscriptionWebhooks { - private endpoints: Map; - - async registerWebhook( - event: WebhookEvent, - endpoint: string, - secret: string - ): Promise { - const webhookId = generateUniqueId(); - - await this.db.webhooks.create({ - id: webhookId, - event, - endpoint, - secret, - status: 'active' - }); - - return webhookId; - } - - async triggerWebhook( - event: WebhookEvent, - data: any - ): Promise { - const webhooks = await this.getWebhooksForEvent(event); - - for (const webhook of webhooks) { - try { - const payload = this.createWebhookPayload(event, data); - const signature = this.signPayload(payload, webhook.secret); - - await this.sendWebhookRequest( - webhook.endpoint, - payload, - signature - ); - - } catch (error) { - await this.handleWebhookError(webhook, error); - } - } - } -} -``` - -## Notification System - -```mermaid -flowchart TB - subgraph NotificationSystem - E[Event Handler] - T[Template Engine] - Q[Queue Manager] - D[Delivery Service] - end - - subgraph Channels - Email[Email Service] - SMS[SMS Service] - Push[Push Notifications] - Web[Web Hooks] - end - - E -->|Event| T - T -->|Formatted| Q - Q -->|Queued| D - D -->|Send| Email - D -->|Send| SMS - D -->|Send| Push - D -->|Send| Web -``` - -```typescript -class SubscriptionNotifier { - async notify( - event: SubscriptionEvent, - subscription: Subscription - ): Promise { - const template = await this.getNotificationTemplate(event); - const recipients = await this.getRecipients(subscription); - - const notifications = recipients.map(recipient => - this.createNotification(template, recipient, subscription) - ); - - await this.queueNotifications(notifications); - } - - private async createNotification( - template: Template, - recipient: Recipient, - subscription: Subscription - ): Promise { - return { - recipient, - content: this.renderTemplate(template, { - subscription, - recipient - }), - channel: recipient.preferredChannel, - priority: this.determinePriority(template.event) - }; - } -} -``` - -## Usage Analytics Dashboard - -```typescript -interface SubscriptionAnalytics { - totalRevenue: number; - activeSubscriptions: number; - churnRate: number; - averageLifetime: number; - topPlans: PlanAnalytics[]; -} - -class AnalyticsDashboard { - async generateDashboardData( - timeframe: TimeFrame - ): Promise { - return { - overview: await this.generateOverview(timeframe), - trends: await this.analyzeTrends(timeframe), - forecasts: await this.generateForecasts(), - recommendations: await this.generateRecommendations() - }; - } - - private async generateOverview( - timeframe: TimeFrame - ): Promise { - return { - totalRevenue: await this.calculateRevenue(timeframe), - activeSubscriptions: await this.countActiveSubscriptions(), - growthRate: await this.calculateGrowthRate(timeframe), - churnMetrics: await this.analyzeChurn(timeframe) - }; - } -} -``` - -## Rate Limiting and Throttling - -```typescript -class RateLimiter { - private readonly redis: Redis; - private readonly limits: Map; - - async checkLimit( - key: string, - operation: string - ): Promise { - const limit = this.limits.get(operation); - if (!limit) return true; - - const current = await this.redis.incr(key); - if (current === 1) { - await this.redis.expire(key, limit.windowSeconds); - } - - return current <= limit.maxRequests; - } - - async handleRateLimit( - subscription: Subscription, - operation: string - ): Promise { - const key = `${subscription.id}:${operation}`; - - if (!await this.checkLimit(key, operation)) { - throw new RateLimitError( - `Rate limit exceeded for ${operation}` - ); - } - } -} -``` - -## Disaster Recovery - -```typescript -class DisasterRecovery { - async backupData(): Promise { - const backup = { - subscriptions: await this.backupSubscriptions(), - payments: await this.backupPayments(), - metadata: await this.backupMetadata() - }; - - await this.storeBackup(backup); - return backup; - } - - async restore( - backupId: string, - options: RestoreOptions - ): Promise { - const backup = await this.loadBackup(backupId); - - // Validate backup integrity - this.validateBackup(backup); - - // Perform restoration - const result = await this.performRestore(backup, options); - - // Verify restoration - await this.verifyRestoration(result); - - return result; - } -} -``` - -## Subscription Lifecycle Events - -```mermaid -stateDiagram-v2 - [*] --> Created - Created --> Active: Payment Successful - Active --> Suspended: Payment Failed - Active --> Cancelled: User Cancellation - Active --> Expired: Term Ended - Suspended --> Active: Payment Resumed - Suspended --> Cancelled: Grace Period Ended - Cancelled --> [*] - Expired --> [*] -``` - -## Future Enhancements - -1. Smart Contract Upgrades -```typescript -class ContractUpgrader { - async upgradeContract( - newVersion: string - ): Promise { - // Validate new version - await this.validateNewVersion(newVersion); - - // Deploy new contract - const newContract = await this.deployNewVersion(newVersion); - - // Migrate state - await this.migrateState(newContract); - - // Switch over - await this.switchToNewContract(newContract); - - return { - newContractAddress: newContract.address, - migrationStatus: 'success' - }; - } -} -``` - -2. Multi-Token Support -```typescript -interface TokenConfig { - address: string; - decimals: number; - symbol: string; -} - -class MultiTokenSubscription { - private supportedTokens: Map; - - async addToken( - config: TokenConfig - ): Promise { - await this.validateToken(config); - this.supportedTokens.set(config.symbol, config); - } - - async createMultiTokenSubscription( - subscriber: string, - token: string, - amount: number - ): Promise { - const config = this.supportedTokens.get(token); - if (!config) throw new Error('Unsupported token'); - - return await this.createSubscription( - subscriber, - config, - amount - ); - } -} -``` - -## API Documentation - -### REST Endpoints - -```typescript -interface SubscriptionAPI { - // Subscription Management - 'POST /subscriptions': { - body: CreateSubscriptionDTO; - response: SubscriptionResponse; - }; - - 'GET /subscriptions/:id': { - params: { id: string }; - response: SubscriptionDetails; - }; - - 'PATCH /subscriptions/:id': { - params: { id: string }; - body: UpdateSubscriptionDTO; - response: SubscriptionResponse; - }; - - 'DELETE /subscriptions/:id': { - params: { id: string }; - response: void; - }; - - // Payment Management - 'GET /subscriptions/:id/payments': { - params: { id: string }; - query: PaymentQueryParams; - response: PaymentHistory; - }; - - // Analytics - 'GET /subscriptions/analytics': { - query: AnalyticsParams; - response: AnalyticsResponse; - }; -} -``` - -## Complete Implementation Checklist - -1. Core Infrastructure - - [ ] Smart Contract Development - - [ ] Database Schema Design - - [ ] API Layer Implementation - - [ ] Payment Processing System - -2. Security Measures - - [ ] Authentication System - - [ ] Authorization Rules - - [ ] Rate Limiting - - [ ] Input Validation - -3. Integration Features - - [ ] Webhook System - - [ ] Notification Service - - [ ] Analytics Dashboard - - [ ] Reporting System - -4. Maintenance Tools - - [ ] Monitoring System - - [ ] Backup Solution - - [ ] Migration Tools - - [ ] Testing Framework - -## Deployment Guide - -```mermaid -flowchart TB - subgraph Preparation - Config[Configuration] - Deps[Dependencies] - Env[Environment Setup] - end - - subgraph Deployment - Contract[Deploy Contract] - Backend[Deploy Backend] - Frontend[Deploy Frontend] - end - - subgraph Verification - Test[Testing] - Monitor[Monitoring] - Backup[Backup] - end - - Preparation --> Deployment - Deployment --> Verification -``` - -## Support and Resources - -### Support Channels -- Technical Support: support@swarms.world -- Developer Discord: discord.gg/swarms -- Documentation Site: docs.swarms.world - -## Version History -- v1.0.0: Initial Release -- v1.1.0: Added Multi-Token Support -- v1.2.0: Enhanced Analytics -- v1.3.0: Improved Error Handling \ No newline at end of file diff --git a/docs/finance/wallet.md b/docs/finance/wallet.md deleted file mode 100644 index f3eeeeec..00000000 --- a/docs/finance/wallet.md +++ /dev/null @@ -1,383 +0,0 @@ -# $swarms Token Integration Guide - -## Overview -This guide covers the integration of $swarms token (74SBV4zDXxTRgv1pEMoECskKBkZHc2yGPnc7GYVepump) payments into your platform using Solana and Phantom wallet. The $swarms token offers numerous benefits on the Solana blockchain, including high transaction per second (TPS) capabilities, low transaction fees, and more. - -## Table of Contents -- [Prerequisites](#prerequisites) -- [Installation](#installation) -- [Architecture Overview](#architecture-overview) -- [Setup Guide](#setup-guide) -- [Integration Examples](#integration-examples) -- [One-Click Payment Implementation](#one-click-payment-implementation) -- [Security Considerations](#security-considerations) -- [Troubleshooting](#troubleshooting) - -## Prerequisites -- Node.js v16.x or higher -- TypeScript 4.x or higher -- Phantom Wallet browser extension -- Solana development environment - -## Installation - -```bash -npm install @solana/web3.js @solana/spl-token @project-serum/anchor @solana/wallet-adapter-react @solana/wallet-adapter-phantom -``` - -## Architecture Overview - -```mermaid -flowchart TB - A[User Interface] -->|Trigger Payment| B[Payment Handler] - B --> C{Phantom Wallet} - C -->|Sign Transaction| D[Solana Network] - D -->|Execute Transfer| E[$swarms Token Contract] - E -->|Confirm Transaction| F[Payment Confirmation] - F -->|Update UI| A -``` - -## Setup Guide - -### 1. Initialize Solana Connection - -```typescript -import { Connection, clusterApiUrl } from '@solana/web3.js'; -import { PhantomWalletAdapter } from '@solana/wallet-adapter-phantom'; - -const connection = new Connection(clusterApiUrl('mainnet-beta')); -const wallet = new PhantomWalletAdapter(); - -// Initialize wallet connection -await wallet.connect(); -``` - -### 2. Configure Token Parameters - -```typescript -const SWARMS_TOKEN_ADDRESS = '74SBV4zDXxTRgv1pEMoECskKBkZHc2yGPnc7GYVepump'; - -interface TokenConfig { - mint: PublicKey; - decimals: number; -} - -const swarmTokenConfig: TokenConfig = { - mint: new PublicKey(SWARMS_TOKEN_ADDRESS), - decimals: 9 -}; -``` - -### 3. Create Payment Handler - -```typescript -export class SwarmPaymentHandler { - private connection: Connection; - private wallet: PhantomWalletAdapter; - - constructor(connection: Connection, wallet: PhantomWalletAdapter) { - this.connection = connection; - this.wallet = wallet; - } - - async createTransferTransaction( - amount: number, - recipientAddress: string - ): Promise { - const transaction = new Transaction(); - - const transferInstruction = createTransferInstruction( - await getAssociatedTokenAddress(swarmTokenConfig.mint, this.wallet.publicKey), - await getAssociatedTokenAddress(swarmTokenConfig.mint, new PublicKey(recipientAddress)), - this.wallet.publicKey, - amount * Math.pow(10, swarmTokenConfig.decimals) - ); - - transaction.add(transferInstruction); - return transaction; - } -} -``` - -## One-Click Payment Implementation - -### React Component Example - -```typescript -import React, { useState } from 'react'; -import { useWallet } from '@solana/wallet-adapter-react'; - -const SwarmPaymentButton: React.FC<{ - amount: number; - recipientAddress: string; -}> = ({ amount, recipientAddress }) => { - const [loading, setLoading] = useState(false); - const wallet = useWallet(); - const paymentHandler = new SwarmPaymentHandler(connection, wallet); - - const handlePayment = async () => { - try { - setLoading(true); - - const transaction = await paymentHandler.createTransferTransaction( - amount, - recipientAddress - ); - - const signature = await wallet.sendTransaction(transaction, connection); - await connection.confirmTransaction(signature); - - // Handle success - console.log('Payment successful:', signature); - } catch (error) { - console.error('Payment failed:', error); - } finally { - setLoading(false); - } - }; - - return ( - - ); -}; -``` - -### Payment Flow Sequence - -```mermaid -sequenceDiagram - participant User - participant UI - participant PaymentHandler - participant PhantomWallet - participant Solana - - User->>UI: Click Pay Button - UI->>PaymentHandler: Create Transaction - PaymentHandler->>PhantomWallet: Request Signature - PhantomWallet->>User: Prompt for Approval - User->>PhantomWallet: Approve Transaction - PhantomWallet->>Solana: Submit Transaction - Solana->>PaymentHandler: Confirm Transaction - PaymentHandler->>UI: Update Status - UI->>User: Show Confirmation -``` - -## Security Considerations - -### Transaction Validation - -```typescript -function validateTransaction( - transaction: Transaction, - expectedAmount: number, - expectedRecipient: PublicKey -): boolean { - try { - const instruction = transaction.instructions[0]; - const decodedData = TOKEN_PROGRAM_ID.decode(instruction.data); - - return ( - decodedData.amount === expectedAmount && - instruction.keys[1].pubkey.equals(expectedRecipient) - ); - } catch (error) { - console.error('Transaction validation failed:', error); - return false; - } -} -``` - -### Error Handling - -```typescript -class PaymentError extends Error { - constructor( - message: string, - public code: string, - public transaction?: string - ) { - super(message); - this.name = 'PaymentError'; - } -} - -async function handlePaymentError(error: any): Promise { - if (error instanceof WalletError) { - // Handle wallet-specific errors - throw new PaymentError( - 'Wallet error occurred', - 'WALLET_ERROR', - error.message - ); - } else if (error.code === 'TransactionError') { - // Handle Solana transaction errors - throw new PaymentError( - 'Transaction failed', - 'TRANSACTION_ERROR', - error.txid - ); - } - // Handle other errors... -} -``` - -## Testing - -### Unit Test Example - -```typescript -import { expect } from 'chai'; -import { SwarmPaymentHandler } from './payment-handler'; - -describe('SwarmPaymentHandler', () => { - let paymentHandler: SwarmPaymentHandler; - - beforeEach(() => { - // Setup test environment - }); - - it('should create valid transfer transaction', async () => { - const amount = 100; - const recipientAddress = 'recipient_address'; - - const transaction = await paymentHandler.createTransferTransaction( - amount, - recipientAddress - ); - - expect(transaction.instructions).to.have.lengthOf(1); - // Add more assertions... - }); -}); -``` - -## Troubleshooting - -### Common Issues and Solutions - -1. **Insufficient Balance** -```typescript -async function checkBalance( - connection: Connection, - walletAddress: PublicKey -): Promise { - const balance = await connection.getTokenAccountBalance( - await getAssociatedTokenAddress(swarmTokenConfig.mint, walletAddress) - ); - - return parseInt(balance.value.amount) > 0; -} -``` - -2. **Transaction Timeout** -```typescript -async function submitWithRetry( - transaction: Transaction, - maxRetries = 3 -): Promise { - let attempt = 0; - - while (attempt < maxRetries) { - try { - const signature = await wallet.sendTransaction(transaction, connection); - const confirmation = await connection.confirmTransaction(signature); - - if (confirmation.value.err) { - throw new Error('Transaction failed'); - } - - return signature; - } catch (error) { - attempt++; - if (attempt === maxRetries) throw error; - await new Promise(resolve => setTimeout(resolve, 1000 * attempt)); - } - } -} -``` - -## Monitoring and Analytics - -### Transaction Monitoring - -```typescript -interface TransactionMetrics { - timestamp: number; - amount: number; - success: boolean; - duration: number; -} - -class TransactionMonitor { - private metrics: TransactionMetrics[] = []; - - logTransaction(metric: TransactionMetrics): void { - this.metrics.push(metric); - // Add your analytics implementation - } - - getAverageSuccessRate(): number { - return ( - this.metrics.filter(m => m.success).length / this.metrics.length * 100 - ); - } -} -``` - -## Advanced Features - -### Batch Payments - -```typescript -async function createBatchPayment( - recipients: Array<{ address: string; amount: number }> -): Promise { - const transaction = new Transaction(); - - for (const recipient of recipients) { - const transferInstruction = createTransferInstruction(/* ... */); - transaction.add(transferInstruction); - } - - return transaction; -} -``` - -### Subscription Payments - -```typescript -class SubscriptionManager { - async createSubscription( - amount: number, - interval: number, - recipientAddress: string - ): Promise { - // Implementation for recurring payments - } - - async cancelSubscription(subscriptionId: string): Promise { - // Implementation for cancellation - } -} -``` - -## Support and Resources - -For additional support: -- Solana Documentation: https://docs.solana.com -- Phantom Wallet Docs: https://docs.phantom.app -- $swarms Token Contract: 74SBV4zDXxTRgv1pEMoECskKBkZHc2yGPnc7GYVepump - -## Version History - -- v1.0.0 - Initial release -- v1.0.1 - Added batch payment support -- v1.0.2 - Enhanced error handling -- v1.0.3 - Added subscription payment feature \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index f43ff90b..171a88b4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,8 +2,20 @@ [![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/jM3Z6M9uMq) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@kyegomez3242) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/kye-g-38759a207/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/kyegomezb) +## Swarms Installation -**Get Started Building Production-Grade Multi-Agent Applications** +```bash +pip3 install swarms +``` + +## Update Swarms + + +```bash +pip3 install -U swarms +``` + +### **Get Started Building Production-Grade Multi-Agent Applications** ## Onboarding