Faucet Component

A self-contained React component for claiming testnet/devnet SOL tokens. Works with any Solana wallet library.

Installation

pnpm add @blueshift-gg/faucet-react @blueshift-gg/ui-components @tanstack/react-query

Usage

With @solana/web3.js (wallet-adapter)

import { useWallet } from "@solana/wallet-adapter-react";
import { Faucet } from "@blueshift-gg/faucet-react";

function MyApp() {
  const { publicKey, signMessage } = useWallet();

  return (
    <Faucet
      config={{
        faucetProgramId: "YOUR_FAUCET_PROGRAM_ID",
        claimAmounts: [1, 2, 5, 10],
      }}
      apiConfig={{
        baseUrl: "https://faucet-api.blueshift.gg",
        devnetRpc: "https://api.devnet.solana.com",
        testnetRpc: "https://api.testnet.solana.com",
      }}
      address={publicKey?.toBase58()}
      signMessage={signMessage}
    />
  );
}

With @solana/react (Kit)

import { useSignMessage } from "@solana/react";
import { Faucet } from "@blueshift-gg/faucet-react";

function MyApp() {
  const [account] = useContext(SelectedWalletAccountContext);
  const signMessage = useSignMessage(account!);

  return (
    <Faucet
      config={{
        faucetProgramId: "YOUR_FAUCET_PROGRAM_ID",
        claimAmounts: [1, 2, 5, 10],
      }}
      apiConfig={{
        baseUrl: "https://faucet-api.blueshift.gg",
        devnetRpc: "https://api.devnet.solana.com",
        testnetRpc: "https://api.testnet.solana.com",
      }}
      address={account?.address}
      signMessage={
        account
          ? async (msg) => (await signMessage({ message: msg })).signature
          : undefined
      }
    />
  );
}

Props

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | config | FaucetConfig | Yes | - | Faucet configuration | | apiConfig | FaucetApiConfig | No* | - | API endpoints (simplest setup) | | service | FaucetService | No* | - | Custom service (advanced) | | network | "devnet" \| "testnet" | No | "devnet" | Current network | | onNetworkChange | (network) => void | No | - | Network change callback | | address | string | No | - | Connected wallet address (base58) | | signMessage | (msg: Uint8Array) => Promise<Uint8Array> | No | - | Sign message function | | notifications | FaucetNotifications | No | Toast | Custom notification handlers | | className | string | No | - | Additional CSS classes | | showReturnSection | boolean | No | true | Show "Return SOL" section |

*Either apiConfig or service must be provided.

FaucetApiConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | baseUrl | string | Yes | Faucet API base URL | | devnetRpc | string | Yes | Devnet RPC endpoint | | testnetRpc | string | Yes | Testnet RPC endpoint |

FaucetConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | faucetProgramId | string | Yes | The faucet program address | | claimAmounts | number[] | No | Available claim amounts (default: [1,2,5,10]) | | challengeUrl | string | No | URL for eligibility challenges | | explorerBaseUrl | string | No | Explorer base URL |

FaucetService Interface

type FaucetService = {
  checkCertification: (address: string) => Promise<{ is_certified: boolean }>;
  
  getClaimStatus: (address: string) => Promise<{
    devnet: { cooldownSeconds: number };
    testnet: { cooldownSeconds: number };
  }>;
  
  submitClaim: (
    network: "devnet" | "testnet",
    address: string,
    message: string,
    signature: Uint8Array | number[],
  ) => Promise<{ signature: string }>;
  
  prepareClaimMessage: (amount: number) => {
    message: string;
    messageBytes: Uint8Array;
  };

  // Optional methods
  getFaucetBalance?: (network: "devnet" | "testnet") => Promise<{ sol: number }>;
  waitForConfirmation?: (signature: string) => Promise<{ confirmed: boolean }>;
};

Custom Notifications

By default, the component uses @blueshift-gg/ui-components Toast for notifications. You can provide your own handlers:

<Faucet
  config={config}
  service={service}
  notifications={{
    onSuccess: (title, message) => myToast.success(`${title}: ${message}`),
    onError: (title, message) => myToast.error(`${title}: ${message}`),
  }}
/>

Advanced: Using the Hook

For custom UIs, use the useFaucet hook directly:

import { useFaucet, FaucetContext } from "@blueshift-gg/faucet-react";

function CustomFaucet() {
  // Must be inside FaucetContext.Provider
  const faucet = useFaucet({ network: "devnet" });

  return (
    <div>
      <p>Connected: {faucet.isConnected ? "Yes" : "No"}</p>
      <p>Certified: {faucet.isCertified ? "Yes" : "No"}</p>
      <p>On Cooldown: {faucet.isOnCooldown ? "Yes" : "No"}</p>
      <button onClick={faucet.claim} disabled={!faucet.canClaim}>
        Claim {faucet.selectedAmount} SOL
      </button>
    </div>
  );
}

Requirements

Must be wrapped in QueryClientProvider from @tanstack/react-query.

CSS Styling

This package uses the Blueshift design tokens provided by @blueshift-gg/ui-components. Make sure the consuming app includes the base styles from that library and defines the CSS variables/classes referenced in the component markup.

License

MIT