Інтеграція фронтенду з @solana/web3.js

Інтеграція фронтенда Solana з @solana/web3.js

Фронтенд Solana не є EVM. Немає ethers.js, немає useContractRead. Модель облікових записів, гаманці через Wallet Adapter, десеріалізація через Borsh — все інакше. Основна пастка для розробників з EVM-фоном — спроба застосувати ті ж паттерни. Це не працює.

Підключення гаманця: Wallet Adapter

@solana/wallet-adapter — стандартний спосіб підключення Phantom, Solflare, Backpack та інших гаманців:

// providers.tsx
import { ConnectionProvider, WalletProvider } from '@solana/wallet-adapter-react'
import { WalletModalProvider } from '@solana/wallet-adapter-react-ui'
import { PhantomWalletAdapter, SolflareWalletAdapter } from '@solana/wallet-adapter-wallets'
import { clusterApiUrl } from '@solana/web3.js'

const wallets = [new PhantomWalletAdapter(), new SolflareWalletAdapter()]
const endpoint = clusterApiUrl('mainnet-beta') // або ваш RPC

export function SolanaProviders({ children }: { children: React.ReactNode }) {
  return (
    <ConnectionProvider endpoint={endpoint}>
      <WalletProvider wallets={wallets} autoConnect>
        <WalletModalProvider>
          {children}
        </WalletModalProvider>
      </WalletProvider>
    </ConnectionProvider>
  )
}

Імпорт стилів обов'язковий: import '@solana/wallet-adapter-react-ui/styles.css'. Без цього модаль підключення не відобразиться коректно.

Читання даних з блокчейну

Connection з @solana/web3.js аналогічна PublicClient у viem. Ключові методи:

import { Connection, PublicKey, LAMPORTS_PER_SOL } from '@solana/web3.js'

const connection = new Connection(
  process.env.NEXT_PUBLIC_RPC_URL!,
  'confirmed' // рівень комітування: processed | confirmed | finalized
)

// SOL баланс
const balance = await connection.getBalance(new PublicKey(address))
const solBalance = balance / LAMPORTS_PER_SOL

// Інформація про облік запису (дані облікового запису програми)
const accountInfo = await connection.getAccountInfo(new PublicKey(address))

Рівні комітування — важливий деталь, яку часто упускають. processed — максимально швидко, але транзакція може відкатитися. confirmed — підтверджено ~66% stake. finalized — необоротно. Для UI зазвичай confirmed, для фінансових операцій — finalized.

Робота з SPL токенами

Більшість dApps працюють з SPL токенами, а не нативним SOL. Вам потрібний @solana/spl-token:

import { getAssociatedTokenAddress, getAccount } from '@solana/spl-token'
import { PublicKey } from '@solana/web3.js'

// Адреса token account користувача
const tokenAccount = await getAssociatedTokenAddress(
  new PublicKey(mintAddress),  // адреса mint токена
  new PublicKey(walletAddress) // гаманець власника
)

// Баланс
try {
  const account = await getAccount(connection, tokenAccount)
  const balance = Number(account.amount) / 10 ** decimals
} catch (e) {
  // TokenAccountNotFoundError — облік запису не створений, баланс 0
}

Нюанс: token account може не існувати, якщо користувач ніколи не тримав цей токен. Це не помилка — просто баланс 0. Вам потрібно обробити TokenAccountNotFoundError.

Відправка транзакцій

import { useWallet } from '@solana/wallet-adapter-react'
import { Transaction, SystemProgram, LAMPORTS_PER_SOL, PublicKey } from '@solana/web3.js'

const { publicKey, sendTransaction } = useWallet()

const handleSend = async () => {
  if (!publicKey) return
  
  const { blockhash, lastValidBlockHeight } = 
    await connection.getLatestBlockhash()
  
  const transaction = new Transaction().add(
    SystemProgram.transfer({
      fromPubkey: publicKey,
      toPubkey: new PublicKey(recipient),
      lamports: amount * LAMPORTS_PER_SOL,
    })
  )
  transaction.recentBlockhash = blockhash
  transaction.feePayer = publicKey

  const signature = await sendTransaction(transaction, connection)
  
  // Очікування підтвердження
  await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight })
}

sendTransaction з wallet adapter автоматично запитує підпис у гаманці користувача.

RPC та Rate Limits

Публічний clusterApiUrl('mainnet-beta') — тільки для розробки, він жорстко лімітований. Для production: Helius, QuickNode, Alchemy (Solana), або власна нода. Helius особливо зручний — надає розширений API з парсингом транзакцій та webhook'ами для on-chain подій.

Інтеграція займає 2–3 дні: налаштування wallet adapter, підключення до RPC, базові операції читання/запису та обробка типових помилок (insufficient funds, blockhash expired, simulation failed).