Verificar endereço

Enviar tokens para o endereço errado pode resultar em perda permanente de fundos. A verificação de endereço garante que você envie tokens apenas para endereços que possam recebê-los e acessá-los adequadamente.

Compreendendo endereços Solana

As contas Solana têm dois tipos de endereços: on-curve e off-curve.

Endereços on-curve

Endereços padrão são as chaves públicas de pares de chaves Ed25519. Estes endereços:

• Têm uma chave privada correspondente que pode assinar transações
• São usados como endereços de carteira

Endereços off-curve (PDAs)

Program Derived Addresses são derivados deterministicamente de um ID de programa e seeds. Estes endereços:

• Não têm uma chave privada correspondente
• Só podem ser assinados pelo programa do qual o endereço foi derivado

Tipos de conta em pagamentos

Use o endereço para buscar uma conta da rede, verifique o proprietário do programa e o tipo de conta para determinar como lidar com o endereço.

Contas do System Program (carteiras)

Contas pertencentes ao System Program são carteiras padrão. Para enviar tokens SPL para uma carteira, você deriva e usa sua associated token account (ATA).

Após derivar o endereço ATA, verifique se a token account existe on-chain. Se a ATA não existir, você pode incluir uma instrução para criar a token account do destinatário na mesma transação da transferência. No entanto, isso requer pagar rent pela nova token account. Como o destinatário possui a ATA, o SOL pago pelo rent não pode ser recuperado pelo remetente.

Token accounts

Token accounts são propriedade do Token Program ou Token-2022 Program e armazenam saldos de tokens. Se o endereço que recebe é propriedade de um token program, deve verificar se a conta é uma token account (não uma mint account) e corresponde à mint account de token esperada antes de enviar.

Mint accounts

Mint accounts rastreiam a oferta de tokens e metadados de um token específico. Mint accounts também são propriedade dos Token Programs mas não são destinatários válidos para transferências de tokens. Tentar enviar tokens para um endereço de mint resulta numa transação falhada, mas nenhum fundo é perdido.

Outras contas

Contas propriedade de outros programas requerem uma decisão de política. Algumas contas (por exemplo, carteiras multisig) podem ser proprietários válidos de token accounts, enquanto outras devem ser rejeitadas.

Fluxo de verificação

O diagrama seguinte mostra uma árvore de decisão de referência para validar um endereço:

Demonstração

O exemplo seguinte mostra apenas a lógica de validação de endereço. Este é código de referência para fins ilustrativos.

A demonstração abaixo usa três resultados possíveis:

/**
 * 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
// =============================================================================