Перевірка адреси

Надсилання токенів на неправильну адресу може призвести до безповоротної втрати коштів. Перевірка адреси гарантує, що ви надсилаєте токени лише на адреси, які можуть належним чином отримати їх та отримати до них доступ.

Розуміння адрес Solana

Акаунти Solana мають два типи адрес: on-curve та off-curve.

Адреси on-curve

Стандартні адреси — це публічні ключі з пар ключів Ed25519. Ці адреси:

• Мають відповідний приватний ключ, який може підписувати транзакції
• Використовуються як адреси гаманців

Адреси off-curve (PDA)

Program Derived Addresses детерміновано виводяться з ідентифікатора програми та seeds. Ці адреси:

• Не мають відповідного приватного ключа
• Можуть бути підписані лише програмою, з якої було виведено адресу

Типи акаунтів у платежах

Використовуйте адресу для отримання акаунта з мережі, перевірте його власника-програму та тип акаунта, щоб визначити, як обробляти адресу.

Акаунти System Program (гаманці)

Акаунти, що належать System Program, є стандартними гаманцями. Щоб надіслати SPL-токени на гаманець, ви виводите та використовуєте його associated token account (ATA).

Після виведення адреси ATA перевірте, чи існує токен-акаунт в мережі. Якщо ATA не існує, ви можете включити інструкцію для створення токен-акаунта одержувача в тій самій транзакції, що й переказ. Однак це вимагає сплати rent за новий токен-акаунт. Оскільки одержувач володіє ATA, SOL, сплачені за rent, не можуть бути повернені відправнику.

Токен-акаунти

Токен-акаунти належать Token Program або Token-2022 Program і зберігають баланси токенів. Якщо отримана адреса належить токен-програмі, ви повинні перевірити, що акаунт є токен-акаунтом (а не mint account) і відповідає очікуваному mint account токена перед відправленням.

Mint accounts

Mint accounts відстежують пропозицію токенів та метадані конкретного токена. Mint accounts також належать Token Programs, але не є дійсними одержувачами для переказів токенів. Спроба надіслати токени на адресу mint призводить до невдалої транзакції, але кошти не втрачаються.

Інші акаунти

Акаунти, що належать іншим програмам, вимагають прийняття рішення щодо політики. Деякі акаунти (наприклад, мультипідписні гаманці) можуть бути дійсними власниками токен-акаунтів, тоді як інші слід відхилити.

Процес перевірки

Наступна діаграма показує еталонне дерево рішень для валідації адреси:

Демонстрація

Наступний приклад показує лише логіку валідації адреси. Це довідковий код для ілюстративних цілей.

Демонстрація нижче використовує три можливі результати:

/**
 * Validates an input address and classifies it as a wallet, token account, or invalid.
 *
 * @param inputAddress - The address to validate
 * @param rpc - Optional RPC client (defaults to mainnet)
 * @returns Classification result:
 *   - IS_WALLET: Valid wallet address
 *   - IS_TOKEN_ACCOUNT: Valid token account
 *   - REJECT: Invalid address for transfers
 */
export async function validateAddress(
  inputAddress: Address,
  rpc: Rpc<GetAccountInfoApi> = defaultRpc
): Promise<ValidationResult> {
  const account = await fetchJsonParsedAccount(rpc, inputAddress);
  // Log the account data for demo
  console.log("\nAccount:", account);

  // Account doesn't exist on-chain
  if (!account.exists) {
    // Off-curve = PDA that doesn't exist as an account
    // Reject conservatively to avoid sending to an address that may be inaccessible.
    if (isOffCurveAddress(inputAddress)) {
      return { type: "REJECT", reason: "PDA doesn't exist as an account" };
    }
    // On-curve = valid keypair address, treat as unfunded wallet
    return { type: "IS_WALLET" };
  }

  // Account exists, check program owner
  const owner = account.programAddress;

  // System Program = wallet
  if (owner === SYSTEM_PROGRAM) {
    return { type: "IS_WALLET" };
  }

  // Token Program or Token-2022, check if token account
  if (owner === TOKEN_PROGRAM || owner === TOKEN_2022_PROGRAM) {
    const accountType = (
      account.data as { parsedAccountMeta?: { type?: string } }
    ).parsedAccountMeta?.type;

    if (accountType === "account") {
      return { type: "IS_TOKEN_ACCOUNT" };
    }
    // Reject if not a token account (mint account)
    return {
      type: "REJECT",
      reason: "Not a token account"
    };
  }

  // Unknown program owner
  return { type: "REJECT", reason: "Unknown program owner" };
}

// =============================================================================
// Examples
// =============================================================================

/**
 * Validates an input address and classifies it as a wallet, token account, or invalid.
 *
 * @param inputAddress - The address to validate
 * @param rpc - Optional RPC client (defaults to mainnet)
 * @returns Classification result:
 *   - IS_WALLET: Valid wallet address
 *   - IS_TOKEN_ACCOUNT: Valid token account
 *   - REJECT: Invalid address for transfers
 */
export async function validateAddress(
  inputAddress: Address,
  rpc: Rpc<GetAccountInfoApi> = defaultRpc
): Promise<ValidationResult> {
  const account = await fetchJsonParsedAccount(rpc, inputAddress);
  // Log the account data for demo
  console.log("\nAccount:", account);

  // Account doesn't exist on-chain
  if (!account.exists) {
    // Off-curve = PDA that doesn't exist as an account
    // Reject conservatively to avoid sending to an address that may be inaccessible.
    if (isOffCurveAddress(inputAddress)) {
      return { type: "REJECT", reason: "PDA doesn't exist as an account" };
    }
    // On-curve = valid keypair address, treat as unfunded wallet
    return { type: "IS_WALLET" };
  }

  // Account exists, check program owner
  const owner = account.programAddress;

  // System Program = wallet
  if (owner === SYSTEM_PROGRAM) {
    return { type: "IS_WALLET" };
  }

  // Token Program or Token-2022, check if token account
  if (owner === TOKEN_PROGRAM || owner === TOKEN_2022_PROGRAM) {
    const accountType = (
      account.data as { parsedAccountMeta?: { type?: string } }
    ).parsedAccountMeta?.type;

    if (accountType === "account") {
      return { type: "IS_TOKEN_ACCOUNT" };
    }
    // Reject if not a token account (mint account)
    return {
      type: "REJECT",
      reason: "Not a token account"
    };
  }

  // Unknown program owner
  return { type: "REJECT", reason: "Unknown program owner" };
}

// =============================================================================
// Examples
// =============================================================================