[DOCS][Finance]

docs/finance/wallet.md

@@ -0,0 +1,383 @@
+# $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<Transaction> {
+    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 (
+    <button 
+      onClick={handlePayment}
+      disabled={loading || !wallet.connected}
+      className="payment-button"
+    >
+      {loading ? 'Processing...' : `Pay ${amount} $swarms`}
+    </button>
+  );
+};
+```
+
+### 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<void> {
+  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<boolean> {
+  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<string> {
+  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<Transaction> {
+  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<string> {
+    // Implementation for recurring payments
+  }
+
+  async cancelSubscription(subscriptionId: string): Promise<void> {
+    // 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

docs/mkdocs.yml

@@ -296,4 +296,7 @@ nav:
   - Corporate:
     - Culture: "corporate/culture.md"
     - Hiring: "corporate/hiring.md"
-    - Swarms Goals & Milestone Tracking; A Vision for 2024 and Beyond: "corporate/2024_2025_goals.md"
+    - Swarms Goals & Milestone Tracking; A Vision for 2024 and Beyond: "corporate/2024_2025_goals.md"
+  - Financial Infrastructure:
+    - Overview: "finance/index.md"
+    - Swarms Wallet: "finance/wallet.md"