@neus/sdk 1.0.5 → 1.0.7

package/utils.js

@@ -1,11 +1,5 @@
-/**
- * NEUS SDK Utilities
- * Core utility functions for proof creation and verification
- */
-
 import { SDKError, ApiError, ValidationError } from './errors.js';
 
-/** CAIP-380 six-line signer message — line 1 (fixed context label). */
 export const PORTABLE_PROOF_SIGNER_HEADER = 'Portable Proof Verification Request';
 
 const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
@@ -59,11 +53,6 @@ function encodeBase58Bytes(input) {
   return out;
 }
 
-/**
- * Deterministic JSON stringification for consistent serialization
- * @param {Object} obj - Object to stringify
- * @returns {string} Deterministic JSON string
- */
 function deterministicStringify(obj) {
   if (obj === null || obj === undefined) {
     return JSON.stringify(obj);
@@ -86,9 +75,6 @@ function deterministicStringify(obj) {
   return `{${  pairs.join(',')  }}`;
 }
 
-/**
- * CAIP-380 EVM: line3 is decimal chainId. Non-EVM: CAIP-2 chain string.
- */
 function chainLineForPortableProofSigner(chain, chainId) {
   if (typeof chain === 'string' && chain.length > 0) {
     const m = chain.match(/^eip155:(\d+)$/);
@@ -101,19 +87,7 @@ function chainLineForPortableProofSigner(chain, chainId) {
   throw new SDKError('chainId is required (or provide chain for universal mode)', 'INVALID_CHAIN_CONTEXT');
 }
 
-/**
- * Construct verification message for wallet signing
- *
- * @param {Object} params - Message parameters
- * @param {string} params.walletAddress - Wallet address
- * @param {number} params.signedTimestamp - Unix timestamp
- * @param {Object} params.data - Verification data
- * @param {Array<string>} params.verifierIds - Array of verifier IDs
- * @param {number} params.chainId - Chain ID
- * @returns {string} Message for signing
- */
 export function constructVerificationMessage({ walletAddress, signedTimestamp, data, verifierIds, chainId, chain }) {
-  // Input validation for critical parameters
   if (!walletAddress || typeof walletAddress !== 'string') {
     throw new SDKError('walletAddress is required and must be a string', 'INVALID_WALLET_ADDRESS');
   }
@@ -139,7 +113,6 @@ export function constructVerificationMessage({ walletAddress, signedTimestamp, d
 
   const chainLine = chainLineForPortableProofSigner(chain, chainId);
 
-  // Address normalization: EVM (`eip155`) is lowercased; non-EVM namespaces preserve the original string.
   const namespace = (typeof chain === 'string' && chain.includes(':')) ? chain.split(':')[0] : 'eip155';
   const normalizedWalletAddress = namespace === 'eip155' ? walletAddress.toLowerCase() : walletAddress;
 
@@ -157,29 +130,14 @@ export function constructVerificationMessage({ walletAddress, signedTimestamp, d
   return messageComponents.join('\n').normalize('NFC');
 }
 
-/**
- * Validate Ethereum wallet address format
- *
- * @param {string} address - Address to validate
- * @returns {boolean} True if valid Ethereum address
- */
 export function validateWalletAddress(address) {
   if (!address || typeof address !== 'string') {
     return false;
   }
 
-  // Basic Ethereum address validation
   return /^0x[a-fA-F0-9]{40}$/.test(address);
 }
 
-/**
- * Validate universal wallet address format.
- * Uses chain namespace when provided; otherwise applies conservative multi-chain checks.
- *
- * @param {string} address - Address to validate
- * @param {string} [chain] - Optional CAIP-2 chain reference (namespace:reference)
- * @returns {boolean} True if valid universal wallet address
- */
 export function validateUniversalAddress(address, chain) {
   if (!address || typeof address !== 'string') return false;
   const value = address.trim();
@@ -204,17 +162,9 @@ export function validateUniversalAddress(address, chain) {
     return /^[a-z0-9._-]{2,64}$/.test(value);
   }
 
-  // Generic fallback for universal-address style identifiers.
   return /^[A-Za-z0-9][A-Za-z0-9._:-]{1,127}$/.test(value);
 }
 
-/**
- * Validate timestamp freshness
- *
- * @param {number} timestamp - Timestamp to validate
- * @param {number} maxAgeMs - Maximum age in milliseconds (default: 5 minutes)
- * @returns {boolean} True if timestamp is valid and recent
- */
 export function validateTimestamp(timestamp, maxAgeMs = 5 * 60 * 1000) {
   if (!timestamp || typeof timestamp !== 'number') {
     return false;
@@ -223,21 +173,10 @@ export function validateTimestamp(timestamp, maxAgeMs = 5 * 60 * 1000) {
   const now = Date.now();
   const age = now - timestamp;
 
-  // Check if timestamp is in the past and within allowed age
   return age >= 0 && age <= maxAgeMs;
 }
 
-/**
- * Create formatted verification data object
- *
- * @param {string} content - Content to verify
- * @param {string} owner - Owner wallet address
- * @param {Object} reference - Reference object
- * @returns {Object} Formatted verification data
- */
 export function createVerificationData(content, owner, reference = null) {
-  // Small, deterministic reference ID for convenience (NOT a cryptographic hash).
-  // Integrators that need a stable binding should prefer contentHash or an explicit reference.id.
   const stableRefId = (value) => {
     const str = typeof value === 'string' ? value : JSON.stringify(value);
     let hash = 0;
@@ -253,17 +192,12 @@ export function createVerificationData(content, owner, reference = null) {
     content,
     owner: validateWalletAddress(owner) ? owner.toLowerCase() : owner,
     reference: reference || {
-      // Must be a valid backend enum value; 'content' is not supported.
       type: 'other',
       id: stableRefId(content)
     }
   };
 }
 
-/**
- * DERIVE DID FROM ADDRESS AND CHAIN
-   * did:pkh:<namespace>:<chainId|segment>:<address_lowercase>
- */
 export function deriveDid(address, chainIdOrChain) {
   if (!address || typeof address !== 'string') {
     throw new SDKError('deriveDid: address is required', 'INVALID_ARGUMENT');
@@ -284,20 +218,6 @@ export function deriveDid(address, chainIdOrChain) {
   }
 }
 
-/**
- * Resolve DID from wallet identity via API endpoint
- *
- * @param {Object} params - DID resolution parameters
- * @param {string} params.walletAddress - Wallet address to resolve
- * @param {number} [params.chainId] - EVM chain ID
- * @param {string} [params.chain] - Universal chain context (namespace:reference)
- * @param {Object} [options] - Request options
- * @param {string} [options.endpoint='/api/v1/profile/did/resolve'] - DID resolve endpoint
- * @param {string} [options.apiUrl] - Absolute API base URL for non-relative endpoints
- * @param {RequestCredentials} [options.credentials] - Fetch credentials mode
- * @param {Record<string, string>} [options.headers] - Extra request headers
- * @returns {Promise<{did: string, data: any, raw: any}>}
- */
 export async function resolveDID(params, options = {}) {
   const endpointPath = options.endpoint || '/api/v1/profile/did/resolve';
   const apiUrl = typeof options.apiUrl === 'string' ? options.apiUrl.trim() : '';
@@ -371,17 +291,6 @@ export async function resolveDID(params, options = {}) {
   }
 }
 
-/**
- * Standardize verification request via backend signer-string endpoint
- *
- * @param {Object} params - Verification request payload
- * @param {Object} [options] - Request options
- * @param {string} [options.endpoint='/api/v1/verification/standardize'] - Standardize endpoint
- * @param {string} [options.apiUrl] - Absolute API base URL for non-relative endpoints
- * @param {RequestCredentials} [options.credentials] - Fetch credentials mode
- * @param {Record<string, string>} [options.headers] - Extra request headers
- * @returns {Promise<any>}
- */
 export async function standardizeVerificationRequest(params, options = {}) {
   const endpointPath = options.endpoint || '/api/v1/verification/standardize';
   const apiUrl = typeof options.apiUrl === 'string' ? options.apiUrl.trim() : '';
@@ -443,13 +352,6 @@ export async function standardizeVerificationRequest(params, options = {}) {
   }
 }
 
-/**
- * Resolve default ZK Passport configuration values.
- * Kept as an SDK utility to preserve existing app integrations.
- *
- * @param {Object} [overrides] - Caller-provided config overrides
- * @returns {Object}
- */
 export function resolveZkPassportConfig(overrides = {}) {
   const defaults = {
     provider: 'zkpassport',
@@ -465,29 +367,12 @@ export function resolveZkPassportConfig(overrides = {}) {
   };
 }
 
-/**
- * Convert a UTF-8 string to `0x`-prefixed hex.
- *
- * @param {string} value
- * @returns {string}
- */
 export function toHexUtf8(value) {
   const input = typeof value === 'string' ? value : String(value || '');
   const bytes = new TextEncoder().encode(input);
   return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
 }
 
-/**
- * Sign an arbitrary message with the provided wallet/provider.
- * Supports EIP-1193 wallets and signer-like objects.
- *
- * @param {Object} params
- * @param {Object} [params.provider] - Wallet provider/signer
- * @param {string} params.message - Message to sign
- * @param {string} [params.walletAddress] - Explicit signer address (recommended)
- * @param {string} [params.chain] - Chain context (`namespace:reference`)
- * @returns {Promise<string>}
- */
 export async function signMessage({ provider, message, walletAddress, chain } = {}) {
   const msg = typeof message === 'string' ? message : String(message || '');
   if (!msg) {
@@ -574,7 +459,7 @@ export async function signMessage({ provider, message, walletAddress, chain } =
           const sig = await resolvedProvider.request({ method: 'personal_sign', params: [hexMsg, address] });
           if (typeof sig === 'string' && sig) return sig;
         } catch {
-          // Continue to additional fallbacks.
+          void 0;
         }
       }
     }
@@ -601,15 +486,9 @@ export async function signMessage({ provider, message, walletAddress, chain } =
   throw new SDKError('Unable to sign message with provided wallet/provider', 'SIGNER_UNAVAILABLE');
 }
 
-/**
- * Determine if a verification status is terminal (completed or failed)
- * @param {string} status - The verification status
- * @returns {boolean} Whether the status is terminal
- */
 export function isTerminalStatus(status) {
   if (!status || typeof status !== 'string') return false;
 
-  // Success states
   const successStates = [
     'verified',
     'verified_no_verifiers',
@@ -618,7 +497,6 @@ export function isTerminalStatus(status) {
     'verified_propagation_failed'
   ];
 
-  // Failure states
   const failureStates = [
     'rejected',
     'rejected_verifier_failure',
@@ -633,11 +511,6 @@ export function isTerminalStatus(status) {
   return successStates.includes(status) || failureStates.includes(status);
 }
 
-/**
- * Determine if a verification status indicates success
- * @param {string} status - The verification status
- * @returns {boolean} Whether the status indicates success
- */
 export function isSuccessStatus(status) {
   if (!status || typeof status !== 'string') return false;
 
@@ -652,11 +525,6 @@ export function isSuccessStatus(status) {
   return successStates.includes(status);
 }
 
-/**
- * Determine if a verification status indicates failure
- * @param {string} status - The verification status
- * @returns {boolean} Whether the status indicates failure
- */
 export function isFailureStatus(status) {
   if (!status || typeof status !== 'string') return false;
 
@@ -674,11 +542,6 @@ export function isFailureStatus(status) {
   return failureStates.includes(status);
 }
 
-/**
- * Format verification status for display
- * @param {string} status - Raw status from API
- * @returns {Object} Formatted status information
- */
 export function formatVerificationStatus(status) {
   const statusMap = {
     'processing_verifiers': {
@@ -781,18 +644,6 @@ export function formatVerificationStatus(status) {
   };
 }
 
-/**
- * Compute keccak256 content hash (0x-prefixed) for arbitrary input
- * Uses ethers (peer dependency) via dynamic import to avoid hard bundling
- *
- * Note: The NEUS backend uses SHAKE256 (quantum-resistant) for content hashing.
- * For content hashes that match the backend, use the /verification/standardize
- * endpoint to get the server-computed hash, or provide the content directly and let
- * the backend compute the hash.
- *
- * @param {string|Uint8Array} input - Raw string (UTF-8) or bytes
- * @returns {Promise<string>} 0x-prefixed keccak256 hash
- */
 export async function computeContentHash(input) {
   try {
     const ethers = await import('ethers');
@@ -803,18 +654,10 @@ export async function computeContentHash(input) {
   }
 }
 
-/**
- * Create a delay/sleep function
- * @param {number} ms - Milliseconds to wait
- * @returns {Promise} Promise that resolves after the delay
- */
 export function delay(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
-/**
- * Status Polling Utility for tracking verification progress
- */
 export class StatusPoller {
   constructor(client, qHash, options = {}) {
     this.client = client;
@@ -838,13 +681,11 @@ export class StatusPoller {
 
           const response = await this.client.getProof(this.qHash);
 
-          // Check if verification is complete using the terminal status utility
           if (isTerminalStatus(response.status)) {
             resolve(response);
             return;
           }
 
-          // Check if we've exceeded max attempts
           if (this.attempt >= this.options.maxAttempts) {
             reject(new SDKError(
               'Verification polling timeout',
@@ -853,7 +694,6 @@ export class StatusPoller {
             return;
           }
 
-          // Schedule next poll with optional exponential backoff
           if (this.options.exponentialBackoff) {
             this.currentInterval = Math.min(
               this.currentInterval * 1.5,
@@ -889,20 +729,14 @@ export class StatusPoller {
         }
       };
 
-      // Start polling immediately
       pollAttempt();
     });
   }
 }
 
-/**
- * NEUS Network Constants
- */
 export const NEUS_CONSTANTS = {
-  /** Default EVM chain id for NEUS protocol signing context (`HUB_CHAIN_ID` name kept for compatibility). */
   HUB_CHAIN_ID: 84532,
 
-  // Supported target chains for cross-chain propagation
   TESTNET_CHAINS: [
     11155111, // Ethereum Sepolia
     11155420, // Optimism Sepolia
@@ -910,15 +744,12 @@ export const NEUS_CONSTANTS = {
     80002     // Polygon Amoy
   ],
 
-  // API endpoints
   API_BASE_URL: 'https://api.neus.network',
   API_VERSION: 'v1',
 
-  // Timeouts and limits
   SIGNATURE_MAX_AGE_MS: 5 * 60 * 1000, // 5 minutes
   REQUEST_TIMEOUT_MS: 30 * 1000,       // 30 seconds
 
-  // Default verifier set for quick starts
   DEFAULT_VERIFIERS: [
     'ownership-basic',
     'nft-ownership',
@@ -926,42 +757,18 @@ export const NEUS_CONSTANTS = {
   ]
 };
 
-/**
- * Additional validation and utility helpers
- */
-
-/**
- * Validate qHash format (0x + 64 hex chars)
- * @param {string} qHash - The qHash to validate
- * @returns {boolean} True if valid qHash format
- */
 export function validateQHash(qHash) {
   return typeof qHash === 'string' && /^0x[a-fA-F0-9]{64}$/.test(qHash);
 }
 
-/**
- * Format timestamp to human readable string
- * @param {number} timestamp - Unix timestamp
- * @returns {string} Formatted date string
- */
 export function formatTimestamp(timestamp) {
   return new Date(timestamp).toLocaleString();
 }
 
-/**
- * Check if a chain ID is supported for cross-chain propagation
- * @param {number} chainId - Chain ID to check
- * @returns {boolean} True if supported
- */
 export function isSupportedChain(chainId) {
   return NEUS_CONSTANTS.TESTNET_CHAINS.includes(chainId) || chainId === NEUS_CONSTANTS.HUB_CHAIN_ID;
 }
 
-/**
- * Normalize wallet address to lowercase (EIP-55 agnostic)
- * @param {string} address - Wallet address to normalize
- * @returns {string} Lowercase address
- */
 export function normalizeAddress(address) {
   if (!validateWalletAddress(address)) {
     throw new SDKError('Invalid wallet address format', 'INVALID_ADDRESS');
@@ -969,13 +776,6 @@ export function normalizeAddress(address) {
   return address.toLowerCase();
 }
 
-/**
- * Validate a verifier payload for basic structural integrity.
- * Lightweight validation checks; verifier authors should document complete schemas.
- * @param {string} verifierId - Verifier identifier (e.g., 'ownership-basic' or custom)
- * @param {any} data - Verifier-specific payload
- * @returns {{ valid: boolean, error?: string, missing?: string[], warnings?: string[] }}
- */
 export function validateVerifierPayload(verifierId, data) {
   const result = { valid: true, missing: [], warnings: [] };
 
@@ -987,7 +787,6 @@ export function validateVerifierPayload(verifierId, data) {
     return { valid: false, error: 'data must be a non-null object' };
   }
 
-  // Minimal field hints for built-in verifiers
   const id = verifierId.replace(/@\d+$/, '');
   if (id === 'nft-ownership') {
     ['contractAddress', 'tokenId', 'chainId'].forEach((key) => {
@@ -1004,10 +803,6 @@ export function validateVerifierPayload(verifierId, data) {
       result.warnings.push('ownerAddress omitted (defaults to the signed walletAddress)');
     }
   } else if (id === 'ownership-basic') {
-    // ownership-basic requires an owner, and needs at least one binding:
-    // - content (inline), or
-    // - contentHash (recommended for large content), or
-    // - reference.id (reference-only proofs)
     if (!('owner' in data)) result.missing.push('owner');
     const hasContent = typeof data.content === 'string' && data.content.length > 0;
     const hasContentHash = typeof data.contentHash === 'string' && data.contentHash.length > 0;
@@ -1025,18 +820,6 @@ export function validateVerifierPayload(verifierId, data) {
   return result;
 }
 
-/**
- * Build a standard verification request and signing message for manual flows.
- * Returns the message to sign and the request body (sans signature).
- * @param {Object} params
- * @param {string[]} params.verifierIds
- * @param {object} params.data
- * @param {string} params.walletAddress
- * @param {number} [params.chainId=NEUS_CONSTANTS.HUB_CHAIN_ID]
- * @param {object} [params.options]
- * @param {number} [params.signedTimestamp=Date.now()]
- * @returns {{ message: string, request: { verifierIds: string[], data: object, walletAddress: string, signedTimestamp: number, chainId: number, options?: object } }}
- */
 export function buildVerificationRequest({
   verifierIds,
   data,
@@ -1078,12 +861,6 @@ export function buildVerificationRequest({
   return { message, request };
 }
 
-/**
- * Create a retry utility with exponential backoff
- * @param {Function} fn - Function to retry
- * @param {Object} options - Retry options
- * @returns {Promise} Promise that resolves with function result
- */
 export async function withRetry(fn, options = {}) {
   const {
     maxAttempts = 3,
@@ -1114,17 +891,6 @@ export async function withRetry(fn, options = {}) {
   throw lastError;
 }
 
-/**
- * Validate signature components for debugging signature verification issues
- * @param {Object} params - Signature components to validate
- * @param {string} params.walletAddress - Wallet address
- * @param {string} params.signature - EIP-191 signature
- * @param {number} params.signedTimestamp - Unix timestamp
- * @param {Object} params.data - Verification data
- * @param {Array<string>} params.verifierIds - Array of verifier IDs
- * @param {number} params.chainId - Chain ID
- * @returns {Object} Validation result with detailed feedback
- */
 export function validateSignatureComponents({ walletAddress, signature, signedTimestamp, data, verifierIds, chainId }) {
   const result = {
     valid: true,
@@ -1133,7 +899,6 @@ export function validateSignatureComponents({ walletAddress, signature, signedTi
     debugInfo: {}
   };
 
-  // Validate wallet address
   if (!validateWalletAddress(walletAddress)) {
     result.valid = false;
     result.errors.push('Invalid wallet address format - must be 0x + 40 hex characters');
@@ -1144,7 +909,6 @@ export function validateSignatureComponents({ walletAddress, signature, signedTi
     }
   }
 
-  // Validate signature format
   if (!signature || typeof signature !== 'string') {
     result.valid = false;
     result.errors.push('Signature is required and must be a string');
@@ -1153,7 +917,6 @@ export function validateSignatureComponents({ walletAddress, signature, signedTi
     result.errors.push('Invalid signature format - must be 0x + 130 hex characters (65 bytes)');
   }
 
-  // Validate timestamp
   if (!validateTimestamp(signedTimestamp)) {
     result.valid = false;
     result.errors.push('Invalid or expired timestamp - must be within 5 minutes');
@@ -1161,7 +924,6 @@ export function validateSignatureComponents({ walletAddress, signature, signedTi
     result.debugInfo.timestampAge = Date.now() - signedTimestamp;
   }
 
-  // Validate data object
   if (!data || typeof data !== 'object' || Array.isArray(data)) {
     result.valid = false;
     result.errors.push('Data must be a non-null object');
@@ -1169,19 +931,16 @@ export function validateSignatureComponents({ walletAddress, signature, signedTi
     result.debugInfo.dataString = deterministicStringify(data);
   }
 
-  // Validate verifier IDs
   if (!Array.isArray(verifierIds) || verifierIds.length === 0) {
     result.valid = false;
     result.errors.push('VerifierIds must be a non-empty array');
   }
 
-  // Validate chain ID
   if (typeof chainId !== 'number') {
     result.valid = false;
     result.errors.push('ChainId must be a number');
   }
 
-  // Generate the message that would be signed
   if (result.valid || result.errors.length < 3) {
     try {
       result.debugInfo.messageToSign = constructVerificationMessage({
@@ -1199,13 +958,6 @@ export function validateSignatureComponents({ walletAddress, signature, signedTi
   return result;
 }
 
-/**
- * Convert a non-negative decimal display amount to agent-delegation `maxSpend`
- * (whole-number string in token base units, 1–78 digits).
- * @param {string|number} humanAmount - e.g. "100.50" or 100.5
- * @param {number} decimals - Number of decimal places for the token (e.g. 6 for USDC, 18 for ETH)
- * @returns {string}
- */
 export function toAgentDelegationMaxSpend(humanAmount, decimals) {
   if (humanAmount === undefined || humanAmount === null) {
     throw new ValidationError('humanAmount is required', 'humanAmount', humanAmount);
@@ -1254,24 +1006,8 @@ export function toAgentDelegationMaxSpend(humanAmount, decimals) {
   return out;
 }
 
-/** Default hosted verify base URL */
 export const DEFAULT_HOSTED_VERIFY_URL = 'https://neus.network/verify';
 
-/**
- * Build standardized hosted checkout/verify URL for your app.
- * Single typed entry point to avoid copy-paste errors.
- * @param {Object} opts
- * @param {string} [opts.gateId] - Gate ID for gate-backed checkout
- * @param {string} [opts.returnUrl] - Partner return URL (postMessage/redirect)
- * @param {string[]} [opts.verifiers] - Verifier IDs (comma-joined)
- * @param {string} [opts.preset] - Preset name (e.g. 'human')
- * @param {string} [opts.mode] - 'popup' or null
- * @param {string} [opts.intent] - 'login' for auth-code flow
- * @param {string} [opts.origin] - Allowed parent origin for popup completion
- * @param {string} [opts.oauthProvider] - Optional OAuth provider id to pre-select for social/org verifiers (hosted flow)
- * @param {string} [opts.baseUrl] - Hosted verify URL override
- * @returns {string} Full URL
- */
 export function getHostedCheckoutUrl(opts = {}) {
   const base = typeof opts.baseUrl === 'string' && opts.baseUrl.trim()
     ? opts.baseUrl.replace(/\/+$/, '')

package/widgets/README.md

@@ -1,45 +1,45 @@
-# NEUS Widgets
-
-**Proof-aware React components** (VerifyGate, ProofBadge) so your UI can show verified state and gate content **using the same checks your server already trusts** - avoid re-implementing verifier rules only in the browser.
-
-## Install
-
-```bash
-npm install @neus/sdk react react-dom
-```
-
-## VerifyGate
-
-Create mode defaults to **unlisted public** for gate-friendly reuse. Override `proofOptions` when you need listed public or private.
-
-```jsx
-import { VerifyGate } from '@neus/sdk/widgets';
-
-export function Page() {
-  return (
-    <VerifyGate
-      appId="your-app-id"
-      requiredVerifiers={['nft-ownership']}
-      verifierData={{
-        'nft-ownership': { contractAddress: '0x...', tokenId: '1', chainId: 8453 }
-      }}
-    >
-      <div>Unlocked</div>
-    </VerifyGate>
-  );
-}
-```
-
-## ProofBadge
-
-```jsx
-import { ProofBadge } from '@neus/sdk/widgets';
-
-<ProofBadge proofId="0x..." showChains />
-```
-
-## Docs
-
-- [Widgets Overview](https://docs.neus.network/widgets/overview)
-- [Verify Component](https://docs.neus.network/widgets/verifygate)
-- [Quickstart](https://docs.neus.network/quickstart)
+# NEUS Widgets
+
+**Proof-aware React components** (VerifyGate, ProofBadge) so your UI can show verified state and gate content **using the same checks your server already trusts** - avoid re-implementing verifier rules only in the browser.
+
+## Install
+
+```bash
+npm install @neus/sdk react react-dom
+```
+
+## VerifyGate
+
+Create mode defaults to **private**. Override `proofOptions` only when you intentionally need public visibility for link-based or public checks.
+
+```jsx
+import { VerifyGate } from '@neus/sdk/widgets';
+
+export function Page() {
+  return (
+    <VerifyGate
+      appId="your-app-id"
+      requiredVerifiers={['nft-ownership']}
+      verifierData={{
+        'nft-ownership': { contractAddress: '0x...', tokenId: '1', chainId: 8453 }
+      }}
+    >
+      <div>Unlocked</div>
+    </VerifyGate>
+  );
+}
+```
+
+## ProofBadge
+
+```jsx
+import { ProofBadge } from '@neus/sdk/widgets';
+
+<ProofBadge proofId="0x..." showChains />
+```
+
+## Docs
+
+- [Widgets Overview](https://docs.neus.network/widgets/overview)
+- [Verify Component](https://docs.neus.network/widgets/verifygate)
+- [Quickstart](https://docs.neus.network/quickstart)