Επαλήθευση διεύθυνσης

Η αποστολή κεφαλαίων σε λάθος διεύθυνση μπορεί να οδηγήσει σε μόνιμη απώλεια. Η επαλήθευση διεύθυνσης διασφαλίζει ότι εσείς και οι χρήστες σας αποστέλλετε μόνο σε διευθύνσεις που μπορούν να λάβουν και να αποκτήσουν πρόσβαση στα κεφάλαια. Εάν διαχειρίζεστε ένα ανταλλακτήριο, συνιστάται να εκτελείτε αυτούς τους ελέγχους και να ζητάτε από τον χρήστη να επαληθεύει τη διεύθυνση πριν από την αποστολή.

Η επικύρωση εξαρτάται από το τι στέλνετε:

• Τα SPL tokens προστατεύονται εν μέρει από μόνα τους. Το Token Program απορρίπτει μια μεταφορά της οποίας οι λογαριασμοί δεν αντιστοιχούν στο αναμενόμενο mint, οπότε μια λανθασμένα κατευθυνόμενη μεταφορά token αποτυγχάνει χωρίς απώλεια κεφαλαίων. Το μεγαλύτερο μέρος αυτής της σελίδας καλύπτει αποστολές SPL token.
• Το εγγενές SOL δεν έχει τέτοια προστασία. Μια μεταφορά System Program επιτυγχάνει σε οποιονδήποτε λογαριασμό, οπότε ένας λανθασμένος παραλήπτης κλειδώνει οριστικά το SOL. Δείτε Αποστολή εγγενούς SOL.

Κατανόηση των Διευθύνσεων Solana

Οι λογαριασμοί Solana έχουν δύο τύπους διευθύνσεων: επί καμπύλης και εκτός καμπύλης.

Διευθύνσεις Επί Καμπύλης

Οι τυπικές διευθύνσεις είναι τα δημόσια κλειδιά από Ed25519 keypairs. Αυτές οι διευθύνσεις:

• Διαθέτουν αντίστοιχο ιδιωτικό κλειδί που μπορεί να υπογράφει συναλλαγές
• Χρησιμοποιούνται ως διευθύνσεις πορτοφολιού

Διευθύνσεις Εκτός Καμπύλης (PDAs)

Τα Program Derived Addresses παράγονται ντετερμινιστικά από ένα αναγνωριστικό προγράμματος και seeds. Αυτές οι διευθύνσεις:

• Δεν διαθέτουν αντίστοιχο ιδιωτικό κλειδί
• Μπορούν να υπογραφούν μόνο από το πρόγραμμα από το οποίο παράχθηκε η διεύθυνση

Τα πορτοφόλια ελεγχόμενα από πρόγραμμα, γνωστά συνήθως ως έξυπνα πορτοφόλια ή έξυπνοι λογαριασμοί, έχουν διευθύνσεις εκτός καμπύλης. Αυτός ο οδηγός χρησιμοποιεί τον όρο "smart wallet" καθ' όλη τη διάρκειά του.

Τύποι Λογαριασμών στις Πληρωμές

Χρησιμοποιήστε τη διεύθυνση για να ανακτήσετε έναν λογαριασμό από το δίκτυο, ελέγξτε τον κάτοχο προγράμματος και τον τύπο λογαριασμού για να προσδιορίσετε πώς να χειριστείτε τη διεύθυνση.

Λογαριασμοί System Program (Πορτοφόλια)

Οι λογαριασμοί που ανήκουν στο System Program είναι τυπικά πορτοφόλια. Για να στείλετε SPL tokens σε ένα πορτοφόλι, παράγετε και χρησιμοποιείτε το Associated Token Account (ATA) του.

Αφού παράγετε τη διεύθυνση ATA, ελέγξτε αν το token account υπάρχει στο onchain. Αν το ATA δεν υπάρχει, μπορείτε να συμπεριλάβετε μια εντολή για τη δημιουργία του token account του παραλήπτη στην ίδια συναλλαγή με τη μεταφορά. Ωστόσο, αυτό απαιτεί την πληρωμή rent για το νέο token account. Καθώς ο παραλήπτης κατέχει το ATA, το SOL που καταβλήθηκε για το rent δεν μπορεί να ανακτηθεί από τον αποστολέα.

