Hook

useRecipientValidation

Runs local recipient safety rules and inspects the real Solana account through @solana/kit RPC without requiring a wallet connection or identity provider.

Installation

terminal

$npx shadcn@latest add https://uxdotsol.xyz/r/use-recipient-validation.json

Usage

use-recipient-validation.tsx

"use client";
 
import { useRecipientValidation } from "@/hooks/uxdotsol/use-recipient-validation";
 
export function RecipientStatus({ recipient }: { recipient: string }) {
  const validation = useRecipientValidation(recipient, {
    rpcEndpoint: "https://api.devnet.solana.com",
  });
 
  return (
    <div aria-live="polite">
      <p>Status: {validation.status}</p>
      {validation.reasons.map((reason) => (
        <p key={reason.code}>{reason.message}</p>
      ))}
    </div>
  );
}

Options

Name	Type	Default	Description
recipient	string \| null \| undefined	required	Recipient address to validate. Empty input keeps the hook idle.
rpcEndpoint / connection	string / { rpcEndpoint: string } \| null	undefined	Direct RPC endpoint or a compatible wallet-adapter Connection used for the real account lookup.
sender / allowSelf	string \| { toString(): string } \| null / boolean	undefined / false	Optional sender and explicit policy for self-transfers.
requireExistingAccount / blockExecutableAccounts	boolean / boolean	false / true	Policies for new addresses and executable program accounts.
blockedAddresses / trustedAddresses	readonly string[] / readonly string[]	[] / []	Application-owned recipient policy lists.
commitment / debounceMs / enabled	Commitment / number / boolean	'confirmed' / 300 / true	RPC commitment, lookup debounce, and hook enablement.

Functions

Name	Type	Default	Description
refetch	() => void	-	Repeats the RPC lookup for the current recipient.
validateRecipientAddress	(recipient, options?) => RecipientLocalValidation	-	Runs the synchronous address, sender, trust-list, and block-list checks without React or RPC.

Types

Name	Type	Default	Description
RecipientValidationStatus	'idle' \| 'invalid' \| 'checking' \| 'safe' \| 'warning' \| 'blocked' \| 'error'	-	Small status vocabulary for recipient safety UI.
RecipientValidationReason	{ code; severity; message }	-	Explainable local or RPC signal.

Returns

Name	Type	Default	Description
status / reasons	RecipientValidationStatus / RecipientValidationReason[]	'idle' / []	Normalized result and explanations.
accountExists / executable / owner / lamports	boolean \| null / boolean \| null / string \| null / bigint \| null	null	Current account properties read from Solana RPC.
isValidAddress / isLoading / isSafe / canSubmit	boolean	false	Convenience flags for form and flow orchestration.
error	Error \| null	null	RPC lookup failure, when present.