solana-payments

This skill guides implementation of a Solana SPL token payment provider for Toppio's existing chain-agnostic PaymentProvider interface. It covers wallet generation, balance checking, transfer detection, and sweeping — all adapted to Solana's unique account model.

Solana vs EVM — Key Differences

Solana is NOT EVM-compatible. Do not use ethers.js or EVM patterns. Key differences:

Concept	EVM (BSC/Polygon)	Solana
Library	ethers.js v6	@solana/web3.js + @solana/spl-token
Keypair	Random wallet (secp256k1)	Ed25519 keypair
Token balances	ERC-20 contract.balanceOf()	Associated Token Account (ATA)
Token transfer	contract.transfer()	createTransferInstruction()
Gas token	BNB / POL	SOL
Gas cost	~$0.01-0.05	~$0.001 (base) + ~$0.40 (ATA creation)
Finality	~3-15s	~400ms (optimistic), ~30s (confirmed)
Block scanning	Transfer events via getLogs	getSignaturesForAddress + getParsedTransaction

Token Addresses (Mainnet)

// USDC — Token Program (not Token-2022)
const USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';

// USDT — Token Program (not Token-2022)
const USDT_MINT = 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB';

// Token Program address (both USDC and USDT use this, NOT Token-2022)
const TOKEN_PROGRAM_ID = 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA';

CRITICAL: USDC and USDT on Solana both use the original Token Program, NOT Token-2022. Using the wrong program produces invalid ATAs and failed transfers.

Dependencies

npm install @solana/web3.js@1 @solana/spl-token bs58

Use @solana/web3.js v1 (stable). v2 is a full rewrite with different APIs. bs58 is needed for encoding/decoding Solana keypairs (not built into web3.js).

Provider Implementation

File: providers/payment/solana.ts

Implement the PaymentProvider interface from providers/payment/types.ts:

interface PaymentProvider {
  readonly chain: string;           // 'Solana'
  readonly chainId: string;         // 'solana'
  readonly token: string;           // 'USDC/USDT'
  readonly decimals: number;        // 6 (both USDC and USDT on Solana are 6 decimals)
  readonly gasToken: string;        // 'SOL'

  generateDepositAddress(): Promise<DepositAddress>;
  checkBalance(address: string): Promise<BalanceResult>;
  getIncomingTransfers(address: string, fromBlock?: number): Promise<TransferInfo[]>;
  sweep(fromPrivateKey: string, toAddress: string): Promise<SweepResult>;
  getExplorerUrl(txHash: string): string;
  getAddressExplorerUrl(address: string): string;
  isValidAddress(address: string): boolean;
  getMasterGasBalance(): Promise<string>;
}