Проверка адреса

Отправка токенов на неверный адрес может привести к безвозвратной потере средств. Проверка адреса гарантирует, что вы отправляете токены только на те адреса, которые могут их корректно получить и использовать.

Понимание адресов Solana

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

On-curve адреса

Стандартные адреса — это публичные ключи из пар ключей Ed25519. Эти адреса:

• Имеют соответствующий приватный ключ, который может подписывать транзакции
• Используются как адреса кошельков

Off-curve адреса (PDA)

Program Derived Addresses (PDA) детерминировано создаются на основе ID программы и seed-значений. Эти адреса:

• Не имеют соответствующего приватного ключа
• Могут быть подписаны только программой, от которой был получен этот адрес

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

Используйте адрес, чтобы получить аккаунт из сети, проверьте его владельца (программу) и тип аккаунта, чтобы понять, как работать с этим адресом.

Аккаунты System Program (кошельки)

Аккаунты, принадлежащие System Program, являются стандартными кошельками. Чтобы отправить SPL токены на кошелек, необходимо получить и использовать его associated token account (ATA).

После получения адреса ATA проверьте, существует ли этот token account в блокчейне. Если ATA не существует, вы можете добавить инструкцию на создание токен-аккаунта получателя в ту же транзакцию, что и перевод. Однако для этого потребуется оплатить rent за новый token account. Поскольку получатель владеет ATA, SOL, потраченные на rent, не могут быть возвращены отправителю.

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

Токен-аккаунты принадлежат Token Program или Token-2022 Program и содержат балансы токенов. Если полученный вами адрес принадлежит токен-программе, необходимо убедиться, что это токен-аккаунт (а не mint account) и что он соответствует ожидаемому mint account токена перед отправкой.

Mint-аккаунты

Mint-аккаунты отслеживают эмиссию токена и метаданные конкретного токена. Mint-аккаунты также принадлежат Token Program, но не являются допустимыми получателями токенов. Попытка отправить токены на адрес 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
// =============================================================================