@verifiedonchain-protocol/sdk 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# VerifiedOnchain SDK (`vo-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
+
+```bash
+npm install vo-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/vo-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.
+
+```tsx
+import { VerifiedOnchainFlow } from 'vo-sdk';
+import 'vo-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.
+
+```tsx
+import { WalletSelection } from 'vo-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.
+
+```tsx
+import { SocialConnection } from 'vo-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.
+
+```tsx
+import { ProofOfHumanity } from 'vo-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`.
+
+```tsx
+import { VerifiedRelayerClient } from 'vo-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.