Adresse verifizieren

Das Senden von Guthaben an eine falsche Adresse kann zu einem dauerhaften Verlust führen. Die Adressverifizierung stellt sicher, dass Sie und Ihre Nutzer nur an Adressen senden, die Guthaben ordnungsgemäß empfangen und darauf zugreifen können. Wenn Sie eine Börse betreiben, wird empfohlen, diese Prüfungen durchzuführen und den Nutzer die Adresse vor dem Senden verifizieren zu lassen.

Die Validierung hängt davon ab, was Sie senden:

• SPL-Token sind teilweise selbstschützend. Das Token Program lehnt eine Überweisung ab, bei der die Konten nicht mit der erwarteten Mint übereinstimmen, sodass eine fehlgeleitete Token-Überweisung fehlschlägt, ohne dass Gelder verloren gehen. Der Großteil dieser Seite behandelt SPL-Token-Sendungen.
• Natives SOL verfügt über keinen solchen Schutz. Eine System Program-Überweisung gelingt in jedes Konto, sodass ein falscher Empfänger das SOL dauerhaft sperrt. Siehe Natives SOL senden.

Solana-Adressen verstehen

Solana-Konten haben zwei Arten von Adressen: On-Curve und Off-Curve.

On-Curve-Adressen

Standardadressen sind die öffentlichen Schlüssel aus Ed25519-keypairs. Diese Adressen:

• Haben einen entsprechenden privaten Schlüssel, der Transaktionen signieren kann
• Werden als Wallet-Adressen verwendet

Off-Curve-Adressen (PDAs)

Program Derived Addresses werden deterministisch aus einer Programm-ID und Seeds abgeleitet. Diese Adressen:

• Haben keinen entsprechenden privaten Schlüssel
• Können nur vom Programm signiert werden, aus dem die Adresse abgeleitet wurde

Programmgesteuerte Wallets, die allgemein als Smart Wallets oder Smart Accounts bezeichnet werden, haben Off-Curve-Adressen. In diesem Leitfaden wird durchgehend der Begriff „Smart Wallet“ verwendet.

Kontotypen bei Zahlungen

Verwenden Sie die Adresse, um ein Konto aus dem Netzwerk abzurufen, und überprüfen Sie den Programmeigentümer sowie den Kontotyp, um zu bestimmen, wie die Adresse zu behandeln ist.

System Program Konten (Wallets)

Konten, die dem System Program gehören, sind Standard-Wallets. Um SPL-Token an eine Wallet zu senden, leiten Sie die zugehörige Associated Token Account (ATA) ab und verwenden Sie diese.

Nach dem Ableiten der ATA-Adresse prüfen Sie, ob das token account bereits onchain existiert. Falls die ATA nicht existiert, können Sie eine Anweisung zum Erstellen des token account des Empfängers in dieselbe Transaktion wie die Überweisung aufnehmen. Dies erfordert jedoch die Zahlung von rent für das neue token account. Da der Empfänger die ATA besitzt, kann der für die rent gezahlte SOL vom Sender nicht zurückgefordert werden.

System-Konten können Off-Curve existieren. Wenn Ihr Nutzer Token an eine Off-Curve-Adresse senden möchte, wird empfohlen, den Nutzer aufzufordern zu bestätigen, dass er beabsichtigt, Guthaben an eine Smart Wallet zu senden.

Token Accounts

Token accounts gehören dem Token Program oder Token-2022 Program und speichern Token-Guthaben. Wenn die Adresse, die Sie erhalten, einem Token-Programm gehört, sollten Sie überprüfen, ob das Konto ein token account ist (kein mint account) und mit dem erwarteten token mint account übereinstimmt, bevor Sie senden.

Mint Accounts

Mint accounts verfolgen das Token-Angebot und die Metadaten eines bestimmten Tokens. Mint accounts gehören ebenfalls Token Programs, sind aber keine gültigen Empfänger für Token-Überweisungen. Der Versuch, Token an eine Mint-Adresse zu senden, führt zu einer fehlgeschlagenen Transaktion, es gehen jedoch keine Mittel verloren.

Andere Konten

Konten, die anderen Programmen gehören, sind gültig, unterliegen jedoch den Berechtigungsregeln des jeweiligen besitzenden Programms. Es wird empfohlen, den Nutzer aufzufordern zu bestätigen, dass er beabsichtigt, Guthaben an eine Smart Wallet zu senden.

Natives SOL senden

Die obige Klassifizierung bestimmt, wohin SPL-Token gesendet werden können. Natives SOL ist strenger: Der einzige sichere Empfänger ist eine System Program-Wallet (oder eine nicht finanzierte On-Curve-Adresse, die zu einer wird).

Eine System Program-Überweisung fügt lamports zu jedem Konto hinzu, einschließlich Mints, token accounts, Programmen und PDAs. Lamports können nur vom eigenen Programm des Kontos abgebucht werden. Daher kann das Senden von SOL an einen falschen Empfänger dazu führen, dass Gelder dauerhaft verloren gehen.

