deCAPTCHA

Web3-aware CAPTCHA components for decentralized applications.

Installation

pnpm install decaptcha

Quick Start

import { SimpleCaptcha } from 'decaptcha';

function App() {
  const handleVerify = (success: boolean) => {
    if (success) {
      console.log('User verified!');
    }
  };

  return (
    <SimpleCaptcha
      onVerify={handleVerify}
      difficulty="medium"
      challengeType="image"
    />
  );
}

Components

SimpleCaptcha

Basic CAPTCHA component with essential verification functionality.

Props:

• onVerify: (success: boolean) => void - Callback when verification completes
• difficulty?: 'easy' | 'medium' | 'hard' - Challenge difficulty (default: 'medium')
• challengeType?: 'image' | 'click' | 'input' - Type of challenge (default: 'image')
• theme?: 'light' | 'dark' | 'auto' - Theme mode (default: 'auto')
• disabled?: boolean - Disable interaction
• className?: string - Custom CSS class

Example:

<SimpleCaptcha
  onVerify={(success) => console.log('Verified:', success)}
  difficulty="hard"
  challengeType="click"
  theme="dark"
/>

AdvancedCaptcha

Enhanced CAPTCHA with multiple challenge types and expiration.

Props:

• All SimpleCaptcha props, plus:
• challengeType?: 'drag-drop' | 'shuffle' | 'math' - Advanced challenge types
• expirationMinutes?: number - Time limit for challenge
• onExpire?: () => void - Callback when challenge expires
• allowRetry?: boolean - Allow retry after failure (default: true)
• maxAttempts?: number - Maximum number of attempts

Example:

<AdvancedCaptcha
  onVerify={(success) => console.log('Verified:', success)}
  challengeType="math"
  expirationMinutes={5}
  maxAttempts={3}
  onExpire={() => console.log('Challenge expired')}
/>

Provider

DeCAPTCHAProvider

Global configuration and state management.

import { DeCAPTCHAProvider } from 'decaptcha';

function App() {
  return (
    <DeCAPTCHAProvider
      config={{
        theme: 'dark',
        defaultDifficulty: 'medium',
      }}
    >
      {/* Your app */}
    </DeCAPTCHAProvider>
  );
}

Hooks

useDeCAPTCHA

Programmatic control over CAPTCHA behavior.

import { useDeCAPTCHA } from 'decaptcha';

function MyComponent() {
  const { isVerified, verify, reset } = useDeCAPTCHA();

  const handleAction = async () => {
    if (!isVerified) {
      const verified = await verify();
      if (!verified) return;
    }
    // Proceed with action
  };

  return (
    <button onClick={handleAction}>
      {isVerified ? 'Proceed' : 'Verify First'}
    </button>
  );
}

Web3 Integration

Ethers.js

import { EthersAdapter } from 'decaptcha';
import { ethers } from 'ethers';

const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();
const adapter = new EthersAdapter(signer);

// Protect transaction
const protectedTx = adapter.withCaptchaProtection(
  contract.transfer,
  async () => {
    // Show CAPTCHA and return verification result
    return await verify();
  }
);

await protectedTx(recipient, amount);

Wagmi

import { createWagmiAdapter } from 'decaptcha';
import { useSigner, useAccount, useSignMessage } from 'wagmi';

const wagmiAdapter = createWagmiAdapter({
  useSigner,
  useAccount,
  useSignMessage,
});

function MyComponent() {
  const { signMessage, sendTransaction } = wagmiAdapter.useWagmiCaptcha(
    async () => {
      // Show CAPTCHA and return verification result
      return await verify();
    }
  );

  // Use protected methods
}

Theming

deCAPTCHA supports light, dark, and auto themes.

import { DeCAPTCHAProvider } from 'decaptcha';

<DeCAPTCHAProvider config={{ theme: 'dark' }}>
  <SimpleCaptcha onVerify={handleVerify} />
</DeCAPTCHAProvider>

Auto theme detects system preference using prefers-color-scheme.

API Reference

Challenge Types

SimpleCaptcha:

• image - Select images matching criteria
• click - Click specific elements
• input - Answer text questions

AdvancedCaptcha:

• drag-drop - Categorize items
• shuffle - Arrange pieces in order
• math - Solve equations

Difficulty Levels

• easy - Simple challenges, more time
• medium - Moderate complexity
• hard - Complex challenges, less time

License

MIT