Xác minh địa chỉ

Gửi tiền đến địa chỉ sai có thể dẫn đến mất vĩnh viễn. Xác minh địa chỉ đảm bảo bạn chỉ gửi đến các địa chỉ có thể nhận và truy cập đúng cách các khoản tiền đó.

Việc xác thực phụ thuộc vào những gì bạn gửi:

• Token SPL có khả năng tự bảo vệ một phần. Token Program từ chối giao dịch chuyển tiền khi các tài khoản không khớp với mint mong đợi, vì vậy một giao dịch token bị chuyển nhầm sẽ thất bại mà không mất tiền. Hầu hết trang này đề cập đến việc gửi token SPL.
• SOL gốc không có biện pháp bảo vệ như vậy. Giao dịch chuyển tiền qua System Program thành công vào bất kỳ tài khoản nào, vì vậy một người nhận không đúng sẽ khóa vĩnh viễn SOL đó. Xem Gửi SOL gốc.

Hiểu về Địa Chỉ Solana

Tài khoản Solana có hai loại địa chỉ: trên đường cong và ngoài đường cong.

Địa Chỉ Trên Đường Cong

Địa chỉ tiêu chuẩn là các khóa công khai từ các keypair Ed25519. Các địa chỉ này:

• Có khóa riêng tư tương ứng có thể ký giao dịch
• Được sử dụng làm địa chỉ ví

Địa Chỉ Ngoài Đường Cong (PDA)

Program Derived Address được suy ra một cách xác định từ ID chương trình và các seed. Các địa chỉ này:

• Không có khóa riêng tư tương ứng
• Chỉ có thể được ký bởi chương trình mà địa chỉ đó được suy ra từ đó

Các Loại Tài Khoản trong Thanh Toán

Sử dụng địa chỉ để truy xuất một tài khoản từ mạng, kiểm tra chủ sở hữu chương trình và loại tài khoản để xác định cách xử lý địa chỉ đó.

Tài Khoản System Program (Ví)

Các tài khoản thuộc sở hữu của System Program là các ví tiêu chuẩn. Để gửi SPL token đến một ví, bạn cần tạo và sử dụng Associated Token Account (ATA) của ví đó.

Sau khi tạo địa chỉ ATA, hãy kiểm tra xem token account đó có tồn tại trên chuỗi hay không. Nếu ATA chưa tồn tại, bạn có thể đưa thêm một lệnh để tạo token account cho người nhận trong cùng một giao dịch với lệnh chuyển. Tuy nhiên, điều này yêu cầu phải trả rent cho token account mới. Vì người nhận sở hữu ATA, số SOL đã trả cho rent sẽ không thể được người gửi thu hồi lại.

Token Accounts

Token accounts thuộc sở hữu của Token Program hoặc Token-2022 Program và lưu trữ số dư token. Nếu địa chỉ bạn nhận được thuộc sở hữu của một token program, bạn nên xác minh rằng tài khoản đó là một token account (không phải mint account) và khớp với mint account token dự kiến trước khi gửi.

Mint Accounts

Mint accounts theo dõi nguồn cung token và siêu dữ liệu của một token cụ thể. Mint accounts cũng thuộc sở hữu của Token Programs nhưng không phải là người nhận hợp lệ cho các giao dịch chuyển token. Việc cố gắng gửi token đến một địa chỉ mint sẽ dẫn đến giao dịch thất bại, nhưng không có khoản tiền nào bị mất.

Các Tài Khoản Khác

Các tài khoản thuộc sở hữu của các chương trình khác đòi hỏi một quyết định về chính sách. Một số tài khoản (ví dụ: ví multisig) có thể là chủ sở hữu token account hợp lệ, trong khi một số khác nên bị từ chối.

Gửi SOL Gốc

Phân loại ở trên xác định nơi token SPL có thể đến. SOL gốc thì chặt chẽ hơn: người nhận an toàn duy nhất là ví System Program (hoặc một địa chỉ trên đường cong chưa được cấp vốn mà sẽ trở thành một ví như vậy).

Một lệnh chuyển System Program thêm lamport vào bất kỳ tài khoản nào, bao gồm các mint, token accounts, chương trình và PDA. Lamport chỉ có thể được rút ra bởi program account sở hữu tài khoản đó, vì vậy việc gửi SOL đến người nhận không đúng có thể dẫn đến việc tiền bị mất vĩnh viễn.

Không giống như lệnh chuyển token SPL, giao dịch không thất bại khi người nhận là một địa chỉ không mong đợi.

Khi gửi SOL gốc, chỉ kết quả IS_WALLET mới được chấp nhận. IS_TOKEN_ACCOUNT thì không: một token account chứa token SPL, và SOL được gửi đến đó nằm ngoài tầm kiểm soát của người gửi.

Luồng Xác Minh

Sơ đồ sau đây hiển thị một cây quyết định tham chiếu để xác thực một địa chỉ:

Demo

Ví dụ sau đây chỉ hiển thị logic xác thực địa chỉ. Đây là mã tham khảo dùng cho mục đích minh họa.

Demo dưới đây sử dụng ba kết quả có thể xảy ra:

Sau đó, nó ánh xạ từng kết quả sang khả năng chấp nhận theo từng tài sản với canReceiveNativeSol (chỉ ví) và canReceiveSplToken (ví hoặc associated token account). Một token account trả về IS_TOKEN_ACCOUNT, do đó nó có thể nhận SPL token nhưng không thể nhận SOL gốc — sự phân biệt giúp ngăn SOL bị khóa.

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