# $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
