Kye Gomez
7 months ago
parent
a33e2154d4
commit
a13e26d6e9
File diff suppressed because it is too large
Load Diff
@ -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<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
|
|
||||||
Loading…
Reference in new issue