Vérifier une adresse

Envoyer des fonds à une mauvaise adresse peut entraîner une perte définitive. La vérification des adresses garantit que vous et vos utilisateurs n'envoyez des fonds qu'à des adresses capables de les recevoir et d'y accéder correctement. Si vous exploitez une plateforme d'échange, il est recommandé d'effectuer ces vérifications et de demander à vos utilisateurs de confirmer l'adresse avant d'envoyer.

La validation dépend de ce que vous envoyez :

• Les tokens SPL sont partiellement auto-protégés. Le Token Program rejette un transfert dont les comptes ne correspondent pas au mint attendu, de sorte qu'un transfert de token mal dirigé échoue sans perte de fonds. La majeure partie de cette page concerne les envois de tokens SPL.
• Le SOL natif ne dispose pas d'une telle protection. Un transfert via le System Program réussit vers n'importe quel compte, donc un destinataire incorrect verrouille définitivement le SOL. Voir Envoyer du SOL natif.

Comprendre les adresses Solana

Les comptes Solana ont deux types d'adresses : sur la courbe et hors courbe.

Adresses sur la courbe

Les adresses standard sont les clés publiques issues de keypairs Ed25519. Ces adresses :

• Possèdent une clé privée correspondante capable de signer des transactions
• Sont utilisées comme adresses de portefeuille

Adresses hors courbe (PDAs)

Les Program Derived Addresses sont dérivées de manière déterministe à partir d'un identifiant de programme et de seeds. Ces adresses :

• Ne possèdent pas de clé privée correspondante
• Ne peuvent être signées que par le programme dont elles sont dérivées

Les portefeuilles contrôlés par des programmes, communément appelés smart wallets ou smart accounts, possèdent des adresses hors courbe. Ce guide utilise le terme "smart wallet" tout au long du document.

Types de comptes dans les paiements

Utilisez l'adresse pour récupérer un compte depuis le réseau, vérifiez son propriétaire de programme et le type de compte pour déterminer comment traiter l'adresse.

Comptes System Program (Portefeuilles)

Les comptes appartenant au System Program sont des portefeuilles standard. Pour envoyer des tokens SPL à un portefeuille, vous dérivez et utilisez son Associated Token Account (ATA).

Après avoir dérivé l'adresse ATA, vérifiez si le token account existe sur la blockchain. Si l'ATA n'existe pas, vous pouvez inclure une instruction pour créer le token account du destinataire dans la même transaction que le transfert. Cependant, cela nécessite de payer le rent pour le nouveau token account. Étant donné que le destinataire est propriétaire de l'ATA, le SOL payé pour le rent ne peut pas être récupéré par l'expéditeur.

Les comptes système peuvent exister hors courbe. Si votre utilisateur souhaite envoyer des tokens à une adresse hors courbe, il est recommandé de l'inviter à vérifier qu'il a bien l'intention d'envoyer des fonds à un smart wallet.

Token Accounts

Les token accounts appartiennent au Token Program ou au Token-2022 Program et contiennent les soldes de tokens. Si l'adresse que vous recevez appartient à un token program, vous devez vérifier que le compte est bien un token account (et non un mint account) et qu'il correspond au mint account du token attendu avant d'envoyer.

Mint Accounts

Les mint accounts suivent l'offre en circulation et les métadonnées d'un token spécifique. Les mint accounts appartiennent également aux Token Programs, mais ne sont pas des destinataires valides pour les transferts de tokens. Tenter d'envoyer des tokens à une adresse de mint entraîne l'échec de la transaction, mais aucun fonds n'est perdu.

Autres comptes

Les comptes appartenant à d'autres programmes sont valides, mais sont régis par les règles d'autorité définies par le programme propriétaire concerné. Il est recommandé d'inviter l'utilisateur à vérifier qu'il a bien l'intention d'envoyer des fonds à un smart wallet.

Envoi de SOL natif

La classification ci-dessus détermine où les jetons SPL peuvent être envoyés. Le SOL natif est plus strict : le seul destinataire sûr est un portefeuille System Program (ou une adresse non financée sur la courbe qui en devient un).

Un transfert System Program ajoute des lamport à n'importe quel compte, y compris les mints, les token accounts, les programmes et les PDA. Les lamport ne peuvent être retirés que par le programme propriétaire du compte ; envoyer du SOL à un destinataire incorrect peut donc entraîner une perte permanente de fonds.

Contrairement à un transfert de jeton SPL, la transaction n'échoue pas lorsque le destinataire est une adresse inattendue.

Lors de l'envoi de SOL natif, seul un résultat IS_WALLET est acceptable. IS_TOKEN_ACCOUNT ne l'est pas : un token account contient des jetons SPL, et le SOL qui y est envoyé échappa au contrôle de l'expéditeur.

Flux de vérification

Le diagramme suivant présente un arbre de décision de référence pour la validation d'une adresse :

Démo

L'exemple suivant illustre uniquement la logique de validation d'adresse. Il s'agit d'un code de référence à titre d'illustration.

La démo ci-dessous utilise trois résultats possibles :

Il associe ensuite chaque résultat à l'acceptabilité par actif avec canReceiveNativeSol (portefeuilles uniquement) et canReceiveSplToken (portefeuilles ou token accounts). Un résultat USER_VERIFICATION n'est pas accepté automatiquement ; votre application doit demander à l'utilisateur de confirmer son intention avant d'envoyer des SPL tokens. Un token account retourne IS_TOKEN_ACCOUNT, ce qui lui permet de recevoir des SPL tokens mais pas du SOL natif — la distinction qui empêche le SOL d'être bloqué.

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