Im Gegensatz zu einer SPL-Token-Überweisung schlägt die Transaktion nicht fehl, wenn der Empfänger eine unerwartete Adresse ist.

Beim Senden von nativem SOL ist nur ein IS_WALLET-Ergebnis akzeptabel. IS_TOKEN_ACCOUNT ist es nicht: Ein token account enthält SPL-Token, und dorthin gesendetes SOL liegt außerhalb der Kontrolle des Absenders.

Verifizierungsablauf

Das folgende Diagramm zeigt einen Referenz-Entscheidungsbaum zur Validierung einer Adresse:

Demo

Das folgende Beispiel zeigt nur die Adressvalidierungslogik. Dies ist Referenzcode zu Illustrationszwecken.

Die folgende Demo verwendet drei mögliche Ergebnisse:

Anschließend ordnet es jedem Ergebnis die asset-spezifische Empfangbarkeit mit canReceiveNativeSol (nur Wallets) und canReceiveSplToken (Wallets oder token accounts) zu. Ein USER_VERIFICATION-Ergebnis wird nicht automatisch akzeptiert; Ihre Anwendung sollte den Nutzer seine Absicht bestätigen lassen, bevor SPL-Token gesendet werden. Ein token account gibt IS_TOKEN_ACCOUNT zurück und kann daher SPL-Token, aber kein natives SOL empfangen – die Unterscheidung, die verhindert, dass SOL gesperrt wird.

/**
 * Validates an input address and classifies it as a wallet, token account,
 * address requiring recipient verification, 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
 *   - USER_VERIFICATION: Require explicit review before sending SPL tokens
 *   - 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 onchain
  if (!account.exists) {
    // An unfunded PDA may belong to a smart wallet, but the address
    // alone cannot prove that its program can access a newly-created ATA.
    if (isOffCurveAddress(inputAddress)) {
      return {
        type: "USER_VERIFICATION",
        reason:
          "Unfunded PDA: confirm the recipient is using a smart wallet and controls this address"
      };
    }
    // On-curve = valid keypair address, treat as unfunded wallet
    return { type: "IS_WALLET" };
  }

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

  // A System Program account can be a standard wallet or an off-curve smart
  // wallet. Require verification before automatically sending to the
  // latter.
  if (owner === SYSTEM_PROGRAM) {
    if (isOffCurveAddress(inputAddress)) {
      return {
        type: "USER_VERIFICATION",
        reason:
          "Off-curve System Program account: confirm recipient is using a smart wallet"
      };
    }
    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"
    };
  }

  // An account owned by another program can be a smart wallet.
  return {
    type: "USER_VERIFICATION",
    reason:
      "Program-owned account: confirm the recipient is using a smart wallet"
  };
}

/**
 * Native SOL is only safe to send to a wallet. Any other account locks it.
 */
function canReceiveNativeSol(result: ValidationResult): boolean {
  return result.type === "IS_WALLET";
}

/**
 * SPL tokens can go to a wallet (via its ATA) or directly to a token account.
 */
function canReceiveSplToken(result: ValidationResult): boolean {
  return result.type === "IS_WALLET" || result.type === "IS_TOKEN_ACCOUNT";
}

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

/**
 * Validates an input address and classifies it as a wallet, token account,
 * address requiring recipient verification, 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
 *   - USER_VERIFICATION: Require explicit review before sending SPL tokens
 *   - 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 onchain
  if (!account.exists) {
    // An unfunded PDA may belong to a smart wallet, but the address
    // alone cannot prove that its program can access a newly-created ATA.
    if (isOffCurveAddress(inputAddress)) {
      return {
        type: "USER_VERIFICATION",
        reason:
          "Unfunded PDA: confirm the recipient is using a smart wallet and controls this address"
      };
    }
    // On-curve = valid keypair address, treat as unfunded wallet
    return { type: "IS_WALLET" };
  }

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

  // A System Program account can be a standard wallet or an off-curve smart
  // wallet. Require verification before automatically sending to the
  // latter.
  if (owner === SYSTEM_PROGRAM) {
    if (isOffCurveAddress(inputAddress)) {
      return {
        type: "USER_VERIFICATION",
        reason:
          "Off-curve System Program account: confirm recipient is using a smart wallet"
      };
    }
    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"
    };
  }

  // An account owned by another program can be a smart wallet.
  return {
    type: "USER_VERIFICATION",
    reason:
      "Program-owned account: confirm the recipient is using a smart wallet"
  };
}

/**
 * Native SOL is only safe to send to a wallet. Any other account locks it.
 */
function canReceiveNativeSol(result: ValidationResult): boolean {
  return result.type === "IS_WALLET";
}

/**
 * SPL tokens can go to a wallet (via its ATA) or directly to a token account.
 */
function canReceiveSplToken(result: ValidationResult): boolean {
  return result.type === "IS_WALLET" || result.type === "IS_TOKEN_ACCOUNT";
}

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