> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solana Implementation

> Solana-specific delegation implementation with SPL Token delegation

## Overview

This guide covers Solana-specific implementation details for delegating wallets. Solana uses a different delegation model than EVM chains, leveraging SPL Token's built-in delegation functionality.

<Note>
  Use the [`/v1/delegation/solana/post-approval`](/api-reference/delegation/solana-post-approval) endpoint for Solana delegations.
</Note>

## Solana Network

**Network Name**: Solana Mainnet Beta
**Currencies**: USDC, USDT
**Block Explorer**: [https://explorer.solana.com](https://explorer.solana.com)
**RPC URL**: [https://api.mainnet-beta.solana.com](https://api.mainnet-beta.solana.com)

**Advantages**:

* Extremely low transaction fees (\~\$0.00025 per transaction)
* Fast block times (\~400ms)
* High throughput (65,000+ TPS capability)
* No gas price fluctuations

**Transaction Cost**: Typically less than \$0.001

## SPL Token Delegation Model

Unlike EVM's ERC20 approval pattern, Solana uses SPL Token's native delegation system.

### How It Works

<Steps>
  <Step title="User Has Token Account">
    User has an Associated Token Account (ATA) for their USDC/USDT
  </Step>

  <Step title="Approve Delegate">
    User calls SPL Token's `Approve` instruction, setting a delegate with spending limit
  </Step>

  <Step title="Delegate Can Transfer">
    Platform's delegate address can call `Transfer` on behalf of the user, up to approved amount
  </Step>

  <Step title="Allowance Decreases">
    Each transfer decreases the delegated amount automatically
  </Step>
</Steps>

### Key Differences from EVM

| Aspect             | EVM (ERC20)                                   | Solana (SPL Token)       |
| ------------------ | --------------------------------------------- | ------------------------ |
| Approval Target    | Smart contract address                        | Delegate public key      |
| Account Model      | Single wallet address                         | Token accounts per token |
| Delegation Storage | Token contract state                          | Token account data       |
| Fee Model          | Variable gas                                  | Fixed \~0.000005 SOL     |
| Confirmation Time  | 12-15 seconds (Ethereum), 2-3 seconds (Linea) | \~400ms                  |

## Implementation

### Prerequisites

Install required packages:

```bash theme={null}
npm install @solana/web3.js @solana/spl-token @solana/wallet-adapter-react @solana/wallet-adapter-wallets
```

### Token Mint Addresses

<CodeGroup>
  ```typescript Solana Token Addresses theme={null}
  const SOLANA_TOKENS = {
    usdc: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC on Solana
    usdt: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'  // USDT on Solana
  };

  const PLATFORM_DELEGATE = 'YourPlatformDelegateAddress...'; // Provided by platform
  ```
</CodeGroup>

<Warning>
  Always verify token mint addresses are correct. Solana has multiple USDC/USDT versions (native, bridged, etc.).
</Warning>

### Complete Solana Delegation Flow

<CodeGroup>
  ```typescript TypeScript (@solana/web3.js) theme={null}
  import {
    Connection,
    PublicKey,
    Transaction,
    TransactionInstruction
  } from '@solana/web3.js';
  import {
    createApproveInstruction,
    getAssociatedTokenAddress,
    TOKEN_PROGRAM_ID
  } from '@solana/spl-token';

  interface SolanaDelegationParams {
    currency: 'usdc' | 'usdt';
    amount: string;
    mintAddress: string;
    delegateAddress: string;
    delegationToken: string;
  }

  async function delegateSolanaWallet(
    wallet: any, // Wallet adapter instance
    params: SolanaDelegationParams
  ): Promise<{
    address: string;
    network: 'solana';
    currency: string;
    amount: string;
    txHash: string;
    sigHash: string;
    sigMessage: string;
    token: string;
  }> {

    if (!wallet.connected || !wallet.publicKey) {
      throw new Error('Wallet not connected. Please connect a Solana wallet.');
    }

    const connection = new Connection(
      'https://api.mainnet-beta.solana.com',
      'confirmed'
    );

    const userPublicKey = wallet.publicKey;
    const mintPublicKey = new PublicKey(params.mintAddress);
    const delegatePublicKey = new PublicKey(params.delegateAddress);

    console.log(`User wallet: ${userPublicKey.toBase58()}`);

    const tokenAccount = await getAssociatedTokenAddress(
      mintPublicKey,
      userPublicKey
    );

    console.log(`Token account: ${tokenAccount.toBase58()}`);

    const accountInfo = await connection.getAccountInfo(tokenAccount);
    if (!accountInfo) {
      throw new Error(
        `Token account not found. Ensure you have ${params.currency.toUpperCase()} in your wallet.`
      );
    }

    const decimals = 6; // USDC and USDT use 6 decimals
    const amountLamports = BigInt(parseFloat(params.amount) * Math.pow(10, decimals));

    console.log(
      `Creating approval for ${params.amount} ${params.currency.toUpperCase()}`
    );

    const approveInstruction = createApproveInstruction(
      tokenAccount,
      delegatePublicKey,
      userPublicKey,
      amountLamports,
      [],
      TOKEN_PROGRAM_ID
    );

    const transaction = new Transaction().add(approveInstruction);
    transaction.feePayer = userPublicKey;

    const { blockhash, lastValidBlockHeight } =
      await connection.getLatestBlockhash();
    transaction.recentBlockhash = blockhash;

    console.log('Requesting signature from wallet...');

    const signedTransaction = await wallet.signTransaction(transaction);

    console.log('Sending transaction...');

    const signature = await connection.sendRawTransaction(
      signedTransaction.serialize()
    );

    console.log('Transaction sent:', signature);
    console.log('Waiting for confirmation...');

    await connection.confirmTransaction({
      signature,
      blockhash,
      lastValidBlockHeight
    });

    console.log('Transaction confirmed!');

    const message = 'Prove wallet ownership for delegation';
    const messageBytes = new TextEncoder().encode(message);

    console.log('Requesting message signature...');

    const messageSignature = await wallet.signMessage(messageBytes);

    const sigHash = Buffer.from(messageSignature).toString('base64');

    return {
      address: userPublicKey.toBase58(),
      network: 'solana',
      currency: params.currency,
      amount: params.amount,
      txHash: signature,
      sigHash,
      sigMessage: message,
      token: params.delegationToken
    };
  }
  ```

  ```typescript React Hook with Wallet Adapter theme={null}
  import { useWallet, useConnection } from '@solana/wallet-adapter-react';
  import { PublicKey, Transaction } from '@solana/web3.js';
  import {
    createApproveInstruction,
    getAssociatedTokenAddress,
    TOKEN_PROGRAM_ID
  } from '@solana/spl-token';

  export function useDelegateSolana() {
    const { publicKey, signTransaction, signMessage } = useWallet();
    const { connection } = useConnection();

    async function delegate(
      currency: 'usdc' | 'usdt',
      amount: string,
      mintAddress: string,
      delegateAddress: string,
      delegationToken: string
    ) {
      if (!publicKey || !signTransaction || !signMessage) {
        throw new Error('Wallet not connected');
      }

      const mintPublicKey = new PublicKey(mintAddress);
      const delegatePublicKey = new PublicKey(delegateAddress);

      const tokenAccount = await getAssociatedTokenAddress(
        mintPublicKey,
        publicKey
      );

      const accountInfo = await connection.getAccountInfo(tokenAccount);
      if (!accountInfo) {
        throw new Error(
          `No ${currency.toUpperCase()} token account found. Please ensure you have ${currency.toUpperCase()} in your wallet.`
        );
      }

      const amountLamports = BigInt(parseFloat(amount) * 1_000_000);

      const approveInstruction = createApproveInstruction(
        tokenAccount,
        delegatePublicKey,
        publicKey,
        amountLamports,
        [],
        TOKEN_PROGRAM_ID
      );

      const transaction = new Transaction().add(approveInstruction);
      transaction.feePayer = publicKey;

      const { blockhash, lastValidBlockHeight } =
        await connection.getLatestBlockhash();
      transaction.recentBlockhash = blockhash;

      const signed = await signTransaction(transaction);

      const signature = await connection.sendRawTransaction(signed.serialize());

      await connection.confirmTransaction({
        signature,
        blockhash,
        lastValidBlockHeight
      });

      const message = 'Prove wallet ownership for delegation';
      const messageBytes = new TextEncoder().encode(message);
      const messageSignature = await signMessage(messageBytes);

      return {
        address: publicKey.toBase58(),
        network: 'solana' as const,
        currency,
        amount,
        txHash: signature,
        sigHash: Buffer.from(messageSignature).toString('base64'),
        sigMessage: message,
        token: delegationToken
      };
    }

    return { delegate };
  }
  ```

  ```typescript React Component Example theme={null}
  import { WalletMultiButton } from '@solana/wallet-adapter-react-ui';
  import { useWallet } from '@solana/wallet-adapter-react';
  import { useDelegateSolana } from './hooks/useDelegateSolana';
  import { useState } from 'react';

  function DelegateSolanaButton() {
    const { connected } = useWallet();
    const { delegate } = useDelegateSolana();
    const [loading, setLoading] = useState(false);
    const [error, setError] = useState<string | null>(null);

    async function handleDelegate() {
      setLoading(true);
      setError(null);

      try {
        const tokenResponse = await fetch('/api/delegation/token');
        const { token } = await tokenResponse.json();

        const proof = await delegate(
          'usdc',
          '5000',
          'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC mint
          'YourPlatformDelegate...', // Platform delegate
          token
        );

        await fetch('/api/delegation/submit', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(proof)
        });

        alert('Delegation successful!');

      } catch (err: any) {
        console.error('Delegation failed:', err);
        setError(err.message);
      } finally {
        setLoading(false);
      }
    }

    if (!connected) {
      return <WalletMultiButton />;
    }

    return (
      <div>
        <button onClick={handleDelegate} disabled={loading}>
          {loading ? 'Delegating...' : 'Delegate Wallet'}
        </button>
        {error && <p className="error">{error}</p>}
      </div>
    );
  }
  ```
</CodeGroup>

### Wallet Adapter Setup

Set up Solana wallet adapter to support multiple wallets:

<CodeGroup>
  ```typescript WalletProvider Setup theme={null}
  import { WalletAdapterNetwork } from '@solana/wallet-adapter-base';
  import {
    ConnectionProvider,
    WalletProvider
  } from '@solana/wallet-adapter-react';
  import { WalletModalProvider } from '@solana/wallet-adapter-react-ui';
  import {
    PhantomWalletAdapter,
    SolflareWalletAdapter,
    BackpackWalletAdapter
  } from '@solana/wallet-adapter-wallets';
  import { clusterApiUrl } from '@solana/web3.js';
  import { useMemo } from 'react';

  require('@solana/wallet-adapter-react-ui/styles.css');

  export function SolanaWalletProvider({ children }: { children: React.ReactNode }) {
    const network = WalletAdapterNetwork.Mainnet;

    const endpoint = useMemo(
      () => clusterApiUrl(network),
      [network]
    );

    const wallets = useMemo(
      () => [
        new PhantomWalletAdapter(),
        new SolflareWalletAdapter(),
        new BackpackWalletAdapter()
      ],
      []
    );

    return (
      <ConnectionProvider endpoint={endpoint}>
        <WalletProvider wallets={wallets} autoConnect>
          <WalletModalProvider>
            {children}
          </WalletModalProvider>
        </WalletProvider>
      </ConnectionProvider>
    );
  }
  ```
</CodeGroup>

## Message Signing

Solana uses Ed25519 signatures instead of ECDSA (used by EVM chains).

### Sign Message

<CodeGroup>
  ```typescript Message Signing theme={null}
  async function signSolanaMessage(
    wallet: any,
    message: string
  ): Promise<string> {
    if (!wallet.signMessage) {
      throw new Error('Wallet does not support message signing');
    }

    const messageBytes = new TextEncoder().encode(message);

    const signature = await wallet.signMessage(messageBytes);

    const signatureBase64 = Buffer.from(signature).toString('base64');

    return signatureBase64;
  }
  ```

  ```typescript Verify Signature (Client-side) theme={null}
  import { sign } from 'tweetnacl';
  import { PublicKey } from '@solana/web3.js';

  function verifySolanaSignature(
    message: string,
    signatureBase64: string,
    publicKeyString: string
  ): boolean {
    try {
      const messageBytes = new TextEncoder().encode(message);
      const signatureBytes = Buffer.from(signatureBase64, 'base64');
      const publicKeyBytes = new PublicKey(publicKeyString).toBytes();

      return sign.detached.verify(
        messageBytes,
        signatureBytes,
        publicKeyBytes
      );
    } catch (error) {
      return false;
    }
  }
  ```
</CodeGroup>

## Check Token Account

Before delegation, verify user has the required token account:

<CodeGroup>
  ```typescript Check Token Account theme={null}
  import { getAccount, getAssociatedTokenAddress } from '@solana/spl-token';
  import { Connection, PublicKey } from '@solana/web3.js';

  async function checkTokenAccount(
    connection: Connection,
    userPublicKey: PublicKey,
    mintPublicKey: PublicKey
  ): Promise<{
    exists: boolean;
    balance?: number;
    address?: string;
  }> {
    try {
      const tokenAccountAddress = await getAssociatedTokenAddress(
        mintPublicKey,
        userPublicKey
      );

      const accountInfo = await getAccount(connection, tokenAccountAddress);

      const decimals = 6; // USDC/USDT
      const balance = Number(accountInfo.amount) / Math.pow(10, decimals);

      return {
        exists: true,
        balance,
        address: tokenAccountAddress.toBase58()
      };
    } catch (error: any) {
      if (error.name === 'TokenAccountNotFoundError') {
        return { exists: false };
      }
      throw error;
    }
  }

  async function ensureTokenAccount(
    wallet: any,
    currency: 'usdc' | 'usdt',
    mintAddress: string
  ): Promise<void> {
    const connection = new Connection('https://api.mainnet-beta.solana.com');
    const mintPublicKey = new PublicKey(mintAddress);

    const accountInfo = await checkTokenAccount(
      connection,
      wallet.publicKey,
      mintPublicKey
    );

    if (!accountInfo.exists) {
      throw new Error(
        `No ${currency.toUpperCase()} account found. ` +
        `Please add ${currency.toUpperCase()} to your wallet first.`
      );
    }

    if (accountInfo.balance === 0) {
      console.warn(
        `Warning: ${currency.toUpperCase()} balance is 0. ` +
        `You may want to add funds before delegating.`
      );
    }

    console.log(
      `${currency.toUpperCase()} balance: ${accountInfo.balance}`
    );
  }
  ```
</CodeGroup>

## Submit to API

After collecting all data, submit to the Solana-specific endpoint:

### API Request

<CodeGroup>
  ```typescript Submit Solana Delegation theme={null}
  interface SolanaDelegationProof {
    address: string;          // Base58-encoded, 32-44 characters
    network: 'solana';
    currency: 'usdc' | 'usdt';
    amount: string;
    txHash: string;           // Base58-encoded transaction signature, 87-88 characters
    sigHash: string;          // Base64-encoded message signature
    sigMessage: string;       // Message that was signed
    token: string;            // From Step 1
  }

  async function submitSolanaDelegation(
    proof: SolanaDelegationProof,
    userAccessToken: string
  ): Promise<boolean> {
    const response = await fetch(
      'https://api.yourplatform.com/v1/delegation/solana/post-approval',
      {
        method: 'POST',
        headers: {
          'x-client-key': process.env.CLIENT_PUBLIC_KEY!,
          'Authorization': `Bearer ${userAccessToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(proof)
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message || 'Delegation failed');
    }

    const data = await response.json();
    return data.success;
  }
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.yourplatform.com/v1/delegation/solana/post-approval" \
    -H "x-client-key: YOUR_PUBLIC_KEY" \
    -H "Authorization: Bearer USER_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "address": "DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK",
      "network": "solana",
      "currency": "usdc",
      "amount": "5000",
      "txHash": "5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnb...",
      "sigHash": "2Uhj5WqpLvZmJqKGx3WKvSC5K1m4YCp1eK3jcGY7GgRq...",
      "sigMessage": "Prove wallet ownership for delegation",
      "token": "100a99cf-f4d3-4fa1-9be9-2e9828b20ebc"
    }'
  ```
</CodeGroup>

**API Reference:** [`POST /v1/delegation/solana/post-approval`](/api-reference/delegation/solana-post-approval)

### Validation Rules

The API performs strict Solana-specific validation:

<AccordionGroup>
  <Accordion title="Address Format">
    * Base58-encoded string
    * Typically 32-44 characters
    * Must be a valid Solana public key
    * Case-sensitive

    **Valid**: `DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK`
    **Invalid**: `0xDYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK` (has 0x prefix)
  </Accordion>

  <Accordion title="Transaction Signature">
    * Base58-encoded string
    * Typically 87-88 characters
    * Must be a confirmed transaction on Solana mainnet
    * Case-sensitive

    **Valid**: `5VERv8NMvzbJMEkV8xnrLkEaWRtSz9CosKDYjCJjBRnbJLgp8uirBgmQpjKhoR4tjF3ZpRzrFmBV6UjKdiSZkQUW`
  </Accordion>

  <Accordion title="Message Signature">
    * Base64-encoded Ed25519 signature
    * Must verify against the provided address and message
    * Generated from `signMessage()` wallet adapter method

    **Valid**: Base64 string from Ed25519 signature
  </Accordion>

  <Accordion title="Message">
    * Any string that was signed by the wallet
    * Commonly: `"Prove wallet ownership for delegation"`
    * Must match exactly what was signed
  </Accordion>
</AccordionGroup>

## Error Handling

### Common Solana Errors

<CodeGroup>
  ```typescript Error Handler theme={null}
  async function handleSolanaDelegation() {
    try {
      await delegateSolanaWallet(wallet, params);
    } catch (error: any) {
      if (error.message?.includes('User rejected')) {
        console.error('User rejected transaction');
        alert('Please approve the transaction in your wallet to continue');
      }
      else if (error.message?.includes('Insufficient funds')) {
        console.error('Insufficient SOL for transaction fees');
        alert('You need a small amount of SOL (~0.00001) to pay for transaction fees');
      }
      else if (error.message?.includes('Token account not found')) {
        console.error('No token account');
        alert(`Please add ${params.currency.toUpperCase()} to your wallet first`);
      }
      else if (error.message?.includes('WalletNotConnectedError')) {
        console.error('Wallet not connected');
        alert('Please connect your Solana wallet');
      }
      else if (error.message?.includes('Blockhash not found')) {
        console.error('Transaction expired');
        alert('Transaction expired. Please try again.');
      }
      else {
        console.error('Unknown error:', error);
        alert(`Delegation failed: ${error.message}`);
      }
    }
  }
  ```
</CodeGroup>

### API Error Responses

| Status | Error                         | Cause                                   | Solution                                |
| ------ | ----------------------------- | --------------------------------------- | --------------------------------------- |
| 400    | Invalid address format        | Address not valid base58                | Ensure valid Solana public key          |
| 400    | Invalid transaction signature | Transaction not found or invalid format | Wait for confirmation, check signature  |
| 400    | Invalid message signature     | Signature doesn't verify                | Re-sign message with correct wallet     |
| 400    | Expired token                 | Delegation token expired                | Generate new token from Step 1          |
| 429    | Rate limited                  | Too many requests                       | Wait and retry with exponential backoff |

## Testing

### Test on Devnet

Before going to production, test on Solana devnet:

<CodeGroup>
  ```typescript Devnet Configuration theme={null}
  const DEVNET_CONFIG = {
    rpcUrl: 'https://api.devnet.solana.com',
    usdcMint: 'Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr', // USDC on devnet
    explorer: 'https://explorer.solana.com/?cluster=devnet'
  };

  async function setupDevnet() {
    return new Connection(DEVNET_CONFIG.rpcUrl, 'confirmed');
  }
  ```
</CodeGroup>

Get devnet SOL from:

* Solana Devnet Faucet: [https://faucet.solana.com](https://faucet.solana.com)

Get devnet USDC:

* Use SPL Token Faucet on devnet
* Or airdrop test tokens

## Performance Optimization

### Transaction Confirmation Strategies

<CodeGroup>
  ```typescript Confirmation Strategies theme={null}
  async function confirmTransactionFast(
    connection: Connection,
    signature: string
  ): Promise<void> {
    const { blockhash, lastValidBlockHeight } =
      await connection.getLatestBlockhash();

    await connection.confirmTransaction({
      signature,
      blockhash,
      lastValidBlockHeight
    }, 'confirmed'); // Can use 'processed', 'confirmed', or 'finalized'
  }

  async function confirmTransactionWithRetry(
    connection: Connection,
    signature: string,
    maxRetries: number = 3
  ): Promise<void> {
    for (let i = 0; i < maxRetries; i++) {
      try {
        const { blockhash, lastValidBlockHeight } =
          await connection.getLatestBlockhash();

        await connection.confirmTransaction({
          signature,
          blockhash,
          lastValidBlockHeight
        }, 'confirmed');

        return; // Success
      } catch (error) {
        if (i === maxRetries - 1) throw error;
        await new Promise(resolve => setTimeout(resolve, 1000)); // Wait 1s
      }
    }
  }
  ```
</CodeGroup>

### Priority Fees

For faster processing during network congestion:

<CodeGroup>
  ```typescript Priority Fees theme={null}
  import { ComputeBudgetProgram } from '@solana/web3.js';

  async function createTransactionWithPriorityFee(
    instructions: TransactionInstruction[],
    feeLamports: number = 1000
  ): Promise<Transaction> {
    const transaction = new Transaction();

    const computeBudgetIx = ComputeBudgetProgram.setComputeUnitPrice({
      microLamports: feeLamports
    });

    transaction.add(computeBudgetIx);
    transaction.add(...instructions);

    return transaction;
  }
  ```
</CodeGroup>

## Wallet Support

### Supported Solana Wallets

<CardGroup cols={3}>
  <Card title="Phantom" icon="ghost">
    Most popular Solana wallet with excellent mobile and browser support
  </Card>

  <Card title="Solflare" icon="sun">
    Full-featured wallet with hardware wallet support
  </Card>

  <Card title="Backpack" icon="backpack">
    Modern wallet with built-in xNFT app store
  </Card>
</CardGroup>

### Wallet Detection

<CodeGroup>
  ```typescript Detect Installed Wallets theme={null}
  function detectSolanaWallets(): string[] {
    const wallets: string[] = [];

    if (window.phantom?.solana) wallets.push('Phantom');
    if (window.solflare) wallets.push('Solflare');
    if (window.backpack) wallets.push('Backpack');

    return wallets;
  }

  function promptWalletInstall() {
    const installed = detectSolanaWallets();

    if (installed.length === 0) {
      return (
        <div className="wallet-prompt">
          <p>No Solana wallet detected. Please install one:</p>
          <a href="https://phantom.app" target="_blank">Install Phantom</a>
          <a href="https://solflare.com" target="_blank">Install Solflare</a>
        </div>
      );
    }

    return null;
  }
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="EVM Implementation" icon="ethereum" href="/guides/delegation/evm-chains">
    Learn how delegation works on EVM chains
  </Card>

  <Card title="Priority Management" icon="ranking-star" href="/guides/delegation/priority">
    Configure wallet charging priority
  </Card>

  <Card title="Redelegation" icon="rotate" href="/guides/delegation/redelegation">
    Update allowances when needed
  </Card>

  <Card title="Implementation Guide" icon="code" href="/guides/delegation/implementation">
    Complete 3-step delegation workflow
  </Card>
</CardGroup>