Osoitteen vahvistaminen

Varojen lähettäminen väärään osoitteeseen voi johtaa pysyvään menetykseen. Osoitteen varmennus varmistaa, että lähetät vain osoitteisiin, jotka voivat asianmukaisesti vastaanottaa ja käyttää varoja.

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

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.

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 edellyttävät käytäntöpäätöstä. Jotkut tilit (esim. multisig-lompakot) voivat olla kelvollisia token account -omistajia, kun taas toiset tulisi hylätä.

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 omaisuuserän hyväksyttävyyteen canReceiveNativeSol (vain lompakot) ja canReceiveSplToken (lompakot tai token accounts). Token account palauttaa IS_TOKEN_ACCOUNT, joten se voi vastaanottaa SPL-tokeneita, mutta ei natiiveja SOL — tämä ero estää SOL:n lukittumisen.

/**
 * 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 onchain
  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" };
}

/**
 * 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, 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 onchain
  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" };
}

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