VerifiedOnchain SDK (@verifiedonchain-protocol/sdk)

A lightweight, framework-agnostic React SDK for integrating the Proof of Humanity face verification, social connections, and wallet abstractions into your dApp.

This SDK captures biometric telemetry, performs local sequential liveness detection (blinking, head movement, emotions), and generates a zero-knowledge SimHash of the user's face. It then securely relays this hash to the VerifiedOnchain backend for Arcium MPC comparison and Solana gas-abstracted submission.

Installation

npm install @verifiedonchain-protocol/sdk

(Note: If you are using React 18, you might need to install peer dependencies like framer-motion for animations, @solana/wallet-adapter-react for Solana support, and wagmi + viem for EVM support if you haven't already).

Quick Start & Setup

The SDK requires two things to function correctly:

1. Tailwind CSS: The UI components are built with Tailwind.
2. Machine Learning Models: The SDK runs facial verification entirely on the client side (in-browser) for privacy. You must host the underlying AI models in your public directory.

1. Hosting the ML Models

Download the standard Human.js models (or copy them from the SDK's node_modules/@verifiedonchain-protocol/sdk/models if available) and place them in your web root under /models. The required models typically include blazeface.json, faceres.json, etc.

2. Basic Usage

The easiest way to integrate the SDK is using the VerifiedOnchainFlow component, which provides a complete turn-key UI for wallet connection, social linking, and biometric scanning.

import { VerifiedOnchainFlow } from '@verifiedonchain-protocol/sdk';
import '@verifiedonchain-protocol/sdk/dist/index.css'; // Optional if you are compiling Tailwind yourself

export default function VerificationPage() {
  const handleSuccess = (data) => {
    console.log("User successfully verified!", data);
    // data.walletAddress
    // data.chain
    // data.humanityCode (The on-chain unique identifier!)
  };

  return (
    <div className="flex justify-center items-center h-screen bg-black">
      <VerifiedOnchainFlow 
        appId="YOUR_APP_ID" // Required for production!
        requiredWallets={['phantom', 'metamask']}
        requiredSocials={['x', 'farcaster']}
        requireBiometrics={true}
        onIdentityVerified={handleSuccess}
        environment="mainnet"
        relayerUrl="https://api.verifiedonchain.com"
      />
    </div>
  );
}

Component API Reference

VerifiedOnchain SDK provides two ways to build your integration:

1. The Turn-Key Flow: A complete, pre-built multi-step wizard (VerifiedOnchainFlow).
2. The Headless / Modular Approach: Highly customizable, individual components you can compose however you want.

1. The Turn-Key Approach

The VerifiedOnchainFlow component is the easiest way to get started. It automatically handles the step-by-step UI for wallet connection, social linking, and biometric scanning.

Props:

• appId: Your registered Application ID (e.g. 'YOUR_APP_ID').
• requiredWallets: Array of wallet types to display (e.g. ['phantom', 'backpack', 'metamask', 'rainbow']).
• requiredSocials: Array of required social platforms (e.g. ['farcaster', 'lens', 'x']).
• requireBiometrics: Boolean (default: true). If false, skips the facial scan.
• onIdentityVerified: Callback function triggered when the flow successfully completes and the relayer returns the humanityCode.
• environment: 'mainnet' or 'testnet'.
• relayerUrl: The base URL of your relayer backend.

2. The Headless / Modular Approach (Custom Flows)

If you need complete control over the user experience, styling, or the order of operations, you can use our individual headless components. You handle the state routing, and we handle the heavy lifting of Web3 connections, OAuth, and zero-knowledge biometrics.

<WalletSelection />

A plug-and-play UI for wallet connections across both EVM and Solana ecosystems.

import { WalletSelection } from '@verifiedonchain-protocol/sdk';

<WalletSelection 
  requiredWallets={['phantom', 'metamask', 'backpack']}
  onWalletConnected={(address, chain) => {
    console.log(`Connected to ${chain}: ${address}`);
  }}
/>

<SocialConnection />

Handles OAuth flows and API integrations for social verification.

import { SocialConnection } from '@verifiedonchain-protocol/sdk';

<SocialConnection 
  requiredSocials={['x', 'farcaster']}
  onSocialConnected={(platform, profileData) => {
    console.log(`Connected to ${platform}:`, profileData);
  }}
/>

<ProofOfHumanity /> and <FaceZK />

The core biometric scanners. ProofOfHumanity provides a structured UI wrapper around the raw FaceZK scanner.

import { ProofOfHumanity } from '@verifiedonchain-protocol/sdk';

<ProofOfHumanity 
  onNextStep={() => console.log("User clicked continue")}
  onVerificationComplete={(hexHash, liveness) => {
    // You now have the secure SimHash and liveness score!
    submitToBackend(hexHash, liveness);
  }}
/>

Backend Submission (Relayer Client)

If you are using the Headless / Modular Approach, you are responsible for submitting the biometric payload to the backend using the VerifiedRelayerClient.

import { VerifiedRelayerClient } from '@verifiedonchain-protocol/sdk';

// Initialize the client
const client = new VerifiedRelayerClient({ 
  baseUrl: 'https://api.verifiedonchain.com/v1',
  network: 'mainnet',
  appId: 'YOUR_APP_ID' // Required for production usage!
});

// Submit the verification payload
const response = await client.submitVerification({
  simhashFull: '...',      // the hex hash from ProofOfHumanity
  livenessCombined: 0.99,  // the liveness score from ProofOfHumanity
  walletAddress: '0x...',  // the connected wallet from WalletSelection
  chain: 'evm'             // 'evm' or 'solana'
});

console.log("Humanity Code:", response.data.humanityCode);

Security & Authentication

The VerifiedOnchain backend enforces strict authentication for relayed requests:

1. AppID (appId): You must provide your officially registered appId when initializing the VerifiedRelayerClient.
2. Domain Origin Constraints: Verification requests will only be accepted from your pre-authorized domain origins (e.g., https://your-dapp-domain.com). Local development (localhost / 127.0.0.1) is permitted for testing.

If your domain is not authorized, the API will reject the request with a 403 FORBIDDEN error.