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

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,46 @@ 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 +162,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/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/run-test.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Helper script to run connected accounts tests with example addresses
+# 
+# Usage:
+#   ./run-test.sh
+#
+# Or with custom addresses:
+#   MAIN_ACCOUNT=0x... CONNECTED_ACCOUNT=0x... ./run-test.sh
+
+# Example test addresses (replace with real ones)
+# These are example addresses - you need to replace them with actual test accounts
+MAIN_ACCOUNT=${MAIN_ACCOUNT:-"0x0000000000000000000000000000000000000000"}
+CONNECTED_ACCOUNT=${CONNECTED_ACCOUNT:-"0x0000000000000000000000000000000000000000"}
+NON_WHITELISTED_ACCOUNT=${NON_WHITELISTED_ACCOUNT:-"0x0000000000000000000000000000000000000000"}
+ENV=${ENV:-"development"}
+
+echo "🧪 Running Connected Accounts SDK Test (TypeScript)"
+echo ""
+echo "Configuration:"
+echo "  Main Account: $MAIN_ACCOUNT"
+echo "  Connected Account: $CONNECTED_ACCOUNT"
+echo "  Non-Whitelisted: $NON_WHITELISTED_ACCOUNT"
+echo "  Environment: $ENV"
+echo ""
+
+MAIN_ACCOUNT=$MAIN_ACCOUNT \
+CONNECTED_ACCOUNT=$CONNECTED_ACCOUNT \
+NON_WHITELISTED_ACCOUNT=$NON_WHITELISTED_ACCOUNT \
+ENV=$ENV \
+npx tsx test/connected-accounts.ts

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

@@ -1,13 +1,4 @@
-import {
-  type Account,
-  type Address,
-  type Chain,
-  type PublicClient,
-  type SimulateContractParameters,
-  type WalletClient,
-  ContractFunctionExecutionError,
-  TransactionReceipt,
-} from "viem"
+import { zeroAddress, type Account, type Address, type Chain, type PublicClient, type SimulateContractParameters, type WalletClient, ContractFunctionExecutionError, TransactionReceipt } from "viem"
 
 import { waitForTransactionReceipt } from "viem/actions"
 
@@ -83,6 +74,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 +156,51 @@ export class ClaimSDK {
     return this.chainId
   }
 
+  /**
+   * Resolves the whitelisted root address for the connected account.
+   * This enables connected accounts to claim on behalf of their main whitelisted account.
+   * 
+   * Failure modes are normalized so callers see predictable behavior:
+   * - Throws when no whitelisted root exists for the connected account.
+   * - Throws when the SDK cannot resolve a whitelisted root (network / domain errors).
+   * 
+   * @returns The whitelisted root address to use for entitlement checks.
+   * @throws Error if no whitelisted root exists or resolution fails for any reason.
+   */
+  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 +221,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,

packages/citizen-sdk/test/README.md

@@ -0,0 +1,105 @@
+# Connected Accounts Test Script
+
+This directory contains a standalone test script to verify the connected accounts claiming flow works correctly.
+
+## Usage
+
+### Basic Usage
+
+```bash
+npx tsx test/connected-accounts.ts
+```
+
+Or use the npm script:
+
+```bash
+npm run test:connected
+```
+
+### With Environment Variables
+
+```bash
+MAIN_ACCOUNT=0x1234... \
+CONNECTED_ACCOUNT=0x5678... \
+NON_WHITELISTED_ACCOUNT=0x9abc... \
+ENV=development \
+npx tsx test/connected-accounts.ts
+```
+
+## Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `MAIN_ACCOUNT` | Main whitelisted account address | No | 0x0...0 |
+| `CONNECTED_ACCOUNT` | Account connected to main account | No | 0x0...0 |
+| `NON_WHITELISTED_ACCOUNT` | Non-whitelisted account | No | 0x0...0 |
+| `ENV` | Environment (development/staging/production) | No | development |
+| `RPC_URL` | Custom RPC URL | No | https://forno.celo.org |
+
+## What It Tests
+
+1. **Main Account Resolution** - Verifies main whitelisted account returns itself as root
+2. **Connected Account Resolution** - Verifies connected account returns main account as root
+3. **Non-Whitelisted Account** - Verifies non-whitelisted account returns 0x0
+4. **Main Account Entitlement** - Verifies entitlement check works for main account
+5. **Connected Account Entitlement** - Verifies entitlement check uses root address (simulating SDK behavior)
+
+## Example Output
+
+```
+🧪 Testing Connected Accounts Claiming Flow
+
+Environment: development
+RPC: https://forno.celo.org
+Identity Contract: 0xF25fA0D4896271228193E782831F6f3CFCcF169C
+UBI Contract: 0x6B86F82293552C3B9FE380FC038A89e0328C7C5f
+
+Test 1: Main whitelisted account
+✓ Main account is whitelisted
+  Root: 0x1234...
+
+Test 2: Connected account resolution
+✓ Connected account resolves to main
+  Root: 0x1234...
+
+Test 3: Non-whitelisted account
+✓ Non-whitelisted account returns 0x0
+  Root: 0x0000000000000000000000000000000000000000
+
+Test 4: Entitlement check (main account)
+✓ Main account entitlement retrieved
+  Entitlement: 1000000000000000000
+
+Test 5: Entitlement check (connected account → root)
+✓ Connected account entitlement via root
+  Root: 0x1234..., Entitlement: 1000000000000000000
+
+==================================================
+
+Test Results: 5/5 passed
+
+✅ All tests passed! Connected accounts flow is working correctly.
+```
+
+## Integration with CI/CD
+
+Add to your CI pipeline:
+
+```yaml
+# .github/workflows/test.yml
+- name: Test Connected Accounts
+  run: |
+    cd packages/citizen-sdk
+    MAIN_ACCOUNT=${{ secrets.TEST_MAIN_ACCOUNT }} \
+    CONNECTED_ACCOUNT=${{ secrets.TEST_CONNECTED_ACCOUNT }} \
+    NON_WHITELISTED_ACCOUNT=${{ secrets.TEST_NON_WHITELISTED }} \
+    ENV=development \
+    npm run test:connected
+```
+
+## Notes
+
+- This script only tests contract interactions, not the full SDK
+- Requires valid test accounts to be set via environment variables
+- Uses read-only contract calls (no transactions)
+- No private key needed (read-only operations)