Οι λογαριασμοί συστήματος μπορούν να υπάρχουν εκτός καμπύλης. Εάν ο χρήστης σας επιθυμεί να αποστείλει tokens σε διεύθυνση εκτός καμπύλης, συνιστάται να του ζητήσετε να επαληθεύσει ότι σκοπεύει να στείλει κεφάλαια σε ένα smart wallet.

Token Accounts

Τα token accounts ανήκουν στο Token Program ή Token-2022 Program και αποθηκεύουν υπόλοιπα tokens. Αν η διεύθυνση που λαμβάνετε ανήκει σε ένα token program, θα πρέπει να επαληθεύσετε ότι ο λογαριασμός είναι ένα token account (όχι ένα mint account) και ότι αντιστοιχεί στο αναμενόμενο token mint account πριν αποστείλετε.

Mint Accounts

Τα mint accounts παρακολουθούν την προσφορά tokens και τα μεταδεδομένα ενός συγκεκριμένου token. Τα mint accounts ανήκουν επίσης στα Token Programs, αλλά δεν αποτελούν έγκυρους παραλήπτες για μεταφορές tokens. Η προσπάθεια αποστολής tokens σε μια διεύθυνση mint οδηγεί σε αποτυχημένη συναλλαγή, αλλά δεν χάνονται κεφάλαια.

Άλλοι Λογαριασμοί

Οι λογαριασμοί που ανήκουν σε άλλα προγράμματα είναι έγκυροι, αλλά διέπονται από τους κανόνες εξουσιοδότησης που ορίζει το αντίστοιχο κατέχον πρόγραμμα. Συνιστάται να ζητάτε από τον χρήστη να επαληθεύσει ότι σκοπεύει να στείλει κεφάλαια σε ένα smart wallet.

Αποστολή εγγενούς SOL

Η παραπάνω κατηγοριοποίηση καθορίζει πού μπορούν να μεταφερθούν τα SPL tokens. Το εγγενές SOL είναι πιο αυστηρό: ο μόνος ασφαλής παραλήπτης είναι ένα πορτοφόλι System Program (ή μια αχρησιμοποίητη διεύθυνση επί καμπύλης που γίνεται τέτοια).

Μια μεταφορά System Program προσθέτει lamport σε οποιονδήποτε λογαριασμό, συμπεριλαμβανομένων των mints, token accounts, προγραμμάτων και PDAs. Τα lamport μπορούν να μετακινηθούν μόνο από το πρόγραμμα ιδιοκτησίας του λογαριασμού, επομένως η αποστολή SOL σε λανθασμένο παραλήπτη μπορεί να οδηγήσει σε μόνιμη απώλεια κεφαλαίων.

Σε αντίθεση με τη μεταφορά SPL token, η συναλλαγή δεν αποτυγχάνει όταν ο παραλήπτης είναι μια μη αναμενόμενη διεύθυνση.

Κατά την αποστολή εγγενούς SOL, μόνο ένα αποτέλεσμα IS_WALLET είναι αποδεκτό. Το IS_TOKEN_ACCOUNT δεν είναι: ένα token account διατηρεί SPL tokens, και το SOL που αποστέλλεται εκεί βρίσκεται εκτός του ελέγχου του αποστολέα.

Ροή Επαλήθευσης

Το παρακάτω διάγραμμα δείχνει ένα δέντρο αποφάσεων αναφοράς για την επικύρωση μιας διεύθυνσης:

Demo

Το παρακάτω παράδειγμα εμφανίζει μόνο τη λογική επαλήθευσης διευθύνσεων. Αυτός είναι κώδικας αναφοράς για λόγους επεξήγησης.

Το demo παρακάτω χρησιμοποιεί τρία πιθανά αποτελέσματα:

Στη συνέχεια, αντιστοιχίζει κάθε αποτέλεσμα στην αποδεκτότητα ανά περιουσιακό στοιχείο με canReceiveNativeSol (μόνο για πορτοφόλια) και canReceiveSplToken (πορτοφόλια ή token accounts). Ένα αποτέλεσμα USER_VERIFICATION δεν γίνεται αυτόματα αποδεκτό· η εφαρμογή σας θα πρέπει να ζητά από τον χρήστη να επιβεβαιώσει την πρόθεσή του πριν από την αποστολή SPL tokens. Ένα token account επιστρέφει IS_TOKEN_ACCOUNT, οπότε μπορεί να λάβει SPL tokens αλλά όχι εγγενή SOL — η διάκριση που αποτρέπει το κλείδωμα του SOL.

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