Adres verifiëren

Fondsen naar het verkeerde adres sturen kan leiden tot permanent verlies. Adresverificatie zorgt ervoor dat jij en je gebruikers alleen naar adressen sturen die de fondsen correct kunnen ontvangen en openen. Als je een exchange beheert, wordt het aanbevolen om deze controles uit te voeren en je gebruiker het adres te laten verifiëren voordat er verzonden wordt.

Validatie hangt af van wat je verstuurt:

• SPL-tokens zijn deels zelfbeschermend. Het Token Program weigert een overdracht waarvan de accounts niet overeenkomen met de verwachte mint, waardoor een verkeerd gerichte tokenoverdracht mislukt zonder fondsen te verliezen. Het grootste deel van deze pagina behandelt het versturen van SPL-tokens.
• Natieve SOL heeft geen dergelijke beveiliging. Een System Program-overdracht slaagt naar elk account, dus een onjuiste ontvanger vergrendelt de SOL permanent. Zie Natieve SOL versturen.

Solana-adressen begrijpen

Solana-accounts hebben twee soorten adressen: on-curve en off-curve.

On-Curve-adressen

Standaardadressen zijn de publieke sleutels van Ed25519 keypairs. Deze adressen:

• Hebben een bijbehorende privésleutel die transacties kan ondertekenen
• Worden gebruikt als walletadressen

Off-Curve-adressen (PDA's)

Program Derived Addresses worden deterministisch afgeleid van een programma-ID en seeds. Deze adressen:

• Hebben geen bijbehorende privésleutel
• Kunnen alleen worden ondertekend door het programma waarvan het adres is afgeleid

Door programma's beheerde wallets, vaak aangeduid als smart wallets of smart accounts, hebben off-curve adressen. Deze handleiding gebruikt de term "smart wallet" door de hele tekst.

Accounttypen bij betalingen

Gebruik het adres om een account op te halen uit het netwerk, controleer de programma-eigenaar en het accounttype om te bepalen hoe het adres verwerkt moet worden.

System Program Accounts (Wallets)

Accounts die eigendom zijn van het System Program zijn standaard wallets. Om SPL-tokens naar een wallet te sturen, gebruik je het bijbehorende Associated Token Account (ATA).

Nadat je het ATA-adres hebt afgeleid, controleer je of het token account onchain bestaat. Als het ATA niet bestaat, kun je een instructie toevoegen om het token account van de ontvanger aan te maken in dezelfde transactie als de overdracht. Dit vereist echter het betalen van rent voor het nieuwe token account. Omdat de ontvanger eigenaar is van de ATA, kan de SOL die voor de rent is betaald niet worden teruggevorderd door de afzender.

Systeemaccounts kunnen off-curve bestaan. Als je gebruiker tokens wil sturen naar een off-curve adres, wordt het aanbevolen de gebruiker te vragen te bevestigen dat ze van plan zijn fondsen naar een smart wallet te sturen.

Token Accounts

Token accounts zijn eigendom van het Token Program of Token-2022 Program en bevatten token-saldi. Als het adres dat je ontvangt eigendom is van een token program, moet je controleren of het account een token account is (geen mint account) en of het overeenkomt met het verwachte token mint account voordat je verstuurt.

Mint Accounts

Mint accounts houden de tokenvoorraad en metadata van een specifiek token bij. Mint accounts zijn ook eigendom van Token Programs, maar zijn geen geldige ontvangers voor token-overdrachten. Proberen tokens te sturen naar een mint-adres resulteert in een mislukte transactie, maar er gaan geen fondsen verloren.

Andere Accounts

Accounts die eigendom zijn van andere programma's zijn geldig, maar worden beheerst door de autorisatieregels die zijn vastgesteld door het respectieve eigenaarsprogramma. Het wordt aanbevolen de gebruiker te vragen te bevestigen dat ze van plan zijn fondsen naar een smart wallet te sturen.

Native SOL versturen

De bovenstaande classificatie bepaalt waar SPL-tokens naartoe kunnen. Native SOL is strikter: de enige veilige ontvanger is een System Program-wallet (of een niet-gefinancierd on-curve-adres dat er een wordt).

Een System Program-overdracht voegt lamports toe aan elk account, inclusief mints, token accounts, programma's en PDA's. Lamports kunnen alleen worden verplaatst door het eigendomsprogramma van het account, dus het versturen van SOL naar een onjuiste ontvanger kan ertoe leiden dat fondsen permanent verloren gaan.

Anders dan bij een SPL-tokenoverdracht mislukt de transactie niet wanneer de ontvanger een onverwacht adres is.

Bij het versturen van native SOL is alleen een IS_WALLET-resultaat acceptabel. IS_TOKEN_ACCOUNT is niet acceptabel: een token account bevat SPL-tokens, en SOL dat daarheen wordt gestuurd valt buiten de controle van de verzender.

Verificatiestroom

Het volgende diagram toont een referentiebeslisboom voor het valideren van een adres:

Demo

Het volgende voorbeeld toont alleen de logica voor adresvalidatie. Dit is referentiecode ter illustratie.

De onderstaande demo gebruikt drie mogelijke uitkomsten:

Vervolgens wordt elk resultaat gekoppeld aan acceptabiliteit per activum met canReceiveNativeSol (alleen wallets) en canReceiveSplToken (wallets of token accounts). Een USER_VERIFICATION-resultaat wordt niet automatisch geaccepteerd; je applicatie moet een gebruiker hun intentie laten bevestigen voordat SPL-tokens worden verzonden. Een token account geeft IS_TOKEN_ACCOUNT terug, zodat het SPL-tokens kan ontvangen maar geen native SOL — het onderscheid dat voorkomt dat SOL wordt vergrendeld.

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