Weryfikacja adresu

Wysłanie tokenów na nieprawidłowy adres może skutkować trwałą utratą środków. Weryfikacja adresu zapewnia, że wysyłasz tokeny tylko na adresy, które mogą je poprawnie odebrać i uzyskać do nich dostęp.

Zrozumienie adresów Solana

Konta Solana mają dwa typy adresów: on-curve i off-curve.

Adresy on-curve

Standardowe adresy to klucze publiczne z par kluczy Ed25519. Te adresy:

• Mają odpowiadający im klucz prywatny, który może podpisywać transakcje
• Służą jako adresy portfeli

Adresy off-curve (PDA)

Program Derived Addresses (adresy pochodne programu) są deterministycznie wyprowadzane z ID programu i seedów. Te adresy:

• Nie mają odpowiadającego im klucza prywatnego
• Mogą być podpisywane tylko przez program, z którego zostały wyprowadzone

Typy kont w płatnościach

Użyj adresu, aby pobrać konto z sieci, sprawdź właściciela programu i typ konta, aby określić, jak obsłużyć dany adres.

Konta System Program (portfele)

Konta należące do System Program to standardowe portfele. Aby wysłać tokeny SPL do portfela, należy wyznaczyć i użyć jego associated token account (ATA).

Po wyznaczeniu adresu ATA sprawdź, czy token account istnieje on-chain. Jeśli ATA nie istnieje, możesz dodać instrukcję utworzenia token account odbiorcy w tej samej transakcji co transfer. Wymaga to jednak opłacenia rent za nowe token account. Ponieważ odbiorca jest właścicielem ATA, SOL zapłacone za rent nie może zostać odzyskane przez nadawcę.

Konta tokenów

Konta tokenów są własnością Token Program lub Token-2022 Program i przechowują salda tokenów. Jeśli otrzymany adres należy do programu tokenów, należy zweryfikować, czy konto jest kontem tokena (a nie mint account) i czy odpowiada oczekiwanemu mint account tokena przed wysłaniem.

Konta mint

Konta mint śledzą podaż tokena i metadane konkretnego tokena. Konta mint są również własnością Token Programs, ale nie są prawidłowymi odbiorcami transferów tokenów. Próba wysłania tokenów na adres mint kończy się nieudaną transakcją, ale środki nie zostają utracone.

Inne konta

Konta należące do innych programów wymagają decyzji politycznej. Niektóre konta (np. portfele multisig) mogą być prawidłowymi właścicielami kont tokenów, podczas gdy inne powinny zostać odrzucone.

Przebieg weryfikacji

Poniższy diagram przedstawia przykładowe drzewo decyzyjne do weryfikacji adresu:

Demo

Poniższy przykład pokazuje wyłącznie logikę walidacji adresu. To kod referencyjny służący do celów ilustracyjnych.

Poniższa demonstracja wykorzystuje trzy możliwe wyniki:

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