Osoitteen vahvistaminen

Varojen lähettäminen väärään osoitteeseen voi johtaa pysyvään menetykseen. Osoitteen varmennus varmistaa, että sinä ja käyttäjäsi lähetätte varoja vain osoitteisiin, jotka voivat asianmukaisesti vastaanottaa ja käyttää varoja. Jos ylläpidät pörssiä, on suositeltavaa suorittaa nämä tarkistukset ja pyytää käyttäjää vahvistamaan osoite ennen lähettämistä.

Validointi riippuu siitä, mitä lähetät:

• SPL-tokenit ovat osittain itsensä suojaavia. Token Program hylkää siirron, jonka tilit eivät vastaa odotettua rahapajaa, joten väärin kohdistettu token- siirto epäonnistuu ilman varojen menetystä. Suurin osa tästä sivusta käsittelee SPL-tokenien lähetystä.
• Natiivilla SOL:lla ei ole tällaista suojaa. System Program -siirto onnistuu mille tahansa tilille, joten väärä vastaanottaja lukitsee SOL:n pysyvästi. Katso Natiivin SOL:n lähettäminen.

Solana-osoitteiden ymmärtäminen

Solana-tileillä on kahdenlaisia osoitteita: käyrällä olevat ja käyrän ulkopuoliset.

Käyrällä olevat osoitteet

Vakio-osoitteet ovat julkisia avaimia Ed25519 keypair -pareista. Nämä osoitteet:

• Sisältävät vastaavan yksityisen avaimen, joka voi allekirjoittaa transaktioita
• Niitä käytetään lompakko-osoitteina

Käyrän ulkopuoliset osoitteet (PDA:t)

Program Derived Addresses johdetaan deterministisesti ohjelman tunnuksesta ja siemenistä. Nämä osoitteet:

• Eivät omaa vastaavaa yksityistä avainta
• Vain ohjelma, josta osoite on johdettu, voi allekirjoittaa niiden puolesta

Ohjelmaohjatut lompakot, joihin viitataan yleisesti älykkäinä lompakkoina tai älykkäinä tileinä, ovat off-curve-osoitteita. Tässä oppaassa käytetään termiä "älylompakko" läpi koko oppaan.

Tilityypit maksuissa

Käytä osoitetta hakeaksesi tilin verkosta, tarkista sen ohjelman omistaja ja tilityyppi määrittääksesi, kuinka osoitetta käsitellään.

System Program -tilit (lompakot)

System Program -omistamat tilit ovat tavallisia lompakoita. Lähettääksesi SPL-tokeneita lompakkoon, johdat ja käytät sen Associated Token Account (ATA) -tiliä.

ATA-osoitteen johtamisen jälkeen tarkista, onko token account olemassa onchainissa. Jos ATA ei ole olemassa, voit sisällyttää saman transaktion yhteyteen ohjeen vastaanottajan token accountin luomiseksi. Tämä kuitenkin edellyttää rent-maksun suorittamista uudelle token accountille. Koska vastaanottaja omistaa ATA:n, lähettäjä ei voi palauttaa rent-maksuna maksettua SOL:ia.

Järjestelmätilit voivat olla olemassa off-curve-muodossa. Jos käyttäjäsi haluaa lähettää tokeneita off-curve-osoitteeseen, on suositeltavaa kehottaa käyttäjää vahvistamaan, että hän aikoo lähettää varoja älykkääseen lompakkoon.

Token Accountit

Token accountit ovat Token Program- tai Token-2022 Program -ohjelmien omistamia ja pitävät sisällään token-saldot. Jos vastaanottamasi osoite on token-ohjelman omistama, sinun tulee varmistaa, että tili on token account (ei mint account) ja vastaa odotettua token mint accountia ennen lähettämistä.

Mint Accountit

Mint accountit seuraavat tietyn tokenin tarjontaa ja metatietoja. Mint accountit ovat myös Token Programs -ohjelmien omistamia, mutta ne eivät ole kelvollisia vastaanottajia token-siirroille. Tokenien lähettäminen mint-osoitteeseen johtaa epäonnistuneeseen transaktioon, mutta varoja ei menetetä.

Muut tilit

Muiden ohjelmien omistamat tilit ovat kelvollisia, mutta niitä hallitsevat kyseisen omistajaohjelman asettamat auktoriteettisäännöt. On suositeltavaa kehottaa käyttäjää vahvistamaan, että hän aikoo lähettää varoja älykkääseen lompakkoon.

Natiivin SOL:n lähettäminen

Yllä oleva luokittelu määrittää, minne SPL-tokenit voivat mennä. Natiivi SOL on tiukempi: ainoa turvallinen vastaanottaja on System Program -lompakko (tai rahoittamaton käyrällä oleva osoite, josta sellainen tulee).

System Program -siirto lisää lamport-yksiköitä mille tahansa tilille, mukaan lukien mintit, token accountit, ohjelmat ja PDA:t. Lamporteja voi siirtää pois vain tilin omistavan ohjelman kautta, joten SOL:n lähettäminen väärään vastaanottajaosoitteeseen voi johtaa varojen pysyvään menetykseen.

Toisin kuin SPL-tokenisiirto, transaktio ei epäonnistu, kun vastaanottaja on odottamaton osoite.

Natiivia SOL:a lähetettäessä hyväksyttävä tulos on vain IS_WALLET. IS_TOKEN_ACCOUNT ei ole: token account sisältää SPL-tokeneita, ja sinne lähetetty SOL on lähettäjän hallinnan ulkopuolella.

Vahvistusprosessi

Seuraava kaavio näyttää viitemuotoisen päätöspuun osoitteen vahvistamiseksi:

Demo

Seuraava esimerkki näyttää ainoastaan osoitteen validointilogiikan. Tämä on viitekoodi havainnollistamista varten.

Demo alla käyttää kolmea mahdollista lopputulosta:

Se sitten kartoittaa jokaisen tuloksen omaisuuskohtaiseen hyväksyttävyyteen canReceiveNativeSol-arvolla (vain lompakot) ja canReceiveSplToken-arvolla (lompakot tai token accountit). USER_VERIFICATION-tulosta ei hyväksytä automaattisesti; sovelluksesi tulee pyytää käyttäjää vahvistamaan aikomuksensa ennen SPL-tokenien lähettämistä. Token account palauttaa IS_TOKEN_ACCOUNT, joten se voi vastaanottaa SPL-tokeneita, mutta ei nativia SOL — tämä ero estää SOL:n lukittumisen.

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