feat: Add Farcaster miniapp support for identity verification flow #10

apps/demo-identity-app/index.html

@@ -10,4 +10,4 @@
     <div id="app"></div>
     <script type="module" src="/src/main.tsx"></script>
   </body>
-</html>
+</html>

apps/demo-identity-app/src/App.tsx

@@ -72,6 +72,7 @@ const App: React.FC = () => {
           setIsVerified(isWhitelisted ?? false)
         } catch (error) {
           console.error("Error checking whitelist:", error)
+          setIsWhitelisted(false)
         } finally {
           setLoadingWhitelist(false)
         }
@@ -87,10 +88,6 @@ const App: React.FC = () => {
     }
   }, [address, identitySDK, isWhitelisted, connectedAccount])
 
-  const handleVerificationSuccess = () => {
-    setIsVerified(true)
-  }
-
   return (
     <TamaguiProvider config={tamaguiConfig}>
       <ScrollView
@@ -180,9 +177,7 @@ const App: React.FC = () => {
             !isWhitelisted &&
             !error ? (
               <YStack alignItems="center" gap={12}>
-                <VerifyButton
-                  onVerificationSuccess={handleVerificationSuccess}
-                />
+                <VerifyButton />
                 <Text fontSize={14} color="$gray10">
                   You need to verify your identity via GoodDollar to continue.
                 </Text>

apps/demo-identity-app/src/components/ClaimButton.tsx

@@ -72,25 +72,21 @@ export const ClaimButton: React.FC = () => {
       setError("ClaimSDK is not initialized.")
       return
     }
-    console.log("handleClaim called")
 
     setIsClaiming(true)
     setError(null)
     setTxHash(null)
 
     try {
-      const callBackExample = async () => {
-        console.log("waiting for claim for 2 seconds...")
-        await new Promise((resolve) => setTimeout(resolve, 2000)) // wait 2 seconds
-        console.log("tx start")
+      const txConfirm = async () => {
+        await new Promise((resolve) => setTimeout(resolve, 2000))
       }
 
-      const tx = await sdk.claim(callBackExample)
+      const tx = await sdk.claim(txConfirm)
       if (!tx) return
 
       setTxHash(tx.transactionHash)
     } catch (err: any) {
-      console.error("Claim failed:", err)
       setError(err.message || "An unexpected error occurred.")
     } finally {
       setIsClaiming(false)

apps/demo-identity-app/src/components/VerifyButton.tsx

@@ -3,13 +3,7 @@ import { Button } from "tamagui"
 import { useIdentitySDK } from "@goodsdks/react-hooks"
 import { useAccount } from "wagmi"
 
-interface VerifyButtonProps {
-  onVerificationSuccess: () => void
-}
-
-export const VerifyButton: React.FC<VerifyButtonProps> = ({
-  onVerificationSuccess,
-}) => {
+export const VerifyButton: React.FC = () => {
   const { address } = useAccount()
   const { sdk: identitySDK } = useIdentitySDK("development")
 
@@ -20,13 +14,12 @@ export const VerifyButton: React.FC<VerifyButtonProps> = ({
       const fvLink = await identitySDK.generateFVLink(
         false,
         window.location.href,
-        42220,
+        undefined,
       )
 
       window.location.href = fvLink
-    } catch (error) {
-      console.error("Verification failed:", error)
-      // Handle error (e.g., show toast)
+    } catch (e) {
+      console.error("Verification failed:", e)
     }
   }
 

apps/demo-identity-app/src/config.tsx

@@ -7,12 +7,11 @@ import React, { ReactNode } from "react"
 
 const queryClient = new QueryClient()
 
-const projectId = "71dd03d057d89d0af68a4c627ec59694"
-
+const projectId = "71dd03d057d89d0af68a4c627ec59694" 
 const metadata = {
   name: "AppKit",
   description: "AppKit Example",
-  url: "https://example.com", // origin must match your domain & subdomain
+  url: "http://localhost:3000",
   icons: ["https://avatars.githubusercontent.com/u/179229932"],
 }
 
@@ -43,6 +42,11 @@ createAppKit({
     "--w3m-color-mix-strength": 40,
     "--w3m-accent": "#00BB7F",
   },
+  allowUnsupportedChain: false,
+  enableWalletConnect: true,
+  enableInjected: true,
+  enableEIP6963: true,
+  enableCoinbase: true,
 })
 
 type ComponentProps = {

apps/demo-identity-app/src/globals.d.ts

@@ -1,3 +1,5 @@
+import React from "react"
+
 declare namespace JSX {
   interface IntrinsicElements {
     "claim-button": React.DetailedHTMLProps<

apps/demo-identity-app/vite.config.mts

@@ -31,4 +31,4 @@ export default defineConfig({
     "process.browser": true,
     "process.env": process.env,
   },
-});
+});

apps/demo-webcomponents/vite.config.mts

@@ -25,4 +25,4 @@ export default defineConfig({
     "process.browser": true,
     "process.env": process.env,
   },
-})
+})

packages/citizen-sdk/README.md

@@ -103,6 +103,32 @@ For Wagmi-based React projects, use the hooks exposed from `@goodsdks/react-hook
 
 Explore the generated TypeScript definitions in `dist/` for the complete surface, including helper enums (`contractEnv`, `SupportedChains`, etc.).
 
+## Farcaster MiniApp Support
+
+The SDK includes support for Farcaster miniapps, which enables proper navigation and callback handling when running inside a Farcaster miniapp environment.
+
+### Configuration
+
+**Important**: The `FarcasterAppConfigs` in `constants.ts` are placeholder values. If you're integrating the SDK into a Farcaster miniapp, you must provide your Farcaster app ID and slug when initializing the SDK.
+
+1. Go to the [Farcaster Developer Portal](https://warpcast.com/~/developers)
+2. Register your Mini App and obtain your `appId` and `appSlug`
+3. Pass these values to `IdentitySDK.init`:
+
+```ts
+const identitySDK = await IdentitySDK.init({
+  publicClient,
+  walletClient,
+  env: "production",
+  farcasterConfig: {
+    appId: "YOUR_APP_ID",
+    appSlug: "YOUR_APP_SLUG"
+  }
+})
+```
+
+The SDK will automatically detect if it's running in a Farcaster miniapp and use Universal Links for callbacks, which ensures proper navigation back to your miniapp after face verification.
+
 ## References
 
 - [Demo Identity App](https://demo-identity-app.vercel.app/)

packages/citizen-sdk/package.json

@@ -35,6 +35,7 @@
     "wagmi": "*"
   },
   "dependencies": {
+    "@farcaster/miniapp-sdk": "^0.1.8",
     "lz-string": "^1.5.0",
     "tsup": "^8.4.0"
   },

packages/citizen-sdk/src/constants.ts

@@ -27,6 +27,29 @@ export const Envs: Record<string, Record<string, string>> = {
   },
 }
 
+/**
+ * Farcaster Mini App configurations for different environments
+ * @notice THESE ARE EXAMPLE / PLACEHOLDER VALUES ONLY.
+* Developers integrating the SDK SHOULD:
+* 1. Pass a custom `farcasterConfig` when initializing IdentitySDK / ClaimSDK
+ *
+* The SDK will default to these values if no config is provided, which will likely fail in production.
+*/
+export const FarcasterAppConfigs: Record<string, { appId: string; appSlug: string }> = {
+  production: {
+    appId: "", // REQUIRED: Replace with actual app ID from Farcaster Developer Portal
+    appSlug: "", // REQUIRED: Replace with actual app slug
+  },
+  staging: {
+    appId: "", // REQUIRED: Replace with actual app ID from Farcaster Developer Portal
+    appSlug: "", // REQUIRED: Replace with actual app slug
+  },
+  development: {
+    appId: "", // REQUIRED: Replace with actual app ID from Farcaster Developer Portal
+    appSlug: "", // REQUIRED: Replace with actual app slug
+  },
+}
+
 export interface ContractAddresses {
   identityContract: `0x${string}`
   ubiContract: `0x${string}`

packages/citizen-sdk/src/index.ts

@@ -1,2 +1,4 @@
 export * from "./sdks"
 export * from "./constants"
+export * from "./utils/auth"
+

packages/citizen-sdk/src/sdks/index.ts

@@ -1,4 +1,3 @@
 export * from "./viem-identity-sdk"
 export * from "./viem-claim-sdk"
 export * from "./viem-custodial-claim-sdk"
-export * from "./viem-custodial-identity-sdk"

packages/citizen-sdk/src/sdks/viem-claim-sdk.ts

@@ -7,6 +7,7 @@ import {
   type WalletClient,
   ContractFunctionExecutionError,
   TransactionReceipt,
+  zeroAddress,
 } from "viem"
 
 import { waitForTransactionReceipt } from "viem/actions"
@@ -20,9 +21,16 @@ import {
   faucetABI,
   isSupportedChain,
   ubiSchemeV2ABI,
+  FarcasterAppConfigs,
 } from "../constants"
 import type { ContractAddresses } from "../constants"
 import { resolveChainAndContract } from "../utils/chains"
+import {
+  createVerificationCallbackUrl,
+  createFarcasterCallbackUniversalLink,
+  isInFarcasterMiniApp,
+  navigateToUrl
+} from "../utils/auth"
 import { triggerFaucet as triggerFaucetUtil } from "../utils/triggerFaucet"
 import {
   createRpcIteratorRegistry,
@@ -82,7 +90,7 @@ export class ClaimSDK {
   private readonly faucetAddress: Address
   private readonly account: Address
   private readonly env: contractEnv
-  public readonly rdu: string
+  public rdu: string
 
   constructor({
     account,
@@ -99,9 +107,11 @@ export class ClaimSDK {
     this.walletClient = walletClient
     this.identitySDK = identitySDK
     this.account = account ?? walletClient.account.address
+    this.env = env
 
+    // Initialize callback URL - will be set properly in initializeCallbackUrl
     this.rdu = rdu
-    this.env = env
+    this.initializeCallbackUrl(rdu);
 
     const { chainId, contractEnvAddresses } = resolveChainAndContract(
       walletClient,
@@ -142,6 +152,37 @@ export class ClaimSDK {
     this.faucetAddress = contractEnvAddresses.faucetContract as Address
   }
 
+  /**
+   * Initialize the callback URL with proper Farcaster Universal Link support
+   * @param rdu - The redirect URL after claim
+   */
+  private async initializeCallbackUrl(rdu?: string): Promise<void> {
+    if (!rdu) return;
+
+    try {
+      // Check if we're in a Farcaster context and should use Universal Links
+      const isFarcaster = await isInFarcasterMiniApp();
+
+      if (isFarcaster && FarcasterAppConfigs[this.env]) {
+        // Create proper Farcaster Universal Link
+        const farcasterConfig = FarcasterAppConfigs[this.env];
+        this.rdu = createFarcasterCallbackUniversalLink(
+          farcasterConfig,
+          'claim',
+          { source: "gooddollar_claim_verification" }
+        );
+      } else {
+        // Fallback to direct callback URL for non-Farcaster environments
+        this.rdu = await createVerificationCallbackUrl(rdu, {
+          source: "gooddollar_claim_verification"
+        });
+      }
+    } catch (error) {
+      // Fallback to original URL on error
+      this.rdu = rdu;
+    }
+  }
+
   private getContractsForChain(chainId: SupportedChains): ContractAddresses {
     const contracts = this.chainContracts.get(chainId)
 
@@ -454,19 +495,21 @@ export class ClaimSDK {
    * @throws If face verification redirect fails.
    */
   private async fvRedirect(): Promise<void> {
-    const fvChainId = this.fvDefaultChain ?? this.chainId
+    // Generate link with current chain ID as default, respecting identity-contract logic
     const fvLink = await this.identitySDK.generateFVLink(
       false,
       this.rdu,
-      fvChainId,
+      this.chainId
     )
-    if (typeof window !== "undefined") {
-      window.location.href = fvLink
-    } else {
-      throw new Error(
-        "Face verification redirect is only supported in browser environments.",
-      )
+
+    // Handle Farcaster Context
+    if (await isInFarcasterMiniApp()) {
+      await navigateToUrl(fvLink, false)
+      return
     }
+
+    // Default legacy behavior
+    window.location.href = fvLink
   }
 
   /**