Fix: Connected accounts can now claim via whitelisted root (#24)

apps/demo-identity-app/.eslintrc.json

@@ -0,0 +1,23 @@
+{
+    "root": true,
+    "env": {
+        "browser": true,
+        "es2020": true
+    },
+    "extends": [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/recommended",
+        "plugin:react-hooks/recommended",
+        "prettier"
+    ],
+    "ignorePatterns": [
+        "dist",
+        ".eslintrc.json"
+    ],
+    "parser": "@typescript-eslint/parser",
+    "plugins": [
+        "@typescript-eslint",
+        "react-hooks"
+    ],
+    "rules": {}
+}

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

@@ -18,7 +18,7 @@ export const ClaimButton: React.FC = () => {
   const [txHash, setTxHash] = useState<string | null>(null)
   const { sdk: claimSDK, loading, error: sdkError } = useClaimSDK("development")
   const [sdk, setSdk] = useState<typeof claimSDK | null>(null)
-  const [claimAmount, setClaimAmount] = useState<Number | null>(null)
+  const [claimAmount, setClaimAmount] = useState<number | null>(null)
   const [altClaimAvailable, setAltClaimAvailable] = useState(false)
   const [altChainId, setAltChainId] = useState<SupportedChains | null>(null)
 

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

@@ -7,9 +7,7 @@ interface VerifyButtonProps {
   onVerificationSuccess: () => void
 }
 
-export const VerifyButton: React.FC<VerifyButtonProps> = ({
-  onVerificationSuccess,
-}) => {
+export const VerifyButton: React.FC<VerifyButtonProps> = () => {
   const { address } = useAccount()
   const { sdk: identitySDK } = useIdentitySDK("development")
 

apps/engagement-app/src/hooks/use-toast.ts

@@ -14,8 +14,8 @@ type ToasterToast = ToastProps & {
   description?: React.ReactNode;
   action?: ToastActionElement;
 };
-
-const actionTypes = {
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const _actionTypes = {
   ADD_TOAST: "ADD_TOAST",
   UPDATE_TOAST: "UPDATE_TOAST",
   DISMISS_TOAST: "DISMISS_TOAST",
@@ -29,25 +29,25 @@ function genId() {
   return count.toString();
 }
 
-type ActionType = typeof actionTypes;
+type ActionType = typeof _actionTypes;
 
 type Action =
   | {
-      type: ActionType["ADD_TOAST"];
-      toast: ToasterToast;
-    }
+    type: ActionType["ADD_TOAST"];
+    toast: ToasterToast;
+  }
   | {
-      type: ActionType["UPDATE_TOAST"];
-      toast: Partial<ToasterToast>;
-    }
+    type: ActionType["UPDATE_TOAST"];
+    toast: Partial<ToasterToast>;
+  }
   | {
-      type: ActionType["DISMISS_TOAST"];
-      toastId?: ToasterToast["id"];
-    }
+    type: ActionType["DISMISS_TOAST"];
+    toastId?: ToasterToast["id"];
+  }
   | {
-      type: ActionType["REMOVE_TOAST"];
-      toastId?: ToasterToast["id"];
-    };
+    type: ActionType["REMOVE_TOAST"];
+    toastId?: ToasterToast["id"];
+  };
 
 interface State {
   toasts: ToasterToast[];
@@ -105,9 +105,9 @@ export const reducer = (state: State, action: Action): State => {
         toasts: state.toasts.map((t) =>
           t.id === toastId || toastId === undefined
             ? {
-                ...t,
-                open: false,
-              }
+              ...t,
+              open: false,
+            }
             : t,
         ),
       };

packages/citizen-sdk/README-ClaimSDK.md

@@ -5,9 +5,11 @@ The Claim SDK ships with `@goodsdks/citizen-sdk` and builds on the Identity SDK
 ## Claim Flow at a Glance
 
 1. **Verify identity** – confirm the wallet is whitelisted through the Identity SDK.
-2. **Check entitlement** – determine the claimable amount on the active chain and look for fallbacks (Fuse ⇄ Celo ⇄ XDC).
-3. **Trigger faucet (optional)** – tops up the claim contract if required.
-4. **Submit claim** – send the `claim()` transaction and wait for confirmation.
+2. **Resolve whitelisted root** – for connected accounts, resolve the main whitelisted address.
+3. **Check entitlement** – determine the claimable amount on the active chain using the whitelisted root address.
+4. **Look for fallbacks** – if no entitlement on the current chain, check alternatives (Fuse ⇄ Celo ⇄ XDC).
+5. **Trigger faucet (optional)** – tops up the claim contract if required.
+6. **Submit claim** – send the `claim()` transaction and wait for confirmation.
 
 ```
 User connects wallet
@@ -16,9 +18,11 @@ IdentitySDK.getWhitelistedRoot
         ↓
 Whitelisted? ── no ──▶ Face verification
         │
-        yes
+        yes (returns root address)
+        ↓
+ClaimSDK uses root address
         ↓
-ClaimSDK.checkEntitlement
+ClaimSDK.checkEntitlement(root)
         ↓
 Can claim? ── no ──▶ nextClaimTime timer
         │
@@ -90,6 +94,59 @@ if (amount > 0n) {
 > switch networks and then re-run `ClaimSDK.init` so the SDK binds to that
 > environment before calling `claimSDK.claim()` again.
 
+## Connected Accounts
+
+Users can connect secondary wallets to their main whitelisted account. When a connected account attempts to claim:
+
+1. **`getWhitelistedRoot(connectedAddress)`** returns the main whitelisted address
+2. **`checkEntitlement`** is automatically called with the whitelisted root address (not the connected wallet)
+3. **Claiming proceeds** as if the main account is claiming
+
+This allows users to claim from any connected wallet without re-verification.
+
+### How it Works
+
+The `IdentityV2.getWhitelistedRoot(address)` contract method returns:
+
+- `0x0` = address is neither whitelisted nor connected
+- `input address` = address is the main whitelisted account
+- `different address` = input is a connected account, returns the main whitelisted address
+
+The ClaimSDK automatically resolves the whitelisted root and uses it for all entitlement checks, making connected accounts work transparently.
+
+### Example
+
+```ts
+// User connects with a secondary wallet (Account B)
+// Account B is connected to main whitelisted Account A
+
+const identitySDK = await IdentitySDK.init({
+  publicClient,
+  walletClient,
+  env: "production",
+})
+const claimSDK = await ClaimSDK.init({
+  publicClient,
+  walletClient,
+  identitySDK,
+  env: "production",
+})
+
+// Behind the scenes:
+// 1. getWhitelistedRoot(Account B) → returns Account A
+// 2. checkEntitlement(Account A) → returns entitlement for Account A
+// 3. User can claim on behalf of Account A
+
+const { amount } = await claimSDK.checkEntitlement()
+if (amount > 0n) {
+  const receipt = await claimSDK.claim()
+  console.log(
+    "Claimed successfully from connected account!",
+    receipt.transactionHash,
+  )
+}
+```
+
 ## Using with React
 
 For Wagmi-based React projects, use the hooks exposed from `@goodsdks/react-hooks`. They wrap these Viem clients with loading/error state and should be the default integration layer for UI code. See `packages/react-hooks/README.md` for full guidance and examples.
@@ -118,6 +175,7 @@ Refer to the generated TypeScript declarations in `packages/citizen-sdk/dist/` f
 ## Best Practices
 
 - Check `identitySDK.getWhitelistedRoot` before instantiating the Claim SDK UI.
+- **Handle connected accounts**: The SDK automatically resolves the whitelisted root, but you may want to display which account is being claimed for in your UI.
 - Surface `altClaimAvailable` hints so users can switch to chains with available allocations.
 - Provide loading and error states around every async interaction.
 - Log transaction hashes and explorer links after a successful claim for supportability.

packages/citizen-sdk/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@goodsdks/citizen-sdk",
-  "version": "1.2.3",
+  "version": "1.2.4",
   "type": "module",
   "scripts": {
     "build": "tsup --clean",
     "dev": "tsc --watch",
-    "bump": "yarn version patch && yarn build && git add package.json && git commit -m \"version bump\""
+    "bump": "yarn version patch && yarn build && git add package.json && git commit -m \"version bump\"",
+    "test:connected": "npx tsx ../../test/citizen-sdk/connected-accounts.ts"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -26,6 +27,7 @@
   ],
   "devDependencies": {
     "@repo/typescript-config": "workspace:*",
+    "tsx": "^4.19.2",
     "typescript": "latest",
     "viem": "latest",
     "wagmi": "latest"

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

@@ -1,4 +1,5 @@
 import {
+  zeroAddress,
   type Account,
   type Address,
   type Chain,
@@ -83,6 +84,7 @@ export class ClaimSDK {
   private readonly account: Address
   private readonly env: contractEnv
   public readonly rdu: string
+  private whitelistedRootCache: Address | null = null
 
   constructor({
     account,
@@ -164,6 +166,44 @@ export class ClaimSDK {
     return this.chainId
   }
 
+  /**
+   * Resolves the main whitelisted address for this account.
+   * Useful for connected accounts to claim on behalf of their root address.
+   */
+  private async getWhitelistedRootAddress(): Promise<Address> {
+    // Return cached value if available
+    if (this.whitelistedRootCache) {
+      return this.whitelistedRootCache
+    }
+
+    try {
+      // Resolve the whitelisted root for this account
+      const { root, isWhitelisted } = await this.identitySDK.getWhitelistedRoot(
+        this.account,
+      )
+
+      // Normalize "no root" / "not whitelisted" cases
+      if (!isWhitelisted || !root || root === zeroAddress) {
+        throw new Error(
+          "No whitelisted root address found for connected account; the user may not be whitelisted.",
+        )
+      }
+
+      // Cache the result
+      this.whitelistedRootCache = root
+
+      return root
+    } catch (error) {
+      // Normalize SDK and transport errors into a predictable failure mode
+      const message =
+        error instanceof Error && error.message ? error.message : String(error)
+
+      throw new Error(
+        `Unable to resolve whitelisted root address for connected account: ${message}`,
+      )
+    }
+  }
+
   private async readChainEntitlement(
     chainId: SupportedChains,
     client?: PublicClient,
@@ -184,12 +224,16 @@ export class ClaimSDK {
       altClient = resolvedClient
     }
 
+    // Use whitelisted root address for entitlement check
+    // This enables connected accounts to claim on behalf of their main account
+    const rootAddress = await this.getWhitelistedRootAddress()
+
     return this.readContract<bigint>(
       {
         address: contracts.ubiContract as Address,
         abi: ubiSchemeV2ABI,
         functionName: "checkEntitlement",
-        args: [this.account],
+        args: [rootAddress],
       },
       altClient,
       chainId,

test/citizen-sdk/.env.example

@@ -0,0 +1,17 @@
+# Connected Accounts Test Configuration
+# Copy this file to .env and replace with your actual test addresses
+
+# Required: Whitelisted account address (main account)
+MAIN_ACCOUNT=0x0000000000000000000000000000000000000000
+
+# Required: Account connected to the main account
+CONNECTED_ACCOUNT=0x0000000000000000000000000000000000000000
+
+# Required: Non-whitelisted account for error testing
+NON_WHITELISTED_ACCOUNT=0x0000000000000000000000000000000000000000
+
+# Optional: Environment (development, staging, production)
+ENV=development
+
+# Optional: Custom RPC URL
+# RPC_URL=https://forno.celo.org

test/citizen-sdk/README.md

@@ -0,0 +1,30 @@
+# Connected Accounts Test Script
+
+Tests that connected accounts can claim UBI via their whitelisted root.
+
+## Run Commands
+
+```bash
+cd test/citizen-sdk
+cp .env.example .env  # Edit with your test addresses
+./run-test.sh
+```
+
+Alternatively from packages/citizen-sdk:
+```bash
+npm run test:connected
+```
+
+## Required Environment Variables
+
+- `MAIN_ACCOUNT` - Whitelisted account address **(required)**
+- `CONNECTED_ACCOUNT` - Account connected to main **(required)**
+- `NON_WHITELISTED_ACCOUNT` - Non-whitelisted account for error testing **(required)**
+- `ENV` - Environment: development, staging, or production (optional, default: development)
+- `RPC_URL` - Custom RPC endpoint (optional, default: https://forno.celo.org)
+
+## Pass/Fail Criteria
+
+**Pass:** All 4 tests pass - main resolves to self, connected resolves to main, non-whitelisted throws error, status retrieval succeeds.
+
+**Fail:** Any test fails - indicates issues with whitelisted root resolution or entitlement checks.